115 lines
4.9 KiB
Markdown
115 lines
4.9 KiB
Markdown
<!--
|
|
The design part of a plan (plan_version 1.8 or later). /trekplan Phase 8 writes it as
|
|
the plan's `## Design` section, between `## Context` and
|
|
`## Implementation Plan`, ONLY when the brief's `ceremony:` is
|
|
`architectural` (an absent field means architectural: heaviest on doubt).
|
|
`small` and `bounded` plans omit it.
|
|
|
|
The design lives in the PLAN, never in the brief: the brief format is a public
|
|
contract (Handover 1), the plan contract is Voyage's own (Handover 4).
|
|
|
|
`plan-validator --strict` checks, for an architectural plan at plan_version
|
|
1.8 or later: the eight
|
|
`###` subsections below exist, the module map is a mermaid graph with no
|
|
cycle, every architecture rule names its enforcer, a checked rule names the
|
|
step that proves it, and an advisory rule names its `.claude/rules/` file.
|
|
`### Decisions (ADR)` and `### Gotchas` are optional.
|
|
|
|
Borrowed, with credit:
|
|
- Section list: Kiro's design.md (architecture, data flow, interfaces, data
|
|
models, error handling, test strategy), and its requirements analysis asked
|
|
as two-choice questions. Kiro's SMT engine is not borrowed.
|
|
- Design questions: obra/superpowers@8ca22db brainstorming (MIT, © 2025 Jesse
|
|
Vincent).
|
|
- Module map with one dependency direction and no cycles, and "use the
|
|
de-facto tool" (e.g. dependency-cruiser): addyosmani/agent-skills@9d0c60d
|
|
(MIT, © 2025 Addy Osmani).
|
|
- Vocabulary (deep module, seam, deletion test), the three-condition ADR bar,
|
|
and pass → fail → pass: mattpocock/skills@c55ee46 (MIT, © 2026 Matt Pocock).
|
|
- Rules that must pass: GitHub Spec Kit's constitution (MIT), changed so each
|
|
rule names what enforces it; in Spec Kit the model ticks the boxes itself.
|
|
- Gotchas and "Derived from <hash>": bashebr/ai-native-sdlc@11fb8d7 (MIT).
|
|
-->
|
|
|
|
## 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.
|
|
|
|
```mermaid
|
|
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.
|