pkuppens/architecture

Architecture

Orchestrates architecture documentation and evolution per arc42. Routes to sub-skills based on mode: Initial (greenfield), Retrofitting (document existing), or Evolving (change/extend).

When to use

• Starting a new (greenfield) project — architecture needed from scratch
• Codebase exists but lacks architecture docs — need to infer and document
• Adding a feature or changing architecture — ADRs, building blocks, or risks need updates

Modes and routing

| Mode | Trigger | Sub-skills invoked | |------|---------|---------------------| | Initial | Greenfield project, no architecture yet | architecture-solution-strategy → architecture-building-blocks | | Retrofitting | Undocumented codebase | architecture-document-existing (or architecture-consult variant) | | Evolving | Change or extend existing architecture | architecture-decisions → architecture-risks-debt as needed |

Flow

1. Determine mode — from user intent or context:

   • "Plan a new app" / "Start from scratch" → Initial
   • "Document our architecture" / "Reverse-engineer structure" → Retrofitting
   • "Add feature X" / "Change decision Y" / "Address tech debt" → Evolving

2. Initial mode

   • Run architecture-solution-strategy (arc42 §4: goals, approach)
   • Run architecture-building-blocks (arc42 §5: structure, hierarchy)

3. Retrofitting mode

   • Run architecture-document-existing to infer and document from code
   • Optionally run architecture-consult to refine placement and constraints

4. Evolving mode

   • Run architecture-decisions for new or updated ADRs (arc42 §9)
   • Run architecture-risks-debt when addressing risks or tech debt (arc42 §11)
   • Use architecture-consult when placing new code within existing structure

Instructions

1. Identify mode from user request (new project vs undocumented vs change).
2. Invoke sub-skills in sequence per mode table above.
3. When unsure, prefer architecture-consult for placement questions; use orchestrator sub-skills for creation or evolution.
4. Reference arc42 sections in docs/architecture/ and docs/architecture/adr/ for consistency.

Output format

Output follows the sub-skill(s) invoked. Orchestrator output summarizes mode and which sub-skills ran:

## Architecture: [Mode]

**Mode:** Initial | Retrofitting | Evolving
**Sub-skills run:** [list]
**Artifacts:** [paths to created/updated docs]

Integration

• Issue-workflow: Can be triggered during issue creation or revision (see issue-workflow). Requirements and implementation plans take architecture concerns into account.
• Plan / Ask: Invoked when planning a new system, asking about ADRs, or scoping architectural changes.
• COOPERATION.md: See architecture flows for when to trigger and how sub-skills compose.

Additional sub-skills

| Sub-skill | When | |-----------|------| | architecture-runtime | Document technical execution paths, sequences | | architecture-deployment | Document deployment topology (arc42 §7) | | architecture-crosscutting | Define dependency rules, layer boundaries, architecture tests | | architecture-quality | Quality tree and scenarios (arc42 §10) | | architecture-glossary | Maintain ubiquitous language, resolve terminology |

These can be invoked from architecture-document-existing during retrofitting, or directly when needed.