4.9 KiB
Design
Derived from:
{brief path}@ sha256{first 12 hex of the brief's sha256}· ceremony: architectural
Architecture
The modules this change adds or alters, and what each one owns. Judge each by the deletion test: if deleting the module would only move its complexity into its callers, it earns its place; a deep module hides much behind a small interface. Name the seams where behaviour can be tested or swapped.
Data Flow
How data enters, moves through and leaves the changed modules — one path per use case in the brief, in order.
Interfaces
Every boundary this plan creates or changes: signature, inputs, outputs,
errors. Steps cite these in Interface in: / Interface out:.
Data Models
Types, schemas, files and their fields. Mark what is new and what changes shape.
Error Handling
Each failure mode, what the system does about it, and what the user sees. Unreadable input, a missing dependency and a partial failure are always listed.
Module Map
Dependencies point one way. The validator rejects a cycle.
graph TD
cli[src/cli] --> core[src/core]
core --> store[src/store]
Architecture Rules
Each rule names what enforces it. checked by <command> — a command the
target repo already has (its own dependency-cruiser, import-linter, linter or a
test); lib/verification/arch-rules.mjs runs dependency-cruiser and
import-linter when the repo configures them, and installs nothing. advisory —
.claude/rules/<file>.md — guidance Claude Code loads in the target repo; a
plan step writes that file. A checked rule is accepted only once it has been
seen to pass, fail on a planted violation, and pass again: the Proof column
names the step that shows it (arch-rules.mjs --prove --rule <name> --plant <file>=<dest> does it in one command for the two supported tools; the planted
run must trip that rule).
| Rule | Enforced by | Proof |
|---|---|---|
| {core never imports cli} | checked by {node_modules/.bin/depcruise --config .dependency-cruiser.cjs src} |
Step {N} |
| {prefer pure functions in core} | advisory — .claude/rules/{core}.md |
— |
Requirements Check
Conflicts and gaps between the brief's requirements, each asked once as a
two-choice question with the recommendation first: keep (the requirement as
written) or change like this (a concrete proposal). Record the answer here.
An answer that changes the brief's Intent, Goal or Success Criteria stops the
plan: the brief is re-run through /trekbrief, never edited by the planner.
| # | Finding | Question | Answer |
|---|---|---|---|
| 1 | {two requirements that cannot both hold / a case no requirement covers} | Keep, or change like this: {proposal}? | {keep / change} |
If there is nothing to ask, write "No conflicts or gaps found" and say what was compared.
Decisions (ADR)
Optional. Only for a decision that is hard to reverse, surprising without context, AND the result of a real trade-off. One paragraph each: context, decision, alternatives rejected and why.
Gotchas
Optional. Each place two constraints collide, the risky call made there, and who decided it.