spec · git:20261106.d8327ee · 2026-11-06 · sha256 246d7e4c92134205

spec git:20261106.d8327eeA

Immutable. This exact content never changes and is served at /api/v1/blob/246d7e4c92134205.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_q3t75u3buoih5r3y/246d7e4c92134205276bf77e987f34fc8a105fb85ab30e610d31e9eb5078cd82.json

Then /plugin install spec@markdownregistry-q3t75u3buoih5r3y in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
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."
argument-hint: <outcome to shape>
---

# Shaping

Shaping turns a request into a brief that settles what done means, so the build starts with no open decision.

## Steps

1. **Gate.**
   - First invoke every installed non-`exo:` skill matching the request.
   - Spec always ends on a brief; 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.
   - When the diff fits one sentence or code settles every point, ask no question and let exo close each choice.
   - Ask only per `../route-skills/references/question.md` `## When to ask`.
   - 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 and 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 alternative.
3. **Ask one at a time.**
   - Ask per `../route-skills/references/question.md`, and record each choice exo decides in Decisions.
   - Recommend a loaded skill's pattern over one it rules out.
   - Plan approval approves only the `Land:` mode, so ask about it only when `ship` is `ask`.
   - With no git repo or no `origin`, write `Land: local` and ask nothing.
   - After the last answer, write the brief with no recap and no yes question.
4. **Map, then locate.**
   - Run `node "${CLAUDE_SKILL_DIR}/scripts/repo-map.mjs"`, in plan mode too.
   - In one background message dispatch up to eight `exo:locate-code` agents for ranges the map omits and one `exo:fetch-docs` round for outside facts. Read none of their output, fill no gap; use results on each completion, no polling or sleep.
   - Search the map with `grep -n`; never read it.
5. **List tasks** per `references/task-list.md`, `references/brief.md` and `references/templates.md`.
6. **Store it** per `references/brief.md`.
7. **Check it.** Run `node "${CLAUDE_SKILL_DIR}/scripts/plan-check.mjs" --plan <brief file> --root <checkout root> --loop`. Fix the flagged lines and any missing heading, `Data:`, Success criterion or `## Manual checks`.
8. **Find open points** per `references/brief.md` `## Open points step`. Rerun step 7 and leave the flagged `## Open points` unfixed.
9. **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. |
| `../route-skills/references/question.md` | Each question and reply. |
| `references/brief.md` | Before writing the brief; step 8. |
| `references/task-list.md` | Before writing the task list. |
| `references/example-plan.md` | Once, before the first task. |
| `references/templates.md` | Step 5. |
| `../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`. |
| `../file-issues/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 AI agent or LLM worker, its prompt, tools or loop. |
| `references/verdict.md` | Step 1. |
| `references/hand-off.md` | Step 9. |
| `references/watching.md` | Step 9, run started. |
| `references/measured-goal.md` | Goal is a measured score, cost or time on a task set. |

Report: brief location and next stage, or question.