SuperAPI AI Directory

architect-pyramid

General & other

View repository

Updated 10-16 09:58

About this skill

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