| name | use-shape |
| description | Run the Shape Up loop (shape → bet → build → ship) for AI-agent-assisted development with the `shape` CLI. Invoke when working in a repo that has a `.shape/` workspace or a `.shaperc.toml`; when the user talks about shaping work, pitches, appetites, bets, scopes, or hill charts; or when you're about to build a non-trivial feature and need to bound scope, avoid over-building, and respect human approval gates. |
| license | MIT OR Apache-2.0 |
Using shape
shape brings the Shape Up method to AI-agent-assisted development. It runs the build loop in four phases — shape → bet → build → ship — with a human approval gate between each one. You (the agent) co-pilot every phase: you draft pitches, hunt rabbit holes, propose scope maps, and do the building. The human is the judge; shape is the referee that holds the artifacts as plain files, enforces the appetite as a budget, and tracks progress on a hill chart.
The single most important rule: do the work inside a phase; stop at the gate. See "The loop and the gates" below.
shape is young. shape init and shape completions work today; the other commands are defined but may print "not implemented yet". The methodology, the gate discipline, and the file-based workspace below are the durable contract. Always check shape --help for what is actually wired up, and when a command isn't ready, do the equivalent by editing the .shape/ files directly.
When to use
- You're in a repo with a
.shape/ workspace or a .shaperc.toml.
- The user talks about shaping, pitches, appetite, bets, scopes, hill charts, or "the cycle".
- You're about to build a non-trivial feature and want to bound the scope before diving in.
- You catch yourself about to over-build, gold-plate, or refactor beyond what was asked — that's the cue to shape and set an appetite instead.
The loop and the gates
An idea moves through four phases. A ▸ marks a human gate you must not cross yourself:
- Shape — co-shape a pitch (problem · appetite · solution · rabbit holes · no-gos). ▸ the human marks it ready.
- Bet — the human picks a pitch and arms the budget. ▸ placing a bet is a human decision.
- Build — you build inside the bet: get one slice done, map scopes, keep the hill honest. ▸ the human accepts the first slice, then the finished work.
- Ship — done = deployed; new requests become raw ideas for the next round.
Gate discipline — the heart of this skill:
- Draft, propose, prepare — then hand off. Say "this pitch is ready for your review" rather than marking it ready.
- Never place a bet, accept a slice, accept "done", or ship on the human's behalf.
- A blown budget (the circuit breaker) means stop and re-shape, not push harder. Only continue past budget if every scope is already downhill (no unknowns left) and the human says so.
Philosophy
- Appetite, not estimate. The human sets a budget (tokens · iterations · time). Fixed budget, variable scope — you cut scope to fit the budget, never grow the budget to fit the scope.
- Scope hammering. Constantly separate must-haves from nice-to-haves. Mark nice-to-haves with a leading
~; default to cutting them. Compare down to baseline (what users do today), not up to an ideal.
- Get one piece done. Build one vertical slice first — core, small, novel — and make it demoable before fanning out. Don't build horizontally (every layer stubbed, nothing actually working).
- Make uncertainty visible. Report each scope's hill position: uphill = still figuring out the approach; downhill = just executing. Don't claim downhill until you've validated the approach by building, not just thinking. A dot that won't move is a signal to ask for help or re-shape — agents loop silently, so say so.
- Leave room. A shaped pitch is rough on purpose. It's boundaries and rules, not a spec. Fill in the real details as you build.
Where the workspace lives
Don't hardcode .shape/. Resolution order:
--dir <path> flag (one-shot override).SHAPE_DIR=<path> environment variable (session override).dir = "..." in .shaperc.toml, discovered by walking up from the cwd. A relative path resolves against the config file's directory.- Default:
.shape/.
If there's no workspace yet and the shape binary is installed, run shape init to scaffold one.
Commands
Run shape --help and shape <command> --help for the authoritative, currently-wired surface. The intended surface:
shape init — scaffold .shape/ (pitch/, bet/, scope/, hill/) and .shaperc.toml. (works today)shape completions <shell> — shell completions for bash, zsh, fish, PowerShell, elvish. (works today)shape pitch new|list|show|ready <name> — co-shape and manage pitches.shape derisk <name> — rabbit-hole / risk pass over a pitch.shape bet <name> [--appetite small|big] — place a bet and arm the circuit breaker (human gate).shape bets — list active and past bets.shape build [--spike] — hand the active bet to the agent and orchestrate the run.shape scope list|add|split|done — map and manage scopes.shape hill [set <scope> <0-100>] — show or update the hill chart.shape status — run dashboard: budget vs. appetite, scopes, hill, stuck dots.shape stop — trip the circuit breaker manually.shape accept slice|done — accept a human gate.shape ship — mark done (deployed) and run the move-on checklist.shape cooldown [start|end] — enter or leave the between-runs period.
Global flags: --dir <path> (also SHAPE_DIR), -q/--quiet.
When a command reports "not implemented yet", do the equivalent by editing the .shape/ files (next section) and tell the human exactly what you changed.
The artifact contract
The workspace is plain text under the resolved dir (default .shape/), so it's diffable and git-friendly:
pitch/<name>.md — a shaped pitch with five ingredients: Problem (a concrete story showing why the status quo fails — the baseline), Appetite (small or big, and why), Solution (rough — breadboards: a Place, affordances under it, → connections; or low-fidelity sketches), Rabbit holes (called-out risks and their patches), No-gos (explicitly excluded to fit the appetite). Rough and bounded, never a spec.bet/<id>-<name>.md — a placed bet: the pitch committed to a run, with the armed budget. Human-owned.scope/<bet>/<scope>.md — an independently completable slice: a checklist of tasks (must-haves; ~ for nice-to-haves) plus the scope's hill position.hill/<bet>.jsonl — append-only hill snapshots, so the human can see how the work is moving, not just where it is.
Workflows
Shape a pitch
- Narrow the problem: ask "when did this actually bite?" to find the real use case, not the feature label.
- Propose an appetite (small/big) and design only what fits inside it.
- Sketch the solution roughly — breadboard the flow (places, affordances, connections) rather than drawing pixels.
- Attack your own concept: list rabbit holes and patch or fence each one; mark the no-gos.
- Write
pitch/<name>.md with all five ingredients, then say it's ready for review — don't self-mark it ready.
Build inside a bet
- Get oriented, then pick the first slice — core, small, novel — and make it work end-to-end.
- Discover tasks by doing the work; map them into scopes as the real structure emerges (not up front).
- Keep the hill honest and surface anything stuck early.
- Scope-hammer continuously; mark nice-to-haves
~ and default to cutting them.
- Stop at the slice gate and the done gate for the human to accept.
What not to do
- Don't cross a human gate (ready / bet / accept / ship) on your own — draft and hand off.
- Don't over-build or gold-plate; cut scope to the appetite and compare down to baseline.
- Don't build horizontally — land one working vertical slice before spreading out.
- Don't claim a scope is downhill until you've validated the approach by building it.
- Don't push past a blown budget; stop and re-shape.
- Don't hardcode
.shape/ in scripts — resolve via --dir / SHAPE_DIR / .shaperc.toml / default.
- Don't treat the pitch as a spec; it's rough boundaries you fill in while building.
- Don't invent new artifact shapes — follow the contract above, or run
shape init first.
