@tduyng/pi-devos 0.0.0-stage → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. package/CHANGELOG.md +1421 -0
  2. package/LICENSE +201 -0
  3. package/README.md +206 -2
  4. package/package.json +44 -4
  5. package/plugins/devos/agents/reader.md +27 -0
  6. package/plugins/devos/agents/verifier.md +155 -0
  7. package/plugins/devos/pi/extension/devos.ts +605 -0
  8. package/plugins/devos/scripts/check-evidence-router.sh +140 -0
  9. package/plugins/devos/scripts/evidence-router.py +254 -0
  10. package/plugins/devos/scripts/gates/check-dod-core.sh +285 -0
  11. package/plugins/devos/scripts/gates/check-dod.sh +38 -0
  12. package/plugins/devos/scripts/gates/check-implementation-boundary.sh +99 -0
  13. package/plugins/devos/scripts/gates/check-port-source.sh +134 -0
  14. package/plugins/devos/scripts/gates/check-report-locations.sh +148 -0
  15. package/plugins/devos/scripts/gates/check-scenario-coverage.sh +104 -0
  16. package/plugins/devos/scripts/gates/gate-check.mjs +204 -0
  17. package/plugins/devos/scripts/gates/phase-gate.sh +208 -0
  18. package/plugins/devos/scripts/gates/plan-template-check.py +141 -0
  19. package/plugins/devos/scripts/gates/run-gate.sh +148 -0
  20. package/plugins/devos/scripts/gates/spec-contract.sh +19 -0
  21. package/plugins/devos/scripts/gates/spec-template-check.py +152 -0
  22. package/plugins/devos/scripts/gates/suite/01-dod.sh +485 -0
  23. package/plugins/devos/scripts/gates/suite/02-integrity.sh +310 -0
  24. package/plugins/devos/scripts/gates/suite/03-archetype.sh +255 -0
  25. package/plugins/devos/scripts/gates/suite/04-spec-validator.sh +183 -0
  26. package/plugins/devos/scripts/gates/suite/05-requires.sh +360 -0
  27. package/plugins/devos/scripts/gates/suite/06-clarify-adapters.sh +435 -0
  28. package/plugins/devos/scripts/gates/suite/07-lint-evals.sh +350 -0
  29. package/plugins/devos/scripts/gates/suite/08-converge.sh +591 -0
  30. package/plugins/devos/scripts/gates/suite/09-quality.sh +516 -0
  31. package/plugins/devos/scripts/gates/suite/10-eval-harness.sh +679 -0
  32. package/plugins/devos/scripts/gates/test-gates.sh +76 -0
  33. package/plugins/devos/scripts/gates/test-integrity-rubric.sh +152 -0
  34. package/plugins/devos/scripts/gates/test-phase-gate.sh +116 -0
  35. package/plugins/devos/skills/absorb/SKILL.md +75 -0
  36. package/plugins/devos/skills/absorb/references/distill.md +67 -0
  37. package/plugins/devos/skills/absorb/scripts/check-refs.sh +108 -0
  38. package/plugins/devos/skills/absorb/scripts/knowledge.py +258 -0
  39. package/plugins/devos/skills/build/SKILL.md +71 -0
  40. package/plugins/devos/skills/build/references/advanced-routing.md +19 -0
  41. package/plugins/devos/skills/build/references/defect.md +17 -0
  42. package/plugins/devos/skills/build/references/exposure.md +28 -0
  43. package/plugins/devos/skills/build/references/hard.md +39 -0
  44. package/plugins/devos/skills/build/references/refactor.md +66 -0
  45. package/plugins/devos/skills/build/references/routes.md +56 -0
  46. package/plugins/devos/skills/build/references/scale.md +84 -0
  47. package/plugins/devos/skills/build/references/spike.md +19 -0
  48. package/plugins/devos/skills/build/scripts/construct-census.py +204 -0
  49. package/plugins/devos/skills/build/scripts/dep-order.py +297 -0
  50. package/plugins/devos/skills/build/scripts/ledger.sh +228 -0
  51. package/plugins/devos/skills/build/scripts/route.sh +5 -0
  52. package/plugins/devos/skills/build/scripts/secret-scan.sh +121 -0
  53. package/plugins/devos/skills/build/scripts/toolchain-preflight.py +302 -0
  54. package/plugins/devos/skills/frame/SKILL.md +54 -0
  55. package/plugins/devos/skills/frame/references/template.md +115 -0
  56. package/plugins/devos/skills/frame/scripts/survey.sh +44 -0
  57. package/plugins/devos/skills/implement/SKILL.md +36 -0
  58. package/plugins/devos/skills/implement/references/conditional-plan.md +17 -0
  59. package/plugins/devos/skills/implement/references/debug-loop.md +7 -0
  60. package/plugins/devos/skills/implement/references/dod.md +37 -0
  61. package/plugins/devos/skills/implement/references/implement.md +54 -0
  62. package/plugins/devos/skills/implement/references/manual-gates.md +16 -0
  63. package/plugins/devos/skills/implement/references/plan.md +142 -0
  64. package/plugins/devos/skills/implement/references/resume.md +9 -0
  65. package/plugins/devos/skills/implement/references/scale.md +86 -0
  66. package/plugins/devos/skills/implement/references/verify-close.md +62 -0
  67. package/plugins/devos/skills/implement/references/visual-verification.md +7 -0
  68. package/plugins/devos/skills/implement/scripts/check-converge.sh +147 -0
  69. package/plugins/devos/skills/implement/scripts/equivalence-check.sh +140 -0
  70. package/plugins/devos/skills/implement/scripts/manifest-queue.sh +185 -0
  71. package/plugins/devos/skills/implement/scripts/ops-log.sh +58 -0
  72. package/plugins/devos/skills/implement/scripts/pilot-consistency.py +173 -0
  73. package/plugins/devos/skills/implement/scripts/validate-spec.sh +220 -0
  74. package/plugins/devos/skills/init/SKILL.md +100 -0
  75. package/plugins/devos/skills/init/references/archetype-sections.md +15 -0
  76. package/plugins/devos/skills/init/references/context.md +42 -0
  77. package/plugins/devos/skills/init/references/conventions-template.md +153 -0
  78. package/plugins/devos/skills/init/references/reverse-engineer.md +3 -0
  79. package/plugins/devos/skills/init/references/rule-format.md +58 -0
  80. package/plugins/devos/skills/init/references/shape-model.md +29 -0
  81. package/plugins/devos/skills/init/scripts/detect-archetype.py +461 -0
  82. package/plugins/devos/skills/init/scripts/render-rule.py +114 -0
  83. package/plugins/devos/skills/init/scripts/reverse-engineer.sh +162 -0
  84. package/plugins/devos/skills/learn/SKILL.md +29 -0
  85. package/plugins/devos/skills/learn/references/destinations.md +43 -0
  86. package/plugins/devos/skills/learn/references/scoring.md +26 -0
  87. package/plugins/devos/skills/review/SKILL.md +54 -0
  88. package/plugins/devos/skills/review/references/comments.md +13 -0
  89. package/plugins/devos/skills/review/references/gaps.md +26 -0
  90. package/plugins/devos/skills/review/references/reviewer.md +124 -0
  91. package/plugins/devos/skills/review/references/routing.md +35 -0
  92. package/plugins/devos/skills/review/scripts/__pycache__/prepare.cpython-313.pyc +0 -0
  93. package/plugins/devos/skills/review/scripts/prepare.py +763 -0
  94. package/plugins/devos/skills/spec/SKILL.md +57 -0
  95. package/plugins/devos/skills/spec/references/prototype.md +21 -0
  96. package/plugins/devos/skills/spec/references/question-craft.md +47 -0
  97. package/plugins/devos/skills/spec/references/roadmap-link.md +5 -0
  98. package/plugins/devos/skills/spec/references/write-spec.md +128 -0
  99. package/plugins/devos/skills/spec/scripts/clarify.sh +173 -0
  100. package/plugins/devos/skills/status/SKILL.md +67 -0
  101. package/plugins/devos/skills/status/references/cost.md +38 -0
  102. package/plugins/devos/skills/status/scripts/artifact-budgets.sh +88 -0
  103. package/plugins/devos/skills/status/scripts/check-requires.py +556 -0
  104. package/plugins/devos/skills/status/scripts/context-cost.sh +89 -0
  105. package/plugins/devos/skills/status/scripts/convention-usage.sh +184 -0
  106. package/plugins/devos/skills/status/scripts/findings-summary.sh +112 -0
  107. package/plugins/devos/skills/status/scripts/quality-correlation.sh +259 -0
  108. package/plugins/devos/skills/status/scripts/sizing-calibration.sh +71 -0
  109. package/plugins/devos/skills/status/scripts/spec-diff.sh +137 -0
@@ -0,0 +1,153 @@
1
+ ---
2
+ devos-contract: 1
3
+ ---
4
+ # Project Conventions
5
+
6
+ Choices this project has made. The agent already knows general best practices; this file only records what it can't guess. Filled in by `/devos:init` or by hand; every line here is a decision, not advice. Delete sections that don't apply.
7
+
8
+ > Tip: a convention that only applies to certain files (e.g. "money is integer cents" in `billing/`) belongs in `devos/standards/rules/` instead, so it auto-attaches when a matching file is edited rather than sitting here unread. `/devos:init` drafts these for you; see `${CLAUDE_PLUGIN_ROOT}/skills/init/references/rule-format.md` for the format (`globs:`, not `paths:`, the documented `paths:` frontmatter is a confirmed Claude Code bug that silently no-ops). Keep this file for project-wide choices with no file glob to attach to.
9
+
10
+ ## Verification commands
11
+
12
+ The commands that prove this project works: the verifier runs these as its primary quality check, whatever shape the project has (test runner, site-generator build, headless editor load, linter). One per line, with the expected result. **Every declared command gets run and reported by name** — a check that belongs here and isn't listed is a check that silently never runs, which is why `detect-archetype.py --facts` lists them mechanically instead of leaving it to inference.
13
+
14
+ - `npm test`: exit 0
15
+ - <!-- The --facts check table already covers every runner it can read: package.json scripts (through the lockfile's own package manager), justfile recipes, Makefile targets. Copy those rows in and add what no manifest declares. -->
16
+ - <!-- Where the project has its own runner (`scripts/test.mjs unit`, a bash entry point, a container-only suite), record the command the project's CI actually invokes, not the underlying tool. -->
17
+ - <!-- Record where each command runs when it is not the host: `docker compose exec app pnpm test:func` (needs `docker compose up -d` first), `kubectl exec deploy/api -- pytest`, or "inside the devcontainer". A container-only suite written here as the bare command fails on the host for reasons that have nothing to do with the change, and the verifier reports that as a failing test. -->
18
+ <!-- Frontend/UI: `npm run test:a11y`, `npm run test:visual`, `npm run storybook:build` -->
19
+ <!-- Mobile: `flutter test`, `xcodebuild test`, `./gradlew test` -->
20
+ <!-- CLI: `cargo test`, `go test ./...`, `python -m pytest` -->
21
+ <!-- Data/ML: `dbt test`, `pytest`, `mlflow models validate` -->
22
+ <!-- Infra: `terraform validate`, `terraform plan`, `kubectl apply --dry-run` -->
23
+ <!-- Static analysis: `eslint .`, `ruff check .`, `clippy`, `golangci-lint run` -->
24
+ <!-- Build proof: `npm run build`, `cargo build --release`, `go build ./...` -->
25
+ - <!-- Replace with your project's proof, e.g. a static site: `zola build` exit 0, link checker clean; an editor config: `nvim --headless "+qa"` exit 0, `luacheck lua/` clean. No automated checks at all? Write "none", the verifier then reports honestly what it couldn't verify instead of guessing. -->
26
+
27
+ ## Preview command
28
+
29
+ How to start this project so it can be looked at, and the URL it serves. Without it, "drive the UI" is not an actionable instruction and every visual acceptance criterion reports UNVERIFIED by default — on the surface where the most defects are invisible to tests, lint and build.
30
+
31
+ - <!-- [inferred, confirm] e.g. `npm run dev`, serves http://localhost:5173. A project with no UI writes "none" and the verifier reports honestly instead of pretending. -->
32
+
33
+ ## Testing
34
+
35
+ - Coverage target: **80%+ on business logic** (not on glue/config)
36
+ - Test timing: critical paths during development; full coverage at feature completion, not per intermediate change
37
+ - Naming & location: `[name].test.ts` co-located | `tests/integration/[name].integration.test.ts` | `tests/e2e/[name].e2e.test.ts`
38
+ - Suite budgets: unit < 30s, integration < 2min, e2e < 10min
39
+
40
+ ## Local CI (before every push)
41
+
42
+ Lint → type-check (strict, no `any`) → tests → build. All green, fail-fast. No "fix CI" commits.
43
+
44
+ ## Commits
45
+
46
+ - Conventional commits (`feat:`, `fix:`, `chore:`); one logical change per commit; imperative subject ≤ 72 chars
47
+ - <!-- Replace with your policy: squash-merge? ticket ID in subject? signed commits? -->
48
+
49
+ ## Branching & workspace
50
+
51
+ Which branch the pipeline works on, and *where* it works: in this checkout, or in an isolated git worktree so this checkout stays yours while the agent implements.
52
+
53
+ - Spec branches: `[spec-name]` off the default branch. The pipeline never commits to the default branch
54
+ - Protected branches beyond the default: none <!-- e.g. `develop`, `release/*`: treated like the default branch, branch off them, never commit on them -->
55
+ - Workspace: default
56
+ - Workspace path: `.worktrees/`
57
+ - Workspace setup: none
58
+
59
+ **Workspace** takes exactly one of three values:
60
+
61
+ | Value | Meaning |
62
+ |---|---|
63
+ | `in-place` | Always implement in this checkout (unavailable to you while the agent works) |
64
+ | `default` | L specs get a worktree, S/M run in place |
65
+ | `worktree` | Every implementation runs in a worktree; this checkout stays free |
66
+
67
+ **Workspace path**: the folder worktrees are created in. Inside the repo by default (`.worktrees/`), so add that one line to `.gitignore`. Any directory works if you prefer them beside the checkout.
68
+
69
+ **Workspace setup**: free text, any shell command; it runs once inside each fresh worktree to make it runnable. `pnpm install --prefer-offline`, `npm ci`, `uv sync`, `bundle install`; chain a copy when the app needs untracked config. `none` = a fresh checkout already runs (Go, Cargo, plain scripts).
70
+
71
+ Filled example, a pnpm app whose owner always wants the checkout free:
72
+
73
+ - Workspace: worktree
74
+ - Workspace path: `.worktrees/`
75
+ - Workspace setup: `cp ../../myapp/.env . && pnpm install --prefer-offline`
76
+
77
+ ## Error handling
78
+
79
+ - Fail loud at boundaries (validate input, reject early); never swallow an exception without logging it
80
+ - <!-- Replace with your stance: error types vs codes? retry policy? user-facing message rules? -->
81
+
82
+ ## Dependencies
83
+
84
+ - Adding a dependency is a decision, not a default: prefer stdlib/existing deps; new ones need a one-line justification in the PR
85
+ - <!-- Add your rules: approved registries? license constraints? pinning policy? -->
86
+
87
+ ## Architecture
88
+
89
+ - Layered: Presentation → Application → Domain → Infrastructure; dependencies point inward, domain imports no framework
90
+ - <!-- Replace with your actual architecture if different (e.g. "Rails conventions, fat models thin controllers") -->
91
+
92
+ ## Performance budgets
93
+
94
+ - API p95 < 200ms; DB query p95 < 50ms; paginate every list endpoint
95
+ - Frontend: Lighthouse > 90, FCP < 1.5s, CLS < 0.1
96
+
97
+ ## API compatibility
98
+
99
+ - Breaking a published API/event requires: version bump or deprecation window (state yours: e.g. "2 releases"), affected consumers listed in the plan, migration note in the changelog
100
+ - <!-- Replace with your policy: semver? event schema registry rules? who signs off on breaking changes? -->
101
+
102
+ ## Product-specific rules
103
+
104
+ - No emoji characters in UI: use the project's icon library
105
+ - <!-- Add hard rules the agent can't infer: "all money amounts are integer cents", "user-facing text goes through i18n", "feature flags via LaunchDarkly only" -->
106
+
107
+ ## Design system / tokens
108
+
109
+ When a `design:*` or `style:*` archetype is detected, this section is **filled or explicitly emptied**, never left as this comment. "No design system declared; UI is improvised per feature" is a decision someone can see and revisit. A template comment is a decision nobody made, and the cost lands one feature at a time as each new screen matches neither of the last two.
110
+
111
+ Name the axes where "unspecified" silently resolves to a model default: **accent + neutral palette, corner-radius scale, spacing scale, shadow/elevation policy, density, type scale**. Each named value is checkable against a built screen later; "clean and modern" is not.
112
+
113
+ - <!-- [inferred, confirm] Token files, theme structure, extension process. Delete if not applicable. -->
114
+
115
+ ## Component conventions
116
+
117
+ - <!-- [inferred, confirm] Naming, folder structure, prop patterns, story vs unit vs visual test. Delete if not applicable. -->
118
+
119
+ ## Styling
120
+
121
+ - <!-- [inferred, confirm] Methodology, breakpoints, dark mode, motion. Delete if not applicable. -->
122
+
123
+ ## Accessibility
124
+
125
+ - <!-- [inferred, confirm] WCAG target, tooling, required patterns. Delete if not applicable. -->
126
+
127
+ ## Visual testing
128
+
129
+ - <!-- [inferred, confirm] Tool, baseline management, review process. Delete if not applicable. -->
130
+
131
+ ## Internationalization
132
+
133
+ - <!-- [inferred, confirm] Library, key naming, extraction. Delete if not applicable. -->
134
+
135
+ ## Data contracts
136
+
137
+ - <!-- [inferred, confirm] Schema location, migration policy, backfill process. Delete if not applicable. -->
138
+
139
+ ## CI & deploy topology
140
+
141
+ What the pipeline does, and which branch or tag reaches which environment. A plan that has to add a job, a stage, or a new environment reads this before writing one. Without it, the agent invents a single-branch pipeline that deploys nowhere real.
142
+
143
+ - <!-- [inferred, confirm] Pipeline file(s) and stage order, e.g. `.gitlab-ci.yml`: install → check → test → build → deploy → version -->
144
+ - <!-- [inferred, confirm] Branch/tag → environment matrix, one row per target, e.g. `main` → staging, `release` → prod, `v*.*.*` tag → prod release. Name the per-brand/per-tenant variants explicitly if the same code deploys several times. -->
145
+ - <!-- [inferred, confirm] Which steps are manual, which are gated on approval, and how a bad deploy is rolled back. -->
146
+
147
+ ## Infrastructure
148
+
149
+ - <!-- [inferred, confirm] Environment topology, secret handling, deploy gate. Delete if not applicable. -->
150
+
151
+ ## Vocabulary
152
+
153
+ Entity names come from `../product/domain-model.md`: code, specs, and docs use those names exactly.
@@ -0,0 +1,3 @@
1
+ # Reverse-engineer mode (init)
2
+
3
+ Brownfield only, and only when asked. Run `bash ${CLAUDE_SKILL_DIR}/scripts/reverse-engineer.sh` from the repo root. It clusters the trailing 6 months of git history by capability and writes one unreviewed spec stub per cluster into `devos/specs/archive/`. Deterministic, no model calls. Say how many stubs it wrote and that every one is **unreviewed seed material** for the behavior corpus and `/devos:status --compare`, never a work item, never promoted into active `devos/specs/`. Skip this on a greenfield repo: with no history to cluster it writes nothing useful.
@@ -0,0 +1,58 @@
1
+ # The rule layer
2
+
3
+ A scoped rule is a small, project-specific convention that a host tool auto-attaches when an edit touches a matching file, instead of sitting in `conventions.md` where nothing re-reads it at edit time. Lives at `devos/standards/rules/<NN>-<category>/<slug>.md`.
4
+
5
+ ## Authoring budget
6
+
7
+ - One topic per file. Bullets, not prose: a handful of bullets, a few words each.
8
+ - One tiny example only if it removes real ambiguity.
9
+ - Project-specific only: a rule exists because the codebase exhibits the convention, or the user declared it. Never a curated per-stack default, never general engineering practice the model already knows.
10
+ - No enforcement surface (nothing to glob)? It's documentation, not a rule: it stays in `conventions.md`, or is marked all-files below.
11
+ - A rule that exists because something broke ends with one `Source:` bullet naming what broke, in a clause. A rule with no scar is the one a future cleanup pass deletes as unexplained, and the deletion looks like tidying. Skip it when the rule just states a convention the codebase already visibly follows.
12
+ - Optional lifecycle frontmatter: `promoted: YYYY-MM-DD` when learn promoted it, and `superseded-by: <new-slug> (<date>)` when a later lesson contradicted it. A superseded rule is dead: kept as audit trail so the contradiction stays visible, never rendered to any tool. Delete nothing.
13
+
14
+ ## The category taxonomy (fixed, numbered; the number is the sort order)
15
+
16
+ | # | Category | Covers |
17
+ |---|---|---|
18
+ | 00 | architecture | layering, module boundaries, API shape |
19
+ | 01 | standards | naming, imports/exports, formatting the linter doesn't own |
20
+ | 02 | languages | language-specific rules (strict mode, a banned pattern) |
21
+ | 03 | frameworks | framework/library-specific conventions |
22
+ | 04 | tooling | build, CI, git hooks |
23
+ | 05 | testing | fixtures, mocking, coverage rules beyond what's in `conventions.md` |
24
+ | 06 | patterns | design patterns this codebase actually uses |
25
+ | 07 | quality | perf and security rules specific to this project |
26
+ | 08 | domain | business-logic rules (money handling, a domain invariant) |
27
+ | 09 | other | anything that doesn't fit above |
28
+
29
+ Place a new rule in the lowest-numbered category it fits (a language-specific rule is `02`, not `09`); when two apply, the more specific number wins (`03` frameworks over `01` standards).
30
+
31
+ ## Canonical file format
32
+
33
+ The source format is Claude Code's own, since it needs no transform. **Use `globs:`, not `paths:`**: Claude Code's documented `paths:` frontmatter is a confirmed bug (silently ignored, no error) as of this writing; `globs:` is the field that actually loads (bare, comma-separated, not a YAML list). Cite this reasoning if a future Claude Code release fixes `paths:` and this needs revisiting.
34
+
35
+ ```markdown
36
+ ---
37
+ globs: src/billing/**/*.ts, src/billing/**/*.test.ts
38
+ ---
39
+ # Money handling
40
+ - All monetary amounts are integer cents, never floats
41
+ - Currency conversion happens only in `billing/convert.ts`
42
+ - Source: float rounding on a refund path shipped a 1-cent discrepancy to production
43
+ ```
44
+
45
+ `Source:` is a body bullet, not frontmatter, so it renders to every tool alongside the rule it explains.
46
+
47
+ An all-files rule (no glob to scope it) omits `globs:` entirely; a tool that requires the field for auto-attach falls back to loading it as part of the always-loaded context instead (documented per-tool below).
48
+
49
+ ## Rendering to other tools
50
+
51
+ `${CLAUDE_SKILL_DIR}/scripts/render-rule.py` (shipped with this skill) takes one canonical rule file and writes Copilot CLI's native equivalent when a `.github/` directory is present:
52
+
53
+ | Tool | Output | Format |
54
+ |---|---|---|
55
+ | Copilot CLI | `.github/instructions/<NN>-<slug>.instructions.md` | `applyTo: "pattern,pattern"` (quoted, comma-separated) |
56
+ | Claude Code, Codex CLI, OpenCode, Pi | no render step | the canonical file is read where it lives, or folded into `AGENTS.md` by `/devos:init` |
57
+
58
+ Codex/OpenCode/Pi's lack of a rules surface is a real, stated gap, not faked: `init` lists active rule files there so the convention is still visible, just always-loaded rather than glob-attached.
@@ -0,0 +1,29 @@
1
+ # Workflow: shape the domain model
2
+
3
+ **Output:** `devos/product/domain-model.md`. Sources and output rules are in `SKILL.md`; this file is the interaction and the format.
4
+
5
+ The one-page cap is a hard limit, not a style note: nearly every spec, plan, verification and doc prompt loads this file, so every line here is paid for on almost every command. Concretely, ~60 lines. Past it, cut descriptions; never split into a second file.
6
+
7
+ Run in the main agent. Every step below waits on the user.
8
+
9
+ 1. **Check for an existing model.** If `domain-model.md` exists, list its entities and ask whether to enrich it. Enrichment merges: existing entities keep their descriptions verbatim, new ones append. Recreating a validated model throws away wording the user already chose, which reads as progress and is a regression.
10
+ 2. **Propose.** Name the entities the sources show, one line each, then ask what to add, remove, or rename. **Wait.** Correcting a proposal is faster for the user than composing from a blank page, the same reason the spec interview attaches a guess to each question.
11
+ 3. **Refine.** One batched round of structured questions (use the harness's tool if it has one) for what the proposal left open: entities users create or manage that you missed, the two or three pieces of information that matter per entity, and how entities relate. **Wait.**
12
+ 4. **Confirm, then write.** Show entities and relationships, iterate until the user validates, then write:
13
+
14
+ ```markdown
15
+ # Domain Model
16
+
17
+ ## Entities
18
+
19
+ ### [EntityName]
20
+ [What it represents, in language a non-technical reader follows.]
21
+
22
+ ## Relationships
23
+
24
+ - [Entity1] has many [Entity2]
25
+ - [Entity2] belongs to [Entity1]
26
+ - [Entity3] links [Entity1] and [Entity4]
27
+ ```
28
+
29
+ Two rules from `SKILL.md` are worth their reason here. Entity names are **singular**: specs, plans, tests and review findings all quote these names exactly, so a plural propagates into every one of them and vocabulary drift becomes a review finding later. Relationships stay **conceptual** (`has many`, `belongs to`, `links X and Y`): the moment this file carries cardinalities or foreign keys it is a schema, and a schema goes stale against the database while a vocabulary does not.