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

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

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

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

1. Check ADRs exist: Verify {REPO_ROOT}/.adlc/drafts/adr/ or {REPO_ROOT}/.adlc/memory/adr/ exists (individual file format)
2. 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 t

…

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.