mirror of
https://github.com/obra/superpowers.git
synced 2026-09-04 12:45:37 +00:00
Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
573a66b671 |
@@ -1,7 +1,7 @@
|
|||||||
---
|
---
|
||||||
name: IDE / Platform Support Request
|
name: IDE / Platform Support Request
|
||||||
about: Request support for a new IDE, editor, or AI coding tool
|
about: Request support for a new IDE, editor, or AI coding tool
|
||||||
labels: platform-support
|
labels: new-harness
|
||||||
---
|
---
|
||||||
|
|
||||||
<!--
|
<!--
|
||||||
|
|||||||
@@ -173,14 +173,6 @@ 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.
|
||||||
@@ -195,10 +187,6 @@ 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.
|
||||||
@@ -220,10 +208,7 @@ 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 task contracts or
|
floor for reviewers and for implementers working from prose descriptions.
|
||||||
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.
|
||||||
@@ -274,13 +259,7 @@ 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. When the brief is a contract
|
make a subagent read the whole plan file.
|
||||||
(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
|
||||||
@@ -301,26 +280,6 @@ 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)
|
||||||
|
|
||||||
@@ -479,16 +438,6 @@ 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,11 +5,8 @@ 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: when the brief carries a Tier line, set from it:
|
model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted
|
||||||
mechanical → the cheapest model the subagent tool offers; judgment →
|
model silently inherits the session's most expensive one]
|
||||||
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,30 +22,6 @@ 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.
|
||||||
|
|||||||
@@ -1,131 +0,0 @@
|
|||||||
# 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