mirror of
https://github.com/obra/superpowers.git
synced 2026-08-31 19:09:13 +00:00
Compare commits
3 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| a56a34365a | |||
| ef0ca09658 | |||
| c3a5abcf33 |
@@ -173,6 +173,14 @@ its own text agrees with itself — the tests it specifies against the code it
|
|||||||
specifies, the files it creates against the files it later touches. "The scan
|
specifies, the files it creates against the files it later touches. "The scan
|
||||||
is clean" without those rows is not a scan you ran.
|
is clean" without those rows is not a scan you ran.
|
||||||
|
|
||||||
|
**When the plan's header declares `Plan shape: skeleton-first`,** the
|
||||||
|
table gets a final section: the DISPATCH PLAN — group the pending tasks
|
||||||
|
into waves. Tasks in the same wave are mutually file-disjoint and consume
|
||||||
|
no interface still under construction — dispatch each wave's implementers
|
||||||
|
concurrently, one worktree per task, and integrate before the next wave;
|
||||||
|
tasks that fail those conditions serialize. On a skeleton-first plan, a
|
||||||
|
scan without a dispatch plan is not a scan you ran.
|
||||||
|
|
||||||
Write the table to the ledger. Rule on everything you find before execution
|
Write the table to the ledger. Rule on everything you find before execution
|
||||||
begins — each finding against the plan text that mandates it — and record
|
begins — each finding against the plan text that mandates it — and record
|
||||||
each ruling in the ledger. If the scan is clean, proceed without comment.
|
each ruling in the ledger. If the scan is clean, proceed without comment.
|
||||||
@@ -187,6 +195,10 @@ Use the least powerful model that can handle each role to conserve cost and incr
|
|||||||
|
|
||||||
**Mechanical implementation tasks** (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.
|
**Mechanical implementation tasks** (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.
|
||||||
|
|
||||||
|
When a task carries a **Tier:** field, follow it — the planner already
|
||||||
|
ruled: mechanical → the cheapest available model; judgment → a standard
|
||||||
|
model. Do not re-litigate the tier at dispatch.
|
||||||
|
|
||||||
**Integration and judgment tasks** (multi-file coordination, pattern matching, debugging): use a standard model.
|
**Integration and judgment tasks** (multi-file coordination, pattern matching, debugging): use a standard model.
|
||||||
|
|
||||||
**Architecture and design tasks**: use the most capable available model.
|
**Architecture and design tasks**: use the most capable available model.
|
||||||
@@ -208,7 +220,10 @@ most expensive — which silently defeats this section.
|
|||||||
**Turn count beats token price.** Wall-clock and context cost scale with how
|
**Turn count beats token price.** Wall-clock and context cost scale with how
|
||||||
many turns a subagent takes, and the cheapest models routinely take 2-3× the
|
many turns a subagent takes, and the cheapest models routinely take 2-3× the
|
||||||
turns on multi-step work — costing more overall. Use a mid-tier model as the
|
turns on multi-step work — costing more overall. Use a mid-tier model as the
|
||||||
floor for reviewers and for implementers working from prose descriptions.
|
floor for reviewers and for implementers working from task contracts or
|
||||||
|
prose descriptions — unless the task's Tier line says mechanical: the
|
||||||
|
planner has already ruled the deliverable fully specified, so treat a
|
||||||
|
mechanical-tier contract like spelled-out content.
|
||||||
When the task's plan text contains the complete code to write, the
|
When the task's plan text contains the complete code to write, the
|
||||||
implementation is transcription plus testing: use the cheapest tier for
|
implementation is transcription plus testing: use the cheapest tier for
|
||||||
that implementer. Single-file mechanical fixes also take the cheapest tier.
|
that implementer. Single-file mechanical fixes also take the cheapest tier.
|
||||||
@@ -259,7 +274,13 @@ and fix-round diffs need it.
|
|||||||
know; (4) your resolution of any ambiguity you noticed in the brief;
|
know; (4) your resolution of any ambiguity you noticed in the brief;
|
||||||
(5) the report-file path and report contract. Exact values (numbers,
|
(5) the report-file path and report contract. Exact values (numbers,
|
||||||
magic strings, signatures, test cases) appear only in the brief. Never
|
magic strings, signatures, test cases) appear only in the brief. Never
|
||||||
make a subagent read the whole plan file.
|
make a subagent read the whole plan file. When the brief is a contract
|
||||||
|
(goal, success criteria, interfaces) rather than written-out code, item
|
||||||
|
(3) also carries the elaboration the contract leaves to dispatch time:
|
||||||
|
the interfaces as actually built by completed tasks, environment facts
|
||||||
|
and discoveries from earlier reports, and any amendment rulings. There
|
||||||
|
the success criteria name the cases the tests must cover, and the
|
||||||
|
implementer designs its own code and tests within the contract.
|
||||||
- **Report file:** name the implementer's report file after the brief
|
- **Report file:** name the implementer's report file after the brief
|
||||||
(brief `…/task-N-brief.md` → report `…/task-N-report.md`) and put it in
|
(brief `…/task-N-brief.md` → report `…/task-N-report.md`) and put it in
|
||||||
the dispatch prompt. The implementer writes the full report there and
|
the dispatch prompt. The implementer writes the full report there and
|
||||||
@@ -280,6 +301,26 @@ and fix-round diffs need it.
|
|||||||
- Record the implementer's agent identity from the dispatch result —
|
- Record the implementer's agent identity from the dispatch result —
|
||||||
fix-loop rounds 1-3 resume this agent.
|
fix-loop rounds 1-3 resume this agent.
|
||||||
- Never dispatch multiple implementation subagents in parallel (conflicts).
|
- Never dispatch multiple implementation subagents in parallel (conflicts).
|
||||||
|
The one exception is a skeleton-first plan whose dispatch plan shows two
|
||||||
|
or more pending tasks mutually file-disjoint with none consuming an
|
||||||
|
interface still under construction. Dispatch those implementers
|
||||||
|
concurrently, each in its own worktree:
|
||||||
|
- Record the integration base commit in the ledger before the first
|
||||||
|
concurrent dispatch.
|
||||||
|
- Create one worktree per concurrent task off that base
|
||||||
|
(`git worktree add <repo-root>/.worktrees/task-<N> -b task-<N>
|
||||||
|
<base>`); each dispatch's `Work from:` is its own worktree, and its
|
||||||
|
BASE is that worktree's HEAD.
|
||||||
|
- Review each task's diff as usual when it reports. Integrate reviewed
|
||||||
|
branches in plan order: merge each into the integration branch
|
||||||
|
(`git merge --no-ff task-<N>`), and run that task's verification
|
||||||
|
commands after each merge.
|
||||||
|
- A merge conflict or post-merge verification failure is that task's
|
||||||
|
fix-loop round 1: rebase the task branch onto the current
|
||||||
|
integration head in its worktree, then resume its implementer
|
||||||
|
there. Never resolve conflicts yourself.
|
||||||
|
- Remove each worktree (`git worktree remove`) once its branch is
|
||||||
|
integrated, and record the integrated range in the ledger as usual.
|
||||||
|
|
||||||
Template: [implementer-prompt.md](implementer-prompt.md)
|
Template: [implementer-prompt.md](implementer-prompt.md)
|
||||||
|
|
||||||
@@ -438,6 +479,16 @@ message as your other bookkeeping:
|
|||||||
- `Task <N>: complete (commits <base7>..<head7>, <K> parked)` after a
|
- `Task <N>: complete (commits <base7>..<head7>, <K> parked)` after a
|
||||||
tripped breaker
|
tripped breaker
|
||||||
|
|
||||||
|
**On a skeleton-first plan,** write one plan-check line with the
|
||||||
|
completion line. Re-read the remaining tasks against what this task
|
||||||
|
actually established — interfaces as built, environment facts,
|
||||||
|
discoveries in the report — and append either `Plan holds` or
|
||||||
|
`Amendment: Task <M>: <what changes and why>` to the ledger. An
|
||||||
|
amendment is plan authority applied at the plan layer: from then on the
|
||||||
|
amended text IS the plan's text, and it rides into every affected task's
|
||||||
|
dispatch under item (3). Never dispatch a task whose brief a completed
|
||||||
|
task's report has already invalidated.
|
||||||
|
|
||||||
Then mark the todo complete and move on. Never move to the next task while
|
Then mark the todo complete and move on. Never move to the next task while
|
||||||
the review has open Critical/Important issues that are neither fixed nor
|
the review has open Critical/Important issues that are neither fixed nor
|
||||||
parked-with-ruling at the cap.
|
parked-with-ruling at the cap.
|
||||||
|
|||||||
@@ -5,8 +5,11 @@ Use this template when dispatching an implementer subagent.
|
|||||||
```
|
```
|
||||||
Subagent (general-purpose):
|
Subagent (general-purpose):
|
||||||
description: "Implement Task N: [task name]"
|
description: "Implement Task N: [task name]"
|
||||||
model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted
|
model: [MODEL — REQUIRED: when the brief carries a Tier line, set from it:
|
||||||
model silently inherits the session's most expensive one]
|
mechanical → the cheapest model the subagent tool offers; judgment →
|
||||||
|
a standard mid-tier model. Otherwise choose per SKILL.md Model
|
||||||
|
Selection. An omitted model silently inherits the session's most
|
||||||
|
expensive one]
|
||||||
prompt: |
|
prompt: |
|
||||||
You are implementing Task N: [task name]
|
You are implementing Task N: [task name]
|
||||||
|
|
||||||
|
|||||||
@@ -22,6 +22,30 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
|
|||||||
|
|
||||||
If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
|
If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
|
||||||
|
|
||||||
|
## Two Plan Shapes
|
||||||
|
|
||||||
|
Before mapping files, classify the plan's shape and say the
|
||||||
|
classification out loud — "this composes three subsystems, so I'll plan
|
||||||
|
it skeleton-first" — so your human partner can override it:
|
||||||
|
|
||||||
|
- **Task-by-task (default)** — tasks build the feature a component at a
|
||||||
|
time, each step carrying the actual content the engineer needs. Use it
|
||||||
|
for changes to code that already exists, for a spec that touches one
|
||||||
|
subsystem, and whenever the alternative's conditions do not clearly
|
||||||
|
hold. The rest of this skill describes this shape.
|
||||||
|
- **Skeleton-first (alternative)** — Task 1 is the thinnest end-to-end
|
||||||
|
slice through every subsystem the spec composes; later tasks widen it
|
||||||
|
one component at a time, each from a contract rather than written-out
|
||||||
|
code. Use it when the spec composes more than one subsystem AND a
|
||||||
|
running end-to-end slice early is worth a longer total build. Read
|
||||||
|
[skeleton-first-plans.md](skeleton-first-plans.md) before writing one
|
||||||
|
— it adds one line to the plan header and replaces this skill's task
|
||||||
|
granularity, task template, and plan-failure list.
|
||||||
|
|
||||||
|
When in doubt, plan task-by-task. Skeleton-first buys an earlier running
|
||||||
|
system and pays for it in total wall clock; it is a trade, not an
|
||||||
|
upgrade.
|
||||||
|
|
||||||
## File Structure
|
## File Structure
|
||||||
|
|
||||||
Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.
|
Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.
|
||||||
|
|||||||
@@ -0,0 +1,131 @@
|
|||||||
|
# Skeleton-First Plans
|
||||||
|
|
||||||
|
The alternative plan shape from writing-plans' Two Plan Shapes router.
|
||||||
|
Each section below replaces the same-named section of
|
||||||
|
[SKILL.md](SKILL.md); everything SKILL.md says that is not named here
|
||||||
|
still binds — Scope Check, File Structure, Task Right-Sizing, the plan
|
||||||
|
header, Self-Review, and the Execution Handoff.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Write a plan that carries the decisions, not the keystrokes:
|
||||||
|
decomposition, file structure, interfaces, constraints, and a precise
|
||||||
|
contract per task. Assume the engineer is skilled and designs their own
|
||||||
|
code and tests from a precise contract, but knows nothing about our
|
||||||
|
codebase, toolset, or problem domain — every name, path, constraint, and
|
||||||
|
behavior they must match is stated explicitly. DRY. YAGNI. TDD.
|
||||||
|
Frequent commits.
|
||||||
|
|
||||||
|
## When This Shape Fits
|
||||||
|
|
||||||
|
Use it when the spec composes more than one subsystem and a running
|
||||||
|
end-to-end slice early is worth a longer total build: the value arrives
|
||||||
|
as soon as real input reaches real output, and every later task widens
|
||||||
|
something that already runs.
|
||||||
|
|
||||||
|
Do not use it for a change to one subsystem, or when the whole point is
|
||||||
|
to land the finished thing as fast as possible. This shape spends its
|
||||||
|
first task on a slice that does almost nothing, and it spends planning
|
||||||
|
effort on contracts and interfaces the task-by-task shape gets for free
|
||||||
|
by writing the code out.
|
||||||
|
|
||||||
|
## Plan Document Header
|
||||||
|
|
||||||
|
The header is SKILL.md's, plus one line directly under the **Goal:**
|
||||||
|
line, which is how executors know which shape they are running:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
**Plan shape:** skeleton-first
|
||||||
|
```
|
||||||
|
|
||||||
|
## Walking Skeleton First
|
||||||
|
|
||||||
|
Task 1 builds the thinnest end-to-end slice through every subsystem the
|
||||||
|
spec composes — real input to real output — before any task deepens a
|
||||||
|
single layer; later tasks widen the skeleton.
|
||||||
|
|
||||||
|
The test of a skeleton is that it runs. A first task that builds the
|
||||||
|
data loader, the schema, or the config layer is a foundation, not a
|
||||||
|
skeleton: nothing runs until something above it exists. A skeleton
|
||||||
|
reaches the output — thinly, with one real case — through every
|
||||||
|
subsystem the spec names.
|
||||||
|
|
||||||
|
## Task Contracts, Not Task Scripts
|
||||||
|
|
||||||
|
A task states WHAT must exist when it is done, precisely enough that a
|
||||||
|
skilled engineer can build it without asking you anything, without
|
||||||
|
prescribing HOW:
|
||||||
|
|
||||||
|
- **Goal:** one short paragraph naming the deliverable and its role in
|
||||||
|
the feature.
|
||||||
|
- **Success criteria:** concrete, checkable behaviors — exact commands
|
||||||
|
to run and what they must show, the cases tests must cover (including
|
||||||
|
failure cases), constraints that bind the implementation.
|
||||||
|
- **Notes:** what the engineer needs and cannot discover alone — spec
|
||||||
|
sections to read, files worth reading first, known pitfalls.
|
||||||
|
|
||||||
|
The Interfaces block carries the exact names, signatures, and types;
|
||||||
|
the success criteria carry the behaviors; the engineer supplies the
|
||||||
|
code and the test design. TDD and frequent commits remain required.
|
||||||
|
|
||||||
|
## Task Structure
|
||||||
|
|
||||||
|
````markdown
|
||||||
|
### Task N: [Component Name]
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Create: `exact/path/to/file.py`
|
||||||
|
- Modify: `exact/path/to/existing.py:123-145`
|
||||||
|
- Test: `tests/exact/path/to/test.py`
|
||||||
|
|
||||||
|
**Interfaces:**
|
||||||
|
- Consumes: [what this task uses from earlier tasks — exact signatures]
|
||||||
|
- Produces: [what later tasks rely on — exact function names, parameter
|
||||||
|
and return types. A task's implementer sees only their own task; this
|
||||||
|
block is how they learn the names and types neighboring tasks use.]
|
||||||
|
|
||||||
|
**Goal:** [one paragraph — the deliverable and its role in the feature]
|
||||||
|
|
||||||
|
**Success criteria:**
|
||||||
|
- Run: `pytest tests/exact/path/to/test.py -v` — all tests pass; tests
|
||||||
|
cover [the specific behaviors and failure cases, named concretely]
|
||||||
|
- [observable behavior the deliverable must exhibit, with the exact
|
||||||
|
command or input/output that demonstrates it]
|
||||||
|
- [constraint that binds the implementation, copied from the spec]
|
||||||
|
|
||||||
|
**Notes:** [spec sections to read; files to read first; known pitfalls]
|
||||||
|
|
||||||
|
**Tier:** mechanical | judgment. Mechanical = the deliverable is fully
|
||||||
|
specified by Files + Interfaces + success criteria above (most tasks in
|
||||||
|
a well-specified plan are mechanical); judgment = multi-file
|
||||||
|
coordination, debugging, or real design latitude remains. The
|
||||||
|
implementer's model follows this field — mark it deliberately.
|
||||||
|
|
||||||
|
**Commit:** one commit ending the task; message named here.
|
||||||
|
````
|
||||||
|
|
||||||
|
## No Vague Contracts
|
||||||
|
|
||||||
|
Every contract must be checkable by someone who did not write it. These
|
||||||
|
are **plan failures** — never write them:
|
||||||
|
- "TBD", "TODO", "implement later", "fill in details"
|
||||||
|
- Goals naming activity instead of a deliverable ("improve error handling")
|
||||||
|
- Success criteria with no observable check ("works correctly", "handles edge cases")
|
||||||
|
- Interfaces blocks omitting a name, signature, or type another task consumes
|
||||||
|
- "Similar to Task N" (state this task's own contract in full — the engineer may be reading tasks out of order)
|
||||||
|
- References to types, functions, or methods not defined in any task's Interfaces block
|
||||||
|
|
||||||
|
## Self-Review
|
||||||
|
|
||||||
|
Run SKILL.md's Self-Review checklist, reading step 2 against "No Vague
|
||||||
|
Contracts" above rather than "No Placeholders".
|
||||||
|
|
||||||
|
## Red Flags
|
||||||
|
|
||||||
|
| Thought | Reality |
|
||||||
|
|---------|---------|
|
||||||
|
| "Task 1 is the data loader — that's the foundation" | A foundation is a layer. The skeleton runs real input to real output through every subsystem the spec names, thinly. |
|
||||||
|
| "The skeleton can return a hardcoded value for now" | It may be thin, but the path must be real: real input, real wiring, real output. A hardcoded response tests nothing end to end. |
|
||||||
|
| "A contract without the code is vague" | Vague is an uncheckable success criterion. Exact names, exact commands, exact expected output — no code. |
|
||||||
|
| "I'll write the test code into the task to be safe" | The success criteria name the cases; the implementer designs the tests. Written-out tests are the task-by-task shape. |
|
||||||
|
| "Skeleton-first is the better shape, so I'll use it here" | It costs total wall clock. Without more than one subsystem and a reason to want an early running slice, plan task-by-task. |
|
||||||
Reference in New Issue
Block a user