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

Note: Routine decision capture is handled by team-boot's continuous capture mechanism, which writes lightweight drafts directly to .adlc/drafts/. This skill is for interactive deep-dive exploration — when you want guided trade-off analysis, multi-option comparison, or structured decision facilitation before documenting.

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

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

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}/docs/adlc/memory/constitution.md (legacy {REPO_ROOT}/.adlc/memory/constitution.md fallback — ADR-401 dual-read) 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:

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:

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

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}/docs/adlc/memory/constitution.md (legacy {REPO_ROOT}/.adlc/memory/constitution.md fallback) if either 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 {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/setup-architect.sh (Requires the architect-clarify skill: adlc-cli skills add tikalk/adlc-team-skills --skill architect-clarify). 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