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

1. **C4 views reference ADRs** — every Container and Component diagram links to the ADRs that explain why they're structured that way
2. **ADRs reference arc42 constraints** — every decision log links to the arc42 quality attribute or constraint that drove the decision
3. **arc42 constraints reference C4 views** — every constraint entry links to the C4 diagram that shows how the constraint is realized
4. **SOURCES sections at every layer** — absolute paths with descriptions, not footnotes
5. **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 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

- Magnus Hedemark, "Clanker Technical Architect: First on the Scene with Progressive Disclosure" — https://magnus919.com/2026/05/clanker-technical-architect-first-on-the-scene-with-progressive-disclosure/