architecture

name	architecture
description	Create or update the technical architecture/design artifact after the spec is stable and before execution planning. Use when a change touches multiple components, data flow, persistence, APIs, deployment, performance, security, or long-lived design decisions.
argument-hint	["feature spec path","proposal path","architecture question","or change name"]

Architecture Package Authoring

You are making the technical design visible before implementation.

The architecture artifact explains how the repository or system is shaped to satisfy the spec. It should expose structure, runtime flow, deployment impact, cross-cutting rules, quality concerns, risks, and durable decisions without becoming an execution task list.

Inputs to read

Read, if present:

• AGENTS.md
• CONSTITUTION.md
• accepted proposal
• approved feature spec and spec-review findings
• the project's architecture method guidance when package shape is in scope
• the project's canonical architecture package
• related project ADRs
• research artifacts and docs/project-map.md
• existing source interfaces, schemas, APIs, modules, CI, deployment config

Upstream status settlement

In workflow-managed downstream execution, before relying on a spec, check whether its tracked status matches clear formal review evidence.

Do not run upstream status settlement for review-only, no-edit, or manual inspection requests. Those requests remain isolated.

During normal workflow-managed downstream execution, do not ask whether edits are allowed; the downstream invocation permits minimal settlement.

Settle only lifecycle/status/readiness/follow-on/closeout metadata. Do not rewrite substantive artifact content.

The clear review evidence check requires:

• durable formal review evidence for the upstream artifact;
• an approving or clean review outcome;
• no later contradictory review record;
• no open findings in review-log.md when present;
• closed review-resolution.md for material findings when required;
• an explicit settlement mapping for this skill.

Mapping for this skill:

• spec-review approved with no unresolved material findings -> spec Status: approved.

If review evidence is missing, contradictory, unresolved, or the status surface is absent, block instead of guessing.

If the artifact type, lifecycle field, next status, or target status is unknown or unmapped, block instead of inferring a settlement.

Report ## Upstream status settlement when settlement was updated, blocked, or stale status was detected:

## Upstream status settlement

- Upstream artifact:
- Review evidence:
- Previous status:
- New status:
- Settlement result: updated | blocked | not-needed
- Settlement blocker:

For blocked settlement with a deterministic target, report that intended target in New status. For blocked settlement with no deterministic target, report New status: not-applicable. Settlement blocker is required for blocked settlement and must distinguish a known target blocked by evidence/state from an unknown target blocked by missing mapping or lifecycle vocabulary.

Architecture Surface Decision

Choose the smallest valid architecture action.

1. No architecture impact

   Record a short no-architecture-impact rationale in the plan, spec, change metadata, or PR evidence.

2. Direction unclear

   Stop and route to proposal or proposal revision.

   Do not create temporary architecture documents to resolve direction uncertainty.

3. Spec unclear

   Stop and route to spec or spec revision.

4. Clear architecture update

   Update the project's canonical architecture package directly.

5. Durable decision

   Create or update an ADR when the change introduces or revises a long-lived architecture decision.

Use the project's canonical architecture package.

Common default paths are:

• docs/architecture/system/architecture.md
• docs/architecture/system/diagrams/
• docs/adr/

If the project uses different architecture paths, follow the project's configured paths.

Artifact placement

Use the project workflow guide for artifact locations when placement matters.

Lookup order:

1. explicit user path or change ID;
2. active plan, change metadata, reviewed artifact path, or current artifact metadata;
3. known governing spec or schema constraint when directly relevant;
4. docs/workflows.md artifact-location table;
5. this skill's portable default path;
6. block on ambiguity.

This discovery order is subordinate to the source-rank rule in docs/workflows.md when sources conflict.

Do not broad-search authoritative documents just to find paths. Use docs/workflows.md as the path index, and consult specs or schemas only when they govern exact shape, placement, or a detected conflict.

Resource map

• COPY assets/architecture-skeleton.md when creating a new canonical architecture package or replacing an incomplete package scaffold. Fill all required sections. Do not emit unfilled placeholders.

• COPY assets/adr-skeleton.md when recording a material architecture decision. Fill decision, context, status, consequences, alternatives considered, and follow-up.

• COPY assets/diagram-styles.mmd when Mermaid flowchart or graph diagrams need copied role styles for people, systems, external systems, and containers.

Full worked examples, if needed, belong outside this skill body, for example in skills/architecture/references/architecture-example.md.

When to Use / When Not to Use

Use the approved C4, arc42, and ADR method when architecture work is required.

Use architecture work when the change affects multiple components, data flow, generated-output flow, deployment, packaging, adapters, quality targets, cross-cutting rules, security boundaries, or durable decisions.

Do not create or update architecture artifacts for leaf changes that do not affect architecture boundaries, data flow, generated-output flow, deployment, packaging, adapters, quality targets, cross-cutting rules, or durable decisions. Record a no-architecture-impact rationale in the plan, test spec, change metadata, or PR evidence instead.

Do not put unaccepted design truth into architecture. If product direction or design choice is unresolved, route it through proposal. If behavior is unclear, route it through spec. Architecture can mention tradeoffs, but it does not own unresolved option selection.

Existing change-local architecture evidence can remain valid history. New change-local architecture evidence is exceptional or legacy closeout evidence, not the normal architecture authoring surface and not a competing canonical source.

arc42 Sections

The canonical architecture.md uses repository lifecycle metadata before all 12 official arc42 sections. Keep sections concise; use Not applicable only with a short rationale. Do not remove or rename official arc42 sections to make the document lighter.

Use the architecture skeleton for section structure. In the skill output, name only the sections changed or explicitly unaffected with rationale.

Update section 6 when behavior, orchestration, failure paths, command flow, generated-output flow, or operational flow changes. Update section 7 when environments, packaging, generated outputs, adapters, release layout, infrastructure, or execution boundaries change. Update section 8 when validation, security, caching, portability, generation, observability, or other cross-cutting rules change. Section 9 is always present and either links ADRs or states that no ADRs are required for the update.

C4 Guidance

Default required C4 diagrams for the canonical package:

• C4 system context diagram
• C4 container diagram

Use separate Mermaid .mmd source files for default diagrams and link them from architecture.md with relative Markdown links. Do not embed package diagrams in Markdown. For Mermaid flowchart or graph diagrams, copy assets/diagram-styles.mmd or an explicitly equivalent copied block so people, systems, external systems, and containers are distinguishable.

Add a component diagram only when container-level structure is not enough to explain changed responsibilities, internal boundaries, or interactions. Add a deployment diagram only when infrastructure, runtime environment, packaging, adapter distribution, or deployment mapping needs visual explanation beyond arc42 section 7.

Update the lowest affected C4 level first, then propagate upward only when the higher-level view actually changes. Do not make generated images, screenshots, or external diagram links the only source of truth.

Minimal context snippet:

C4Context
  Person(contributor, "Contributor or agent")
  System(repo, "Project repository")
  Rel(contributor, repo, "Authors and reviews architecture artifacts")

Minimal container snippet:

C4Container
  Person(contributor, "Contributor or agent")
  System_Boundary(repo, "Project repository") {
    Container(skills, "Canonical skills", "Markdown", "Authoring source")
    Container(templates, "Architecture templates", "Markdown/Mermaid", "Scaffolds architecture packages")
  }
  Rel(contributor, skills, "Updates")
  Rel(skills, templates, "References")

Keep diagrams small and accurate. Prefer multiple focused diagrams over one unreadable diagram.

ADR Triggers

Create an ADR when the change introduces or revises a durable architecture decision, including:

• system boundary changes
• adapter generation or packaging rules
• validation architecture
• cache or indexing strategy
• portability constraints
• release architecture
• major workflow architecture decisions

Use the ADR skeleton and store real ADRs under docs/adr/. Each ADR includes title, status, context, decision, alternatives considered, consequences, and follow-up.

Accepted or active ADRs are decision history. Later changes should supersede or deprecate an old ADR with a new ADR or explicit lifecycle update rather than rewriting the old decision as if it had always been different.

Authoring Rules

• Update only the arc42 sections and C4 views the change actually affects.
• Put accepted durable architecture truth in the canonical package before an architecture-significant change is complete.
• Keep legacy docs/architecture/ documents as legacy or historical context until the legacy normalization artifact classifies them.
• Do not write an execution milestone list here; use plan after design review.
• Do not hide tradeoffs.
• Do not introduce architecture that the spec does not require.
• Do not change behavior in the architecture doc without updating the spec.
• Do not claim compatibility, rollback, or performance safety without explaining the mechanism.
• Do not use reviewed as a durable architecture status. Once the design is relied on, normalize the tracked artifact to approved or the appropriate terminal state.
• Preserve Next artifacts as planning history. Use Follow-on artifacts for actual downstream artifacts, replacement, or terminal closeout.
• If an architecture document is superseded, identify the replacement with superseded_by or equivalent labeled text.
• Do not include secrets, credentials, private keys, tokens, or machine-local debug-only data.

Evidence Collection Efficiency

Use summary and stable-ID first reasoning before broad reads or raw excerpts. Prefer check IDs, requirement IDs, section numbers, ADR IDs, diagram paths, file paths, and line citations. Read exact sections first, then expand only when the narrower evidence cannot answer the architecture question.

Workflow handoff behavior

• In a workflow-managed flow, successful architecture completion hands off to architecture-review when that review is the next mandatory or triggered downstream stage.
• If the design still has open questions that block safe review, stop and report the blocker instead of implying architecture-review can proceed.
• Only the explicitly armed workflow-managed authoring-through-plan-review profile can continue after the matching architecture-review, and that continuation depends on a clean recorded review and no stop condition.
• This v1 contract does not otherwise imply architecture-review -> plan; other review-to-next-authoring transitions remain outside the autoprogression boundary unless a later approved change adds them.

When full-file read is required

Read the full file when creating or replacing the canonical architecture package, when the whole file is the review target, when checking all 12 arc42 headings or lifecycle metadata, when a canonical update may affect multiple sections, when superseding or deprecating an ADR, when legacy status affects the conclusion, when the relevant section cannot be isolated safely, when bounded searches disagree, or when a behavior-changing edit depends on the whole source-of-truth artifact.

Expected output

Start with:

## Result

- Architecture surface: no-impact-rationale | canonical-update | ADR | blocked
- Canonical architecture changed:
- Diagrams changed:
- ADRs created or updated:
- Direction/spec blockers:
- Next stage:

Then include:

• changed arc42 sections and C4 diagram paths;
• requirement-to-architecture mapping;
• ADR paths for durable decisions, or a clear no-ADR-required rationale;
• alternatives, consequences, risks, quality concerns, deployment impact, and security/privacy notes where relevant;
• readiness statement for architecture-review or blocker state.