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

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:

## 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
• Performance - Response time, throughput, scalability

Situational (Select Based on Requirements):

Quality	Question	If Yes → Apply Perspective
Availability	Does the system need high uptime (>99%)?	Availability & Resilience
Evolution	Will the system need to change significantly over time?	Evolution
Regulation	Is the system subject to laws/regulations (GDPR, HIPAA)?	Regulation
Accessibility	Will users with disabilities use this system?	Accessibility
Internationalization	Will the system support multiple languages/regions?	Internationalization
Location	Are there geographic distribution concerns?	Location
Usability	Is ease of use a critical success factor?	Usability
Resources	Are there significant constraints on people/budget/time?	Development Resource

Present to user:

## Quality Requirements

Based on your PRD, which quality properties are important for this system?

### Core (Always Recommended)
- [x] Security
- [x] Performance

### Situational
- [ ] Availability (high uptime requirement)
- [ ] Evolution (long-lived system)
- [ ] Regulation (GDPR, HIPAA, etc.)
- [ ] Other: ___________

Please indicate which apply (e.g., "Availability, Regulation").

Store selected perspectives in ADR metadata for /architect-implement:

<!-- Quality Requirements -->
<!-- perspectives: security, performance, availability, regulation -->

2. Sub-System Organization:

If decomposed, structure the ADR file as:

# Architecture Decision Records

## ADR Index

| ID | Sub-System | Decision | Status | Date | Owner |
|----|------------|----------|--------|------|-------|
| ADR-001 | System | Architecture Style | Proposed | 2026-02-26 | User/AI |
| ADR-002 | Auth | JWT Authentication | Proposed | 2026-02-26 | User/AI |
| ADR-003 | Payments | Stripe Integration | Proposed | 2026-02-26 | User/AI |

---

## System-Level ADRs

### ADR-001: [Decision Title]

[Full ADR content...]

---

## Auth Sub-System ADRs

### ADR-002: [Decision Title]

[Full ADR content...]

---

## Payments Sub-System ADRs

### ADR-003: [Decision Title]

[Full ADR content...]

3. Cross-Cutting ADRs: Some decisions affect multiple sub-systems (e.g., "Use PostgreSQL for all sub-systems"). Mark these as System-Level and note impact on each sub-system.

4. ADR Format (MADR 3.0.0 — see templates/adr-template.md):

---
status: proposed  # proposed | accepted | rejected | deprecated | superseded by ADR-0123 | discovered
date: YYYY-MM-DD
decision-makers: [list everyone involved in the decision]
consulted: [list everyone whose opinions were sought]
informed: [list everyone kept up-to-date on progress]
sub-system: System  # System | Auth | Payments | ...
superseded-by: ""
---

# {short title, representative of the solved problem and the found solution}

## Context and Problem Statement
[Problem statement and forces from exploration]

## Decision Drivers
* {decision driver 1}
* {decision driver 2}

## Considered Options
* {title option 1}
* {title option 2}

## Decision Outcome
Chosen option: "{title option 1}", because {justification}.

### Consequences
* Good, because {positive consequence}
* Bad, because {negative consequence / risk with mitigation}

### Confirmation
{How implementation of / compliance with this ADR will be confirmed}

## Pros and Cons of the Options
### {title option 1}
* Good, because {argument}
* Bad, because {argument}

## Constitution Alignment
| Principle | Alignment | Notes |
|-----------|-----------|-------|

## Related ADRs
* [ADR-XXX: {Related decision}](ADR-XXX.md)

## More Information
{Additional evidence, links, when/how to re-visit}

3. Number ADRs sequentially: Start from ADR-001 for new projects, or continue from highest existing number

Phase 4: ADR Output

Objective: Write finalized ADRs to file

1. Run Setup Script:

   • Execute scripts/bash/setup-architect.sh to ensure {REPO_ROOT}/.adlc/drafts/adr/ directory exists
   • Script creates from template if directory is empty
   • Pass --no-decompose if decomposition was disabled

2. Write ADRs:

   • Write each new ADR as {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md
   • The setup script auto-generates adr.md and adr.md index after writes
   • Update ADR index table at top of file (include Sub-System column)
   • Preserve any existing ADRs (don't overwrite)
   • If decomposed: Add section headers for each sub-system

3. Report Summary:

   • List of sub-systems identified
   • ADRs created per sub-system with IDs and titles
   • Constitution alignment status
   • Cross-cutting decisions noted
   • Recommended next steps

Summary Format:

## Sub-System Decomposition Summary

### Sub-Systems Identified: 3

| # | Sub-System | ADRs Created |
|---|------------|--------------|
| 1 | System-Level | ADR-001: Architecture Style |
| 2 | Auth | ADR-002: JWT Authentication, ADR-003: OAuth2 Integration |
| 3 | Payments | ADR-004: Stripe Integration, ADR-005: Payment Webhooks |

### Cross-Cutting Decisions
- ADR-001 affects all sub-systems

### Next Steps
1. Review ADRs with /architect-clarify
2. Generate AD.md with /architect-implement

Key Rules

Exploration First

• Do NOT generate architecture directly from PRD
• Engage in discussion to validate assumptions
• Surface trade-offs before committing to decisions
• Allow iteration - user can revisit earlier decisions

Constitution Compliance

• ADRs must align with constitution principles
• Flag conflicts between PRD requirements and constitution
• Constitution violations require explicit override with justification

Incremental ADRs

• Create focused ADRs - one decision per ADR
• Link related ADRs when decisions interact
• Defer decisions that can be made later
• Mark provisional decisions that may need revision

Quality Standards

• Every ADR must have clear context explaining why decision was needed
• Consequences must include both positive and negative outcomes
• Alternatives must explain why they were rejected
• Decisions must be actionable - clear enough to implement

Sub-System Decomposition

• Auto-detect domains: Analyze PRD for distinct business domains automatically
• Interactive confirmation: Always confirm sub-system breakdown with user
• Balanced granularity: Aim for 3-7 sub-systems; avoid over-decomposition
• Clear boundaries: Each sub-system should have distinct responsibilities
• Cross-cutting concerns: Document system-level decisions separately
• Per-sub-system exploration: Run architectural exploration per sub-system for focused decisions
• Use --no-decompose: Skip decomposition for simple/small systems

Workflow Guidance & Transitions

After /architect-init

Recommended next steps:

1. Review ADRs: Ensure all decisions are accurate and complete
2. Run /architect-clarify: Refine any ambiguous or incomplete ADRs
3. Run /architect-implement: Generate full Architecture Description from ADRs
4. Proceed to features: Use /architect-specify to create new ADRs for additional decisions

Context

$ARGUMENTS

Next Steps

After specify completes, run /architect-clarify to refine and validate the ADRs.

Verification