architecture-docs

Files (23)

• SKILL.md
• arc42-01-introduction-and-goals.md · references/
• arc42-02-constraints.md · references/
• arc42-03-context-and-scope.md · references/
• arc42-04-solution-strategy.md · references/
• arc42-05-building-block-view.md · references/
• arc42-06-runtime-view.md · references/
• arc42-07-deployment-view.md · references/
• arc42-08-crosscutting-concepts.md · references/
• arc42-09-architecture-decisions.md · references/
• arc42-10-quality-requirements.md · references/
• arc42-11-risks-and-technical-debt.md · references/
• arc42-12-glossary.md · references/
• arc42-snapshot.md · references/
• product-intent-citations.md · references/
• generate.mjs · snapshot/
• loadDocs.mjs · snapshot/
• package-lock.json · snapshot/
• package.json · snapshot/
• render.mjs · snapshot/
• shell.mjs · snapshot/
• render.test.mjs · snapshot/test/
• shell.test.mjs · snapshot/test/

SKILL.md (first lines)

# Maintain Architecture Documentation

Maintain a concise explanation of **how** the system is structurally shaped. Use the canonical twelve arc42 sections as the explicit structure under `docs/architecture/`; `README.md` is the navigation index, not a thirteenth section.

Treat architecture maintenance as evidence-led analysis and a reviewable proposal. Distinguish observed implementation, maintainer-supplied intent, assumptions, and proposed documentation. Code and configuration establish current behavior, not why it was chosen or whether a future direction is accepted. Ask the maintainer when a material intent or decision cannot be established safely, and never present a proposal as accepted.

Keep these ownership boundaries intact:

| Source | Owns |
| --- | --- |
| The project's product-intent source, when one exists (for example `docs/product/model/` under ProductShape) | Product intent: what and why |
| `docs/architecture/` and, during migration, `docs/ARCHITECTURE.md` | Architecture: how the system realizes that intent |
| Source, configuration, tests and infrastructure | Implementation reality |
| `docs/adr/` | Rationale and consequences of significant decisions |

Architecture documentation may summarize a product concern only to explain its architectural realization. It never becomes another source of product requirements, terminology, drift state or traceability semantics. Never edit `docs/DESIGN.md` from this skill.

## arc42 references

Read only the sections affected by the task:

| Concern | Reference |
| --- | --- |
| Goals and architectural drivers | [Introduction and goals](references/arc42-01-introduction-and-goals.md) |
| Constraints | [Constraints](references/arc42-02-constraints.md) |
| System context and boundaries | [Context and scope](references/arc42-03-context-and-scope.md) |
| Solution strategy | [Solution strategy](references/arc42-04-solution-strategy.md) |
| Static decomposition | [Building block view](references/arc42-05-building-block-view.md) |
| Runtime interactions | [Runtime view](references/arc42-06-runtime-view.md) |
| Deployment | [Deployment view](references/arc42-07-deployment-view.md) |
| Crosscutting concepts | [Crosscutting concepts](references/arc42-08-crosscutting-concepts.md) |
| Architecture decisions | [Architecture decisions](references/arc42-09-architecture-decisions.md) |
| Quality realization | [Quality requirements](references/arc42-10-quality-requirements.md) |
| Risks and technical debt | [Risks and technical debt](references/arc42-11-risks-and-technical-debt.md) |
| Architecture terminology | [Glossary](references/arc42-12-glossary.md) |

When an architectural concern depends on product intent, also read [product-intent citations](references/product-intent-citations.md). When the project maintains no product-intent source, treat product-dependent claims as unverified assumptions and say so rather than inventing a source of truth.

To publish a shareable, self-contained HTML rendering of the arc42 documentation, read [arc42 snapshot](references/arc42-snapshot.md).

## Document contract

Every numbered architecture document starts with this minimal YAML frontmatter:

```yaml
---
title: <canonical arc42 section title>
arc42-section: "<zero-padded section number>"
description: <one sentence naming the architecture knowledge owned here>
---
```

Use only these three keys. `arc42-section` gives coding agents a stable section identity; `title` and `description` support discovery without reading the full document. Do not add status, owner, review-date, implementation inventory or traceability fields that can drift. `README.md` may use `title` and `description`, but never `arc42-section` because it is navigation rather than a thirteenth section.

Each section reference contains its canonical document scaffold. Use that scaffold when creating a document, replace bracketed labels with evidence-backed content, and remove unused optional headings. Never commit template placeholders. When a section has no substantive content, keep the document and state that concisely rather than inventing architecture.

## Workflow

### 1. Establish bounded evidence coverage

Read `docs/README.md`, `docs/architecture/` when present, the relevant parts of legacy `docs/ARCHITECTURE.md`, the ADR index and relevant ADRs, and the project's product-intent source when one exists. Inspect the source, tests, configuration, and infrastructure that implement the affected behavior. Treat generated files and legacy architecture prose as leads to verify, never as proof.

If the request concerns a change, inspect its diff or planned touch points first and focus evidence review on the affected claims. If it is a general audit or reverse-engineering task, work in bounded rounds and track sources as reviewed, excluded, pending, or changed; do not claim complete coverage while material evidence remains pending. When ArcShape's evidence-session CLI is available, use `arcshape session start`, `status`, and `next` to create or resume rounds, record source classifications and findings with `mark`, correct mistakes with `unmark`, and re-read sources reported as changed. Without that CLI, use a concise working evidence map and report its coverage and limits; do not invent or commit a new tracking format unless requested. This step is complete when every claim under review has an identified owner and current evidence, and remaining gaps are explicit.

### 2. Apply the significance gate

Update architecture documentation when the change alters or reveals at least one of these:

- system context, trust boundary or external system;
- major component responsibility, dependency direction or interface;
- architecturally important runtime interaction or failure path;
- persistence strategy, data ownership or consistency boundary;
- security, identity or authorization mechanism;
- deployment topology or mapping from software to infrastructure;
- major technology choice or cross-cutting mechanism;
- realization of a quality attribute;
- significant architectural risk or technical debt.

Normally classify class-level details, endpoint internals, local validation, routine dependency updates, isolated refactors and ordinary feature code as **no architecture impact**. A change is not significant merely because it changes many lines. If no item above changes, report `No architecture documentation impact` with one sentence of evidence and stop without editing architecture files.

This step is complete when the outcome is either a justified no-impact decision or a list of affected architecture concerns.

### 3. Map the impact to arc42

Map each architectural fact to one canonical owning section. A change may affect multiple sections; update every affected view, but do not duplicate the same authoritative explanation across them. Keep the sections distinct even when one is intentionally small; never merge distinct concerns into a generic document. `README.md` only identifies the documentation boundary, links the twelve sections and points to supporting diagrams.

For initial generation or an explicitly approved full migration, establish `README.md` and all twelve numbered documents with the document contract and section-specific scaffolds, then fill them with concise, evidence-backed content. For normal maintenance, preserve valid frontmatter and update only affected documents. Add no other architecture document unless a concrete volume, audience or maintenance need makes the canonical section impractical; keep supporting diagram sources under `docs/architecture/diagrams/`.

This step is complete when every affected fact has one arc42 owner and every affected view is identified.

### 4. Update only the affected documents

Write stable architectural structures, interactions, mechanisms, consequences and evidence at the abstraction defined by the owning arc42 section. Keep one fact in one authoritative location and link to it from other sections. Put operational procedures in runbooks, detailed API behavior in specifications or generated API documentation, and volatile inventories in source-controlled manifests or infrastructure.

Use Mermaid when a diagram communicates relationships better than prose. Keep diagram source beside the architecture document or under `docs/architecture/diagrams/`; every diagram needs explanatory text and names consistent with the prose. Link to implementation evidence instead of copying package, class, route, table or resource inventories.

Remove claims disproved by current evidence and consolidate duplicates into their canonical section. This step is complete when each changed document is concise, current, evidence-backed and limited to its arc42 responsibility.

### 5. Bind product-dependent claims to the product-intent source

When the project maintains a product-intent source with a citation mechanism, follow the repository-specific workflow in the [product-intent citations](references/product-intent-citations.md) reference. Architecture explains the realization of product intent and places the citation immediately below the grounded statement or coherent block of statements; it never copies the requirement, actor, use case, rule, constraint, quality requirement or domain definition as architecture truth.

Do not add citation metadata, drift markers, IDs, resolvers or verification tooling of your own; the product-intent source owns citation generation, validation, identity, status and drift. A single citation may ground a coherent paragraph, table row, architectural rule, mechanism or other meaningful unit when that unit derives from the same canonical product intent. This step is complete when every architecture statement or coherent block of statements that materially depends on product intent is grounded by the relevant current citation, or the absence of a product-intent source is reported, and architecture defines no product intent.

### 6. Use ADRs for significant decisions

Create or reference an ADR through the repository's existing ADR process when a significant choice needs rationale, alternatives or consequences. When the shared `adr` skill is available, use it for authoring and lifecycle; this skill owns the resulting architecture views, not a second ADR workflow. `09-architecture-decisions.md` is the architecture-facing index of accepted decisions; other arc42 views describe the resulting shape and link to the ADR where relevant.

Keep rationale, rejected alternatives and consequences in the ADR rather than repeating them in arc42 sections. This step is complete when every significant decision has one authoritative ADR and all affected architecture views link to it without duplicating it.

### 7. Migrate legacy content incrementally

Treat `docs/ARCHITECTURE.md` as untrusted migration input. Classify each touched passage before moving it:

| Classification | Action |
| --- | --- |
| Product intent | Remove the duplicate; cite the product-intent source from any retained architectural realization |
| Actual architecture | Verify against implementation, then map it to one of the twelve arc42 documents |
| Architecture decision | Link an existing ADR or create a proposed ADR; keep only the resulting shape in the view |

From juangcarmona/agent-toolkit, MIT.

More from juangcarmona/agent-toolkit