shadowx4fox/architecture-docs

Architecture Documentation Skill

This skill provides comprehensive guidelines for creating and maintaining ARCHITECTURE.md files using the standardized template from ARCHITECTURE_DOCUMENTATION_GUIDE.md. It enforces consistency across all documentation sections through the Foundational Context Anchor Protocol — a dependency-aware editing workflow that loads required upstream context before any downstream section edit, requires source attribution for derived claims, and detects downstream impact when any section changes.

CRITICAL: Section Number vs File Prefix Disambiguation

Internal section numbers (S1-S13) and file prefix numbers (01-11) are independent and do NOT align.

| Internal Section | Name | File | |---|---|---| | S1+S2 | Executive Summary + System Overview | docs/01-system-overview.md | | S3 | Architecture Principles | docs/02-architecture-principles.md | | S4 | Architecture Layers | docs/03-architecture-layers.md | | S5 | Component Details | docs/components/ | | S6 | Data Flow Patterns | docs/04-data-flow-patterns.md | | S7 | Integration Points | docs/05-integration-points.md | | S8 | Technology Stack | docs/06-technology-stack.md | | S9 | Security Architecture | docs/07-security-architecture.md | | S10 | Scalability & Performance | docs/08-scalability-and-performance.md | | S11 | Operational Considerations | docs/09-operational-considerations.md | | S12 | ADRs | adr/ directory | | S13 | Risks and Technical Debt | docs/10-risks-and-technical-debt.md |

Rules:

• When a user says "update Section 9" → resolve to S9 = docs/07-security-architecture.md, NOT docs/09-*
• docs/09-operational-considerations.md = S11, not Section 9
• Always use S-prefix (S1-S13) to identify sections, file paths to identify files
• NEVER assume file prefix NN equals section number N
• Legacy layouts (created before S13 existed) place References at docs/10-references.md with no docs/10-risks-and-technical-debt.md. Any workflow operating on an existing multi-file project MUST run Workflow 11 (Layout Migration Gate) as a preflight before proceeding.

When This Skill is Invoked

Automatically activate when:

• User asks to create architecture documentation
• User asks to update or edit ARCHITECTURE.md
• User mentions documenting system architecture
• User requests architecture review, audit, or analysis (triggers Design Drivers calculation prompt)
• User explicitly asks to "calculate design drivers" or "update design drivers"
• User asks about architecture documentation structure or best practices
• User edits Section 1 Executive Summary Key Metrics (triggers metric consistency check)
• User edits any downstream section (S4–S11) → triggers Context Anchor load
• User requests metric consistency check, verify metrics, or audit metrics
• User asks informational questions about the documented architecture (if ARCHITECTURE.md exists)
  • "What is our [authentication/scaling/data flow/etc.] approach?"
  • "How does [component/system/integration] work?"
  • "What technologies do we use for [purpose]?"
  • "Tell me about the architecture of [system]"
• User asks to generate, create, add, or update diagrams in architecture documentation (triggers Workflow 8)
  • "Generate my architecture diagrams"
  • "Create Mermaid diagrams from ARCHITECTURE.md"
  • "Add diagrams to my architecture"
  • "Update my architecture diagrams"
  • "Refresh / regenerate diagrams to reflect recent changes"
• User asks to release, freeze, or tag an architecture version (triggers Workflow 10)
  • "Release architecture version"
  • "Bump architecture to v1.2.0"
  • "Freeze architecture baseline"
  • "Tag architecture version"

Version Drift Detection (informational, every invocation)

On any invocation of this skill, if ARCHITECTURE.md contains a <!-- ARCHITECTURE_VERSION: --> comment AND the project is under git:

1. Read the doc version from the comment
2. Run git tag -l 'architecture-v*' --sort=-version:refname | head -1 to get the latest architecture-v* tag
3. If doc version > latest tag: emit ℹ️ Architecture v{doc} is not tagged in git. Run Workflow 10 (Release Architecture Version) to publish a tag.
4. If doc version < latest tag: emit ⚠️ Architecture tag architecture-v{tag} exists in git but the doc shows v{doc}. Possible regression — verify before committing.
5. If doc version == latest tag: silent (no message)

Drift detection is informational only — it does not block other workflows. See RELEASE_WORKFLOW.md → "Drift Detection" for full details.

Query Pattern Triggers

This skill automatically activates when users ask questions about documented architecture, including:

Reference Patterns:

• "According to my architecture documentation..."
• "Based on the architecture..."
• "What does the architecture use/require/implement for..."
• "My architecture documentation shows/says..."
• "The architecture specifies/defines..."
• "Check/Validate/Verify the architecture [aspect]..."
• "Audit the [architecture component/pattern]..."

Technical Query Keywords:

• Components: "components", "services", "modules", "microservices", "systems"
• Data: "data structures", "data flow", "database", "schema", "models", "entities"
• Integration: "APIs", "integrations", "external systems", "endpoints", "interfaces"
• Security: "authentication", "authorization", "encryption", "security", "compliance"
• Performance: "scaling", "performance", "SLA", "capacity", "throughput", "latency"
• Deployment: "deployment", "cloud provider", "infrastructure", "environments", "regions"
• Technology: "tech stack", "languages", "frameworks", "tools", "libraries", "versions"
• Decisions: "why choose", "decision", "trade-offs", "alternatives", "ADR", "rationale"
• Validation: "check", "validate", "verify", "audit", "alignment", "BIAN", "META", "service domain", "layer", "standards", "compliance check"

Multi-section Queries:

• Questions requiring synthesis across multiple sections
• Cross-cutting concerns (e.g., "How does authentication work with external systems?")
• Implementation details spanning components, data, and deployment

Do NOT activate for (redirect to the correct skill):

• Requirements deviation checks, requirements traceability, or PO Spec coverage analysis → use architecture-traceability skill
• Component migration to C4, component index sync, add/remove/update components → use architecture-component-guardian skill
• Peer review or architecture quality assessment → use architecture-peer-review skill
• Compliance contract generation → use architecture-compliance skill

Component Operations Delegation Rule: All structural operations on docs/components/ MUST delegate to architecture-component-guardian:

• Creating, renaming, or deleting component files → delegate to guardian
• Creating or updating docs/components/README.md → delegate to guardian (sync action)
• Migrating flat components to C4 multi-system structure → delegate to guardian (migrate action)
• Adding C4 metadata (Type, C4 Level, system folders) → delegate to guardian This skill may read component files for context (editing sections, propagation checks) but must NOT directly create, restructure, or modify the component index.

---

🎯 AUTOMATIC WORKFLOW DETECTION

IMPORTANT: Immediately upon skill invocation, analyze the user's request to detect their intent.

Detection Logic

Check the user's original message (before /architecture-docs was invoked) for these patterns:

Workflow 8: Diagram Generation

Triggers:

• Keywords: "generate", "create", "add", "update", "make" + "diagram", "diagrams", "Mermaid diagram", "architecture diagram"
• Examples: "generate my architecture diagrams", "create diagrams from ARCHITECTURE.md", "add diagrams to my architecture"
• Section-specific: "generate diagrams for Section 4", "create data flow diagrams"
• Format mentions: "Mermaid diagrams", "visual diagrams", "architecture diagrams"
• Reconciliation: "reconcile diagrams", "move diagrams", "consolidate diagrams"
• Audit/coverage: "check diagram coverage", "audit diagrams", "diagram completeness", "diagram audit"
• Placement: "diagrams in wrong location", "fix diagram placement", "diagram location"
• External intake: user provides external file path and mentions diagrams

Action when detected:

1. Confirm: "I'll help you generate architecture diagrams."
2. Jump directly to Workflow 8, Step 1 (Diagram Type Selection)
3. Do NOT ask which workflow - proceed automatically

Scope clarification: Workflow 8 is for regenerating, updating, or auditing diagrams on an existing ARCHITECTURE.md. It is NOT how new architectures get their first diagrams — Workflow 1 (initial creation) auto-runs diagram generation as Step 7 (Mandatory Diagram Generation) and will not complete until the BLOCKING DIAGRAMS_GATE in Step 7.3 passes. If the user is creating a new architecture, route to Workflow 1, not Workflow 8.

Workflow 9: Migrate to docs/ Structure

Triggers:

• Keywords: "migrate", "restructure", "split", "reorganize", "convert" + "architecture", "ARCHITECTURE.md"
• Size complaints: "too large", "too long", "hard to navigate", "split into files"
• Explicit: "migrate my architecture to the new structure", "convert to docs/ layout"

Action when detected:

1. Confirm: "I'll help you migrate ARCHITECTURE.md to the multi-file docs/ structure."
2. Jump directly to Workflow 9, Step 1
3. Do NOT ask which workflow - proceed automatically

Workflow 10: Release Architecture Version

Triggers:

• Keywords: "release architecture", "release architecture version", "bump architecture version", "freeze architecture", "tag architecture version"
• Lifecycle: "publish architecture", "ship architecture", "finalize architecture", "architecture release"
• Semver: "bump architecture to major/minor/patch", "architecture v1.1.0"

Action when detected:

1. Confirm: "I'll run the Release Architecture Version workflow."
2. Read RELEASE_WORKFLOW.md for the full procedure
3. Jump directly to Workflow 10, Step 1 (Read Current Version)
4. Do NOT ask which workflow — proceed automatically

Other Workflows

If the user's request matches other documented workflows (1-10), follow their respective trigger patterns.

Note: Workflow 1 (new ARCHITECTURE.md creation) starts at Step 0 (PO Spec prerequisite check), then Step 0.3 (Enterprise Alignment Gate — MANDATORY, no skip) verifies ENTERPRISE_ALIGNMENT.md exists at the project root and blocks otherwise (directing the user to /sa-skills:architecture-enterprise-alignment; cascading-skip when PO Spec was skipped), then Step 0.5 (ADR pre-identification) establishes the ADR Context Block — a list of ADR candidates derived from PO Spec analysis that is maintained through all creation steps for decision consistency. Workflow 1 always concludes with Step 7 (Mandatory Diagram Generation), which produces the 4 standard diagrams (Logical View ASCII, C4 L1, C4 L2, Detailed View) into docs/03-architecture-layers.md and a mode-aware set of sequence diagrams into docs/04-data-flow-patterns.md: in Phase Catalog mode (default — see ARCHITECTURE_DOCUMENTATION_GUIDE.md → Section 6 → "Mode selection") one sequenceDiagram per phase H4 in ## Phase Catalog plus one full wire sequence per UC in ## End-to-End Wire Sequences; in Single-Flow mode (legacy fallback) one sequenceDiagram per ### [Flow Name] Flow H3. Step 7.3 is a BLOCKING audit gate (DIAGRAMS_GATE) — Workflow 1 does NOT print ✅ Architecture creation complete until every mandatory diagram is verified present and Pre-Write-Validation-clean. There is no SKIP DIAGRAMS override. See ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md for the full flow and examples/04-data-flow-patterns.example.md for a Phase Catalog mode reference.

If No Pattern Matches

If the user's request doesn't match any workflow triggers:

1. Acknowledge the skill invocation
2. Ask which workflow they want to use
3. Provide brief description of available workflows

---

Lazy-Load Contract — Workflow-Gated Reference Guides

This skill ships with several large reference guides that are loaded only when the matching workflow fires, never speculatively. Each guide is 350–2,000 lines; loading one outside its trigger consumes Opus context unnecessarily and invalidates downstream prompt-cache prefixes when the user later switches workflows.

| Guide | Size (lines) | Triggering workflow / signal | |---|---|---| | ARCHITECTURE_DOCUMENTATION_GUIDE.md | ~2,009 | Workflow 1 (new ARCHITECTURE.md), section editing requiring template structure | | ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md | ~1,200 | Workflow 1 Step 0 (PO Spec gate) + Step 0.3 (Enterprise Alignment gate, MANDATORY) + type selection | | MERMAID_DIAGRAMS_GUIDE.md | ~1,024 | Workflow 8 (diagram generation) | | references/DIAGRAM-GENERATION-GUIDE.md | ~743 | Workflow 8 (diagram generation) | | RELEASE_WORKFLOW.md | ~687 | Workflow 10 (release) — also for the drift-detection text deep-dive | | QUERY_SECTION_MAPPING.md | ~650 | Workflow 7 (informational query) when section mapping is needed | | DESIGN_DRIVER_CALCULATIONS.md | ~593 | "calculate / update design drivers", "architecture review" Design Drivers branch | | PRINCIPLE_VALIDATION.md | ~474 | Section 3 Enforcement Gate — every write to docs/02-architecture-principles.md | | METRIC_CALCULATIONS.md | ~350 | Section 1 Key Metrics edits, "verify metrics", "audit metrics" | | RESTRUCTURING_GUIDE.md | ~146 | Workflow 9 (multi-file migration) | | references/{TYPE}-ARCHITECTURE.md + {TYPE}-TO-C4-TRANSLATION.md | ~400–1,000 each | Workflow 1 type selection (load only the chosen type's pair) |

Rules:

• Do NOT pre-load any of the guides above "to be ready" — wait for the trigger.
• When a workflow fires, load only its row's guide(s); do not chain into other workflows' guides.
• For type-specific references (MICROSERVICES, BIAN, META, 3-TIER, N-LAYER), load only the pair that matches the architecture's <!-- ARCHITECTURE_TYPE: --> value — never load all five.
• Workflow detection (the AUTOMATIC WORKFLOW DETECTION section above) is what selects the trigger; once selected, no other workflow's guides are loaded.
• The Section 3 Enforcement Gate's PRINCIPLE_VALIDATION.md is the only large guide loaded mid-edit (Layer 1); the Layer 2 sub-agent loads the foundational architecture files separately and is invoked via the Agent tool, so its reads do not pollute the orchestrator's context.

This contract is what keeps the orchestrator's main-session context narrow enough that SKILL.md + the active workflow's guides fit in cache; speculative pre-loads would burst the working set and force prefix re-evaluation on every tool call.

---

File Naming Convention

IMPORTANT: All architecture documentation uses the multi-file docs/ structure.

• ARCHITECTURE.md at the project root is the navigation index only (~130 lines)
• All section content lives under docs/ as numbered Markdown files
• Component details (Section 5) live under docs/components/ — one file per component

File naming pattern: NN-kebab-case-name.md — lowercase, hyphens only, no spaces, no uppercase, no underscores.

• Section files: docs/01-system-overview.md, docs/06-technology-stack.md
• Component files: docs/components/01-api-gateway.md, docs/components/02-payment-service.md

See RESTRUCTURING_GUIDE.md for the full directory structure and naming conventions.

Location

• ARCHITECTURE.md — always at the project root
• docs/ — always at the project root (sibling to ARCHITECTURE.md)
• docs/components/ — inside docs/
• For multi-project repositories, each project subdirectory gets its own ARCHITECTURE.md + docs/

---

Working with Architecture Documentation — Context Optimization

IMPORTANT: The multi-file structure makes context loading simple — individual docs/ files are 50–400 lines each (full file fits in context). No line-offset tricks needed.

Context-Efficient Workflow

1. Find the target section

   • Read ARCHITECTURE.md navigation table to identify which docs/NN-name.md file contains the target section
   • Example: "Edit security architecture" → navigate to docs/07-security-architecture.md

2. Load Context Anchor (REQUIRED for downstream sections)

   • Section 3 Enforcement Gate (BLOCKING — runs on every write to docs/02-architecture-principles.md):
     1. Layer 1 — Prescriptive checklist. Read skills/architecture-docs/PRINCIPLE_VALIDATION.md and execute every rule in order. Each rule's report MUST quote its grep output verbatim — a finding without quoted output is treated as FAIL (anti-self-attestation). Emit the PRINCIPLE_VALIDATION_REPORT block at the end. If any BLOCKING finding, regenerate docs/02-architecture-principles.md per the recommendations and re-run from rule 1. Increment round counter.
     2. Layer 2 — Semantic review. Invoke agents/reviewers/principle-quality-reviewer.md with the appropriate mode (first-write for new docs; edit-delta for edits). Pass principles_file, arch_type (read from <!-- ARCHITECTURE_TYPE: --> in docs/03-architecture-layers.md), system_overview_file, arch_layers_file, tech_stack_file, adr_index_glob, round. If status: FAIL with BLOCKING findings, regenerate per recommendations and re-run from Layer 1.
     3. Round-3 escalation. After 3 failed rounds across both layers (counted together), STOP. Show the user all 3 rounds' reports side by side and ask: "Three revision rounds have not produced a passing principles document. Pick: (a) edit further manually, (b) accept the current version with the listed findings (explicit override), or (c) abort the workflow." Do NOT silently accept.
     4. Fail-open clauses:
        • If Layer 2 sub-agent returns empty / errors / times out: treat as PASS-with-warning ("manual review required"). Do not block forever on tool failure.
        • If Layer 1 grep tools are unavailable (grep: command not found): treat as fail-closed → escalate immediately. The user fixes the environment or overrides.
   • SKIP the Context Anchor load below when editing docs/01-system-overview.md only, or for typo/formatting-only fixes
   • For edits to docs/02-architecture-principles.md: load docs/01-system-overview.md, docs/03-architecture-layers.md, docs/06-technology-stack.md, and the ADR index BEFORE editing — the Section 3 Enforcement Gate above runs after the edit
   • REQUIRED when editing any file from docs/03-architecture-layers.md through docs/09-operational-considerations.md, or any docs/components/*.md file
   • Universal Foundation: Always load docs/01-system-overview.md + docs/02-architecture-principles.md
   • Relevant ADRs: Match ADR titles from ARCHITECTURE.md navigation table against target section keywords; load matched ADRs
   • Section-Specific Parents: Load parent sections per the Foundational Context Anchor Protocol dependency table (see below)
   • Example for S9 (Security): load S1+2 (foundation) + S5/README (components) + S7 (integrations) + S8 (tech stack) + relevant ADRs
   • Context budget: 250–850 lines depending on section tier

3. Read the entire target file

   • Individual docs/ files are small enough to read in full
   • Read(file_path="docs/07-security-architecture.md") — no offset/limit needed

4. Edit the target file directly

   • Use the Edit tool on the specific docs/NN-name.md file
   • Do NOT edit ARCHITECTURE.md unless you are adding a new section/file to the navigation table
   • Source Attribution (during editing): When writing derived content in downstream sections, insert cross-reference links to the source:
     • Metrics: When repeating a metric from S1 Key Metrics → (see [Key Metrics](01-system-overview.md#key-metrics))
     • ADR decisions: When content implements an ADR → per [ADR-NNN](../adr/ADR-NNN-title.md)
     • Principles: When invoking an S3 principle → per [Principle Name](02-architecture-principles.md#anchor)
     • Parent section references: When referencing components, layers, integrations, or tech → link to the specific file
     • Unverifiable claims: If a specific claim (metric, decision, constraint) cannot be traced to an existing section, user input, or ADR → insert <!-- TODO: Add source reference --> marker

5. Post-Write Alignment & Traceability Audit

   • Check A — Principle traceability: Written content does not contradict Section 3 principles
   • Check B — Metric consistency: Numeric values match Section 1 Key Metrics
   • Check C — ADR alignment: Content does not contradict loaded ADR decisions
   • Check D — Parent section alignment: Content references valid components (S5), integrations (S7), tech (S8) as loaded
   • Check E — Source citation audit: Scan the written content for:
     • Numeric values (TPS, latency, SLO, %) → must link to S1 Key Metrics or be marked as section-local
     • Technology names matching S8 → should link to tech stack or governing ADR
     • Architecture pattern references → should link to S3 or S4
     • <!-- TODO: Add source reference --> markers → count and report
   • Silent pass if no issues found; display alignment report only when misalignment or missing citations are detected

5.5. Downstream Documentation Propagation

Runs immediately after the Post-Write Alignment Audit passes. Detects downstream files whose content may be stale due to the edit and offers to update them.

Trigger Gate

Run when: The edit changed substantive content — metrics, technology names, component names, architectural patterns, constraints, requirements, or interface definitions.

Skip silently when: The edit was cosmetic — typo fixes, formatting, grammar, markdown structure, comment updates, <!-- TODO --> markers, or source attribution links. Heuristic: if the diff contains only whitespace/punctuation/link/formatting changes with no word-level changes to technical terms, skip entirely.

Anti-recursion rule: Propagation updates (Phase 3 edits) do NOT re-trigger Step 5.5.

Reverse Dependency Table

| Edited Section | File | Downstream Section Files | |---|---|---| | S1+S2 (System Overview) | docs/01-system-overview.md | ALL sections (S4–S11) + docs/components/* | | S3 (Principles) | docs/02-architecture-principles.md | ALL sections (S4–S11) + docs/components/* | | S4 (Layers) | docs/03-architecture-layers.md | S5 (docs/components/*), S8 (docs/06-technology-stack.md) | | S5 (Components) | docs/components/*.md | S6 (docs/04-data-flow-patterns.md), S7 (docs/05-integration-points.md), S8 (docs/06-technology-stack.md), S9 (docs/07-security-architecture.md), S10 (docs/08-scalability-and-performance.md), S11 (docs/09-operational-considerations.md), Refs (docs/11-references.md), + S3 semantic re-check (Phase 1.5 — invoke principle-quality-reviewer in mode: downstream-impact with downstream_file = docs/02-architecture-principles.md; flag any principle whose Implementation/Trade-offs the new component contradicts) | | S6 (Data Flow) | docs/04-data-flow-patterns.md | (leaf — no downstream sections) | | S7 (Integration) | docs/05-integration-points.md | S9 (docs/07-security-architecture.md) | | S8 (Tech Stack) | docs/06-technology-stack.md | S9 (docs/07-security-architecture.md), S10 (docs/08-scalability-and-performance.md), S11 (docs/09-operational-considerations.md), Refs (docs/11-references.md) | | S9 (Security) | docs/07-security-architecture.md | (leaf) | | S10 (Scalability) | docs/08-scalability-and-performance.md | S11 (docs/09-operational-considerations.md) | | S11 (Operations) | docs/09-operational-considerations.md | (leaf) | | S12 (ADRs) | ARCHITECTURE.md (navigation table) | adr/ directory → delegate to /skill architecture-definition-record, Refs (docs/11-references.md) | | S13 (Risks & Technical Debt) | docs/10-risks-and-technical-debt.md | (leaf — full TDRs live at /tdr/ and are managed by the technical-debt-records skill) |

Cross-cutting (always scanned regardless of table): docs/components/, handoffs/, docs/11-references.md

References file (docs/11-references.md) propagation

docs/11-references.md is a cross-cutting file that aggregates links from multiple sections. It MUST be included in the downstream scan when any of these change:

| Change Type | What to update in 10-references.md | |---|---| | ADR added, removed, renamed, or status changed (adr/*.md) | ADR index table — add/remove/rename row, update status | | New technology in S5 components or S8 tech stack | Technology documentation links — add official doc URL | | Technology removed or replaced | Technology documentation links — remove or replace entry | | New glossary-worthy term introduced in any section | Glossary — add definition |

When 10-references.md is flagged for update during Phase 2 (Generate Checklist), present specific sub-items showing which table(s) need updating (ADR index, technology links, glossary).

S12 ADR Table Propagation (Special Rule)

When the edited file is ARCHITECTURE.md and the edit added or modified rows in the Section 12 ADR table:

1. Detect new ADR rows: Compare the ADR table before and after the edit. Extract any new rows matching | [ADR-NNN](...) | ... |
2. Check for existing files: For each new ADR row, check if adr/ADR-NNN-slug.md already exists
3. Delegate creation: For ADR rows where the file does NOT exist, invoke /skill architecture-definition-record with context:
   • Trigger reason: "Section 12 ADR table updated — generate ADR files for new entries"
   • Pass the ADR metadata (number, title, status, date, impact) from the table row
   • The architecture-definition-record skill runs Workflow 1 Steps 1.3–1.5 (extract → load template → generate)
4. Skip if file exists: If the ADR file already exists, do not overwrite — report: adr/ADR-NNN-slug.md already exists — skipped

After ADR file creation (or skip), always update docs/11-references.md:

• Add new ADRs to the ADR index table
• Update ADR titles or status if changed
• Remove entries for deleted ADRs

This rule runs instead of the standard Phase 1–3 propagation for S12 changes. ADR table changes do not trigger downstream section updates — they trigger ADR file creation and references update.

Phase 1: Impact Discovery

1a. Fact-delta extraction — Compare the file content before and after the edit. Produce a concrete bullet list of what changed (e.g., "Database: PostgreSQL → CockroachDB", "Added: Redis caching layer", "Removed: legacy SOAP endpoint"). If zero substantive deltas → skip propagation entirely.

1b. Structural dependency scan — Look up the edited section in the reverse dependency table above. Collect all downstream section files.

1c. Cross-reference scan — Grep across docs/, docs/components/, handoffs/ for explicit references to the edited filename (links, section anchors, (see [...](...))).

grep -rl "{edited_filename}" docs/ docs/components/ handoffs/ 2>/dev/null

1d. Handoff scan — For each fact-delta keyword (component names, technology names, pattern names), grep handoffs/ for matching terms.

1e. Merge and deduplicate — Combine results from 1b+1c+1d. Remove duplicates and remove the edited file itself.

Phase 1.5: Principle Alignment Audit (S3 edits only)

Runs only when the edited file is docs/02-architecture-principles.md AND Phase 1a's fact-delta extraction reported substantive word-level changes in any of {Description, Implementation, Trade-offs} subsections.

Trigger gate — skip Phase 1.5 silently when:

• The diff contains only whitespace, punctuation, link reformatting, or markdown structure changes (no word-level changes inside D/I/T blocks).
• The Section 3 Enforcement Gate above failed and the principles file was regenerated wholesale (the regenerated file is treated as a first-write, not an edit, and the orchestrator already re-ran the gate).
• Phase 1a's diff is empty (no substantive changes detected).

Audit procedure when the gate fires:

1. Extract per-principle deltas from the diff. For each principle that changed, capture:

   • principleNumber, principleName
   • Which subsection(s) changed (Description / Implementation / Trade-offs)
   • A 1-line summary of the change (what was added, removed, or rephrased)
   • Token set for pruning — derived from the raw added/removed lines of the changed subsections (not from the 1-line summary). Build a single de-duplicated set containing:
     • Principle names — the principleName of every changed principle.
     • ADR IDs — every ADR-NNN token (regex ADR-\d{3}) that appears in either the before-text or the after-text of changed Description / Implementation / Trade-offs subsections.
     • Affected tech tokens — every named tech term that appears on an added or removed diff line AND is enumerated in docs/06-technology-stack.md (i.e., a tech this system actually uses). Intersecting with the tech stack avoids matching English words that happen to be tech-name-shaped. Compare case-insensitive on whole-token boundaries.

   This token set powers the pruning step below; if the set ends up empty (e.g., the diff only rephrased Description prose with no concrete principle names, ADR IDs, or system-tech tokens) the fall-back is conservative — fan out to all candidates without pruning.

2. Pre-fan-out pruning — Token-grep each candidate downstream file against the token set from step 1 to drop files with zero references to anything that changed. The reviewer is Opus and the median S3 edit touches one principle's Implementation, so most downstream files don't even mention the changed content. Skipping them on the basis of a cheap structural grep avoids spending Opus on guaranteed NO_IMPACT verdicts.

   Candidate set = the reverse dependency files for S3 (S4–S11 + every docs/components/**/*.md listed in docs/components/README.md).

   Pruning rule (per candidate file):

   • If the token set from step 1 is empty → KEEP the file (conservative: nothing concrete to grep against; fall through to fan-out).
   • Else, run a single composite case-insensitive grep over the file using a regex alternation of every token in the set (escape regex metacharacters in principle names; whole-line match is fine — we only need a hit/no-hit signal). Examples:

     grep -liE 'Principle Name 1|Principle Name 4|ADR-005|ADR-012|Spring Boot|PostgreSQL|Redis' \
       docs/03-architecture-layers.md docs/04-data-flow-patterns.md \
       docs/05-integration-points.md docs/06-technology-stack.md \
       docs/07-security-architecture.md docs/08-scalability-and-performance.md \
       docs/09-operational-considerations.md docs/components/*.md
     

   • File path emitted by grep → KEEP for the fan-out in step 3.
   • File NOT emitted → SKIP. Record one Phase 2 note for the user:

     ℹ️  {file} — no token references to changed principles, cited ADRs, or affected tech; semantic review skipped (Phase 1.5 pruning).
     

   Empty kept-set after pruning — when zero candidate files token-match (and the token set was non-empty, so the prune was real), emit one consolidated Phase 2 note ("Principle Alignment Audit: no downstream files reference any of the changed principles, cited ADRs, or affected tech — nothing to review.") and skip steps 3–6 of this Audit procedure. Phase 2 still runs with the structural impact list from Phase 1b–1d.

   Fail-open — if grep is unavailable or returns an unexpected error, emit a one-line Phase 2 warning ("Phase 1.5 pruning unavailable; fanned out to the full candidate set") and fall through to step 3 with all candidates kept. Pruning is an optimization, not a gate.

   Why this is recall-safe — the token set includes principle names AND cited ADR IDs AND affected tech, all three. Most "implicit contradiction" cases (a downstream file paraphrases a principle without naming it) still surface because the file usually mentions either the cited ADR or the affected tech. The conservative empty-set fallback covers the long tail (pure prose changes with no concrete tokens).

3. Fan out to principle-quality-reviewer in mode: downstream-impact. The orchestrator MUST construct the sub-agent prompt using the stable-prefix → dynamic-suffix template below so parallel calls in the same batch share the maximum cacheable prefix (Anthropic prompt cache hits on byte-identical prefixes within the 5-min TTL).

   Read-once foundational context. Before dispatching any sub-agent in this fan-out, read the four foundational files once in the orchestrator's session and capture their content. The five blocks below are byte-identical across every sub-agent call in the fan-out, so inlining them lets calls 2..N hit the prompt cache for the entire prefix instead of each agent re-Reading the same files independently:

   • docs/02-architecture-principles.md (post-edit) → <principles> block
   • docs/01-system-overview.md → <system_overview> block
   • docs/03-architecture-layers.md → <arch_layers> block
   • docs/06-technology-stack.md → <tech_stack> block
   • Glob('adr/*.md') ID list (one ADR-NNN per line, sorted) → <adr_index> block (the IDs alone — bodies are not needed for existence checks)

   Prompt template — positional, order must not change. Lines above the marker are stable across the batch; only downstream_file (last line) differs per call:

   mode: downstream-impact
   round: <int>
   arch_type: <MICROSERVICES|META|BIAN|3-TIER|N-LAYER|unknown>
   principles_file: docs/02-architecture-principles.md
   principles_diff: |
     <per-principle deltas from step 1, identical for every call in this batch>
   
   <principles>
   {full content of docs/02-architecture-principles.md (post-edit)}
   </principles>
   
   <system_overview>
   {full content of docs/01-system-overview.md}
   </system_overview>
   
   <arch_layers>
   {full content of docs/03-architecture-layers.md}
   </arch_layers>
   
   <tech_stack>
   {full content of docs/06-technology-stack.md}
   </tech_stack>
   
   <adr_index>
   {one ADR-NNN id per line, sorted}
   </adr_index>
   
   # === Stable prefix ends here. Only the line below differs per call. ===
   
   downstream_file: {absolute path to the specific downstream file under audit}
   

   The agent's Step 1 consumes the five inlined blocks directly — it does NOT re-Read the four foundational files when the blocks are present. See agents/reviewers/principle-quality-reviewer.md Step 1 (Inlined-blocks fast path) for the consumption contract.

   Why the order matters: Anthropic's prompt cache is a prefix matcher. Any per-call discriminator above the marker would split the cache and force every parallel call to be a cache miss. Keep downstream_file as the LAST line; keep principles_diff and the five inlined blocks above it; keep them in the order shown so all calls in the batch share a byte-identical prefix.

   Backward compatibility: when running the reviewer outside this orchestrator (e.g., direct invocation, older callers), the agent still accepts path-only inputs and falls back to Read / Glob. The path parameters (system_overview_file, arch_layers_file, tech_stack_file, adr_index_glob) remain in the prompt as fallback values; they are ignored when the inlined blocks are present.

   Parallelism: dispatch in batches of 4 (mirrors v3.16.0 explorer fan-out pattern). Wait for each batch before starting the next.

   Cache-warm sequencing (first batch only): in the FIRST batch of any Phase 1.5 fan-out, fire one sub-agent call first and wait for its response to settle before firing the remaining 1–3 calls in parallel. The first call's response writes the byte-identical stable prefix (the five inlined blocks above) into Anthropic's prompt cache; the remaining calls in that batch — and every call in every subsequent batch within the 5-min cache TTL — read the prefix from cache instead of re-paying it. After the first batch completes, dispatch subsequent batches normally (full parallel of 4); the cache is already warm.

   The latency cost is one extra serialized call (~30–60s) paid only on the first batch of each Phase 1.5 fan-out. For typical S3 edits where step 2 pruning leaves 2–4 candidate files, this adds < 1 minute of wall-clock time. For wider fan-outs (8+ files post-pruning) the savings compound across batches because each non-first batch hits cache for the full prefix instead of re-writing it.

4. Aggregate results — each sub-agent returns one of:

   • status: PASS with findings: [] and a finding checkType: downstream-impact, severity: NO_IMPACT → file unaffected; no action.
   • status: PASS with WARNING findings → surface in Phase 2 checklist as [principle-impact] items but don't block.
   • status: FAIL with BLOCKING findings → file contradicts a changed principle; surface in Phase 2 checklist as [principle-impact-BLOCKING] items requiring user review.

5. Fail-open clauses:

   • Sub-agent timeout / empty / error on any single file: skip that file with a Phase 2 warning ("{file} — principle alignment review unavailable; manual review required"). Do not block.
   • All sub-agents fail (e.g., system-wide tool outage): emit one warning at the top of Phase 2 ("Principle Alignment Audit unavailable; downstream files not semantically re-checked. Run /skill architecture-peer-review after edits land if reliability matters for this change.") and proceed to standard Phase 2 with structural impacts only.

6. Inject findings into Phase 2 checklist — semantic findings appear as a dedicated subsection labeled "Principle Alignment Findings" between the structural impact list and the "Approve all?" prompt. Pruning notes from step 2 (skipped files) appear in the same subsection under a "Skipped (no token references)" sub-heading so the user retains visibility into what was deliberately not reviewed. User can approve / deselect / skip per file (same UX as structural impacts).

Anti-recursion: Phase 1.5 sub-agent calls do NOT trigger another Phase 1.5 invocation when their findings translate into Phase 3 edits.

Phase 2: Generate Checklist

Present a structured checklist grouped by file type:

═══════════════════════════════════════════════════════════
DOWNSTREAM UPDATES REQUIRED — {edited_file} ({section_name})
═══════════════════════════════════════════════════════════

Changes detected:
- {bullet list from Phase 1a}

─── Downstream Sections ──────────────────────────────────
[ ] 1. docs/07-security-architecture.md — references {changed_tech}; security controls may need updating
[ ] 2. docs/09-operational-considerations.md — mentions {old_value}; align with new value

─── Component Files ──────────────────────────────────────
[ ] 3. docs/components/03-payment-service.md — uses {changed_component}; integration details may be stale

─── Handoff Docs ─────────────────────────────────────────
[ ] 4. handoffs/03-payment-service-handoff.md — Section 4 references {old_tech}

─── No Updates Required ──────────────────────────────────
ℹ️  docs/04-data-flow-patterns.md — no references to changed content
═══════════════════════════════════════════════════════════
Approve all? ('all', comma-separated numbers to deselect, or 'skip')

Wait for user response before proceeding.

Phase 3: Execute Updates

Process approved files in tier order (lower tiers first → higher tiers last) so each updated file is available as context for files that depend on it.

For each approved docs/*.md or docs/components/*.md file:

1. Load Context Anchor (universal foundation + section-specific parents per the dependency table)
2. Read the target file in full
3. Identify passages affected by the fact-deltas
4. Apply updates, maintaining Source Attribution links (per [Section X](../...))
5. Run the 5-check Post-Write Alignment Audit on the updated file
6. Mark as [x]

For approved handoffs/*.md files: Read, locate affected passages, update following the dev-handoff Documentation Fidelity Policy. Mark as [x].

If user selected skip: Add <!-- PROPAGATION PENDING: upstream {edited_file} changed ({date}) — downstream not yet updated --> comment at the top of the edited file.

Component File Edit Handling

When the edited file is docs/components/*.md (not a section file):

• Cascade through S5's row in the table (S6, S7, S8, S9, S10, S11)
• Additionally grep for the component name (not just filename) across all docs/ files
• Always include the matching handoffs/{component}-handoff.md if it exists
• If docs/components/README.md needs updating, delegate to the architecture-component-guardian skill

Phase 4: Propagation Report

═══════════════════════════════════════════════════════════
DOWNSTREAM PROPAGATION — COMPLETION REPORT
═══════════════════════════════════════════════════════════

Source: {edited_file} ({section_name})
Changes: {summary from Phase 1a}

Completed:
[x] docs/07-security-architecture.md — {what was updated}
[x] docs/components/03-payment-service.md — {what was updated}

Verified (no change needed):
✓  docs/08-scalability-and-performance.md — content still accurate

Deselected (manual update required):
[ ] docs/09-operational-considerations.md — user chose manual update

Failed (require manual review):
⚠️  {any files where edit could not be applied cleanly}
═══════════════════════════════════════════════════════════

Phase 5: Asset Regeneration Advisory

Runs after: Phase 4 report is displayed. Also runs when: User selected skip in Phase 2 and handoff files exist in handoffs/ — in this case, note that handoff text was also not updated.

Skip silently when: No handoffs/*.md files appeared in the Phase 3 update list (completed, deselected, or failed) AND propagation was not skipped.

Step 5a — Detect asset-impacting changes: Scan the fact-deltas from Phase 1a for asset-impact keywords (case-insensitive):

| Keywords | Potentially Stale Asset | |----------|------------------------| | API, endpoint, REST, GraphQL, gRPC, route, path, method, request, response, header, status code | openapi.yaml | | database, table, column, schema, index, constraint, migration, DDL, SQL | ddl.sql | | Redis, cache, key, TTL, expiration, eviction | redis-key-schema.md | | deployment, container, pod, replica, port, resource, limit, CPU, memory, image, Kubernetes, K8s | deployment.yaml | | message, event, topic, queue, consumer, producer, Kafka, RabbitMQ, stream | asyncapi.yaml | | Avro, schema registry | schema.avsc | | Protobuf, proto | schema.proto | | cron, schedule, batch, job, CronJob | cronjob.yaml |

If no keywords match → skip this phase silently.

Step 5b — Identify affected components: For each handoffs/*-handoff.md file that was touched in Phase 3 (or would have been if propagation was skipped/deselected), check whether handoffs/assets/NN-<component-name>/ exists and contains any of the matched asset types. Exclude components with no asset directory or no matching asset files on disk.

If zero components remain after filtering → skip silently.

Step 5c — Present advisory:

───────────────────────────────────────────────────────────
ASSET REGENERATION ADVISORY
───────────────────────────────────────────────────────────

The propagation above updated handoff document text, but
the following scaffolded assets may now be stale:

  Component: {component-name}
    → openapi.yaml  (changes mention: endpoint, API)
    → ddl.sql       (changes mention: table, column)

  Component: {component-name-2}
    → deployment.yaml  (changes mention: container, port)

These assets were generated by the dev-handoff skill and
contain structured specs derived from architecture docs.
In-place text patches do not regenerate them.

Would you like to regenerate handoff documents and assets
for the affected components?

  [Yes] → I will provide the commands to run
  [No]  → No action needed right now

Note: You can regenerate all handoffs at any time with:
  /skill architecture-dev-handoff
───────────────────────────────────────────────────────────

If propagation was skipped: prepend to the advisory:

Note: Propagation was skipped — handoff document text was also not updated. Full regeneration is recommended.

Wait for user response.

• Yes → Display one line per affected component: Run: /skill architecture-dev-handoff (for each affected component by name). Do NOT invoke the skill automatically.
• No → Acknowledge and proceed with no further action.

---

6. Verification
   • After edits, re-read the modified docs/ file to verify changes
   • Use Grep to search for specific content without loading multiple files

Discovering Available Files

When the target section is not obvious, read ARCHITECTURE.md first:

# Step 1: Read navigation table
nav_content = Read(file_path="ARCHITECTURE.md")

# Step 2: Parse the Documentation table to find the target file
# Example row: | 8 | Security Architecture | [docs/07-security-architecture.md](docs/07-security-architecture.md) | ... |

# Step 3: Read that specific docs/ file in full
target_content = Read(file_path="docs/07-security-architecture.md")

Technology Context Enrichment (context7) — Component Documentation

When creating NEW component documentation (Workflow 1, Section 5), and the component's Technology field references specific frameworks, libraries, or tools, use the context7 MCP tool to fetch current documentation for those technologies.

Prerequisite: The context7 MCP tool must be available (resolve-library-id and get-library-docs functions). If not available, skip silently — component doc generation proceeds normally.

When to use:

• During Workflow 1 (new ARCHITECTURE.md creation) when populating Section 5 component files
• When a user explicitly asks to "enrich" or "validate" technology references in an existing component doc
• NOT during routine section edits, NOT during compliance generation, NOT during handoff generation

Procedure:

1. Extract technology names from the component's Technology field (e.g., "Java 17, Spring Boot 3.1.5, PostgreSQL 15").

2. For each distinct technology, call resolve-library-id (e.g., spring-boot, postgresql, nestjs).

3. For each resolved library, call get-library-docs with a topic hint scoped to configuration patterns and version features for the documented version (e.g., "Spring Boot 3.1 actuator endpoints and configuration properties").

4. Present a Technology Context Brief to the user as an advisory checklist — do NOT auto-fill any document fields:

   Technology Context Brief — [Component Name]
   
   Spring Boot 3.1.5:
   - Key config patterns: application.yml (spring.datasource.*, management.endpoints.*)
   - Health check endpoints: /actuator/health (liveness), /actuator/health/readiness
   - Suggested fields to document: connection pool settings, JPA dialect, security filter chain
   
   PostgreSQL 15:
   - Notable in v15: MERGE statement, improved JSON path, pg_walinspect
   - Suggested fields to document: connection pool strategy (PgBouncer?), vacuum/autovacuum, extensions used
   

5. The architect decides which items to include in the component doc. The skill does NOT auto-populate any fields from this brief.

What this is NOT:

• Not a replacement for the architect's knowledge or documentation decisions
• Not auto-filled content (the "no invention" policy still applies)
• Not blocking — generation proceeds with or without it

Updating the Navigation Index

Update ARCHITECTURE.md only when:

• A new section file is added to docs/
• A new component file is added to docs/components/
• A file is renamed or removed

Do NOT update ARCHITECTURE.md for content edits within existing docs/ files.

---

Architecture Type Selection Workflow

Full workflow for guiding users through architecture type selection (Banking/BIAN, Microservices, Monolith, etc.), the PO Spec prerequisite check, template loading, and diagram generation is in ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md.

Read it when:

• User is creating a NEW architecture document
• User asks to change architecture type
• No existing ARCHITECTURE.md is detected

The workflow runs Steps 0–7 (PO Spec gate → type selection → template load → metadata → multi-file creation → ADR delegation → diagrams).

ADR operations: Any ADR creation, update, or supersede must delegate to /skill architecture-definition-record. This skill reads adr/*.md for context only.

When to Trigger

Activate this workflow when:

• ✅ User asks to create a NEW ARCHITECTURE.md document
• ✅ User explicitly requests to "change architecture type" or "select architecture type"
• ✅ User is updating an existing ARCHITECTURE.md and mentions changing from one architecture type to another

Prerequisite: Step 0 (PO Spec check) runs before Step 1 for all new document creation triggers

Skip this workflow when:

• ❌ Editing an existing ARCHITECTURE.md (type already selected)
• ❌ User is only updating specific sections unrelated to architecture type
• ❌ Document type is already clear from context

See ARCHITECTURE_TYPE_SELECTION_WORKFLOW.md for full workflow details.

---

Navigation Index Updates

When to update the navigation index in ARCHITECTURE.md:

• ✅ When a new docs/NN-*.md file is added
• ✅ When a docs/NN-*.md file is renamed or removed
• ✅ When a new ADR is accepted (add row to the ADR table)
• ✅ When a component is added/removed/renamed (delegate to architecture-component-guardian for docs/components/README.md)

Do NOT update for:

• ❌ Content edits within existing docs/NN-*.md files (no line ranges to maintain)
• ❌ Typo or formatting fixes
• ❌ Metric value updates inside a file

Workflow:

1. Check ls docs/*.md against the Documentation table in ARCHITECTURE.md
2. Add/remove rows as needed — each row has S-prefix, title, file link, one-line description
3. Report changes to user

The navigation index has no line numbers — each row links directly to a docs/NN-*.md file that is read in full when needed.

---

Metric Consistency Detection & Management

Full workflow and reference details are in METRIC_CALCULATIONS.md (Read it when this workflow is needed).

Quick summary: Automatically detects and reviews metric inconsistencies when Section 1 Key Metrics are updated, scanning the entire document for stale duplicates and presenting a structured audit report before applying changes.

When to invoke: After editing Section 1 Executive Summary Key Metrics, or when user requests "check metric consistency", "verify metrics", or "audit metrics".

---

Foundational Context Anchor Protocol

Full workflow and reference details are in ARCHITECTURE_DOCUMENTATION_GUIDE.md (Read it when this workflow is needed).

Quick summary: Dependency-aware editing workflow that loads required upstream context (S1+S2, S3, ADRs, and section-specific parents) before any downstream section edit, requires source attribution for derived claims, and detects downstream impact when any section changes (executed via Step 5.5 Downstream Documentation Propagation).

When to invoke: Before editing any docs/ file from docs/03-architecture-layers.md through docs/09-operational-considerations.md, or any docs/components/*.md file.

---

Design Drivers Impact Metrics Calculation

Full workflow and reference details are in DESIGN_DRIVER_CALCULATIONS.md (Read it when this workflow is needed).

Quick summary: Automatically calculates and maintains Design Drivers impact metrics (Value Delivery, Scale, Impacts) from Sections 1, 2.3, 5, and 8, using a 6-phase workflow to extract data, present findings, and update Section 2.2.1.

When to invoke: When user requests "architecture review", "calculate design drivers", "update design drivers", or "assess design impact".

---

Architecture Reference Docs (C4 Model + Type-Specific Rules)

The references/ directory contains the architecture rules and C4 translation guides for each architecture type. These are loaded during Step 3 of the Architecture Type Selection Workflow.

| File | Purpose | |------|---------| | references/ICEPANEL-C4-MODEL.md | Governing C4 reference — defines C4 abstractions, diagram levels, boundary test. Constrains component documentation behavior. | | references/MICROSERVICES-ARCHITECTURE.md | Microservices architecture rules and patterns | | references/MICROSERVICES-TO-C4-TRANSLATION.md | Microservices → C4 mapping (services=containers, not systems) | | references/3-TIER-ARCHITECTURE.md | 3-Tier architecture rules (Presentation, Logic, Data) | | references/3-TIER-TO-C4-TRANSLATION.md | 3-Tier → C4 mapping (tier≠container distinction) | | references/N-LAYER-ARCHITECTURE.md | N-Layer variants (DDD, Clean, Hexagonal, 5-Layer Extended) | | references/N-LAYER-TO-C4-TRANSLATION.md | N-Layer → C4 mapping (inner layers=C3, infra=C2) | | references/META-ARCHITECTURE.md | META 6-layer banking architecture rules | | references/META-TO-C4-TRANSLATION.md | META → C4 mapping (layers as visual groupings at C2) | | references/BIAN-ARCHITECTURE.md | BIAN V12.0 5-layer architecture rules | | references/BIAN-TO-C4-TRANSLATION.md | BIAN → C4 mapping (Service Domains as containers) | | references/DIAGRAM-GENERATION-GUIDE.md | Diagram generation reference — defines 4 standard architecture diagrams with type-specific templates for META, BIAN, 3-Tier, N-Layer, and Microservices. Includes C4 color conventions, Mermaid compatibility rules, and generation workflow. |

Critical rule: Every architecture type MUST have both reference docs. Types without them are greyed out in the selection menu and cannot be used.

---

Documentation Structure

Full workflow and reference details are in QUERY_SECTION_MAPPING.md (Read it when this workflow is needed).

Quick summary: Covers when and how to use ARCHITECTURE_DOCUMENTATION_GUIDE.md for creating, documenting, and maintaining architecture docs, the 9 required Architecture Principles, the 12 required section names with exact format, and the Workflow 7 Informational Query workflow for answering questions from architecture documentation.

When to invoke: When creating new architecture documents, documenting existing projects, maintaining architecture docs, or answering user questions about documented architecture content.

---

Workflow 8: Diagram Generation (Generate Architecture Diagrams)

Two reference files (read both when this workflow is needed):

• references/DIAGRAM-GENERATION-GUIDE.md — Primary generation reference: defines the 4 standard diagrams (Logical View ASCII, C4 L1 Context, C4 L2 Container, Detailed View Mermaid), architecture-type-specific templates for all 5 types (META, BIAN, 3-Tier, N-Layer, Microservices), data sources, C4 color conventions, Mermaid compatibility rules, and the generation workflow algorithm.
• MERMAID_DIAGRAMS_GUIDE.md — Authoring reference: Mermaid syntax patterns, component guidelines, data flow conventions, standard color scheme, common scenarios, and best practices.

Quick summary: Generate all 4 standard diagrams in order (ASCII logical → C4 L1 → C4 L2 → Detailed) under ## Architecture Diagrams in docs/03-architecture-layers.md. Each diagram adapts its grouping, naming, and color conventions to the detected architecture type and theme preference (light/dark). Theme is detected from <!-- DIAGRAM_THEME: light|dark --> in docs/03-architecture-layers.md — if absent, ask the user once and persist. Dark theme applies %%{init: {'theme': 'dark'}}%% to C4/sequence diagrams and uses the dark classDef palette for the Detailed View. Data Flow sequence diagrams are generated separately in docs/04-data-flow-patterns.md. External diagram reconciliation, canonical location enforcement, and completeness audit rules apply.

When to invoke: When user requests "generate diagrams", "create diagrams", "add diagrams", "update diagrams", or references Mermaid/architecture/visual diagrams.

---

Workflow 9: Migrate Existing ARCHITECTURE.md to docs/ Structure

Full workflow and reference details are in RESTRUCTURING_GUIDE.md (Read it when this workflow is needed).

Quick summary: Covers migrating a monolithic ARCHITECTURE.md to the multi-file docs/ structure (6 steps: analyze, propose target layout, extract files, rewrite ARCHITECTURE.md as navigation index, update external references, verify), plus optional enhancements and reference document inventory.

When to invoke: When user mentions "migrate", "restructure", "split", "reorganize", or "convert" with "architecture" or "ARCHITECTURE.md", or when the file is "too large" or "hard to navigate".

---

Workflow 10: Release Architecture Version

Full workflow and reference details are in RELEASE_WORKFLOW.md (Read it when this workflow is needed).

Quick summary: Formal release of a new architecture version. Bumps the semver version, generates a docs/CHANGELOG.md entry from detected changes (new/modified components, accepted/superseded ADRs, section edits), updates version metadata across ARCHITECTURE.md and all component files, and creates an annotated git tag architecture-v{version} on HEAD (when repo is under git, working tree is clean). If the project is NOT under git, creates an immutable archive snapshot at archive/v{version}/ as the baseline mechanism; git projects can opt into the archive for audit compliance.

When to invoke: When user asks to "release architecture", "release architecture version", "bump architecture version", "freeze architecture", "tag architecture version", or transitions an architecture from Draft to Released status.

Preconditions:

• ARCHITECTURE.md exists with <!-- ARCHITECTURE_VERSION: --> metadata block
• If repo is under git: working tree must be clean, architecture-v{new-version} tag must not already exist

Drift detection (informational, on every architecture-docs invocation): if doc version ≠ latest architecture-v* git tag, emit a one-line warning. Does not block other workflows. See RELEASE_WORKFLOW.md → "Drift Detection" for details.

---

Workflow 11: Layout Migration Gate (Legacy → Current)

Purpose: Migrate older multi-file docs/ layouts to the current numbering convention. Older versions of this skill placed References at docs/10-references.md (with no Risks & Technical Debt section). The current convention puts Risks & Technical Debt (S13) at docs/10-risks-and-technical-debt.md and shifts References to docs/11-references.md so the cross-cutting References file remains the highest-numbered file by convention.

Auto-trigger preflight: Every workflow that operates on an existing multi-file project (Workflows 2 / 3 / 8 / 10 and any informational query against docs/*.md) MUST run the detection check below before proceeding. New-project creation (Workflow 1) and the single-file → multi-file restructure (Workflow 9) emit the current layout directly and skip this gate.

When to invoke explicitly: User says "migrate layout", "upgrade architecture file numbering", "fix references file position", or any other workflow auto-fires the preflight.

Detection (legacy layout signature) — both conditions must hold:

• docs/10-references.md exists, AND
• docs/10-risks-and-technical-debt.md does NOT exist

If both true → legacy layout, run the steps below. Otherwise → current layout, exit with ℹ️ Layout already current — nothing to migrate.

Steps:

1. Confirm with user before any rename:

   ⚠️  Legacy layout detected: docs/10-references.md occupies the cross-cutting
       "last file" slot, but the current convention reserves docs/10-* for
       Risks & Technical Debt (S13) and shifts References to docs/11-*.
   
       Migrate now? [Y/n]
   

   If n → halt and emit a one-line skip note. The calling workflow does NOT proceed; the user must either re-run and accept, or invoke Workflow 11 explicitly later.

2. Rename References file: docs/10-references.md → docs/11-references.md.

   • Under git: git mv docs/10-references.md docs/11-references.md
   • Otherwise: mv docs/10-references.md docs/11-references.md

3. Create Risks & Technical Debt file: write docs/10-risks-and-technical-debt.md from the Section 13 template in ARCHITECTURE_DOCUMENTATION_GUIDE.md (empty 13.1 Risks and 13.2 Technical Debt tables, plus the conventions block).

4. Rewrite internal cross-references: locate every link to docs/10-references.md across docs/, docs/components/, adr/, and ARCHITECTURE.md, then rewrite to docs/11-references.md.

   grep -rl "docs/10-references" docs/ adr/ ARCHITECTURE.md 2>/dev/null \
     | xargs -r sed -i 's|docs/10-references|docs/11-references|g'
   

5. Update the navigation table in ARCHITECTURE.md: locate the Documentation table (rows of the form | NN | <Section Name> | [docs/...](docs/...) | ... |) and:

   • Update the References row to point at docs/11-references.md
   • Insert a new row for | 13 | Risks and Technical Debt | [docs/10-risks-and-technical-debt.md](docs/10-risks-and-technical-debt.md) | ... | if S13 is not yet listed

6. Report:

   ✅ Layout migrated:
       - References:               docs/10-references.md → docs/11-references.md
       - Risks & Technical Debt:   created docs/10-risks-and-technical-debt.md (empty Section 13 template)
       - Internal links updated:   {N} cross-references rewritten across {M} files
       - Navigation table:         updated in ARCHITECTURE.md
   
       The calling workflow can now proceed.
   

7. Resume the original workflow (the one whose preflight detected the legacy layout). The user does NOT re-issue the original command — Workflow 11 hands control back automatically.

Idempotency: Workflow 11 is safe to re-run. After a successful migration the detection check returns false and the workflow exits with ℹ️ Layout already current — nothing to migrate.

Out of scope: this workflow does NOT alter section content, ADRs, component files, or version metadata. It is purely a file-renumber + S13 scaffold + cross-reference rewrite + navigation-table update.