spec ยท diff
git:20261115.2e7260d to git:20261115.0326cb7
17 added, 54 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: spec
- description: "Use when a request leaves done, data, architecture or a trade-off open. When a new visual surface does not name its data or behavior, spec decides those first; design-ui follows for presentation. Not for a clear goal, a failure, or visual-only work."
+ description: "Shapes a request into a brief: the decisions only the user can make, then a plan of tasks that each carry a proof command. Use when the user asks to plan or spec a change ('plan this', 'write a spec'), when a request leaves done, data, architecture or a trade-off open, or the user asks for options or ideas. Not for a clear goal, a failure, or visual-only work."
argument-hint: <outcome to shape>
---
- # Shaping
+ # Spec
- Shaping turns a request into a brief that settles what done means, so the build starts with no open decision.
+ Spec settles every decision the user would notice before any code is written, so the build runs without stopping to ask.
## Steps
- 1. **Gate.**
- - First invoke every installed non-`exo:` skill matching the request.
- - Spec ends on a brief unless the verdict is `stop`; with no open decision the brief still gets written.
- - Open with the verdict. An open decision is one the user would notice that neither request nor code settles.
- - Fast route: under three files with a known proof, skip questions, plan and gate; one worktree worker per build `## No spec`.
- - Read `references/verdict.md` for the no-question case.
- - When the user asked for options, follow `references/architecture-sketch.md` and write no file.
- 2. **Sort each point.**
- - When running or reading code answers a point, record it; ask nothing.
- - Each open decision passes `## When to ask`. A plain product choice only the user can make becomes a question, root first; exo decides any other.
- - A decision the user left open stays open whatever the code does.
- - Name the owning layer and a smaller option.
- 3. **Ask one at a time.**
- - Ask per `../../lib/references/question.md`, and record each choice exo decides in Decisions.
- - Read `references/step-rules.md` for recommendations and the `Land:` question.
- - After the last answer, write the brief with no recap and no yes question.
- 4. **Dispatch steps 4 and 5 as one `exo:orchestrator` part** with `Workers: 1`, `Reads: none` and a Result file under `.exo/`. It runs:
- - `node "${CLAUDE_SKILL_DIR}/scripts/repo-map.mjs"`, then `references/step-rules.md`.
- - List tasks per `references/task-list.md`, `references/brief.md` and `references/templates.md`; store per `references/brief.md`.
- - `node "${CLAUDE_SKILL_DIR}/scripts/plan-check.mjs" --plan <brief file> --root <checkout root> --loop`; fix flagged lines and any missing heading, `Data:`, Success criterion or `## Manual checks`.
- - Open points per `references/brief.md` `## Open points step`, then rerun plan-check; leave flagged `## Open points` unfixed.
- 5. **Hand off** per `references/hand-off.md`.
-
- ## References
-
- | File | Read it when |
- |---|---|
- | `references/stored-brief.md` | Request names or extends a brief, issue or plan. |
- | `../../lib/references/question.md` | Each question and reply. |
- | `references/brief.md` | Before writing the brief; step 4. |
- | `references/task-list.md` | Before writing the task list. |
- | `references/example-plan.md` | Before the first task. |
- | `references/templates.md` | Step 4. |
- | `../build/references/data-migration.md` | When its first line applies. |
- | `../build/references/test-design.md` | When its first line applies. |
- | `../build/references/security.md` | When its first line applies. |
- | `references/brief-in-an-issue.md` | `specs` is `issues` or `both`. |
- | `../ship/references/fields.md` | Before creating that issue. |
- | `references/architecture-sketch.md` | Two or more structural shapes compete. |
- | `../../docs/principles/README.md` | Request adds or changes an LLM agent, its prompt, tools or loop. |
- | `references/verdict.md` | Step 1. |
- | `references/step-rules.md` | Steps 1, 3, 4, mode `research`. |
- | `references/hand-off.md` | Step 5. |
- | `references/watching.md` | Step 5, run started. |
- | `references/research.md` | Mode `research`. |
- | `references/sources.md` | Mode `research`. |
- | `references/verification.md` | Mode `research`. |
- | `references/worker-modes.md` | Mode `research`. |
- | `references/ideate.md` | Mode `ideate`. |
-
- Report: the brief file to open, next stage or question.
+ 1. **Verdict.** State `Verdict: go`, `clarify` or `stop`, and `Objection:`, the likeliest reason the work fails or is not worth doing, backed by code or an existing tool. `clarify` asks the one question that makes it `go`; `stop` writes no brief and names what already covers the request.
+ - Fast route: under three files with a known proof, skip questions and plan; `exo:build` edits directly.
+ - The user asked for options or ideas: follow `references/architecture-sketch.md` instead of the steps below; its draw command is `node "${CLAUDE_SKILL_DIR}/scripts/draw-seats.mjs"`.
+ 2. **Find the open decisions.** Run `node "${CLAUDE_SKILL_DIR}/scripts/repo-map.mjs"` and search its output with `grep -n`. For ranges it omits, send up to four `exo:researcher` agents (`Sources: repo`) and one (`Sources: docs`) for outside facts in one background message. Record what code answers; ask none of it.
+ 3. **Ask one at a time.** Ask only for a preference or product outcome only the user knows, where a wrong guess is costly to undo. Take a safe default silently, recorded in Decisions ending `(exo decided)`. Each question: a bold title ending in `?`, two or three lines `- **(A) Label**: what the user gets`, then `Recommended: (A), because <reason>`. `ok` or a second "I don't know" takes the recommendation. A decision the user left open stays open.
+ 4. **Write the brief** in the shape of `references/example-plan.md`. Read the `specs` setting with `node --input-type=module -e "import { settingValue } from '${CLAUDE_PLUGIN_ROOT}/lib/settings-store.mjs'; console.log(settingValue('specs'))"`, store the brief where it prints, and name the place:
+ - `docs`: `docs/specs/<topic>.md`, gitignored, so never `git add` it. In plan mode, the harness plan file.
+ - `issues`: one GitHub issue whose body opens `<!-- exo:spec -->`, with only labels and fields the repository already defines; build reads its copy at `node "${CLAUDE_PLUGIN_ROOT}/lib/scratch-path.mjs" specs/<n>.md`. With no GitHub `origin` or a failing `gh auth status`, write the file and say so.
+ - `both`: the file, then the issue naming it; the file wins when they differ.
+ - New wishes for an outcome that already has a brief (a `#<n>`, path, branch handoff, `<!-- exo:spec -->` issue or `docs/specs/` file) edit that brief in place, and its decisions stay closed unless the wishes contradict them.
+ - `node "${CLAUDE_SKILL_DIR}/scripts/plan-template.mjs" done --plan <brief> --root <root>` chains the commands of the project's definition-of-done file onto the Success criterion.
+ 5. **Check it.** Run `node "${CLAUDE_SKILL_DIR}/scripts/plan-check.mjs" --plan <brief>` and `node "${CLAUDE_SKILL_DIR}/scripts/verdict-check.mjs" --plan <brief>` and fix what they flag.
+ 6. **Open points.** Unless the plan has at most 3 tasks with static proofs, dispatch `exo:researcher` (`Sources: repo`) in the background with the brief path, to read it as a builder who cannot ask anyone and list each point where a wrong guess changes the build as `code` (answer and `path:line`), `assume` (cheap to undo) or `user`. Put `code` and `assume` points under `## Assumptions`, ask each `user` point as in step 3, and list an unanswered one under `## Open points`, which `plan-check.mjs` refuses. Then rerun step 5.
+ 7. **Hand off.** Invoked by another stage: return without asking. In plan mode, plan approval is the reply. Else show the brief path or `#<n>`, say that `exo:build` runs it next and start nothing before the reply. On `ok`, invoke `exo:build` with the brief path; on a change, edit the brief, rerun step 5 and ask again.