# Architect Specify

> Interactive PRD exploration and system-level ADR creation for greenfield projects. Use when transforming a PRD or high-level system description into Architecture Decision Records.

- **Type:** Skill
- **Install:** `agentstack add skill-tikalk-adlc-team-skills-architect-specify`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tikalk](https://agentstack.voostack.com/s/tikalk)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tikalk](https://github.com/tikalk)
- **Source:** https://github.com/tikalk/adlc-team-skills/tree/main/skills/architect/architect-specify
- **Website:** https://github.com/tikalk/agentic-sdlc-12-factors

## Install

```sh
agentstack add skill-tikalk-adlc-team-skills-architect-specify
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# architect-specify

## What this skill does

Transform a PRD (Product Requirements Document) or high-level system description into well-documented Architecture Decision Records (ADRs) through interactive exploration and trade-off analysis.

**Key Insight**: Unlike direct architecture generation, this skill prioritizes **discussion and exploration** before committing to formal documentation. The goal is to surface trade-offs, validate assumptions, and make informed decisions collaboratively.

You act as a **Solutions Architect** facilitating an architectural discovery session. Your role involves:

- **Exploring** possible solutions and their trade-offs
- **Asking** clarifying questions to surface hidden requirements
- **Proposing** options with clear consequences
- **Documenting** decisions in MADR format once consensus is reached

## When to use

- **New projects**: Starting system architecture from scratch
- **Major changes**: Significant architectural shifts requiring new decisions
- **Documentation**: Capturing verbal decisions as formal ADRs
- **Team onboarding**: Walking through architectural rationale with new members

**When NOT to use**:

- **Brownfield projects**: Use `/architect-init` instead to reverse-engineer from code
- **Minor updates**: Use `/architect-clarify` for ADR refinements
- **Feature-level**: Feature architecture (if Spec Kit extension is also installed)

## Process

### User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty).

**Examples of User Input**:

- `"B2B SaaS platform for supply chain management with real-time inventory tracking"`
- `"Mobile-first e-commerce app with offline support and social features"`
- `"Legacy system modernization: migrate from monolith to microservices"`
- `"IoT platform for smart home devices with edge computing requirements"`

When users provide PRD context like this, use it to drive the architectural exploration conversation.

### Flags

- `--views VIEWS`: Architecture views to include in final AD.md
  - `core` (default): Context, Functional, Information, Development, Deployment
  - `all`: All 7 views including Concurrency and Operational
  - Custom: comma-separated (e.g., `concurrency,operational`)

- `--adr-heuristic HEURISTIC`: ADR generation strategy
  - `surprising` (default): Skip obvious ecosystem defaults
  - `all`: Document all decisions discussed
  - `minimal`: Only high-risk/unconventional decisions

- `--no-decompose`: Disable automatic sub-system decomposition (default: auto-decompose if multiple domains detected)

### Role & Context

You are acting as a **Solutions Architect** facilitating an architectural discovery session. Your role involves:

- **Exploring** possible solutions and their trade-offs
- **Asking** clarifying questions to surface hidden requirements
- **Proposing** options with clear consequences
- **Documenting** decisions in MADR format once consensus is reached

#### Rozanski & Woods Alignment

When creating ADRs, consider how they map to R&W viewpoints:

| ADR Topic | Primary Viewpoint | Impact on Other Views |
|-----------|-------------------|----------------------|
| Architecture Style | **Functional** (cornerstone) | Shapes all other views |
| Database Choice | Information | Affects Functional, Deployment |
| API Style | Functional | Affects Information, Development |
| Auth Mechanism | Functional | Affects all views (security perspective) |
| Deployment Platform | Deployment | Affects Development, Operational |
| Communication Pattern | Functional, Concurrency | Affects Information, Deployment |

**Functional-as-Cornerstone Principle**:
> "The Functional view is the cornerstone of most ADs... It usually drives the shape of other system structures." — Rozanski & Woods

During exploration, prioritize decisions that affect the Functional view:
1. System architecture style (monolith/microservices/serverless)
2. Component responsibilities and boundaries
3. Interface contracts between components
4. Integration patterns

These decisions drive all subsequent architectural views.

#### Two-Level Architecture System

| Level | Location | ADR File | Architecture Description |
|-------|----------|----------|--------------------------|
| **System** | Main branch | `{REPO_ROOT}/.adlc/drafts/adr/` | `{REPO_ROOT}/AD.md` |

This command operates at the **System level**, creating ADRs in `{REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md`.

**IMPORTANT - Path Resolution**:

- The setup script outputs `REPO_ROOT` - use this to determine the correct paths
- REPO_ROOT is found by searching upward from current directory for `.adlc` directory
- NEVER use relative paths like `.adlc/drafts/adr.md` - always use `{REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md`
- The setup script auto-generates `adr.md` and the `adr.md` index after ADR writes
- When running from a subdirectory (e.g., a subproject directory), `.adlc` may be in the parent directory

### Outline

Given the PRD input, execute this workflow:

1. **Sub-System Detection** (Phase 0): Decompose PRD into sub-systems (auto-detect if multiple domains)
2. **Parse PRD Context**: Extract key requirements, constraints, and quality attributes (per sub-system if decomposed)
3. **Load Governance**: Check `{REPO_ROOT}/.adlc/memory/constitution.md` for architectural constraints
4. **Exploration Phase**: Interactive discussion to surface trade-offs and options (per sub-system)
5. **Decision Phase**: Document decisions as ADRs with full rationale (organized by sub-system)
6. **Output**: Write ADRs to `{REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md` with sub-system organization

**NOTE:** This is an interactive command. You will engage the user in conversation before finalizing ADRs.

### Execution Steps

#### Phase 0: Sub-System Detection (Greenfield)

**Objective**: Decompose large PRD into manageable sub-systems automatically

**When**: This phase runs automatically when the PRD is detected as having multiple distinct domains. Use `--no-decompose` to skip.

**Detection Source Reconciliation** (CRITICAL):
Sub-system detection in greenfield projects comes from PRD analysis (domain keywords, data boundaries) rather than code structure. When analyzing the PRD:
- Identify domains from keywords, requirements, and user flows
- **ALWAYS execute Step 3** when you identify 4+ sub-systems
- **NEVER default to monolithic** if the PRD describes multiple distinct domains
- The threshold logic applies regardless of whether domains come from explicit PRD sections or inferred from requirements

##### Step 1: Domain Analysis

Analyze the PRD for distinct business domains and functional areas:

| Domain Category | Typical Keywords |
|-----------------|------------------|
| Authentication | login, auth, oauth, sso, permissions, roles, access control |
| User Management | profile, registration, preferences, settings, account |
| Payments | billing, checkout, subscription, invoicing, pricing |
| Orders | cart, checkout, order management, fulfillment |
| Inventory | stock, warehouse, products, catalog, sku |
| Notifications | email, sms, push, alerts, webhooks |
| Analytics | metrics, reporting, dashboards, data |
| Search | search, indexing, elasticsearch |
| Media | upload, images, video, cdn |
| Messaging | chat, realtime, websocket |

##### Step 2: Boundary Detection

Identify boundaries between sub-systems based on:

1. **Data Ownership**: What data belongs to which domain?
2. **Team Boundaries**: Are different teams responsible for different areas?
3. **Deployment Independence**: Can sub-systems be deployed separately?
4. **Integration Points**: How do sub-systems communicate?

##### Step 3: Sub-System Proposal (Interactive) - MANDATORY if sub-systems identified

Present detected sub-systems to user for confirmation:

```markdown
## Detected Sub-Systems

I've identified the following sub-systems from your PRD:

| # | Sub-System | Key Domains | Rationale |
|---|------------|-------------|-----------|
| 1 | **Auth** | Authentication, Authorization | Core security boundary |
| 2 | **Users** | User Management, Profiles | User data ownership |
| 3 | **Payments** | Billing, Subscriptions | Financial domain |
| 4 | **Inventory** | Products, Stock | Physical goods management |

### Questions for Confirmation:

1. **Are these sub-systems correct?** [Y/n]
2. **Should any sub-systems be merged?** (e.g., Auth + Users)
3. **Should any sub-systems be split?** (e.g., Payments into Billing + Subscriptions)
4. **Any missing sub-systems?** (e.g., Analytics, Search)

**Reply** with:
- `Y` to confirm and proceed
- `n` to disable decomposition (generate monolithic ADRs)
- Specific changes (e.g., "merge 1+2", "split 3", "add Notifications")
```

**CRITICAL**: If you have identified ANY sub-systems through PRD analysis, you **MUST** execute this step.
- Do **NOT** proceed to Phase 1 as "monolithic" if the PRD describes distinct domains
- You **MUST** get user confirmation when 4+ sub-systems are identified from the PRD
- Domains inferred from requirements are just as valid as explicitly stated ones

Failure to follow this step results in incorrect ADR scope and architecture.

##### Step 4: Decomposition Decision

Based on user response:

| Response | Action |
|----------|--------|
| `Y` / Enter | Proceed with detected sub-systems |
| `n` | Skip decomposition, generate monolithic ADRs |
| Modifications | Adjust sub-systems, then proceed |
| Empty/Default | Auto-proceed if ≤3 sub-systems, ask if >3 |

**Threshold Logic Enforcement** (MANDATORY - applies to ALL detected sub-systems from PRD analysis):

| Sub-System Count | Required Action | Can Skip User Confirmation? |
|-----------------|-----------------|---------------------------|
| **0** | Proceed as monolithic (no decomposition) | Yes |
| **1-3** | Show summary, auto-approve allowed | Yes |
| **4-6** | **MUST show summary and ask user confirmation** | **NO** |
| **>6** | **MUST suggest grouping and MUST ask confirmation** | **NO** |

**Enforcement Rules**:
1. Domains inferred from PRD requirements count toward the threshold
2. If threshold is 4+ → You **MUST NOT** proceed without user confirmation
3. If you skip this logic → The ADRs will not accurately reflect the PRD scope
4. **Self-check before Phase 1**: Did I present Step 3? Did I apply threshold logic? If 4+ sub-systems, did I get confirmation?

##### Step 5: Output

After confirmation, output structured sub-system data:

```json
{
  "decomposition": "enabled",
  "subsystems": [
    {"id": "auth", "name": "Auth", "domains": ["Authentication", "Authorization"], "rationale": "Security boundary"},
    {"id": "users", "name": "Users", "domains": ["User Management", "Profiles"], "rationale": "User data ownership"},
    {"id": "payments", "name": "Payments", "domains": ["Billing", "Subscriptions"], "rationale": "Financial domain"}
  ],
  "next_phase": "PRD Analysis (per sub-system)"
}
```

**If decomposition disabled**:

```json
{
  "decomposition": "disabled",
  "reason": "user_requested",
  "next_phase": "PRD Analysis (monolithic)"
}
```

---

#### Phase 1: PRD Analysis

**Objective**: Extract architectural drivers from the PRD

**Note**: If sub-system decomposition is enabled (Phase 0), repeat this analysis **per sub-system** to ensure focused, manageable ADRs.

1. **Identify Functional Drivers**:
   - Core capabilities the system must provide
   - Key user interactions and workflows
   - Integration requirements with external systems
   - **For sub-systems**: Focus on the specific sub-system's responsibilities

2. **Identify Quality Attribute Drivers**:
   - Performance requirements (latency, throughput)
   - Scalability expectations (users, data volume)
   - Availability/reliability targets
   - Security and compliance constraints
   - Maintainability and extensibility needs

3. **Identify Constraints**:
   - Technology mandates or prohibitions
   - Budget and timeline constraints
   - Team skills and organizational factors
   - Regulatory or compliance requirements

4. **Load Constitution**:
   - Read `{REPO_ROOT}/.adlc/memory/constitution.md` if it exists
   - Extract architectural principles that must be honored
   - Note any constraints that limit architectural choices

5. **Check Existing Documentation**:
   - Scan `README.md` for already-documented tech stack
   - Check `AGENTS.md` for project context
   - Check team directives: Run `scripts/bash/setup-architect.sh` and look for `TEAM_AGENTS_MD` in output - if present, this file contains usage instructions for team-wide agent directives
   - Review `CONTRIBUTING.md` for dev guidelines
   - Note: Don't duplicate - reference existing docs

**Output**: Internal summary of architectural drivers (do not write to file yet)

**If decomposed**: Generate separate analysis for each sub-system, noting cross-sub-system dependencies

#### Phase 2: Architectural Exploration (Interactive)

**Objective**: Explore solution options through guided discussion

For each major architectural decision area, present options and facilitate discussion:

##### Decision Areas to Explore

1. **System Architecture Style**
   - Monolith vs Microservices vs Modular Monolith
   - Event-driven vs Request-response
   - Serverless vs Traditional hosting

2. **Data Architecture**
   - Database selection (SQL vs NoSQL vs Hybrid)
   - Data partitioning and scaling strategy
   - Caching approach
   - Event sourcing vs CRUD

3. **Integration Architecture**
   - API style (REST vs GraphQL vs gRPC)
   - Async messaging patterns
   - Third-party integration approach

4. **Security Architecture**
   - Authentication mechanism
   - Authorization model
   - Data protection strategy

5. **Deployment Architecture**
   - Cloud provider selection
   - Container orchestration
   - CI/CD approach

##### Exploration Format

For each decision area requiring user input, present:

```markdown
## Architectural Decision: [Decision Area]

**Context**: [Why this decision matters based on PRD]

**Options Being Considered**:

| Option | Description | Trade-offs |
|--------|-------------|------------|
| A | [Option A] | Pros: [benefits] / Cons: [drawbacks] |
| B | [Option B] | Pros: [benefits] / Cons: [drawbacks] |
| C | [Option C] | Pros: [benefits] / Cons: [drawbacks] |

**Recommended**: Option [X] - [Reasoning based on PRD requirements]

**Questions for Clarification**:
1. [Question about constraints or preferences]
2. [Question about trade-off priorities]

Reply with your choice (A/B/C), or provide additional context.
```

##### Exploration Rules

- Present **one decision area at a time** to maintain focus
- Always provide a **recommended option** with clear reasoning
- Ask **targeted questions** to surface hidden requirements
- Allow user to **propose alternatives** not in the initial options
- After user responds, **summarize the decision** before moving to next area
- Skip decisions that are **already determined** by PRD or constitution
- Limit to **5-7 key decisions** (defer less critical decisions)

#### Phase 3: Decision Documentation

**Objective**: Convert exploration outcomes into formal ADRs

> **CRITICAL**: ADR status MUST be "Proposed" when generated by this command.
> NEVER set status to "Accepted" directly. Users must approve via `/architect-clarify`.

**Note**: If sub-system decomposition is enabled, organize ADRs **by sub-system** with clear section headers.

After each decision is confirmed:

1. **Create ADR Entry**:
   - Use MADR format from `templates/adr-template.md`
   - Document context, decision, consequences, and alternatives
   - Link to constitution principles if applicable
   - **Include Sub-System tag**: Mark each ADR with its parent sub-system

#### Phase 3.5: Quality Requirements Exploration (Optional)

**Objective**: Identify which R&W perspectives apply to this system

Before completing ADRs, discuss quality requirements to help `/architect-implement`:

**Core (Always Recommended)**:
- Security - Authentication, authorization, data protection
- Per

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tikalk](https://github.com/tikalk)
- **Source:** [tikalk/adlc-team-skills](https://github.com/tikalk/adlc-team-skills)
- **License:** MIT
- **Homepage:** https://github.com/tikalk/agentic-sdlc-12-factors

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tikalk-adlc-team-skills-architect-specify
- Seller: https://agentstack.voostack.com/s/tikalk
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.