Architect Implement

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:

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

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:

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}/docs/adlc/memory/adr/ (legacy {REPO_ROOT}/.adlc/memory/adr/ fallback) 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}/docs/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 {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). 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}/docs/adlc/memory/adr/ or legacy {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:

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:

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:

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:

{
  "version": "1.1.0",
  "created_at": "2024-01-20T10:30:00Z",
  "updated_at": "2024-01-20T10:30:00Z",
  "phase": "plan_approved",
  "views_mode": "core",
  "workflow": {
    "clarify_completed": false,
    "clarify_completed_at": null,
    "adrs_approved_count": 0,
    "implement_started": false,
    "implement_started_at": null
  },
  "subsystems": [
    {
      "id": "core",
      "name": "Core",
      "adrs": ["ADR-001", "ADR-005", "ADR-008"],
      "characteristics": ["microservices", "event-driven"],
      "dag": ["context", "functional", "information", "concurrency", "development", "deployment"],
      "progress": {
        "context": "pending",
        "functional": "pending",
        "information": "pending",
        "concurrency": "pending",
        "development": "pending",
        "deployment": "pending"
      }
    },
    {
      "id": "auth",
      "name": "Auth",
      "adrs": ["ADR-002", "ADR-006"],
      "characteristics": ["api-first"],
      "dag": ["context", "functional", "information", "development", "deployment"],
      "progress": {
        "context": "pending",
        "functional": "pending",
        "information": "pending",
        "development": "pending",
        "deployment": "pending"
      }
    }
  ],
  "perspectives": ["security", "performance"],
  "output_file": "docs/adlc/architect/AD.md"
}

PHASE 2: EXECUTE (Execute Agent)

Objective: Generate views per sub-system following the DAG, with dependency context passing

Script Action: The agent reads state.json and executes views in DAG order

Step 2.1: Read Execution State

1. Load {REPO_ROOT}/.adlc/architect/state.json
2. Identify next view(s) to generate (views with all dependencies completed)
3. Load relevant ADRs for the current sub-system

Step 2.2: Generate Views in DAG Order

For each view in the DAG:

0. DAG Membership Check: Confirm the view is listed in the sub-system's dag array in state.json. If absent → mark skipped, do NOT generate, continue to next view.
1. Check Dependencies: Ensure all dependency views are completed
2. Load Dependency Context: Read completed view files for context
3. Load View Template: Read from templates/views/{view}.md
4. Generate View Content: Fill template with ADR-derived content
5. Write View File: Save to {REPO_ROOT}/docs/adlc/architect/views/{subsystem}/{view}.md
6. Update State: Mark view as "completed" in state.json

View Generation with Dependency Context:

## Generating: Functional View for "Core" sub-system

**Dependencies loaded**:
- Context View: {REPO_ROOT}/docs/adlc/architect/views/core/context.md (completed)

**ADRs for this view**: ADR-001 (Microservices), ADR-005 (API Gateway)

**Generating content...**

Step 2.3: View Templates and Placeholders

Each view template contains placeholders to be filled:

Step 2.4: View Generation Details

Context View

Purpose: System scope and external interactions (blackbox view) Dependencies: None (first in DAG) Template: templates/views/context.md Key Content:

• System scope description
• External entities table (stakeholders + external systems only)
• Context diagram (system as single blackbox)
• External dependencies table

Functional View (★ CORNERSTONE - USER CHECKPOINT)

Purpose: Internal components, responsibilities, interactions Dependencies: Context View Template: templates/views/functional.md Key Content:

• Functional elements table
• Element interactions diagram
• Functional boundaries

IMPORTANT: After generating the Functional view, execution pauses for user approval. This is the "cornerstone" view that shapes all subsequent views.

Rozanski & Woods: "The Functional view is the cornerstone... It usually drives the shape of other system structures."

Checkpoint Options:

• A: Approve - Continue to remaining views
• B: Modify - Edit functional view, then continue
• C: Restart - Regenerate with feedback
• D: Cancel - Stop execution

If skipping checkpoint (--no-checkpoint flag): Generate without pause but log warning.

Information View

Purpose: Data storage, management, and flow Dependencies: Context View, Functional View Template: templates/views/information.md Key Content:

• Data entities table
• ER diagram
• Data flow description

Concurrency View (Optional)

Purpose: Runtime processes, threads, coordination Dependencies: Functional View, Information View Template: templates/views/concurrency.md Condition: Only if --views all or --views concurrency Key Content:

• Process structure table
• Sequence diagram
• Coordination mechanisms

Development View

Purpose: Code organization, dependencies, CI/CD Dependencies: Functional View Template: templates/views/development.md Key Content:

• Code organization structure
• Module dependencies
• Build & CI/CD description

Deployment View

Purpose: Physical environment, nodes, networks Dependencies: Development View Template: templates/views/deployment.md Key Content:

• Runtime environments table
• Network topology diagram
• Hardware requirements

Operational View (Optional)

Purpose: Operations, support, maintenance Dependencies: Deployment View Template: templates/views/operational.md Condition: Only if --views all or --views operational Key Content:

• Operational responsibilities
• Monitoring & alerting
• Disaster recovery

Step 2.5: Update Progress in state.json

WARNING: Batching state updates (e.g., updating only after all views for a sub-system are complete) violates Constraint 2. Update state.json immediately after each individual view file is written and verified.

After each view is generated:

{
  "progress": {
    "context": "completed",
    "functional": "completed",
    "information": "in_progress",
    "development": "pending",
    "deployment": "pending"
  },
  "updated_at": "2024-01-20T11:15:00Z"
}

Step 2.6: Resumability

If the agent session is interrupted:

1. Next session loads state.json
2. Identifies views with "pending" or "in_progress" status
3. Continues from where it left off
4. Skips already "completed" views