architect-implement

What this skill does

Generate a full Architecture Description (AD.md) from Architecture Decision Records (ADRs) using a multi-agent DAG orchestration approach:

1. Plan Agent: Analyze ADRs, detect sub-systems, generate a customized DAG, and get user approval.
2. Execute Agent: Generate architecture views per sub-system following the DAG, with dependency context passing.
3. Summarize Agent: Aggregate all views, resolve cross-subsystem conflicts, and generate a unified AD.md.

Key Insight: ADRs capture why decisions were made; the Architecture Description captures what the system looks like as a result of those decisions.

When to use

• After /architect-specify or /architect-clarify: Generate AD from discussed and accepted ADRs.
• After /architect-init: Document brownfield architecture.
• ADR Updates: Regenerate AD.md after new decisions.
• Documentation Sprint: Create comprehensive architecture docs.

When NOT to use

• No ADRs exist: Use /architect-specify or /architect-init first.
• Feature-level: Feature AD is generated during the feature's plan phase, not by this skill.
• Minor updates: Use direct editing for small changes.

Process

User Input

$ARGUMENTS

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

Examples of User Input:

• "Focus on deployment and operational views - we need infrastructure docs"
• "Generate all views with emphasis on security perspective"
• "Update existing AD.md with new ADRs from recent decisions"
• Empty input: Generate complete Architecture Description from all ADRs

Flags

• --views VIEWS: Architecture views to generate

  • core (default): Context, Functional, Information, Development, Deployment (5 core views)
  • all: All 7 views including Concurrency and Operational
  • Custom: comma-separated (e.g., concurrency,operational) - always includes core views

• --sequential (default): Execute views sequentially for maximum quality

  • Recommended: Allows checkpoint after Functional view

• --parallel: Allow parallel execution where dependency chains permit

  • Warning: May reduce cross-view consistency - use only when time-constrained

• --no-checkpoint: Skip Functional view checkpoint (not recommended)

  • Warning: Functional view is the "cornerstone" that shapes all others

• --force: Bypass workflow state validation (emergency use only)

  • WARNING: Use only when you understand the risks
  • Skips clarify Phase 5.5 completion check
  • Skips pre-flight ADR status validation
  • May result in incomplete or inconsistent architecture

Important: When --views is core (default), skip Concurrency View (3.4) and Operational View (3.7) entirely. Only generate them when explicitly requested via --views all or --views concurrency,operational.

Rozanski & Woods Methodology Alignment

This command implements the Viewpoints and Perspectives framework from Software Systems Architecture (2nd Edition) by Nick Rozanski and Eoin Woods.

Core Principles

1. Functional View is the Cornerstone

   "The Functional view is the cornerstone of most ADs... It usually drives the shape of other system structures such as the information structure, concurrency structure, deployment structure, and so on." — Rozanski & Woods

2. Views are Interrelated, Not Independent

   "The decisions taken in one view can have a considerable impact on the others, and it is a big part of the architect's job to make sure that these implications are understood."

3. Perspectives Apply to Views

   "You never work with perspectives in isolation but instead use them with each view to analyze and validate the qualities of your architecture."

4. Quality Over Speed Architecture mistakes are expensive to fix. Sequential execution with checkpoints is the default to ensure quality.

Viewpoint Dependency Graph

                    ┌──────────┐
                    │ Context  │  (System boundaries)
                    └────┬─────┘
                         │
                         ▼
                 ┌───────────────┐
                 │  FUNCTIONAL   │  ★ CORNERSTONE ★
                 │  (Drives all  │  USER CHECKPOINT
                 │   other views)│  REQUIRED HERE
                 └───────┬───────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
         ▼               ▼               ▼
   ┌───────────┐   ┌───────────┐   ┌───────────┐
   │Information│   │Concurrency│   │Development│
   │           │   │(optional) │   │           │
   └─────┬─────┘   └─────┬─────┘   └─────┬─────┘
         │               │               │
         └───────────────┼───────────────┘
                         │
                         ▼
                  ┌────────────┐
                  │ Deployment │
                  └──────┬─────┘
                         │
                         ▼
                  ┌────────────┐
                  │ Operational│  (optional)
                  └────────────┘

Dynamic Viewpoint & Perspective Selection

Viewpoints and perspectives are selected dynamically based on system characteristics:

Category	Always Included	Auto-Detected (Optional)
Viewpoints	Context, Functional	Information, Concurrency, Development, Deployment, Operational
Perspectives	Security, Performance	Accessibility, Availability, Evolution, Internationalization, Location, Regulation, Usability, Development Resource

Reference: https://www.viewpoints-and-perspectives.info/

Goal

Transform Architecture Decision Records (ADRs) into a comprehensive Architecture Description (AD.md) using a multi-agent DAG orchestration approach:

1. Plan Agent: Analyze ADRs, detect sub-systems, generate customized DAG, get user approval
2. Execute Agent: Generate views per sub-system following the DAG, with dependency context
3. Summarize Agent: Aggregate all views, resolve conflicts, generate unified AD.md

Role & Context

You are acting as an Architecture Orchestrator managing a multi-phase documentation generation workflow. Your role involves:

• Planning the generation DAG based on sub-system analysis
• Executing view generation with proper dependency ordering
• Summarizing views into a unified Architecture Description
• Persisting state for resumability across AI agent sessions

Architecture Document Hierarchy

Document	Purpose	Location
{REPO_ROOT}/.adlc/drafts/adr/	Architectural decisions with rationale (individual file format)	Input
{REPO_ROOT}/.adlc/architect/state.json	DAG execution state	State
{REPO_ROOT}/.adlc/architect/views/{subsystem}/{view}.md	Per-view outputs	Reference
{REPO_ROOT}/AD.md	Full Architecture Description	Output
{REPO_ROOT}/.adlc/memory/constitution.md	Governance principles	Constraint

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 reads individual ADR files from the adr/ directory
• When running from a subdirectory (e.g., a subproject directory), .adlc may be in the parent directory

View Templates

Located in the skill's templates/ directory:

Template	Purpose
templates/views/context.md	Context View template
templates/views/functional.md	Functional View template
templates/views/information.md	Information View template
templates/views/concurrency.md	Concurrency View template (optional)
templates/views/development.md	Development View template
templates/views/deployment.md	Deployment View template
templates/views/operational.md	Operational View template (optional)

Perspective Templates (10 total)
templates/perspectives/security.md
templates/perspectives/performance.md
templates/perspectives/accessibility.md
templates/perspectives/availability.md
templates/perspectives/evolution.md
templates/perspectives/internationalization.md
templates/perspectives/location.md
templates/perspectives/regulation.md
templates/perspectives/usability.md
templates/perspectives/development-resource.md

Three-Phase DAG Workflow

┌─────────────────────────────────────────────────────────────────────────────┐
│                          PHASE 1: PLAN                                      │
│  ┌─────────────┐    ┌─────────────────┐    ┌─────────────────────────────┐ │
│  │ Load ADRs   │───▶│ Detect Sub-     │───▶│ Generate DAG per Sub-system │ │
│  │             │    │ systems         │    │ (apply customization rules) │ │
│  └─────────────┘    └─────────────────┘    └──────────────┬──────────────┘ │
│                                                           │                 │
│                                            ┌──────────────▼──────────────┐ │
│                                            │ Present Plan for Approval   │ │
│                                            │ (user confirms or modifies) │ │
│                                            └──────────────┬──────────────┘ │
│                                                           │                 │
│                                            ┌──────────────▼──────────────┐ │
│                                            │ Write state.json            │ │
│                                            └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          PHASE 2: EXECUTE                                   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  For each sub-system, execute DAG in topological order:             │   │
│  │                                                                      │   │
│  │  ┌─────────┐    ┌────────────┐    ┌─────────────┐    ┌───────────┐ │   │
│  │  │ Context │───▶│ Functional │───▶│ Information │───▶│Development│ │   │
│  │  └─────────┘    └────────────┘    └─────────────┘    └───────────┘ │   │
│  │                        │                                    │       │   │
│  │                        ▼                                    ▼       │   │
│  │               ┌─────────────┐                      ┌────────────┐  │   │
│  │               │ Concurrency │                      │ Deployment │  │   │
│  │               │ (optional)  │                      └────────────┘  │   │
│  │               └─────────────┘                             │        │   │
│  │                                                           ▼        │   │
│  │                                                   ┌─────────────┐  │   │
│  │                                                   │ Operational │  │   │
│  │                                                   │ (optional)  │  │   │
│  │                                                   └─────────────┘  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  Each view: Read dependencies → Generate content (with perspectives inline)
│             → Update state.json with progress                               │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          PHASE 3: SUMMARIZE                                 │
│  ┌──────────────────┐    ┌─────────────────────┐    ┌──────────────────┐   │
│  │ Read all view    │───▶│ Detect cross-       │───▶│ Resolve conflicts│   │
│  │ files            │    │ subsystem conflicts │    │ using ADRs       │   │
│  └──────────────────┘    └─────────────────────┘    └────────┬─────────┘   │
│                                                               │             │
│  ┌──────────────────┐                       ┌──────────────▼───────────┐ │
│  │ Move Accepted    │◀─────────────────────────│ Aggregate into            │ │
│  │ ADRs to memory   │                         │ unified AD.md (views include│ │
│  └──────────────────┘                         │ perspective sections)     │ │
│                                             └───────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘

Note: Perspectives (Security, Performance, etc.) are now applied during view generation in Phase 2, not as a separate step in Phase 3. This follows the R&W principle: "use them with each view to analyze and validate the qualities of your architecture."

Pre-Flight Validation (MANDATORY - Hard Enforcement)

CRITICAL: These validations are ENFORCED. Execution will HALT if checks fail. Use --force flag only in emergency situations with full understanding of risks.

Before starting Phase 1, you MUST validate prerequisites:

Workflow State Check (unless --force)

1. Check clarify completion in state.json:
   • Load {REPO_ROOT}/.adlc/architect/state.json
   • Check workflow.clarify_completed field
   • If false or missing:

     ❌ WORKFLOW VALIDATION FAILED
     
     The implement command requires ADRs to be approved via /architect-clarify first.
     
     Current workflow state: clarify_completed = false
     
     Required: Run /architect-clarify and complete Phase 5.5 (ADR Approval)
     
     Options:
     1. Run /architect-clarify to approve ADRs
     2. Use --force to bypass (NOT RECOMMENDED - may cause inconsistent architecture)
     
     ⚠️  Using --force skips important validation steps and may result in:
        - Processing unapproved ADRs
        - Missing critical architectural decisions
        - Incomplete architecture documentation
     

   • HALT execution (unless --force flag provided)

ADR Status Check

2. Check ADRs exist: Verify {REPO_ROOT}/.adlc/drafts/adr/ or {REPO_ROOT}/.adlc/memory/adr/ exists (individual file format)
3. Check for Accepted ADRs: Count ADRs with status "Accepted"
   • If zero Accepted ADRs: STOP and output:

     ❌ Cannot proceed: No Accepted ADRs found
     
     The implement command requires ADRs with "Accepted" status.
     Current ADRs are: [list statuses found]
     
     Run /architect-clarify to review and approve ADRs first.
     

   • If ≥1 Accepted ADR: Proceed and report: "✓ Found N Accepted ADRs"

Mandatory Execution Constraints

CRITICAL -- READ THIS BEFORE PROCEEDING

The following constraints are MANDATORY. Violation of any constraint invalidates the output and requires restart.

Constraint 1: View Files MUST Be Written to Disk

You MUST write each view to disk as a separate file before proceeding to the next view. Location: {REPO_ROOT}/.adlc/architect/views/{subsystem}/{view}.md

• Do NOT hold views in memory and write only AD.md
• Do NOT combine multiple views into a single write operation
• Each file MUST be readable and standalone
• Minimum content: 20 lines with proper section headers

Constraint 2: State MUST Be Updated After EACH View

You MUST update state.json immediately after EACH individual view file is written to disk and verified readable -- before starting the next view in the DAG. Do NOT batch updates per-subsystem or per-phase. Mark each view's progress as "completed" only AFTER the file exists on disk and you've verified it by reading it back.

Constraint 3: Functional View Checkpoint is MANDATORY

You MUST pause after Functional view for user checkpoint (unless --no-checkpoint). Do NOT silently continue. Present checkpoint options A/B/C/D and WAIT for response. The Functional view is the "cornerstone" -- user approval is required.

Constraint 4: Phase "completed" Requires Verification

You MUST NOT mark phase as "completed" in state.json until:

• All view files exist on disk (verify by reading each file)
• AD.md has been written with content aggregated from view files
• Drafts cleanup has been performed and verified
• The final verification table (10 checks) has been output

Constraint 5: AD.md Content MUST Come From View Files

You MUST NOT write AD.md directly from ADRs. AD.md content MUST come from reading the generated view files. The flow is strictly: ADRs → Views (files on disk) → AD.md (aggregated from views)

Constraint 6: Phase 3 MUST Read From Disk

You MUST read view files from disk in Phase 3, not from memory. Use file read operations. This ensures resumability and auditability. If a view file cannot be read, STOP and report the error.

Constraint 7: Views MUST Be in Sub-system DAG

You MUST NOT generate a view that is not listed in the sub-system's dag array in state.json. Before generating any view, check the DAG. If the view is absent, mark it as skipped in state.json and proceed. Generating views outside the DAG creates orphaned files and invalidates the architecture.

Constraint 8: AD.md MUST Be Organized by Viewpoint

You MUST organize AD.md by viewpoint (§3.1 Context, §3.2 Functional, §3.3 Information, etc.), NOT by subsystem. Each viewpoint section presents the unified system-level perspective that merges content from all subsystems. Subsystem-specific detail is accessible via "Subsystem Details" links (see Step 3.5).

WRONG (per-subsystem — this is what subsystem view files are for): ## 5. Sub-System: Auth → ### 5.1 Context → ### 5.2 Functional

RIGHT (per-viewpoint — unified across ALL subsystems): ## 3. Architectural Views → ### 3.1 Context View → ### 3.2 Functional View

Constraint 9: Diagrams MUST Use Mermaid Syntax

You MUST use Mermaid syntax for all architectural diagrams in both view files and AD.md. ASCII box-drawing art (characters like ┌, └, ├, │, ───, ═══) is NOT permitted for architecture diagrams.

Accepted Mermaid diagram types:

• graph TB/LR — architecture, topology, flow diagrams
• erDiagram — data models and entity relationships
• sequenceDiagram — interaction flows
• flowchart — process flows

Directory tree listings (code organization) may use plain text code blocks — these are not architectural diagrams.

PHASE 1: PLAN (Plan Agent)

Objective: Analyze ADRs, detect sub-systems, generate customized DAG, get user approval

Script Action: Run scripts/bash/setup-architect.sh which calls plan-dag internally

Step 1.1: Load and Analyze ADRs

1. Read ADR Directory: Load ADRs from {REPO_ROOT}/.adlc/drafts/adr/ (and check {REPO_ROOT}/.adlc/memory/adr/ if drafts is empty)
2. Parse ADR Index: Extract sub-systems from {REPO_ROOT}/.adlc/drafts/adr/adr.md or individual ADR files
3. Group ADRs by Sub-system: Create mapping of sub-system → ADRs
4. Validate ADR Status (MANDATORY):
   • Count ADRs by status: Accepted / Proposed / Discovered
   • If zero Accepted ADRs: STOP execution and output error:

     ❌ PHASE 1 BLOCKED: No Accepted ADRs
     
     Found: [N] Proposed, [M] Discovered, [0] Accepted
     
     The implement command ONLY processes "Accepted" ADRs.
     Run /architect-clarify to approve ADRs before implementation.
     

   • Report to user: "✓ Found [N] Accepted ADRs ready for implementation"

ADR Index Table Format:

| ID | Sub-System | Decision | Status | Date | Owner |
|----|------------|----------|--------|------|-------|
| ADR-001 | Core | Microservices architecture | Accepted | 2024-01-15 | @architect |
| ADR-002 | Auth | OAuth2 with PKCE | Accepted | 2024-01-16 | @security |
| ADR-003 | Data | PostgreSQL primary store | Accepted | 2024-01-17 | @data |

Step 1.2: Detect Sub-systems and Characteristics

For each sub-system, analyze ADRs to detect:

Characteristic	Detection Pattern	DAG Customization
Serverless	Lambda, Functions, serverless	Deployment view first
Event-driven	Events, messaging, async, Kafka, RabbitMQ	Include Concurrency view
Data-intensive	Analytics, ETL, data pipeline	Information view priority
API-first	REST, GraphQL, OpenAPI	Functional view priority
Multi-region	Global, multi-region, geo	Deployment + Operational

Step 1.3: Generate Customized DAG per Sub-system

Default DAG (Core Views):

Context → Functional → Information → Development → Deployment

Extended DAG (All Views):

Context → Functional → Information ──┬─→ Development → Deployment → Operational
                                     └─→ Concurrency ─────────────────┘

DAG Customization Rules:

Pattern Detected	DAG Modification
Serverless	Deployment before Development
Event-driven	Add Concurrency after Information
Data-intensive	Information has highest priority after Context
Microservices	Add Concurrency, expand Functional
Monolith	Simplify Functional, skip Concurrency

Step 1.4: Present Plan for User Approval

Sub-System Count Threshold Enforcement (MANDATORY): Regardless of any prior approval from /architect-specify, you MUST apply the following rules before presenting the DAG plan:

Sub-System Count	Required Action
1–3	Present plan; auto-approve allowed
4–6	MUST ask user confirmation — do not proceed without explicit approval
>6	MUST suggest grouping and MUST ask confirmation

CRITICAL: Approval from /architect-specify (Phase 0) does NOT substitute for DAG execution plan approval. The user must confirm the per-sub-system DAG plan independently.

Present the execution plan to the user:

## DAG Execution Plan

**Sub-systems detected**: 3
**Total views to generate**: 15 (5 views × 3 sub-systems)

### Sub-system: Core
**ADRs**: ADR-001, ADR-005, ADR-008
**Characteristics**: Microservices, Event-driven
**DAG**: Context → Functional → Information → Concurrency → Development → Deployment

### Sub-system: Auth
**ADRs**: ADR-002, ADR-006
**Characteristics**: API-first
**DAG**: Context → Functional → Information → Development → Deployment

### Sub-system: Data
**ADRs**: ADR-003, ADR-004, ADR-007
**Characteristics**: Data-intensive
**DAG**: Context → Information → Functional → Development → Deployment

---

**Approve this plan?** [Yes/Modify/Cancel]

Step 1.5: Write state.json

After user approval, write the execution plan to {REPO_ROOT}/.adlc/architect/state.json: