Architecture awareness

Architecture Awareness

Architecture knowledge lives in two artifact types that complement specs:

     SPEC (WHAT)
    /           \
   /             \
ADR (HOW+WHY) -- C4 (CONTEXT MAP)

• Specs describe WHAT the system does (capabilities, acceptance criteria)
• ADRs describe HOW the system is built and WHY those technical choices were made
• C4 Diagrams provide the CONTEXT MAP — how everything relates structurally

All three are persistent, first-class artifacts. Backlog items are transient; these are not.

ADR Organization

Architecture Decision Records capture significant technical decisions using the Michael Nygard pattern.

Directory Structure

docs/decisions/
  ADR-000-use-adrs-for-architecture-decisions.md   # bootstrapping record
  ADR-001-{slug}.md
  ADR-002-{slug}.md

Flat directory. No subdirectories. The domain field in frontmatter provides domain association.

Frontmatter Schema

Schema: schemas/adr.schema.md v1.0

Required: adr_version, type: adr, id (ADR-NNN), title, status, created, deciders Optional: domain, spec_refs, backlog_ref, superseded_by, supersedes, tags

ADR Lifecycle

/define (proposed) → /design (accepted) → [lives indefinitely]
                                        → /design (superseded by new ADR)
                                        → /design (deprecated if no longer relevant)

• proposed — Created by /define when a behavioral delta involves an architectural choice
• accepted — Created or promoted by /design after evaluating alternatives
• deprecated — Decision no longer relevant (e.g., feature removed). Set by /design
• superseded — A newer ADR replaces this one. superseded_by points to the replacement

ADR Creation Threshold

Create an ADR ONLY when BOTH conditions are true:

1. Multiple viable alternatives exist — There is a genuine choice between approaches
2. Hard to reverse OR affects multiple domains — The decision has lasting consequences

Do NOT create ADRs for: trivial decisions, single-option choices, easily reversible choices, or implementation details within a single component.

Numbering Convention

Sequential 3-digit zero-padded: ADR-000, ADR-001, ADR-002, etc. To determine the next number: scan docs/decisions/ADR-*.md and increment the highest found.

C4 Diagram Organization

C4 Mermaid diagrams provide the contextual map — how everything relates structurally.

Directory Structure

docs/architecture/
  system-context.md          # Level 1: System and external actors
  containers.md              # Level 2: High-level containers/services
  components/                # Level 3: Per-domain component diagrams
    {domain}.md              # One per domain, parallels docs/specs/{domain}/

Frontmatter Schema

Schema: schemas/architecture-diagram.schema.md v1.0

Required: diagram_version, type: architecture-diagram, level (1-3), title, updated, updated_by Optional: domain (L3 only), backlog_ref, adr_refs, tags

C4 Levels

Level	File	Scope
1 — System Context	docs/architecture/system-context.md	System and external actors
2 — Container	docs/architecture/containers.md	High-level containers/services
3 — Component	docs/architecture/components/{domain}.md	Per-domain components

Level 4 (Code) is NOT supported. Source code is the code-level diagram.

Diagram Format

Each diagram file contains:

• YAML frontmatter with type: architecture-diagram
• Mermaid flowchart diagram with Neon Dark styling (dark backgrounds, neon accent colors)
• Infrastructure context subgraphs (USERS, SYSTEM, EXTERNAL, etc.)
• Nodes with bold titles, responsibility descriptions, and tech stack
• ## Coupling Notes section — runtime, build-time, and data dependencies
• ## Cohesion Assessment section — rates domain cohesion (HIGH/MEDIUM/LOW) with justification (Level 3 only)

Diagram Style Reference

See schemas/architecture-diagram.schema.md for full color palette and node format.

Node format:

["<b>Title</b><br/> <br/><span>Responsibility</span><br/><span>Technology</span>"]

Key colors:

• Actors: #ff2e97 (hot pink) on #2a0f1e
• Core system: #00fff5 (cyan) on #0d2a2a
• Services: #b967ff (purple) on #1f0d2e
• External: #9d4edd (violet) on #1a0d24

Staleness Threshold

Diagrams not updated within 90 days are flagged as potentially stale by /context:load and /diagnose.

When Active

This skill activates during:

• /arch:init — Bootstrap ADR-000 and initial C4 diagrams for existing projects
• /context:load — Report ADR count by status and diagram staleness
• /context:refresh — Detect drift between diagrams and code structure
• /spec:init — Generate initial C4 diagrams (L1-L2) from discovered domains
• /define — Create proposed ADRs when behavioral delta involves an architectural choice
• /design — Create accepted ADRs; update C4 diagrams when boundaries change
• /deliver — Read ADRs for implementation context (WHY constraints exist)
• /discern — Verify ADR compliance; check for boundary violations
• /handoff — Inject ADR-specific transition guidance into handoff output
• /diagnose — Coupling violations, cohesion drift, ADR health, diagram staleness
• /discover — Surface existing ADRs as context for exploration

Behaviors

Common: ADR Loading Pattern

All commands that read ADRs follow this pattern:

1. Check for adr_refs in the backlog item or design document frontmatter
2. If adr_refs is present: Read each referenced ADR file from docs/decisions/
3. If adr_refs is missing: Scan docs/decisions/ADR-*.md for ADRs matching the domain or tags
4. If docs/decisions/ does not exist: Warn and continue:

   No ADRs directory found. Architecture decisions are not being tracked.

5. Never block — ADRs are valuable but optional. All commands warn and continue.

Common: C4 Diagram Loading Pattern

All commands that read C4 diagrams follow this pattern:

1. Check for docs/architecture/ directory
2. If present: Read relevant diagram files based on scope (L1-L2 for broad context, L3 for domain-specific)
3. If missing: Warn and continue:

   No architecture directory found. C4 diagrams are not being maintained.

4. Never block — diagrams are valuable but optional. All commands warn and continue.

During /define (AC-3)

Creates proposed ADRs when a behavioral delta involves an architectural choice:

1. While analyzing the behavioral delta, check if the change involves a HOW decision (not just WHAT changes)
2. Apply the ADR Creation Threshold — both conditions must be true
3. If threshold met: a. Determine next ADR number by scanning docs/decisions/ADR-*.md b. Create docs/decisions/ADR-{NNN}-{slug}.md with status: proposed c. Fill in Context and Alternatives Considered sections (captured while the problem is fresh) d. Leave Decision section with placeholder: "To be determined by /design" e. Add adr_refs to the backlog item frontmatter
4. If threshold not met: No ADR created. Proceed normally.

Reads: docs/decisions/ADR-*.md (for numbering and dedup) Writes: docs/decisions/ADR-{NNN}-{slug}.md (proposed), backlog frontmatter adr_refs

During /design (AC-2, AC-7)

Creates accepted ADRs and updates C4 diagrams:

ADR Behavior:

1. Load existing ADRs via common pattern (especially any proposed ADRs from /define)
2. For each significant technical decision during design: a. Apply ADR Creation Threshold b. If a proposed ADR exists for this decision: Complete the Decision section, update status: accepted c. If no ADR exists: Create new docs/decisions/ADR-{NNN}-{slug}.md with status: accepted d. If design supersedes an existing decision: Create new ADR, update old ADR with status: superseded and superseded_by
3. Add adr_refs to the design document and backlog item frontmatter

C4 Diagram Behavior:

1. Load existing diagrams via common pattern
2. If design changes structural boundaries (new containers, new components, changed relationships): a. Update the affected diagram file(s) b. Update flowchart arrows (-->) to reflect new dependencies c. Update ## Coupling Notes section d. Update frontmatter: updated date, updated_by: "/design", backlog_ref
3. If no structural changes: Leave diagrams unchanged

Reads: docs/decisions/ADR-*.md, docs/architecture/**/*.md Writes: docs/decisions/ADR-{NNN}-{slug}.md, docs/architecture/**/*.md frontmatter and body

During /deliver (AC-4)

Reads ADRs for implementation context — does NOT create or modify them:

1. Load ADRs via common pattern (from design adr_refs or domain scan)
2. Surface relevant decisions that constrain implementation:
   • Technology choices (e.g., "ADR-001 specifies JWT refresh tokens, not sessions")
   • Boundary constraints (e.g., "ADR-003 requires auth to stay in its own service")
3. Reference ADR ids in implementation notes when decisions guide choices
4. If an implementation approach would violate an accepted ADR: Warn prominently
5. Transition guidance (conditional): a. If adr_refs exist in backlog item frontmatter:

   ADR compliance: This work references {N} architecture decision(s). Ensure the approach aligns with each accepted decision. Violations will be flagged during /discern review.

Reads: docs/decisions/ADR-*.md, docs/architecture/components/{domain}.md Writes: Nothing (read-only for architecture artifacts)

During /discern (AC-4)

Verifies ADR compliance and checks for boundary violations:

1. Load ADRs via common pattern
2. Add ADR Compliance to the review checklist:
   • For each referenced ADR: Does the implementation follow the decision?
   • Flag any violations (implementation contradicts accepted ADR)
3. Load component diagram for the domain (if exists)
4. Check for boundary violations: Does the implementation introduce dependencies not documented in the diagram?
5. Output ADR Compliance table:

| ADR | Decision | Compliant? | Notes |
|-----|----------|------------|-------|
| ADR-001 | JWT refresh tokens | YES | Implemented as specified |
| ADR-003 | Auth service boundary | VIOLATION | Direct DB access bypasses service |

Reads: docs/decisions/ADR-*.md, docs/architecture/components/{domain}.md Writes: Nothing (compliance output goes in the review document, not in ADRs)

During /diagnose (AC-8)

Primary consumer of architecture artifacts for health analysis:

Coupling Analysis:

1. Load container diagram (docs/architecture/containers.md) and component diagrams
2. Parse flowchart arrows (-->) from Mermaid diagrams to build declared dependency graph
3. Scan source code for actual import/dependency patterns (heuristic: directory + import scanning)
4. Compare: Flag undocumented dependencies (code imports not in diagram) and stale dependencies (diagram arrows with no code evidence)

Cohesion Analysis:

1. Load component diagrams for each domain
2. Check whether components import mostly within their domain (high cohesion) or heavily across domains
3. Compare against ## Cohesion Assessment ratings — flag mismatches

ADR Health:

1. Scan all ADRs in docs/decisions/
2. Flag: proposed ADRs with no recent /design activity, contradictory accepted ADRs, superseded ADRs still referenced by active code

Diagram Staleness:

1. Check updated field in each diagram's frontmatter
2. Flag diagrams not updated within 90 days as potentially stale

Reads: docs/decisions/ADR-*.md, docs/architecture/**/*.md, source code imports Writes: Nothing (findings go in the diagnose report)

During /spec:init (AC-6)

Generates initial C4 diagrams from discovered domains:

1. After domain discovery and spec creation, generate C4 diagrams: a. Level 1 — docs/architecture/system-context.md: System and discovered external actors b. Level 2 — docs/architecture/containers.md: High-level containers inferred from project structure c. Level 3 directory — mkdir docs/architecture/components/ (files created later by /design)
2. Set frontmatter: updated_by: "/spec:init", current date
3. Include ## Coupling Notes with initial observations from project structure
4. These are initial diagrams — /design refines them as architecture evolves

Reads: Project structure, discovered domains Writes: docs/architecture/system-context.md, docs/architecture/containers.md, docs/architecture/components/ directory

During /arch:init

Bootstraps architecture artifacts for existing projects:

1. Pre-check for existing architecture artifacts (ADR-000, L1, L2, components/)
2. Read project structure and docs/specs/{domain}/ for domain awareness
3. Create ADR-000 bootstrapping record if missing
4. Generate Level 1 (System Context) and Level 2 (Container) diagrams with user confirmation
5. Create docs/architecture/components/ directory
6. Does NOT touch specs — reads domain structure only

Reads: CLAUDE.md, README.md, source directories, config files, docs/specs/{domain}/ (directory names only) Writes: docs/decisions/ADR-000-*.md, docs/architecture/system-context.md, docs/architecture/containers.md, docs/architecture/components/ directory

During /discover

Surfaces existing ADRs as context for exploration:

1. Scan docs/decisions/ADR-*.md for ADRs related to the discovery topic
2. Include relevant ADR summaries in the Architecture Context section of output
3. Note: Does not create or modify ADRs

Reads: docs/decisions/ADR-*.md Writes: Nothing (read-only)

During /handoff

Injects ADR-specific transition guidance into handoff output:

1. Load ADRs via common pattern
2. If ADRs found relevant to the work: a. For design → deliver handoff:

   ADR context for Crafter: {N} architecture decision(s) constrain this work: {list ADR ids + 1-line summaries}. Implementation must align with these decisions. b. For deliver → discern handoff: ADR context for Critic: {If adr_refs exist: "Verify ADR compliance for: {list ADR ids}. Check for boundary violations."}

3. If no ADRs: Silently continue (no guidance injected)

Reads: docs/decisions/ADR-*.md Writes: Nothing (read-only — guidance injection only)

During /context:load (AC-9)

Reports architecture artifact status:

1. Scan docs/decisions/ADR-*.md — count by status (proposed, accepted, deprecated, superseded)
2. Scan docs/architecture/**/*.md — check updated dates against 90-day threshold
3. Report in Architecture section of output:
   • ADR count by status
   • Diagram staleness warnings
   • Recommendations: "No ADRs found — consider creating ADR-000 via /design"

Reads: docs/decisions/ADR-*.md, docs/architecture/**/*.md Writes: Nothing (read-only)

During /context:refresh (AC-9)

Detects drift between diagrams and code structure:

1. Load C4 diagrams
2. Compare diagram containers/components against actual project structure
3. Flag drift: new directories/services not in diagrams, diagram elements with no code evidence
4. Report in Diagram Drift section of output:
   • Containers/components in diagram but not in code
   • Code structures not reflected in diagrams
   • Recommended updates

Reads: docs/architecture/**/*.md, project directory structure Writes: Nothing (read-only — drift is reported, humans and /design fix it)

Architecture Update Rules (All Commands)

These rules apply to ALL commands that interact with architecture artifacts:

1. Warn, never block — Missing ADRs or diagrams are warnings, not workflow blockers
2. ADR threshold is strict — Only create ADRs when both conditions are met (multiple alternatives AND hard to reverse or cross-domain)
3. Diagrams are updated by /design only — Other commands read diagrams but do not modify them. /spec:init and /arch:init create initial diagrams.
4. ADR statuses are managed by /define and /design only — /define creates proposed, /design creates accepted or changes status
5. Domain is a human decision — Same as specs. Never auto-assign domains for component diagrams
6. Drift is detected, not prevented — /context:refresh and /diagnose report drift. Humans and /design update diagrams
7. ADRs explain boundaries — When /diagnose detects coupling violations, reference the ADR that established that boundary

What This Skill Does NOT Do

• Does NOT block any workflow — only warns and informs
• Does NOT auto-generate ADRs for every design decision — strict threshold applies
• Does NOT auto-sync diagrams with code — drift is detected, not prevented
• Does NOT support C4 Level 4 (Code) — source code is the code-level diagram
• Does NOT put ADRs inside specs — different lifecycle, different purpose
• Does NOT auto-detect domains for component diagrams — domain is a human decision
• Does NOT validate Mermaid syntax — rendering issues are warnings, not blockers