---
name: project-architecture
description: Use when creating or reviewing architecture docs after a PRD exists or when architecture decisions need stable IDs and traceability to requirements.
---

# Project Architecture

Use this skill to design architecture that maps back to PRD requirements.

## Rules

- Create or update the canonical `.prd_plugin/state/artifacts/architecture/<artifact-id>.json`.
- Generate Markdown only on explicit human request.
- Use `ARCH-COMP-*` for components.
- Use `ARCH-DEC-*` for architecture decisions.
- Use `ARCH-IF-*` for interfaces and integration boundaries.
- Use `ARCH-RISK-*` for architecture risks.
- Every major component or decision should cite `PRD-*` or `DEC-*` sources.
- Route unproven architecture lessons, critical-path fixes, and regressions
  through a `DBR-*` document branch before changing mainline architecture docs.
- When architecture decisions should be agent-queryable, update or propose
  `.prd_plugin/state/decisions.json` records that cite the matching
  `ARCH-DEC-*` or `DEC-*` IDs.
- When architecture changes affect active work or project direction, update or
  propose `TRK-*` and `CHG-*` records with `AGENT-*` / `SES-*` provenance.
- Create or update `HLT-*` health findings when architecture items are unmapped,
  risky without mitigation, or missing validation strategy.
- Link accepted `REQ-*` records when architecture incorporates request-intake
  work.

## Staleness Coverage

Apply the shared policy in `.prd_plugin/method/staleness-rules.md`.


Before changing mainline architecture, review existing open or stale `HLT-*`,
`TRK-*`, `REQ-*`, and `DBR-*` records that reference the affected architecture
IDs. Resolve, refresh, or explicitly leave stale findings open with a reason.

## Canonical Format

JSON/JSONL is canonical for planning artifacts. Keep the architecture JSON
compact: component IDs, interface IDs, decision IDs, risk IDs, requirement
links, validation strategy, stale follow-ups, and implementation mappings.
Markdown exports are human snapshots only and must not be edited as project
truth.

## Required Sections

1. Artifact metadata
2. Agent summary
3. Context
4. Principles
5. Components
6. Interfaces
7. Data/state model
8. Decisions
9. Risks
10. Validation strategy
11. Traceability map
12. State updates, if applicable

## Review Checklist

- Components have clear responsibilities.
- Interfaces define producer, consumer, and contract.
- Decisions explain tradeoffs.
- Risks have mitigation or explicit acceptance.
- Architecture deltas from document branches include evidence and regression
  conditions before promotion.
- Memory, decision-index, tracking, or changelog updates cite their source
  architecture IDs.
- Relevant `HLT-*` findings are created, resolved, or left open with a reason.
- Accepted `REQ-*` records that affect architecture are linked or graduated.