Architect Specify

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

$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:

## 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:

{
  "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:

{
  "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

1. Identify Quality Attribute Drivers:

• Performance requirements (latency, throughput)
• Scalability expectations (users, data volume)
• Availability/reliability targets
• Security and compliance constraints
• Maintainability and extensibility needs

1. Identify Constraints:

• Technology mandates or prohibitions
• Budget and timeline constraints
• Team skills and organizational factors
• Regulatory or compliance requirements

1. 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

1. 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

1. Data Architecture

• Database selection (SQL vs NoSQL vs Hybrid)
• Data partitioning and scaling strategy
• Caching approach
• Event sourcing vs CRUD

1. Integration Architecture

• API style (REST vs GraphQL vs gRPC)
• Async messaging patterns
• Third-party integration approach

1. Security Architecture

• Authentication mechanism
• Authorization model
• Data protection strategy

1. Deployment Architecture

• Cloud provider selection
• Container orchestration
• CI/CD approach

Exploration Format

For each decision area requiring user input, present:

## 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
• Source: 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.