| name | architect-pyramid |
| description | Output orchestrator for the technical-architect profile — maps C4 structural views, ADR decision records, and arc42 constraints into a unified artifact pyramid. Manages the pyramid structure, cross-referencing rules, and handoff convention. Load after c4-diagramming, adr-authoring, and arc42-context. |
Architect Pyramid
Output orchestrator for the technical-architect profile. Takes structural views (C4), decision records (ADRs), and context/constraint documentation (arc42) and assembles them into a single artifact pyramid.
Pyramid Output Structure
<project>/
├── 00-index.md
├── 01-summary/
│ ├── system-context.md ← C4 Level 1 (System Context diagram)
│ └── quality-tree.md ← arc42 Canvas / quality attributes
├── 02-analysis/
│ ├── structural-views/
│ │ ├── container.md ← C4 Level 2 (Container diagram)
│ │ └── components.md ← C4 Level 3 (Component diagram)
│ ├── architecture-decisions/
│ │ └── ADR-001.md ← Active ADRs (one per decision)
│ ├── constraints-and-context.md ← arc42 sections 1-2 (goals, constraints)
│ └── solution-strategy.md ← arc42 section 4
└── 03-dossiers/
├── code-level-detail.md ← C4 Level 4 (Code diagram)
├── adr-superseded.md ← Superseded ADRs
└── arc42-supplemental.md ← arc42 sections 5-12 (risks, deployment, glossary)
Cross-Referencing Rules
- C4 views reference ADRs — every Container and Component diagram links to the ADRs that explain why they're structured that way
- ADRs reference arc42 constraints — every decision log links to the arc42 quality attribute or constraint that drove the decision
- arc42 constraints reference C4 views — every constraint entry links to the C4 diagram that shows how the constraint is realized
- SOURCES sections at every layer — absolute paths with descriptions, not footnotes
- ADR lifecycle awareness — C4 views should only reference
accepted ADRs as authoritative. Links to proposed ADRs should be marked tentative. When an ADR is superseded, C4 views must relink to the replacement — see references/dimension-boundaries.md for the full lifecycle table.
Related Approach: Architecture as Code (AaC) Repo Convention
The artifact pyramid is the right output format for agent-driven architecture work — the consumer is another agent or the pyramid serves as a one-time analysis deliverable at /tmp/architect-workflow/.
For teams that need long-lived, tool-rendered architecture documentation in a git repo, the AaC community has converged on a Structurizr-based convention that combines C4 + ADRs + arc42 in a single repository with Docker preview.
Mapping: Pyramid → AaC Convention
| Pyramid Layer | Pyramid File | AaC Convention |
|---|
| L1 (Summary) | 01-summary/system-context.md | model/system.dsl (C4 Level 1 via Structurizr) |
| L1 (Summary) | 01-summary/quality-tree.md | src/10_quality_requirements.adoc (arc42) |
| L2 (Analysis) | 02-analysis/structural-views/container.md | model/system.dsl (C4 Level 2 via Structurizr) |
| L2 (Analysis) | 02-analysis/architecture-decisions/ADR-NNN.md | adr/NNNN-title.md (adr-tools format) |
| L2 (Analysis) | 02-analysis/constraints-and-context.md | src/01_introduction.adoc + 02_constraints.adoc |
| L3 (Dossiers) | 03-dossiers/code-level-detail.md | model/system.dsl (C4 Level 4 via Structurizr) |
| L3 (Dossiers) | 03-dossiers/arc42-supplemental.md | src/05-12 (remaining arc42 sections) |
When to Use Each
| Situation | Recommendation |
|---|
| Agent-driven analysis, single engagement, no Docker | Artifact pyramid — no tooling dependencies, portable, agent-native |
| Team maintaining docs in a repo, wants local preview | AaC convention — Structurizr Lite for docker compose up, CI for publishing |
| Mixed: agent produces initial docs, team maintains long-term | Produce pyramid first → if team adopts it, migrate to AaC structure |
Full reference in references/architecture-as-code-ecosystem.md (c4-diagramming skill).
Handoff Convention
The response to any caller is the absolute path to 00-index.md. Not a summary. Not a natural-language handoff. A path.
metadata={"artifact": "/tmp/architect-workflow/<slug>/00-index.md"}
Contents
references/pyramid-handoff-convention.md — kanban API, delegate_task, quality gate checklistreferences/dimension-boundaries.md — which fact lives in which file, cross-reference rules, ADR lifecycle states and awareness table, immutable vs living document model note
Canonical Reference
