shape · git:20260723.7a5ade6 · 2026-07-23 · sha256 c5d46e7bbccdb3f7
shape git:20260723.7a5ade6A
Immutable. This exact content never changes and is served at /api/v1/blob/c5d46e7bbccdb3f7.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_5oqbjovdj2z33bui/c5d46e7bbccdb3f7bd4ac497862a1d00eba1fce0bb43e64872331a1b616c4169.json
Then /plugin install shape@markdownregistry-5oqbjovdj2z33bui 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: shape
description: Use when turning a fuzzy idea, a position to stress-test, or a set of already-clear requirements into a written spec — grill mode tests a position, explore mode is open-ended, synthesis mode drafts straight from clear requirements. Invoke via route or explicit command.
---
# shape
Turns an idea into a spec file. Three entry modes reach the same exit: a written
spec, self-reviewed, waiting on approval. Route hands you a mode directly
(`shape-synthesis`, `shape-grill`, `shape-explore`, `shape-wayfinder`); a request
that names a mode itself — "grill me", "requirements are settled" — picks the mode
the same way.
## Picking a mode, if not already told
- A position exists and needs stress-testing → grill.
- Open-ended, no position yet → explore.
- Requirements are already clear enough to state → synthesis.
- The topic won't resolve in one sitting → wayfinder (below).
## Grill
Stress-tests a position someone already holds.
1. Build a decision tree of the open questions, ordered by dependency: which
decisions block which others. An early answer can change what the later
questions even are.
2. Split each node into a fact or a decision. A fact is checkable — confirm it
(read the code, ask one direct question) and move on. A decision is a choice
among options — that gets the interview treatment below.
3. Ask one decision at a time, in dependency order. Never put a list of questions
in one turn — the position gets stress-tested one decision at a time.
4. Every question carries a concrete recommendation: state your pick and the
one-line reason before asking, then let the user confirm, override, or answer
differently. A bare question with no stance is not a grill question.
```
Next: does "reviews" mean buyer reviews of a storefront, or reviews of the
platform itself? Recommend buyer reviews of a storefront — that's the noun
already in use, and "platform reviews" isn't a stated need yet.
```
5. The moment a decision confirms, append its line to memory-progress.md —
immediately, not batched for later. An interview is exactly the kind of work a
session dies mid-way through; a decision that only lives in the conversation
dies with it.
```
DECISION [<topic>] <question> → <choice>
```
6. Keep going until every branch of the tree is resolved or explicitly deferred
with a named owner. "This got hard, let's stop" is not an exit — resolved or
deferred-with-an-owner are the only two ways out of grill. When you defer a
branch to a later cycle, append it to the backlog per /galdr:backlog
(skills/backlog/SKILL.md) — don't restate the format here.
7. Once the tree is exhausted, continue to Synthesis.
## Explore
Open-ended: no position exists yet to test.
1. Read the project's context first — CLAUDE.md, memory.md, the existing code —
before proposing anything. An approach that ignores what's already there gets
rejected on the first read anyway.
2. If the request spans more than one subsystem, decompose the scope: name each
subsystem's slice of the question separately before designing any of them.
3. For each slice, present 2-3 approaches with a recommendation stated first, not
a neutral list, before going into design detail: the pick and why, then the
alternatives and their tradeoffs.
4. Once a direction is picked for a slice, any open question left in it gets the
same treatment as grill: one at a time, recommendation first.
5. Continue to Synthesis.
## Synthesis
The exit every mode reaches, and a mode in its own right.
- Entered directly (`shape-synthesis`, or the requirements are already stated as
clear): skip the interview entirely. Do not ask a clarifying question — the
request already said what's needed. Go straight to the spec draft.
- Arrived here after grill or explore: the interview already happened; there is
nothing left to skip, just write.
Write the spec to `docs/specs/YYYY-MM-DD-<topic>.md` in the target repo. Near the
header, carry a one-line `Lifecycle status:` field. It moves through four states
over the spec's life — `shaped → planned → in-progress → shipped` — and shape
sets it to `shaped` when it writes the spec.
- **Goal** — what this spec is for, one paragraph.
- **Non-goals** — what's explicitly out of scope, so it can't drift back in later.
- **Constraints** — project-wide rules every task must obey (style, consent,
cross-repo invariants). The plan skill copies this section forward verbatim, so
write it as rules, not prose.
- **Decision log** — every decision reached (grill/explore) or assumed (direct
synthesis), as a table: `# | Decision | Choice`.
- **Acceptance criteria** — stated per future wave, so the downstream `plan` skill
has something concrete to check tasks against.
- **Roles touched** — one line, `**Roles touched:** <comma-separated role names>` or
`**Roles touched:** none`. Names are roles cited from the target repo's
`docs/agents/roles-and-journeys.md`, if that doc exists; if the repo has no such
doc, the field is always `none`.
### 5-point self-review
Before showing the spec, check it against these five and fix inline — don't flag
a problem and leave it for later:
1. **Placeholders** — any "TBD", "handle edge cases", "similar to X"? Replace with
the actual content.
2. **Contradictions** — do any two sections disagree with each other? Reconcile
them.
3. **Scope** — does the spec match what was actually asked, no more and no less?
Trim anything that crept in.
4. **Ambiguity** — could two different readers build this two different ways?
Sharpen the wording until one reading survives.
5. **Roles drift** — check what "Roles touched" ended up being:
- No existing role named (the field is `none`, or names only roles absent from
`docs/agents/roles-and-journeys.md`): this point is done — the review is the
original four points, unchanged.
- An existing role is named and the spec's claims about that role's
capabilities/boundaries match the doc's `**Capabilities:**` /
`**Boundaries:**` lines for it: passes silently, same as any other point that
finds nothing wrong.
- An existing role is named and the spec's claims conflict with the doc (the
spec assumes a capability the doc's `**Boundaries:**` rules out, or contradicts
a stated `**Capabilities:**` line): stop synthesis before the spec is shown for
approval, and tell the user to either fix the spec to match the doc, or run
`setup`'s refresh to update the doc first — then resume. Never fix this by
editing `docs/agents/roles-and-journeys.md` yourself in-session; that file is
only ever written by `setup`.
On a session with the Workflow tool: after the inline fixes above, dispatch one
independent reviewer at the `spec-review` binding from the repo's
`docs/agents/galdr.md` §Models — an activity row that names a tier, resolved through
that tier's own binding. Input: the draft spec and its decision log. Return: findings
against the same five points above. Fix its findings inline, the same way the five
points are fixed, before the spec is shown for approval — the reviewer is a second
opinion from a context that did not write the spec, which is the point.
On any runtime without the Workflow tool: skip the dispatch. The self-review above is
the whole review, unchanged.
### Hard gate
No implementation action — no code, no plan file, no wave dispatch — happens
until the user has approved this spec. This is a hard rule, not a preference: an
unapproved spec is a draft, and drafts don't get built.
## Wayfinder
When a topic won't reach a spec in one session — too many open branches, or the
session runs out before the tree is exhausted — load `references/wayfinder.md`.
It covers the multi-session fog map: what to record, what never to record, and
how the map closes back out into a spec.
## Notes
- A memory-progress.md decision line and the spec's Decision log table are not
the same artifact: the line is written the moment a decision lands, mid-
interview; the table is the same decisions, collected, at the end.
- Facts and decisions differ in treatment, not in stakes — a wrongly assumed fact
is still a spec bug, it just didn't need an interview to catch.