<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"}

references/pyramid-handoff-convention.md — kanban API, delegate_task, quality gate checklist
references/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

architect-pyramid

Architect Pyramid

Pyramid Output Structure