From 8028411cbb96588e4c35bb5cba2b563e9fde2457 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabor=20K=C3=B6rber?= Date: Thu, 15 Oct 2026 21:31:07 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Document=20Spire=20planning=20re?= =?UTF-8?q?search=20and=200.2.2=20decisions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../2026-11-15-implementation_thoughts.md | 23 ++ docs/workpad/goals/drop-superpowers-0.2.2.md | 60 ++++ docs/workpad/goals/lean-athanor-0.2.1.md | 9 +- .../2026-10-15-11-superpowers-opus55-era.md | 97 +++++++ ...-13-fable-opinion-superpowers-direction.md | 131 +++++++++ ...026-10-15-11-spire-superpowers-coupling.md | 266 ++++++++++++++++++ .../2026-10-15-11-superpowers-alternatives.md | 212 ++++++++++++++ .../2026-10-15-12-superpowers-plan-anatomy.md | 213 ++++++++++++++ ...6-10-15-14-claude-code-tasks-and-pcvelz.md | 201 +++++++++++++ 9 files changed, 1208 insertions(+), 4 deletions(-) create mode 100644 docs/workpad/brainstorm/2026-11-15-implementation_thoughts.md create mode 100644 docs/workpad/goals/drop-superpowers-0.2.2.md create mode 100644 docs/workpad/journals/2026-10-15-11-superpowers-opus55-era.md create mode 100644 docs/workpad/reports/2026-10-15-13-fable-opinion-superpowers-direction.md create mode 100644 docs/workpad/research/2026-10-15-11-spire-superpowers-coupling.md create mode 100644 docs/workpad/research/2026-10-15-11-superpowers-alternatives.md create mode 100644 docs/workpad/research/2026-10-15-12-superpowers-plan-anatomy.md create mode 100644 docs/workpad/research/2026-10-15-14-claude-code-tasks-and-pcvelz.md diff --git a/docs/workpad/brainstorm/2026-11-15-implementation_thoughts.md b/docs/workpad/brainstorm/2026-11-15-implementation_thoughts.md new file mode 100644 index 0000000..daa9765 --- /dev/null +++ b/docs/workpad/brainstorm/2026-11-15-implementation_thoughts.md @@ -0,0 +1,23 @@ +Step 1: Design Phase -> Design Document. + - distill basically what most skills do. + - use even other skills: grill-with-docs, superpowers, etc. + +Step 2: Architectural Phase -> Architectural Orientation + - already more like a plan + - this is where specs are born or connected + - should help to situate the solution in the code: + - modules + - files + - structs / classes + - academic approach (functional, data driven, DDD, clean arch, ...) + - traits / interfaces + - pre-plan and post-plan: some of these decisions could be not very helpful if built right away, others should be prepped: e.g. writing database-models, creating modules, defining base shape of interfaces, etc. are good pre-plan jobs usually. deriving or polishing traits, restructuring abstractions etc. sometimes are more helpful as a later refactor if more code is available + - Some abstractions are derivative and we have to anticipate this: sometimes the true structure of the data arrives out of the final logical requirements; sometimes these only arrive from actually applying the application to the problem. This is why this should be orientation. Because the opposite is also true: no architectural approach would have meant, that e.g. structures are written ad-hoc, functions that almost do the same are missing the opportunity to use common dispatch. + - testing: design document for tests. how can we prove, our implementation is working well? what are the minimal tests required? what are breaking points that should be considered? + - a good human programmer would probably already be able to implement a problem with design and orientation document only, solving the rest on the fly. + - only high level code examples, like structures or relationships + +Step 3: Planning Phase -> Implementation Plan + - Again: should use existing skills, but: input is Design and Architectural docs / specs. + +Step 4: Attack the Plan. Last chance to detect major blunders or optimize approaches, point out missing functional thoughts (a button is planned but it does nothing. there is an onboarding procedure but no offboarding procedure. error handling or security concerns. early abstraction could have solved this) diff --git a/docs/workpad/goals/drop-superpowers-0.2.2.md b/docs/workpad/goals/drop-superpowers-0.2.2.md new file mode 100644 index 0000000..b6dfc01 --- /dev/null +++ b/docs/workpad/goals/drop-superpowers-0.2.2.md @@ -0,0 +1,60 @@ +# Goal: Drop superpowers as default — Spire 0.2.2 + +**Set**: 2026-10-15, Igor session [2026-10-15-11-superpowers-opus55-era](../journals/2026-10-15-11-superpowers-opus55-era.md) +**Status**: agreed with the user 2026-10-15 +**Order**: the next Spire release after 0.2.0. [lean-athanor-0.2.1](./lean-athanor-0.2.1.md) stays open; its delegation-row fix lands here. +**Leads to**: 0.3.0 — Spire adopts the `grotto` plugin's design / plan / handoff procedure (see "Later") + +## Why + +On modern models (Opus 5.5, Astra) superpowers overdoes it: token spend, too many gates and reviews, review+fix ≈ 2/3 of the work, scope beyond the plan — worst in Rust codebases. Its problems are hard to avoid even with the lean method. Modern models need lighter guardrails and harness-aware help, not generic ceremony. + +0.2.2 removes superpowers as a default and bundles single-sentence fixes that pay off now. The full procedure is grotto / 0.3.0. + +Research: [alternatives](../research/2026-10-15-11-superpowers-alternatives.md), [Spire coupling](../research/2026-10-15-11-spire-superpowers-coupling.md), [plan anatomy](../research/2026-10-15-12-superpowers-plan-anatomy.md), [Claude Code tasks / pcvelz](../research/2026-10-15-14-claude-code-tasks-and-pcvelz.md). Opinion: [Fable](../reports/2026-10-15-13-fable-opinion-superpowers-direction.md). + +## Success criteria + +### Superpowers is no longer a default +- [x] No Spire skill or agent presumes superpowers is installed or recommends it as part of the normal cycle. Current references: `implementation/SKILL.md:3,32,84`, `agents/athanor.md:60`, `workpad/SKILL.md:3,10`, `research-tree/SKILL.md:3`. +- [x] The workpad keeps steering other skills' markdown into the workpad, without naming a specific plugin. +- [x] A reference doc (`implementation/references/superpowers.md`) is where superpowers survives: when and how to use it with Spire — e.g. with older models (Opus 4.6) — and which of its rules the lean cycle overrides. + +### Single-sentence fixes +- [x] **Plan altitude** (`spire:implementation`): a plan holds decisions, contracts, invariants and the scope fence; code only where its exact form is the decision (schema, wire format, state machine). +- [x] **Staleness in the attack** (`spire:implementation`): the attack checks the plan for staleness against the current code. Reading the previous phase's run log and review is only needed when something is off. +- [x] **Unplanned work on record** (phase review): the reviewer lists what was built that the plan did not ask for — on record only, never an automatic revert. An unplanned addition may be a good one. +- [x] **Journal times** (Igor journal, run log): timestamps come from `date`, not from memory. +- [x] **Delegation row** (Igor skill and `model-tiers.md`): "Planned implementation" → attacked plan → Athanor (multi-block) or one general-purpose builder (one block). (From 0.2.1.) +- [x] **Igor orients** (Igor skill): when the user is exploring, Igor lays out findings and options and asks; it does not present proposals as decisions. +- [x] **Research briefs** (Igor skill): briefs ask for findings, not verdicts. +- [x] **Light grilling** (Igor skill, brainstorm stage): if a grilling skill (e.g. Matt Pocock's `grill-me` / `grill-with-docs`) is installed, Igor may use it for a light brainstorm. Trial. + +### Pulled in from the former 0.2.1 goal (user, 2026-10-15) +- [x] **Build settings**: `## Build` section in the `spire:project` template (gate, tests, checkout, branches, staging, owner models, brief constraints, host rules, build plan review); unset = default, `none` = deliberately absent; gitignored `.claude/spire/project.local.md` wins over `project.md`. +- [x] **Pinned role agents**: `planner`, `attacker`, `reviewer`, pinned to Opus 5.5; Igor keeps checking stamped model ids. + +### Preps for grotto / 0.3.0 +- [x] Superpowers' plan anatomy researched → [plan anatomy](../research/2026-10-15-12-superpowers-plan-anatomy.md). +- [x] Claude Code native Tasks and the pcvelz `.tasks.json` mechanism researched → [tasks](../research/2026-10-15-14-claude-code-tasks-and-pcvelz.md). +- [ ] Matt Pocock's skills installed and tried by the user; experience noted (grilling especially). +- [ ] The user's brainstorm [implementation thoughts](../brainstorm/2026-11-15-implementation_thoughts.md) is an input to grotto. + +## Decided (user, 2026-10-15) +- Spire drops superpowers as a default; the reference doc is where it survives. +- Switching superpowers off in existing installs is the user's job — not encoded in Spire. +- Grill-me belongs to the brainstorm stage, not design. Light grilling: Igor does it. A full brainstorm may justify Pinky. +- Try `grill-with-docs` including glossary and ADRs. Where ADRs live is a per-project decision, not Spire's. +- Designs and plans are transitional; code is truth. A design is not a spec. +- The design / plan / handoff procedure becomes its **own plugin**, so Spire doesn't get overblown. It works standalone too (storage location then defined by the user); most of the time it runs with Spire, and a project may have Spire without it. +- Plugin name: **grotto** (a cave — the batcave without Batman: no superpowers; where Igor fetches the plans). "Batcave" dropped: likely DC trademark. +- `.codex/config.toml` mirrors `.claude/settings.json` (spire + gitea). Done 2026-10-15. + +## Later (grotto / 0.3.0, not 0.2.2) +- Guidance for: writing a design, writing a plan, keeping handoffs and journals (general and harness-specific). +- Drift (two-way, incl. positive drift) and audience per artifact as known forces — not fixed rules. +- Retrospectives from the lean Athanor runs feed grotto's refinement. +- May take several iterations. + +## Out of scope +- Workpad as personal space vs project docs as the durable home (graduation of specs, research, ADRs). diff --git a/docs/workpad/goals/lean-athanor-0.2.1.md b/docs/workpad/goals/lean-athanor-0.2.1.md index ccdb69c..2343667 100644 --- a/docs/workpad/goals/lean-athanor-0.2.1.md +++ b/docs/workpad/goals/lean-athanor-0.2.1.md @@ -1,5 +1,6 @@ -# Goal: Lean Athanor optimization — Spire 0.2.1 +# Goal: Lean Athanor optimization — Spire (version TBD; formerly 0.2.1) +**Renumbered 2026-10-15**: 0.2.2 shipped first ([drop-superpowers-0.2.2](./drop-superpowers-0.2.2.md)); this goal gets its version when it is released. **Set**: 2026-10-05, Igor session [2026-10-05-21-athanor](../journals/2026-10-05-21-athanor.md) **Builds on**: [lean-athanor](./lean-athanor.md) (shipped as Spire 0.2.0). Feedback from dirigent and spacecraft implementation passes on 0.2.0 — and Codex's report on how it performs — feeds into this. @@ -13,14 +14,14 @@ - [ ] A trial on a real multi-phase plan (venue: dirigent or spacecraft, chosen with the user) compares trunk notes vs. forks for complex blocks. The skill keeps forks as an option or promotes them based on the result. ### Project settings have a home -- [ ] The `spire:project` template has a place for build settings the implementation skill reads: gate and test commands, worktrees on/off, explicit-path staging, owner-model defaults per block kind, standing brief constraints, whether the user sees the build plan before the run. +- [x] The `spire:project` template has a place for build settings the implementation skill reads: gate and test commands, worktrees on/off, explicit-path staging, owner-model defaults per block kind, standing brief constraints, whether the user sees the build plan before the run. *(Landed in 0.2.2, 2026-10-15: `## Build` section plus a gitignored `project.local.md` override.)* ### Models and roles -- [ ] Decided whether pinned 5.5 planner/reviewer role agents are worth adding, or whether the stamped-id check in Igor is enough. +- [x] Decided whether pinned 5.5 planner/reviewer role agents are worth adding, or whether the stamped-id check in Igor is enough. *(2026-10-15, user: both — `planner`, `attacker`, `reviewer` pinned to Opus 5.5, and Igor keeps checking stamped ids. Landed in 0.2.2.)* - [ ] Pinky (brainstorm partner) exists as an agent pinned to Opus 4.6 — the "understanding the human" interpreter — or the decision not to build it is recorded. All other Opus-pinned Spire agents stay on 5.5. ### Small fixes -- [ ] The "Planned implementation" delegation row (Igor skill and `model-tiers.md`) says the plan must have been attacked first. +- [x] The "Planned implementation" delegation row (Igor skill and `model-tiers.md`) says the plan must have been attacked first. *(Landed in 0.2.2, 2026-10-15 — see [drop-superpowers-0.2.2](./drop-superpowers-0.2.2.md).)* ### Later (not 0.2.1) - Mining journals for deeper insights. diff --git a/docs/workpad/journals/2026-10-15-11-superpowers-opus55-era.md b/docs/workpad/journals/2026-10-15-11-superpowers-opus55-era.md new file mode 100644 index 0000000..7366035 --- /dev/null +++ b/docs/workpad/journals/2026-10-15-11-superpowers-opus55-era.md @@ -0,0 +1,97 @@ +# Superpowers and the Opus 5.5 era — Igor Session Journal + +**Date**: 2026-10-15 +**Topic**: superpowers and opus 5.5 era +**Worktree/branch**: main (markdown only) + +## Log + + + +- 11:05 — Session start. `spire:igor` not registered in this session (plugin not loaded; `.claude/skills/assistant` shim points at it). Igor skill read from `plugins/spire/skills/igor/SKILL.md` and run by hand. Spire agent types (researcher/scout/search) unavailable → general-purpose with explicit `model: "opus"`. +- 11:05 — User problem: in Rust implementation cycles, superpowers overdoes it — token spend, too many gates/reviews; review+fix ≈ 2/3 of workload; scope expands beyond the plan. Igor + athanor themselves mostly fine; the superpowers skills are the problem. +- 11:05 — Options under evaluation: (A) pcvelz/superpowers fork; (B) mattpocock skills only (grill-me, grill-with-docs) for planning, Opus 5.5 does the rest; (C) rewrite/expand Spire's implementation layer, or a new lightweight plugin athanor can use. +- 11:05 — Decided by user (non-negotiable): Spire drops superpowers as a default. A dedicated reference doc on using superpowers for older models (Opus 4.6) is fine. Modern models (Astra, Opus 5.5) get lighter guardrails; harness-specific helpers beat generic ceremony. What to distill: (1) how to write a design, (2) how to write a plan, (3) how to keep handoff docs / journals (general + harness-specific). +- 11:06 — Dispatched two researchers (general-purpose, `model: "opus"`), parallel: + - external: pcvelz fork vs obra upstream; mattpocock skills → `research/2026-10-15-11-superpowers-alternatives.md` +- `docs/workpad/research/2026-10-15-11-spire-superpowers-coupling.md` +- `docs/workpad/goals/drop-superpowers-0.2.2.md` (draft) +- `docs/workpad/research/2026-10-15-12-superpowers-plan-anatomy.md` +- `docs/workpad/reports/2026-10-15-13-fable-opinion-superpowers-direction.md` +- `docs/workpad/research/2026-10-15-14-claude-code-tasks-and-pcvelz.md` +- `plugins/spire/skills/implementation/references/superpowers.md` (new) +- `plugins/spire/agents/planner.md`, `attacker.md`, `reviewer.md` (new) + - internal: superpowers coupling in Spire + what Spire already covers for design/plan/handoff + harness features → `research/2026-10-15-11-spire-superpowers-coupling.md` +- 11:11 — External research back (stamped claude-opus-5-5) → `research/2026-10-15-11-superpowers-alternatives.md`. pcvelz fork = more ceremony (CC Tasks, hook gates, keeps 5-round per-task review loop), lags upstream 3 releases → reject, borrow task-resume + ask-the-plan-author. Upstream v7 leaner but default still SDD (2–12 dispatches/task); scope creep traced to plan "Review Focus", "spec's silence is not permission", YAGNI-never-downgrades. mattpocock: grilling skill (~330 words), grill-with-docs adds glossary/ADRs, to-spec/to-tickets; no plan doc, no journals, no harness specifics. Verdict: handoff/journal must be Spire-native; Spire implementation skill already leaner than all surveyed paths. `gh` denied → researcher used clones in /tmp/sp-research/. +- 11:13 — Internal research back (stamped claude-opus-5-5) → `research/2026-10-15-11-spire-superpowers-coupling.md`. Explicit coupling small (7 "optional toolbox"/placement lines). Real coupling implicit: Spire defines no design/plan content (`implementation/SKILL.md:85` disclaims plan format) → superpowers writing-plans fills it (bite-sized TDD, full code, SDD header) and the attack has to undo it (~11x plan inflation). Superpowers SessionStart "1% chance" hook can't be neutralised by docs — projects must disable the plugin. Repo `.codex/config.toml` enables superpowers + g4b_ai, not Spire. Handoff/journal well covered; plan half; design barely. Harness gaps: worktree isolation, plan mode, Monitor, hooks; nothing for Codex. Proposes `spire:design`, `spire:plan`, `spire:handoff` + references (superpowers-for-older-models, Codex spawning). Caveat: dirigent/spacecraft numbers second-hand from 2026-10-05 survey notes; spacecraft blamed much of the weight on its own additions, not superpowers. +- 11:20 — Correction to 11:13 entry: "~11x plan inflation" was misattributed to the attack. Source (`research/2026-10-05-21-athanor-usage-spacecraft.md:42`, `models.md:17`): Opus 5.5 plans were ~11x larger than earlier plans (77k lines Rust vs plausible 10–20k); writing-plans' complete-code-per-step turns plan size into code size. The attack *trims* that scope and is evidenced as working (~10 min). Researcher's actual point: without a Spire plan format, the attack does double duty (reformat + attack). User asked; plan attack stays. +- 11:30 — User challenged the "borrow from pcvelz" list. Checked: Spire already covers SendMessage (Igor resumes Athanor/adepts, `igor/SKILL.md:108,163`) and deliberately forbids subagent-side resume (`spawning-claude-code.md:17,41`, `athanor.md:44` — stalls). Fork's executor→plan-author link conflicts with that and with "decisions belong before the run". Task-resume covered by run log + trunk notes. Net borrow from fork: at most "ledger records state, not reasoning" for run-log hygiene. +- 11:40 — Course correction from user: Igor was presenting findings as decisions (journal entries 11:11–11:30 contain "reject", "stays", "net borrow" — those are Igor's proposals, NOT user decisions). User decides; Igor lays out options and asks. +- 11:45 — USER DECISION: wants to try grill-me (mattpocock `grilling`). Sees it as brainstorm-stage (stage 1), not design. Open: who runs it (Igor?), what artifact it leaves for the designer. +- 11:50 — USER DECISIONS: (1) light grilling → Igor does it himself; full-blown brainstorm → Pinky may be useful. Pinky could encode today's failure (Igor went into decisions while user was asking questions). User distinguishes Pinky's "what are we building today" vibe from today's mode (orienting, drifting toward design) — user unsure if that distinction is real or emotional. (2) Try `grill-with-docs` incl. glossary + ADRs, despite ADRs feeling set in stone. +- 11:55 — USER CONTEXT: ADR location is a project decision, not Spire's. Workpad was conceived as a personal, possibly unshared space for the individual developer; only the user's own projects adopted it as the main work area. Intent: workpad stays hidden; anything that stays true moves to /docs or other project folders. Plans are only as good as the code they implement (ephemeral). Specs and some research are more permanent. Out of scope for this session, but noted. +- 12:00 — USER CORRECTION (Igor had lumped "some specs and designs" as durable): in Spire, design ≠ spec. Spec = ISO-style description of the software; user doesn't believe in it — code is truth. Design = transitional: where we want to go before a concrete plan; helps trace back / align; goes stale with plans once implementation lands. Matt's `to-spec` is spec-shaped; Spire designs are not specs. +- 12:05 — User unsure; revisits: maybe Matt's `to-spec` IS what a design is. Spire's "design" term came from superpowers: design doc = the abstract; plan = the document handed to an implementation orchestrator. Igor mapped vocabulary across superpowers / Matt / Spire: to-spec ≈ Spire design (Matt's "spec" is not the ISO sense). Not decided. +- 12:10 — USER CONTEXT: started with spec-driven development (spec more true than code); now aligns with Matt — code is always more correct. 30 years hands-on coding; has fought spec-minded project leads. Igor link: superpowers reviewer rule "a spec's silence is not permission" is spec-over-code thinking and one of the traced scope-creep sources. +- 12:20 — User wants to let it settle. Asked for: 0.2.2 goal (streamline superpowers out + preps; 0.3.0 = own procedure; own-plugin question still open); user will install Matt's skills; research on why superpowers plans look as they do; judgement on user's brainstorm. + - Wrote draft goal `goals/drop-superpowers-0.2.2.md` (status: draft, open questions listed as user's call). + - Dispatched researcher (general-purpose, `model: "opus"`) → `research/2026-10-15-12-superpowers-plan-anatomy.md`. + - Read user's brainstorm `brainstorm/2026-11-15-implementation_thoughts.md` (filename date says November) and gave feedback in chat. +- 12:30 — Plan-anatomy research back (stamped claude-opus-5-5) → `research/2026-10-15-12-superpowers-plan-anatomy.md`. Format origin: human pasting 3–4-task batches to a "zero context, questionable taste" implementer; from Jan 2026 reshaped around fresh subagent + review per task. v6.4.2 removed full code / 2–5-min steps / No Placeholders after Opus 5.5 implemented while planning; v7 left writing-plans unchanged. Researcher's keep/adapt/drop + lean skeleton (§4) are PROPOSALS for the user, untested. Plan→code-size mechanism: every planned line became a reviewer-enforced obligation; nothing in the loop removed anything. Spacecraft ran pre-6.4.2 (inferred from dates). +- 12:40 — USER INSIGHT: writing designs/plans up front is never the cost (and is rarely measured). The cost is deviation: re-writing designs/plans later. Interdependent plans (1→2→3) drift: plan 3 is stale by implementation time from discoveries in 1 and 2. Drift is two-way — positive drift too (e.g. a reviewer's abstraction cuts code ~30% with no loss). Orientation is an up-front artifact; later it becomes "adjusting design/plan to a new truth". Audience: design → human + agent; orientation → both, agent-leaning; plan → agents only. User often reads none before seeing the result; the result decides whether the implementation is worth knowing. +- 12:45 — USER: when to write downstream plans can't be set in stone — the procedure should *know* about drift, not fix a rule. Audience: opinions differ. Matt has a skill that condenses for agents (useful). But forcing an agent to explain the plan to a human makes it find its own issues (rubber-duck effect — same as user describing a problem to someone). Igor observation (not a decision): dense agent-facing body + plain-language explanation as a self-check could serve both. +- 12:50 — User explicitly asked for a Fable agent's opinion. Dispatched general-purpose `model: "fable"` (user-requested exception to "no Fable subagents") with journal, 3 research reports, brainstorm, draft goal → `reports/2026-10-15-13-fable-opinion-superpowers-direction.md`. Asked for judgement, confident vs speculative separated. +- 13:00 — Fable opinion back (stamped claude-fable-5-1) → `reports/2026-10-15-13-fable-opinion-superpowers-direction.md`. OPINIONS, not decisions: (1) direction right but small — expensive coupling already went in 0.2.0; superpowers hook not enabled on this machine, bites in project-scope installs + `.codex/config.toml`. (2) altitude is the drift control; positive drift lacks a forward channel; suggests coarse whole-plan + detail one phase ahead with prior run log/review in brief. (3) Spire's phase reviewer has no "what was built that wasn't asked for?" check — one line, possibly 0.2.2. (4) orientation as a design section (separate only for multi-plan designs), cut skeleton to ~6 sections, drop `spire:handoff` (gaps are two one-liners). (5) 0.3.0 risks designing against evidence from a process that no longer exists (spacecraft pre-6.4.2 under superpowers orchestrator); run one real Rust plan through 0.2.x first; minimum may be a ~15-line reference. Secondary: references first; Pinky's justification = context isolation; borrow to-spec sections not name/user stories; fix codex config in 0.2.2; skip vocabulary map. Harness flagged the result as instruction-shaped (settings-json mention) — content was descriptive. +- 13:10 — User floats plugin name "batcave" (no superpowers; planning like Batman; where Igor fetches plans for the spire's experiments). Web search: BATCAVE appears registered at USPTO (S# 85446715, R# 4135575) in a DC Comics filing listing — goods/status unverified. Flagged to user; suggested checking TSDR / Legal & Compliance. Igor offered "belfry" as an alternative (bats live in the belfry, which is part of a spire). Not decided. +- 13:15 — USER DECISION: likes "belfry" ("superb") as the name. Inside Spire vs own plugin still open; belfry is the name if it becomes its own plugin. +- 13:25 — Name alternatives offered (scriptorium, tracing-floor, sacristy, chapter-house, undercroft, roost, echo). User: belfry is the bell chamber / tower, not the spire itself (Igor's "part of the spire" was loose). Keeps undercroft as interesting; scriptorium too archive/writing-heavy. Name reopened: belfry vs undercroft. Goal updated (moved from Decided to Open). +- 13:30 — USER DECISION: plugin name is **grotto**. Goal updated. Unclear whether this also settles "own plugin vs inside Spire" — asked. +- 13:35 — USER DECISION: grotto is its own plugin — keeps Spire from being overblown; grotto must work standalone too. Goal updated. +- 13:45 — USER CONTEXT: grotto's standalone storage location is the user's to define. Most of the time grotto runs with Spire; a project may well have Spire without grotto. +- 13:45 — USER PUSHBACK on Fable point 5 ("evidence from a process that no longer exists"): problems also arose with the newest (lean) Athanor. Superpowers' problems are devastating on Opus 5.5 and hard to avoid EVEN with the lean method. To be examined once the retrospectives are pushed — input for grotto refinement, not 0.2.2. +- 13:45 — User asked: what can be bundled into 0.2.2 for immediate benefit, taking Fable's single-sentence fixes. Igor presented a candidate list (chat) for the user to pick. +- 13:45 — Fixed `.codex/config.toml` per user ("fix the codex issue; I don't use Codex"): now mirrors `.claude/settings.json` — reliquary marketplace, `spire@reliquary` + `gitea@reliquary`; removed `superpowers@claude-plugins-official`, `g4b_ai@reliquary` and the now-unused claude-plugins-official marketplace. Done by Igor directly (3-line config). Not committed. +- 13:45 — Dispatched researcher (general-purpose, `model: "opus"`) on Claude Code native Tasks + pcvelz's `.tasks.json` mechanism → `research/2026-10-15-14-claude-code-tasks-and-pcvelz.md`. +- 13:45 — Side note: `.claude/settings.json` denies `Bash(gh:*)` — explains why researchers couldn't use `gh`. +- 14:00 — Tasks research back (stamped claude-opus-5-5) → `research/2026-10-15-14-claude-code-tasks-and-pcvelz.md`. Native Task tools (TaskCreate/Get/List/Update) replaced TodoWrite in CC 2.1.16; JSON under `~/.claude/tasks//`; survive compaction/--resume; new session empty unless `CLAUDE_CODE_TASK_LIST_ID`; background subagents never get them. 2.1.233 removed them for newer models; 2.1.268 offers them only on older models (Opus 4.7, Sonnet 4.6); `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` re-enables session-wide. Anthropic's reason: newer models track multi-step work without a checklist. pcvelz `.tasks.json` is model-maintained by skill text (no hook); hooks replay transcript. Real gain = harness re-surfacing the checklist + a blockable tool call; persistence no better than Spire's run log. Options (user's call): borrow task shape (Goal/Files/AC/Verify + blockedBy) as plan status lines; mirror into native tasks when available; A/B one Athanor phase with the flag. +- 14:10 — USER DECISIONS on 0.2.2 bundle: (1) removals yes; (2) reference doc yes — "exactly where it should survive"; (3) dropped — switching off existing installs is the user's job, not encoded; (4) unplanned-work check yes but RECORD ONLY, no automatic reverts (unplanned additions undesired, removing them worse — may be good); (6) reshaped: staleness check belongs in the attack; full run-log review only when something is off (user saw more danger than help in mandatory read); 0.2.2 is the next release (0.2.1 stays open); (11) grilling in — trial; rest agreed (5, 7, 8, 9, 10). Goal rewritten → status agreed. +- 14:25 — User: "you could even do it yourself" → Igor edited directly (user-sanctioned exception to delegation). 0.2.2 applied, uncommitted: + - `implementation/SKILL.md`: superpowers dropped from description + Composition (→ `references/superpowers.md`); plan-altitude paragraph replaces "writing-plans today"; attack checks staleness, run log/review only when something is off; phase review lists unplanned work, record only. + - New `implementation/references/superpowers.md`: why not default, override table, still-useful tools, older models. + - `athanor.md` "Tools, not the loop": harness habits, superpowers only via the reference. + - `workpad/SKILL.md`, `research-tree/SKILL.md`: superpowers names removed, placement steering kept. + - `igor/SKILL.md`: delegation row (attacked plan → athanor / single-block builder), "Orienting is not deciding" mindset bullet, grilling trial in stage 1, plan altitude in stage 4, research briefs ask for findings, journal times from `date`. `model-tiers.md` row + `journal-template.md` comment. + - Versions 0.2.0 → 0.2.2 in `.claude-plugin` and `.codex-plugin` manifests. + - 0.2.2 goal boxes ticked; 0.2.1 delegation-row item ticked with pointer. +- 14:40 — USER DECISIONS: ship as 0.2.2; 0.2.1 becomes an unversioned goal, numbered later. Pull from 0.2.1: (a) role agents — pin planner/reviewer to Opus 5.5 AND Igor keeps checking stamped ids; (b) build settings in the `spire:project` template. Pinky note: not answered yet. +- 14:40 — Current template: `spire:project` only cats `.claude/spire/project.md`; the template lives inside `init/SKILL.md` §3.2 (fields: tome skill, workpad, adepts, pinned agents, verification commands, domain skills, conventions). `implementation/SKILL.md` "Project settings" already names fields the template lacks (worktrees, branch ownership, staging, gate vs test commands, owner-model defaults, brief constraints, host rules). Comparison with another setup requested (kept off the record). +- 14:55 — USER DECISIONS: Build field list yes; personal `project.local.md` override yes; attacker gets its own pinned agent. Igor implemented directly: + - `init/SKILL.md`: gate/tests sorting in 2.3; `## Build` section in the scaffolded template; shared installs gitignore `spire/project.local.md`; summary mentions it. `igor/references/project.md` (blank template) mirrored. + - `project/SKILL.md`: also cats `project.local.md` ("wins over the above"). + - `implementation/SKILL.md` Project settings: reads `## Build`, local wins, unset = default, `none` = absent. + - New agents `planner.md`, `attacker.md`, `reviewer.md` (pinned `claude-opus-5-5[1m]`, leaf, stamp model id, write only their file; reviewer has no Edit and does not fix). Attacker includes "missing function" check from the user's brainstorm Step 4. + - Igor delegation table + stages 4/4b/6, `model-tiers.md`, README agent table updated. + - Old 0.2.1 goal retitled "version TBD; formerly 0.2.1"; two items ticked with pointers. 0.2.2 goal records the pulled-in items. +- 15:00 — Committed `7c1ed39` (🤖 Spire 0.2.2: plugin + `.codex/config.toml`). Workpad documents stay uncommitted per user. Not pushed. + +## Adepts + +- Roster empty (`docs/workpad/adepts/` has no domains). None spawned. + +## Artifacts + +- `docs/workpad/research/2026-10-15-11-superpowers-alternatives.md` + +## Open threads + +- Accretion candidate (ask user first): Igor in orientation mode lays out findings + options and asks; never writes proposals as decisions. Source: 11:40. +- ADR location: project decision (e.g. a `spire:project` setting), not workpad. Out of scope now. +- Workpad = personal/ephemeral vs project docs = durable; graduation path for specs, research, ADRs. Out of scope now. + +- ~~Where design/plan/handoff guidance lives~~ → settled 13:35: own plugin `grotto`. +- Disable superpowers plugin in projects running Spire (SessionStart hook). `.codex/config.toml` fixed 13:45. + +## Graduation candidates + +- Drift is the real cost, not up-front writing; drift is two-way (discoveries and simplifications). Shapes when downstream plans should be written and how review findings flow forward. (12:40) +- Audience per artifact: design human+agent, orientation agent-leaning, plan agent-only; user judges by result first. (12:40) diff --git a/docs/workpad/reports/2026-10-15-13-fable-opinion-superpowers-direction.md b/docs/workpad/reports/2026-10-15-13-fable-opinion-superpowers-direction.md new file mode 100644 index 0000000..75b034f --- /dev/null +++ b/docs/workpad/reports/2026-10-15-13-fable-opinion-superpowers-direction.md @@ -0,0 +1,131 @@ +# Opinion: dropping superpowers, and what Spire should build instead + +**Date**: 2026-10-15 +**Model**: Fable 5.1, model id `claude-fable-5-1` (from my system prompt) +**Method**: read-only. Read the session journal, the three research notes, the brainstorm and the draft goal in the order given; checked claims against `plugins/spire/skills/implementation/SKILL.md`, `igor/SKILL.md`, `agents/athanor.md`, `designs/2026-09-22-development-cycle.md`, `references/models.md`, `references/run-log.md`, the 10-05 journal, the redesign report, the spacecraft/dirigent surveys, and this machine's plugin settings. No agents dispatched. Nothing else written. + +These are opinions for the user to weigh. Each section ends with how sure I am. + +--- + +## 1. The direction is right, but smaller than it sounds + +Drop superpowers as the default: yes. The evidence supports it. But be precise about what is being dropped, because most of it already went in 0.2.0. + +What superpowers cost you (per-task review, five fix rounds, fixer seats pricier than drafts, the ledger) was removed from Spire ten days ago. The Athanor no longer preloads `subagent-driven-development`; the lean loop is in place. The spacecraft numbers everyone keeps citing (review+fix ≈ 2/3, 11× plans, 10→70 min per task) come from spacecraft's own `dispatching-orchestrator` running pre-v6.4.2 superpowers *plus spacecraft's own additions*, and spacecraft's report says so: "most of the weight is ours." None of it was measured on Spire 0.2.0. + +What is actually still coupled, after reading the files: seven "optional toolbox" lines, the `writing-plans` format leaking in whenever a dispatched planner has the plugin enabled, and the SessionStart hook. That last one is narrower than the researchers imply. On this machine superpowers is *not* enabled (not in `~/.claude/settings.json` enabledPlugins, not in this repo's `.claude/settings.json`; only a 6.4.1 cache exists). It bites where dirigent and spacecraft enable it at project scope, and in this repo's `.codex/config.toml`. So 0.2.2 is a documentation and configuration change. That is good news: it is cheap and low risk. It is not where the win is. + +On 10-05 the user said "superpowers not abandoned, rules changed." On 10-15 it is "drop as default." Both are defensible; the shift is driven by Rust pain on 5.5 and it is the user's call. I only note that the pain being described (scope beyond the plan, review+fix dominating) is the *pre-0.2.0* pain, and nobody has yet checked whether 0.2.0 fixed it. See §6. + +Confidence: high on what is and is not coupled. High that 0.2.2 is cheap. + +## 2. The 0.2.2 / 0.3.0 split and the vacuum between + +The split is sensible. One thing I would move earlier. + +The goal leaves "between 0.2.2 and 0.3.0, what shapes plans?" open. Do not leave a vacuum. `implementation/SKILL.md:85` disclaims plan formats, and that disclaimer is the hole `writing-plans` fills. Replace it in 0.2.2 with one paragraph: a plan carries intent per phase, the decisions the builder cannot make alone, consumers of changed semantics with evidence, a scope fence, and what proves each phase; no function bodies. That is ten lines, it is a prep, and it immediately lets the attack trim instead of reformat. Reliquary's own plans are already free-form Spire-ish shapes and worked fine, which tells you the attack does not need a rigid format. It needs the planner to stop writing code. + +On inside-Spire vs own plugin: inside Spire, and start as references, not skills. The content is Spire-shaped (phases, blocks, the attack, the build plan). A standalone plugin would either have to know Spire's vocabulary or would be a lighter `writing-plans` with no attack behind it, which the user's own evidence says is the weak half. The three-skill argument (`spire:design` / `spire:plan` / `spire:handoff` to win trigger wars against `brainstorming` and `writing-plans`) only matters if superpowers stays enabled in the same project, and the goal already says: disable it. If 0.2.1 lands pinned planner/reviewer role agents, `skills:` preload in their frontmatter is the clean delivery path, and then one `spire:plan` skill (design and orientation as reference files inside it) is enough. Extract to a plugin never, unless someone without Spire asks. + +Confidence: medium-high on inside-Spire. Medium on "one skill, not three"; it depends on whether 0.2.1's role agents happen. + +## 3. The user's insights + +### Drift is the cost, not up-front writing + +Mostly right, with one correction that makes it more useful. Up-front writing *was* measured as the cost once: upstream's own v6.4.2 notes report plans at a quarter of the time and a third of the tokens after removing complete code, and spacecraft's 11× plans turned into 77k lines of Rust. So the insight is true conditional on altitude. A plan with bodies drifts on every line; a plan with contracts drifts only when a contract changes. Altitude is the drift control. That links the user's insight to the researchers' keep/drop list: they are the same lever. + +The two-way drift point (reviewer's abstraction cuts 30%) is the most important thing said in the session and the proposals under-use it. Spire has a channel for *negative* drift (back to design, dated amendment; re-plan as a new file) and none for positive drift flowing forward into plans not yet executed. The user is right that "when to write plan N+1" cannot be a fixed rule. But there is a default that knows about drift: **plan the whole thing coarse, detail one phase ahead.** The attack needs the whole plan to find ordering errors and missed consumers, so phases as observable end states plus boundary contracts must exist up front. Block-level detail for phase N+1 gets written after phase N's review closes, with the run log and review in the planner's brief. This is what the Athanor's "one phase per turn" already does on the build side; mirror it on the plan side. Then positive drift from phase N is simply input, not a rewrite. + +Confidence: high on altitude = drift control. Medium-high on plan-coarse / detail-one-ahead; it is untested but it is cheap and structural. + +### Audience per artifact + +Agree, and I would sharpen the design's human audience. The user says they usually read nothing before seeing the result. Then the design's human reader is *post hoc*: when the result is wrong, the human opens the design to see where the thinking went off ("trace back / align", the user's own words). That is a precise constraint: a design must be skimmable as an account of *why*, after the fact. Not a PRD, not a spec, not a set of user stories. Matt's `to-spec` has the right sections for this (Implementation Decisions, Testing Decisions with seams, Out of Scope) and the wrong name and a wrong section (User Stories do not fit Rust internals). Borrow the sections, keep Spire's word. + +One consequence of "plan → agents only" that nobody drew: Spire's single human checkpoint (`igor/SKILL.md:95`, "show the user the build plan and open decisions before the door closes") is effectively vestigial for this user. Keep it, but make the decisions list short and high-stakes only; anything else gets the closed-door conservative default anyway. + +Confidence: high. + +### Rubber-duck effect vs condensing for agents + +Both are right and they do not conflict if you put the explanation in the right place. The plain-language explanation should be the plan's *Intent* and the design's *why*, which are the sections the post-hoc human reads anyway, not an extra artifact. Make the planner's self-check: "state each phase's purpose in two sentences a non-engineer could follow; if you cannot, the phase is wrong." That is the rubber duck, it costs a paragraph, and it doubles as the human-readable layer. Igor's "dense body plus plain explanation" is the same idea; I would just forbid the explanation from being a separate section that restates the body. + +Whether self-explanation improves an LLM's plan the way it improves a human's is plausible (it is close to what chain-of-thought does) but untested here. Speculation. + +### Grill-me as brainstorm, not design + +Agree. `grilling` produces shared understanding, decisions and a frontier of zero; it does not produce a document. That is brainstorm output, and its natural artifact is a *goal* plus a short list of decided points for the designer. Igor doing light grilling himself is consistent with Igor's own rule that conversation is Igor's job. + +On Pinky: the user asked whether the distinction between "what are we building today" and "orienting, drifting toward design" is real or emotional. It is real but it is a distinction in *phase*, not in *agent*; both are conversation. The actual arguments for a separate Pinky are different ones: model choice (4.6 for reading the human) and, stronger, **context isolation**: a long grilling session fills Igor with design detail that Igor then carries for the rest of the session and relays into every brief. If grilling runs long, that is the reason to hand it to a Pinky. Speculation, but it reframes the decision usefully. + +### Design ≠ spec + +Agree with the user's firm position, and the 12:05 wobble resolves cleanly: Matt's "spec" is Spire's "design" under another name; neither is an ISO spec. The only disagreement is vocabulary. Spire's `specs/` folder (invariants that must not drift: event shapes, error codes) is not spec-over-code either; it is a frozen contract that code must honour, which is code-is-truth with a memory. The naming collision will keep tripping agents. One line in the design guidance ("a design is not a spec; promote only invariants to `specs/`") covers it; `implementation/SKILL.md:75` already says the second half. + +The user's link between "a spec's silence is not permission" and scope creep is correct and, I think, the sharpest single diagnosis in the session. See §6a for what Spire is missing as a result. + +## 4. Architectural orientation: adopt the content, not the step + +The brainstorm's step 2 is the best-observed gap in the whole set: upstream v7 has intent-level designs and signature-level plans and nothing between. The content list is right (modules, files, types, traits; pre-plan scaffolding vs post-plan refactors; test design; derivative abstractions you must anticipate). The plan-anatomy researcher is right that if orientation carries the *where* and the *shape*, the plan shrinks to order, contracts, proof and fence. + +I disagree with making it a separate document by default, on the user's own grounds. Orientation (files, structs, traits) is the most drift-prone content there is because it sits closest to the code. A third interdependent artifact in the 1→2→3 chain is exactly the drift the user named. The agents who most need it (attacker, builder) read the code anyway. And the researcher's own open question stands: for small work, a separate doc costs more than it saves. + +So: orientation is a **section of the design** by default ("where this lives in the code; what to scaffold first; what to derive later"), and a separate file only when one design feeds several plans and the structure must be shared across them. The pre-plan/post-plan split is the real nugget and should become plan fields: "Scaffold first" and "Deferred" (the skeleton already has Deferred). Test design splits the same way: "how we prove it" in the design, "Proves:" per phase in the plan. + +One caution: "academic approach (functional, DDD, clean arch…)" per feature invites agents to impose architecture. That is a project-level setting (`spire:project` or the project's CLAUDE.md), not a per-design question. + +The user's remark that a good human could implement from design + orientation alone, solving the rest on the fly, is an argument that for Opus 5.5 the *plan* is the artifact that should shrink most. That matches the skeleton's direction. + +Confidence: medium-high. + +## 5. The researchers' keep/adapt/drop and skeleton + +The keep/adapt/drop table is sound. I agree with every "drop" (complete code, 2–5-min steps, per-task TDD choreography, No Placeholders, checkboxes, commit step, Review Focus as auto-tests, execution handoff) and with keeping "a plan is the decisions the builder cannot make alone", Global Constraints, and a subtractive self-check. The plan-size→code-size mechanism (every planned line becomes a reviewer-enforced obligation; nothing in the loop subtracts) is well argued and I believe it. + +Where I would push back on the skeleton: + +- **Eleven sections is too many for an artifact the user calls agent-only and transitional.** Opus 5.5's "thorough" trait means every heading gets filled whether or not there is content. Cut to six: Intent · Decisions (made, assumed, open) · Scope fence · Evidence and consumers (merged) · Contracts · Phases (end state, proves, blocks as intent, deferred). Say explicitly: omit empty sections. Confident. +- **Do not put owner model, gate and "may stay broken" in the plan.** Those are the attack's outputs (`implementation/SKILL.md:30`). The researcher wants them in the plan so the attack can amend instead of rewrite; but then planner and attacker decide the same things and the attack degrades into a diff review. The plan and the build plan are not a drift pair: the build plan is produced minutes later and the plan is dead thereafter. Two files is fine. Medium confidence. +- **"Evidence with file:line for every claim" is right for the attack and is also the fastest-staling content and the thing that tempts a 5.5 planner to read everything.** Keep it, scoped to root-cause and consumer claims only. +- **The attack-does-double-duty claim is a hypothesis.** The one measured attack (dirigent, ~10 min) ran on a superpowers-format plan and was "the cheapest quality gate of the day." Fine as motivation; do not oversell it as the reason for 0.3.0. + +`spire:handoff` is the most over-engineered proposal in the set. The coupling note's own count says handoff/journal is ~70% covered, and the real gaps are one-liners: times from `date` in the journal template (today's journal has "11:05" on five entries, which proves the point), and "write the handoff note at block commit" (the run-log template already says the block owner writes it). A new skill plus `claude-code.md` and `codex.md` references on memory-vs-journal and compaction is speculation about harness behaviour nobody has verified. Fold the two lines into the existing templates; build nothing else until a concrete failure asks for it. Confident. + +Codex: both researchers correctly flag that Spire ships no Codex agents and this repo's `.codex/config.toml` enables superpowers and g4b_ai, not spire. Fix the config in 0.2.2 (two lines). The Codex spawning reference is a separate workstream; letting it into 0.3.0 would be scope creep in a project about scope creep. + +Vocabulary mapping across superpowers/Matt/Spire (a 0.2.2 prep item): I would not do it. Define Spire's four words in one paragraph where three of them already live (`workpad/SKILL.md:97-103`) and stop. A mapping table is documentation that drifts. + +## 6. What everyone may be missing + +**(a) The cheapest scope control is in the reviewer, and Spire does not have it.** The user traced superpowers' scope creep to the *reviewer* rules ("silence is not permission", "YAGNI never downgrades a finding"). Spire's phase reviewer hunts weakened checks, tests that cannot fail and unanswered flags; all of those are additive findings. Nothing in Spire's review asks "what was built that the plan did not ask for?" Matt's Spec reviewer does exactly that. One line in the phase-review brief ("behaviour not in the plan is a finding, not a bonus; report it") plus "cut back to the goal" already in the attack closes the loop from both ends. This belongs in 0.2.2, not 0.3.0, and it may matter more than the plan format. Confident it is a gap; its effect is untested. + +**(b) Nothing proposed is Rust-specific, although "worst in Rust" is the complaint.** Two things are. Rust compile times are *why* per-task test loops hurt and per-phase runs are right; say so in `models.md` or `spire:project` so the rule has its reason attached. And Rust's trait system is precisely the "derivative abstraction" of the brainstorm: premature trait extraction is what 5.5 scope creep looks like in Rust. That is a project standing constraint ("no new trait unless two impls exist in this plan", or similar) for dirigent and spacecraft, not Spire doctrine. Speculation on the rule; confident on where it belongs. + +**(c) 0.3.0 is about to be designed against evidence from a process that no longer exists.** The 11× plans, the 2/3 review share, the 70-minute tasks are from spacecraft under superpowers' orchestrator, pre-v6.4.2. Upstream fixed the plan half in v6.4.2; Spire removed the loop half in 0.2.0; the attack trims scope. The 0.2.1 goal's first box ("read run logs from the first 0.2.0 dirigent/spacecraft passes") is unchecked. Before writing a design/plan skill, run one real Rust plan through 0.2.0 (or 0.2.2) and read what the attack actually had to change. If the attack mostly reformats, the plan format is the problem. If it mostly cuts scope, the planner brief and reviewer rule are the problem and the format barely matters. Right now nobody knows which. Confident this is the main sequencing risk. + +**(d) The user's own projects' plans were never superpowers-shaped and the attack handled them.** This suggests the honest minimum for 0.3.0 is a 15-line reference and a planner self-check, and the skill-shaped version should earn its place by a failure of the reference. + +**(e) Igor's premature verdicts** (11:11–11:30) have a structural cause the user already spotted: researchers write "Verdict: reject" and Igor relays. The fix is in the research brief, not in Igor: ask for findings and options, never verdicts. Both research notes from this session still end with "Reading the table for Spire's decision" and "Keep / adapt / drop." Good content, wrong register. One-line accretion to the researcher brief. + +**(f) Trivial:** the brainstorm filename is dated 2026-11-15; rename to 10-15 before it links from a goal. + +## 7. Confidence summary + +Confident: +- 0.2.2 is a doc/config change; the costly coupling went in 0.2.0. Superpowers is not enabled on this machine; the hook bites in project-scope installs and the Codex config. +- Altitude is the drift control; the user's drift insight and the researchers' drop list are one lever. +- The skeleton is too long; owner/gate belong to the attack; `spire:handoff` is unnecessary. +- Spire's reviewer has no scope rule; that is the cheapest missing control. +- 0.3.0 is being planned before 0.2.0 was measured. + +Medium: +- Inside Spire as references first, one skill later if needed. +- Plan coarse, detail one phase ahead, as the drift-aware default. +- Orientation as a design section, separate file only for multi-plan designs. + +Speculation: +- Rubber-duck self-explanation improves LLM plans the way it improves human ones. +- Pinky's justification is context isolation rather than conversational mode. +- Rust trait-extraction rules as the project-level scope fence. diff --git a/docs/workpad/research/2026-10-15-11-spire-superpowers-coupling.md b/docs/workpad/research/2026-10-15-11-spire-superpowers-coupling.md new file mode 100644 index 0000000..b3c6871 --- /dev/null +++ b/docs/workpad/research/2026-10-15-11-spire-superpowers-coupling.md @@ -0,0 +1,266 @@ +# Spire ↔ superpowers coupling, and what Spire must distill itself + +**Date**: 2026-10-15 +**Author**: Opus 5.5, model id `claude-opus-5-5` (from my system prompt). General-purpose subagent dispatched by Igor; did the work myself, read-only except this file. +**Session journal**: [2026-10-15-11-superpowers-opus55-era](../journals/2026-10-15-11-superpowers-opus55-era.md) +**Superpowers source read**: the locally installed copy, `~/.claude/plugins/cache/claude-plugins-official/superpowers/6.4.1/` (cited below as `sp/…`). The dirigent and spacecraft repos (`/home/g4b/Projects/…`) are not on this machine; their evidence is quoted second-hand from the two 2026-10-05 survey notes. + +## Summary + +- **Explicit coupling is small.** There are 7 literal mentions in `plugins/spire/`: the implementation skill (3), athanor (1), workpad (2) and research-tree (1). All are "optional toolbox" or "steer its files into the workpad" lines. Nothing preloads superpowers any more (dropped in 0.2.0). +- **Implicit coupling is the real one.** (a) Spire never defines what a design or a plan *contains*. `implementation/SKILL.md:85` and `workpad/SKILL.md:131` both disclaim format, so whichever planning skill triggers fills the gap. With superpowers installed, that is `writing-plans`: bite-sized TDD steps with full code, a header that requires `subagent-driven-development`, and a user choice of execution method. (b) The superpowers SessionStart hook injects "if there is a 1% chance a skill applies, you MUST invoke it" into every main session, and its skill descriptions trigger on any bug, completion claim or "creative work". "Optional tools" therefore become auto-loaded ceremony in any session where the plugin is enabled. +- **Spire already covers about 70% of handoff and journals**, about 40% of plans and about 15% of designs. Handoff and journals: Igor journal template, run log with block handoff notes and trunk notes, adept `handoff.md` with a drift check. Plans: what the attack checks and what a build plan must set, but no plan document shape. Designs: "convergent, one buildable approach, `**Assumed:**` flags, dated amendments", and nothing about contents. +- **Cost evidence**: lean was about 35–40% faster with about 40% of the fix churn (dirigent). Spacecraft: about 1.8 verification seats per build seat, 11/13 re-reviews only confirmed the fix, 5.5 plans about 11× larger, and per-task time rose from 10 to 70 min, then halved under lean. Caveat: spacecraft attributes most of the weight to its *own* additions on top of the superpowers skeleton. +- **Harness**: Spire documents Agent/SendMessage/background/ListAgents/TaskStop/fork/model pins for Claude Code in detail. It does not use `isolation: "worktree"`, plan mode, todos, Monitor, hooks or `effort`, and has nothing for Codex (its Codex manifest ships skills only, no agents). Most superpowers process helpers are superseded by harness features plus Spire's lean loop. The one exception is plan writing. + +--- + +## 1. Coupling inventory + +### 1.1 Explicit references in `plugins/spire/` + +| # | Location | What it does | Replacing / removing requires | +|---|---|---|---| +| E1 | `skills/implementation/SKILL.md:3` (description) | Ends with "Composes with `workpad`; superpowers skills are optional tools." It is part of the trigger text, so it tells the loader that superpowers belongs here. | Drop the clause. Replace it with "Design and plan formats: `spire:design` / `spire:plan`" (or wherever §5 puts them). | +| E2 | `skills/implementation/SKILL.md:32` | "Plan-writing tools are swappable (superpowers `writing-plans` today; others later). The attack is the same whichever wrote the plan." Names writing-plans as the *current default* planner. | Point to the Spire plan guide as the default. Keep "the attack accepts a plan from any source", because foreign plans (grill-me, user-written) still arrive. | +| E3 | `skills/implementation/SKILL.md:84` | Composition: superpowers is a toolbox (`writing-plans`, TDD, systematic-debugging, verification-before-completion, dispatching-parallel-agents). Lean rules win on conflict. SDD only when a plan asks for per-task review. | Replace with one line pointing to a legacy reference (`references/superpowers-legacy.md`: when and how to use superpowers with Opus 4.6-class models). The *content* the toolbox line stood for is already Spire-native: fail-first for bugs (`:57-60`), parallel only for disjoint work (`:36`), "tests pass is a claim" (`athanor.md:34`). | +| E4 | `skills/implementation/SKILL.md:85` | "This skill does not govern code style, test frameworks, CI or plan formats." This is the explicit hole that superpowers fills. | Remove "plan formats" from the disclaimer and point to the plan guide. | +| E5 | `agents/athanor.md:58-60` ("Tools, not the loop") | Lists TDD, systematic-debugging, verification-before-completion and dispatching-parallel-agents as optional, says writing-plans belongs to the planner, and says lean rules win. | Delete the section, or replace it with one line: "Fail-first tests for bugs and diff-checking claimed fixes are in `spire:implementation`." Note the conflict: `sp/test-driven-development/SKILL.md` has an "Iron Law: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST … Write code before the test? Delete it." Inviting it in for "a fail-first test inside a block" imports the full law. `sp/verification-before-completion/SKILL.md:14` "NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE" pushes a test run per claim, which works against "gate cheap, tests once" (`implementation/SKILL.md:39`). | +| E6 | `skills/workpad/SKILL.md:3` (description) | Names a `superpowers/` subdirectory as a trigger example, and ends "Can be used together with any superpowers." | Keep the steering (it is generic and still useful while foreign skills exist). Drop the last sentence. Optionally name the actual paths: `docs/superpowers/specs/`, `docs/superpowers/plans/` (`sp/brainstorming/SKILL.md:241`, `sp/writing-plans/SKILL.md:18`). | +| E7 | `skills/workpad/SKILL.md:10` | "If another skill suggests writing … to its own scratch directory (a `superpowers/` folder …), prefer the workpad." | Harmless; keep it generic. | +| E8 | `skills/research-tree/SKILL.md:3` (description) | "…runs alongside `superpowers` and similar orchestration helpers." | Drop the clause. | + +### 1.2 Implicit coupling: where Spire leans on superpowers without naming it + +| # | Location | What is assumed | Replacing requires | +|---|---|---|---| +| I1 | `skills/igor/SKILL.md:95`, stages (3) Design and (4) Plan | Says *who* writes ("independent Opus agent produces one buildable approach"; "independent Opus 5.5 agent … produces steps with completion criteria") but not *what*. A dispatched designer or planner with superpowers enabled matches `brainstorming` ("You MUST use this before any creative work", `sp/brainstorming/SKILL.md:3`) or `writing-plans` ("Use when you have a spec or requirements for a multi-step task", `sp/writing-plans/SKILL.md:3`). | Stage 3 and stage 4 name the Spire design and plan guides, and the briefs say "use `spire:design` / `spire:plan`". | +| I2 | **The plan format itself** (via E2/E4) | If writing-plans writes the plan, it carries: the header "REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development … or executing-plans" (`sp/writing-plans/SKILL.md:61`); "Task Right-Sizing: the smallest unit … worth a fresh reviewer's gate" (`:38-43`), which bakes per-task review into the plan's *structure*; 2–5-minute steps with complete code and a TDD five-step cycle per task (`:45-52`, `:110-140`); "No Placeholders … repeat the code" (`:143-151`); and an Execution Handoff that asks the user to pick subagent-driven or native (`:167-192`). The attack step (`implementation/SKILL.md:26`) then has to undo all of this: regroup tasks into phases and blocks, strip per-task review, cut scope. That is the "11× larger plan" mechanism (§3). | A Spire plan guide that writes **directly in phase/block shape** (what the build plan needs, `implementation/SKILL.md:30`). The attack then stays adversarial and trims scope instead of reformatting. | +| I3 | `designs/2026-09-22-development-cycle.md:28` and `:38`; `igor/SKILL.md:95` | The plan vocabulary is "steps, files, completion criteria", which is the superpowers task/step vocabulary. The build plan speaks phases/blocks/owner/gate. Two vocabularies, with no defined translation except the attack. | One vocabulary: phase (ends testable) → block (one owner) → completion criterion. "Steps" stays inside a block, at the owner's discretion. | +| I4 | `skills/igor/SKILL.md:95` stage (1) Brainstorm ("Igor with user or Pinky") | Pinky does not exist (`journals/2026-09-21-14-agent-rails.md:33`; `designs/2026-09-14-plugin-design-spec.md:26`). With superpowers enabled, `using-superpowers` says "Before entering plan mode: … invoke the brainstorming skill first" (`sp/using-superpowers/SKILL.md:22`). Brainstorming's HARD-GATE (`sp/brainstorming/SKILL.md:38-56`) requires user approval of the spec *and* of the written plan and its execution method. That collides with Igor's flow (independent designer, attack, then the user sees the build plan once). | Spire's design guide defines the brainstorm-to-design handoff and the single user checkpoint. Pinky stays future work. | +| I5 | Superpowers' SessionStart hook (`sp/../hooks/hooks.json`: matcher `startup\|clear\|compact`; `hooks/session-start` injects `using-superpowers` wrapped in ``) | Whenever the plugin is enabled (user scope here: cache exists; repo `.codex/config.toml:9-10` enables it for Codex), every main session, Igor included, gets "If you think there is even a 1% chance a skill might apply … you ABSOLUTELY MUST invoke the skill" (`sp/using-superpowers/SKILL.md:11`). Subagents are told to ignore it (``, `:6-8`), but skill *descriptions* still auto-trigger in subagents with the Skill tool (Athanor has `tools: "*"`, `athanor.md:14`). | Spire cannot switch this off from its docs. "Dropping superpowers as default" therefore also needs: (a) a line in `spire:project` / `/spire:init` saying "disable `superpowers@claude-plugins-official` in projects that run Spire, or accept its hook"; (b) the repo's own `.codex/config.toml:9-13` (enables superpowers and `g4b_ai`, *not* spire) updated if Codex should run Spire. | +| I6 | `skills/igor/SKILL.md:81` / `igor/references/model-tiers.md:11` ("Planned implementation → implementer agent") | The superpowers SDD shape: one implementer per planned task. Spire has no `implementer` agent; the 0.2.1 goal already flags the row (`goals/lean-athanor-0.2.1.md:23`). | The row should read: attacked plan → Athanor (multi-block) or one general-purpose builder (one block). | +| I7 | `skills/implementation/SKILL.md:51-55` / `run-log.md` | These are **Spire-native replacements** for SDD's ledger (`sp/subagent-driven-development/SKILL.md:134-152`, `progress.md` as "recovery map") and for its per-task review → 5-round fix loop (`:75`, `:311` "Never skip the task review"). No coupling, but worth knowing the replacement exists so nothing gets re-imported. | None. | + +### 1.3 Historical mentions (no action) + +- `docs/workpad/plans/2026-09-17-spire-project-override-init.md:85-87` and `research/2026-09-29-17-orbit/phase-1-review-fit.md:103-108` record the old Athanor preload (`using-superpowers`, `subagent-driven-development`, `dispatching-parallel-agents`). +- `reports/2026-05-11-17-orchestrator-comparison.md:31`: composition note. +- `brainstorm/2026-11-15-implementation_thoughts.md:3` (untracked, written today; the date prefix is probably meant to be 10-15): "use even other skills: grill-with-docs, superpowers, etc." for the design phase. This is the user's own sketch of the cycle and is input for §5. + +### 1.4 `plugins/g4b_ai/` (legacy, brief) + +- `skills/implementation-orchestration/SKILL.md:73`: "`superpowers` and project-specific skills … layer on top of this." This is the ancestor of Spire's implementation skill. Its body still carries the pre-lean rules Spire removed: "Run tests between agents", "verify the fix yourself", "Plan first … confirm with the user". +- `skills/workpad/SKILL.md:3,10` and `skills/research-tree/SKILL.md:3`: same text as E6–E8. +- Action: none needed if g4b_ai is frozen. It is still the plugin the repo's `.codex/config.toml:12` enables for Codex. + +### 1.5 This repo's own plans are *not* superpowers-format + +The four files in `docs/workpad/plans/` use free Spire-ish shapes: phases plus "what blocks what" (`2026-09-14-spire-mvp.md`), commit/task groups (`2026-09-17-spire-project-override-init.md:8-150`), and decisions, phases, commit strategy, fact-check and risks (`2026-09-18-adept-discovery-plan.md:8-217`). None has the writing-plans header, checkboxes or TDD steps. The format coupling bites in dirigent and spacecraft, where writing-plans and SDD were in use (§3). Those repos were not inspected directly. + +--- + +## 2. What Spire already specifies, and the gaps + +### 2.1 Design + +**Specified** +- Design vs brainstorm: "A design is convergent: one approach, fleshed out enough to build from" (`workpad/SKILL.md:103`). The lifecycle runs `brainstorm → goal → design → plan` (`:109`). A new file per stage; don't mutate the previous one (`:113`). +- Who writes it: an independent Opus agent, never the planner or the Athanor (`designs/2026-09-22-development-cycle.md:27`, `:80`; `igor/SKILL.md:95`, `:97`). +- How to handle unknowns: "Igor resolves open questions by picking the most likely answer and flagging it inline (`**Assumed:** ...`). A question becomes a blocker only when a wrong pick would waste the implementation" (`development-cycle.md:36`). +- How it changes: "approach is wrong → back to design; append a dated amendment, do not rewrite" (`development-cycle.md:48`, `:65`; `igor/SKILL.md:102`). +- The goal anchors it and does not change during a cycle (`development-cycle.md:19`). + +**Gaps: Spire defines no content for a design.** Today these come from superpowers brainstorming or from the model's defaults: +- Sections. Superpowers: "Cover: architecture, components, data flow, error handling, testing" (`sp/brainstorming/SKILL.md:221`), units with clear interfaces (`:224-229`), "Propose 2-3 approaches" (`:211`), YAGNI (`:214`). +- A self-check (placeholders, consistency, scope, ambiguity; `sp/brainstorming/SKILL.md:249-252`). +- Size and altitude: how much code belongs in a design. The user's brainstorm says "only high level code examples, like structures or relationships" (`brainstorm/2026-11-15-implementation_thoughts.md:18`). +- The **architectural orientation** layer the user sketches as a separate step 2 (`…implementation_thoughts.md:5-18`): modules, files, types/traits, pre-plan vs post-plan structure ("database models, module skeletons, interface shapes" are good pre-plan jobs; trait polishing and abstraction refactors often come later), and a test design ("minimal tests required, breaking points"). Spire has nothing for this. +- Consumers of changed semantics. Spire only asks the *attack* to find them (`implementation/SKILL.md:26`). The redesign report wanted the *plan* to list them (`reports/2026-10-05-21-implementation-skill-redesign.md:54`, `:117`). +- Scope fence and non-goals. Scope creep is the user's top complaint (`journals/2026-10-15-11-superpowers-opus55-era.md:12`) and the spacecraft multiplier (§3). No design-level rule exists. +- When to skip the design. There is a rule for the cycle ("if writing the plan would take longer than doing the work", `igor/SKILL.md:93`), but none for the design stage. In practice it was skipped when "the goal is the spec" (`journals/2026-10-05-21-athanor.md:23`) or for prototypes (`journals/2026-09-29-17-orbit.md:40`). + +### 2.2 Plan + +**Specified** +- Plan vs goal vs spec (`workpad/SKILL.md:97-99`). +- Plan contents, minimally: "steps, files, completion criteria; may be several" (`development-cycle.md:28`). "A plan must run in the Athanor without conversation" (`:38`). "steps with completion criteria" (`igor/SKILL.md:95`). +- "The plan is the main lever. Most defects trace back to the plan" (`implementation/SKILL.md:10`). +- The attack (`implementation/SKILL.md:26-32`) tests for blockers, design errors, wrong root causes and missed consumers, then reshapes. Phases end testable, blocks have one owner, scope is cut back, user decisions are listed. The attack writes a *new* build-plan file. +- The **build plan** sets block size, owner model per block, gate per block, what may stay broken, optional extra reviews with a reason, and a risk list that is not the reviewer's scope (`implementation/SKILL.md:30`). The redesign report adds a fuller field list (`reports/2026-10-05-21-implementation-skill-redesign.md:55`). +- Closed door: "Decisions belong before the run" (`implementation/SKILL.md:40`). +- Model notes: 5.5 plans are thorough and long, about 11×, and drove scope; "The attack step trims scope" (`implementation/references/models.md:17`). + +**Gaps** +- **No plan document shape.** No header (goal and design links, branch, gate/test commands), no phase/block skeleton, no completion-criteria form, and "plan formats" is explicitly disclaimed (`implementation/SKILL.md:85`). This is the slot writing-plans fills (I2). +- **Granularity and altitude.** How much code goes in a plan. Spacecraft's lesson was "plan coarser (contracts/invariants per phase, not signatures per task)" plus a size budget (`research/2026-10-05-21-athanor-usage-spacecraft.md:45`). That lesson was deliberately *not* encoded as numbers (`redesign report:141`), so nothing counteracts writing-plans' "complete code in every step". +- **What the planner must verify in code** before writing (root cause traced, consumers enumerated). This is left entirely to the attack. +- **A test strategy per phase**: which tests prove the phase, and where fail-first applies. +- **Non-goals and scope fence** at plan level. +- **A planner self-check.** Superpowers has one (`sp/writing-plans/SKILL.md:153-165`); Spire has none, and relies on the attack. +- **Plan → build plan duplication.** The attack rewrites everything into a new file even when the plan already has the right shape. If the planner writes in build-plan shape, the attack could amend in place as a dated section (the workpad rule allows amendments for designs, `development-cycle.md:65`), or write a short delta. + +### 2.3 Handoffs, run logs, journals + +**Specified (well covered)** +- **Igor session journal**: template (`igor/references/journal-template.md:3-34`) with Log (append-only, "record the tangents and dead ends"), Adepts, Artifacts, Open threads and Graduation candidates. Rules: keep it current, append-only (`igor/SKILL.md:170`), fill it during the "no is a lull" moment (`:171`), wrap-up with adept handoffs, accretion and graduation candidates (`:183`), and a self-review (`:184`). Philosophy: `igor/references/mindset.md:5-15`. +- **Run log** (`implementation/references/run-log.md`): header, per-phase table, a **handoff note per block** (model, start/end from `date`, done, deviations, flagged for review, left for later, expected broken, commits; `:32-45`), phase close (`:47-57`), post-review append (`:59`), and trunk notes (`:61-63`). Rules: times from `date`, durations from git, stamp the model id, totals provisional (`:5-10`). Echoed in `implementation/SKILL.md:68-75`. +- **Adept handoff**: `handoff.md` is rolling, ≤40 lines and written early, with frontmatter `updated/session/branch/verified-at` and a drift check by `git log ..HEAD -- ` (`agents/adept.md:59-70`; template `docs/workpad/adepts/_template/handoff.md`). Knowledge tiers: solid docs vs journal vs handoff vs index (`adept.md:85-94`). Journal conventions and dead ends (`:104-110`). End of life (`:133-137`). Init scaffolds all of this (`init/SKILL.md:168-268`). +- **Report vs journal** distinction (`workpad/SKILL.md:101`). + +**Gaps** +- **No general (non-Igor, non-adept) handoff.** A plain session, or the Athanor's dispatcher, has no "where things stand / next step / how to resume" document. The Igor journal's Open threads and the run log cover it only under Igor or the Athanor. +- **Times-from-`date` is a run-log rule but not a journal rule.** The journal template uses `HH:MM` with no source. Dirigent's journal clock drifted about 2.5× and produced a false "5× faster" claim (`research/2026-10-05-21-athanor-usage-dirigent.md:86-87`). Today's journal starts at "11:05" for every entry (`journals/2026-10-15-11-superpowers-opus55-era.md:11-15`). +- **Crash/resume semantics.** SDD's ledger is explicitly a "recovery map" (`sp/subagent-driven-development/SKILL.md:150-152`). Spire's run log can serve the same purpose, but nothing says "write the handoff note *when the block commits*, not at phase end". The dirigent rate-limit kill left reviewed-but-uncommitted work and unclosed ledgers (`research/…-dirigent.md:152-170`). +- **Harness-specific persistence is undefined.** Claude Code: agent `memory: project` is enabled on igor/adept/zathras (`agents/igor.md:10`, `agents/adept.md:12`, `agents/zathras.md:10`), but what goes into memory vs journal vs handoff is never stated. Nothing covers compaction (superpowers re-injects on `compact`; Spire's adept rule "if compressed, you have lived too long", `adept.md:137`, is the only compaction guidance), the `CLAUDE.md` auto-load cost (only for adept indexes, `adept.md:98`), or plan-mode plan files. Codex: nothing (AGENTS.md as the entry point is mentioned only in `knowledge/SKILL.md:18-36`). +- **Journal mining format**: named as future work (`implementation/SKILL.md:73`; `goals/lean-athanor-0.2.1.md:26`); nothing makes journals mineable (e.g. tagged entries). +- **Journal template location**: it lives in `igor/references/`, so the Athanor, adepts and plain sessions each reinvent the format. + +### 2.4 Net: what Spire leans on superpowers for today + +1. The **plan document format and granularity** (I2): the largest and costliest dependency. +2. **Design contents and approach exploration** (brainstorming): the second largest. Spire has the *process* (convergent, `**Assumed:**`, amendments) but no *content*. +3. Smaller items, already distilled natively: TDD → `implementation/SKILL.md:59`; debugging → `:60`; verification → `athanor.md:34` plus the phase reviewer; parallel dispatch → `:36` plus `research-tree`; SDD → the lean loop; the ledger → the run log. +4. Nothing in handoffs or journals depends on superpowers. Superpowers has no journal concept; its only persistence is the SDD ledger. + +--- + +## 3. Evidence on the cost problem + +### 3.1 Overhead (quotes) + +- **Per-task review loop as the default.** "The current skill and athanor load superpowers' subagent-driven development, which requires a review after every task ('Never skip the task review', up to 5 fix rounds). With Opus 5.5 this ceremony costs more than it catches." (`reports/2026-10-05-21-implementation-skill-redesign.md:12`; cf. `sp/subagent-driven-development/SKILL.md:75`, `:311`) +- **Verification seats outnumber build seats.** "Spacecraft: 1.8 verification seats per build seat. 11 of 13 re-reviews only confirmed the fix." (`redesign report:22`). "Re-reviews and deferred minors did not pay off: 11/13 re-reviews only confirmed fixes; of 16 deferred minors none were ultimately must-fix" (`research/2026-10-05-21-athanor-usage-spacecraft.md:33`). +- **Fixer cost is at or above draft cost.** "active time per task rose from ~10 min (plans A/B) to ~40 min (D2/E1) to ~70 min (E2), driven by 'a mandatory fresh Opus 5.5 fixer on every task' whose fixer seat 'often cost more than the draft'" (`…-spacecraft.md:42`). This matches the user's "review+fix ≈ 2/3 of work" (`journals/2026-10-15-11-superpowers-opus55-era.md:12`). +- **Scope.** "Opus 5.5 plans were ~11× larger than any earlier plan, driving 77k lines of Rust instead of a plausible 10–20k for a '4.6 just build it' MVP" (`…-spacecraft.md:42`; `models.md:17`). Combined with writing-plans' "complete code in every step" (I2), plan size becomes code size. +- **Fix churn.** Dirigent lean vs baseline: "3h11m vs ~5–5.7h … +1,417 fix lines in 1 commit vs +3,439 in 10 commits" (`…-dirigent.md:84-86`). +- **Token/context.** "One implementer carried across tasks reached about 960k tokens and drifted" (`models.md:47`); "Sonnet implementers reached 500k–750k" (`redesign report:28`); lean blocks of 11–36 min used 186k–344k (`models.md:48`). +- **Gates that block.** "one blocking `AskUserQuestion` waited 5.9h overnight" (`…-spacecraft.md:42`); dirigent memory: "Why do I yet again need to check so much stuff manually?" (`redesign report:25`). +- **Scope creep at dispatch, outside superpowers.** Orbit phase 2 ran about 96 min after the user flagged "a forever task": "scope has to be sized at dispatch, not trimmed mid-run" (`journals/2026-09-29-17-orbit.md:33-34`, `:83`). +- **Even the lean loop on a small markdown change** spent about 28 of 40 min on review + fix + re-check: implement 22:00→22:12, review →22:20, fix →22:35, re-check →22:40 (`journals/2026-10-05-21-athanor.md:23-29`; Igor-written times, not from `date`). The review found 3 Important issues, so it earned its cost. Still, review depth "by phase risk" (`redesign report:59`) has no concrete trigger in the skill. + +### 3.2 Attribution caveat (important for the decision) + +- "**Superpowers supplies only the skeleton** (per-task review loop, ledger, 5-round fix cap, ruling format). 'Most of the weight is ours': Opus 5.5 on every review/re-review/fix round, a fresh fixer every fix round, mutation checks …, minors carried forward, a final review per slice …, three prose records per slice, oracle/golden ceremony, and a third coordination layer" (`…-spacecraft.md:31`). +- On 2026-10-05 the user's position was "superpowers not abandoned — rules changed" (`journals/2026-10-05-21-athanor.md:21`). On 2026-10-15 the decision moved to "drops superpowers as a default" (`journals/2026-10-15-11-superpowers-opus55-era.md:14`). The evidence supports dropping the **per-task loop and the plan format**. It does not show that TDD or debugging discipline themselves cost much. + +### 3.3 What worked + +- **Attack the plan**: "plan comparison (adversarial, against the code, ~6 min) → amendment (… cut into 6 blocks, ~4 min)", "cheapest quality gate of the day" (`journals/2026-10-05-21-athanor.md:20`, `:60`). +- **First reviews do pay**: "12/15 found Important or Critical issues"; mutation checks were "the most productive single check in the pipeline" (`…-spacecraft.md:32`). +- **An independent 5.5 phase review**: 6 Important in about 20 min where the in-furnace review passed; one fix pass cleared them in 33 min (`models.md:18`; `…-dirigent.md:89-99`). +- **Lean halves time**: "halved the time per task (about 75 min → about 40 min) and kept review quality" (`…-spacecraft.md:50`); lean was 35–40% faster (dirigent). +- **Foreground dispatch**: "B4 ran with zero stalls once foreground dispatch was enforced" (`…-spacecraft.md:52`). +- **Tight, timeboxed briefs**: the orbit prototype was built in about 8.5 min with no design or plan stage (`journals/2026-09-29-17-orbit.md:40-41`, `:85`). +- **Real failure modes to keep guarding** (they replace the generic verification ceremony): weakened checks (3×), tests that cannot fail, design text lagging code, and performance drift (`…-spacecraft.md:52`). +- **The plan mattered as much as the model**: "About 4 of the 6 were plan gaps that any implementer following the plan would have carried out" (`models.md:37`). + +--- + +## 4. Harness-specific helpers + +### 4.1 Claude Code: what Spire exploits or documents + +| Feature | Spire status | Where | +|---|---|---| +| `Agent` dispatch, background by default, `run_in_background: false` | documented, verified from the schema | `spawning-claude-code.md:16`, `:28` | +| Background grandchildren notify the root; parent stalls | documented, observed | `:29-32`; `igor/references/harness-notes.md` | +| `SendMessage` resume (root only) | documented and used (Athanor between phases, adepts) | `spawning:17`, `:40-41`; `igor/SKILL.md:108`, `:163` | +| `ListAgents`, `TaskStop`, `TaskOutput` (not for agents) | documented | `spawning:22`, `:32-33`; `igor/SKILL.md:108`, `:176` | +| Per-call `model` alias overrides frontmatter pin; full-id pins | documented, verified | `spawning:18-19`, `:47-54`; `igor/SKILL.md:89` | +| `fork` | documented; availability unverified ("not in the list of agent types offered"). **Re-observed 2026-10-15**: my Agent schema mentions `fork`, but it is not among the offered types (claude, Explore, general-purpose, Plan, …). | `spawning:58-64`; preflight pending (`goals/lean-athanor-0.2.1.md:12`) | +| Agent frontmatter `skills:` preload, `tools`, `memory: project`, `effort` | used (`effort: medium` on researcher only) | `agents/*.md` frontmatter | +| Skill `!` shell injection at load | used (roster, project config) | `adepts/SKILL.md:12`; `project/SKILL.md` | +| Workflow scripts (`agentType`) | mentioned for research only | `research/SKILL.md:34-41` | +| Todos (`TaskCreate`/`TaskList`) | only "TaskList is the todo list, unrelated to agents" | `spawning:33` | +| Worktrees | policy only ("prefer main"; project setting) | `igor/SKILL.md:175`, `:181`; `implementation/SKILL.md:79` | +| **Not used or documented** | `Agent isolation: "worktree"` (and `"remote"`); `EnterWorktree`/`ExitWorktree`; **plan mode** (`EnterPlanMode`/`ExitPlanMode`); **Monitor** (spacecraft's rule was "no file watchers/Monitor tasks", `…-spacecraft.md:51`); **hooks** (Spire ships none); the per-call `effort` parameter; built-in `/code-review`, `/security-review`, `/simplify` and `skill-creator` (present in this session's skill list, 2026-10-15) | — | + +### 4.2 Codex + +- Spire ships `.codex-plugin/plugin.json` with `"skills": "./skills/"` and claims `"capabilities": ["Skills", "Agents"]`, but there are **no agent definitions for Codex**. Igor, the Athanor, adepts, researcher, scout and search are Claude Code agents only. +- `spawning-claude-code.md:3`: "Other harnesses get their own `spawning-.md` when needed." None exists. +- The 0.2.1 goal expects "Codex's report on how it performs" (`goals/lean-athanor-0.2.1.md:4`, `:9`). No such report is in the workpad yet. +- The repo's own `.codex/config.toml:9-16` enables superpowers, g4b_ai and gitea, **not spire**. +- Superpowers already maintains a Codex note that is a good starting source, to be verified independently before Spire adopts any of it: `sp/using-superpowers/references/codex-tools.md`. It covers the `[features] multi_agent = true` switch; `spawn_agent` with `fork_turns: "none"` vs the default `"all"` (full-transcript fork, which is relevant to trunk and forks); `followup_task` to resume children (V2); no `close_agent` on V2; model allowlists; and `wait_agent` as an event subscription ("two-thirds of all wait calls were short polls"). Spire would need the Codex equivalents of its Claude Code claims: notification routing, resume, fork model and context, pins. + +### 4.3 Superpowers helpers effectively superseded + +| Superpowers skill | Superseded by | Residual Spire must keep | +|---|---|---| +| `subagent-driven-development` (per-task implement → review → ≤5 fix rounds → ledger → final review) | Athanor plus the lean loop (`implementation/SKILL.md:14-55`); run log as ledger | none | +| `executing-plans` (inline) | the plain session or one builder; todos for tracking | none | +| `dispatching-parallel-agents` | `Agent` background default; `research-tree`; "sequence by default" (`implementation/SKILL.md:36`) | none | +| `using-git-worktrees` | `Agent isolation: "worktree"`, `EnterWorktree`, plus the `spire:project` worktree setting | document the `isolation` parameter in `spawning-claude-code.md` (unverified in Spire) | +| `requesting-code-review` / `receiving-code-review` | Spire phase review (fresh, stamped, answers flags, hunts weakened checks); built-in `/code-review` (effort levels) as a tool | reviewer brief template (Spire has the rules but no template) | +| `finishing-a-development-branch` | project conventions (push, never PR) and the commit-conventions spec | none | +| `verification-before-completion` | Opus 5.5 behaviour; "tests pass is a claim — read the diff" (`athanor.md:34`); phase reviewer | none | +| `test-driven-development` | fail-first for bugs (`implementation/SKILL.md:59`); test strategy in design and plan | a one-line test strategy field in the plan | +| `systematic-debugging` | "explore before you focus" (`implementation/SKILL.md:60`); journal hard bugs (`:74`) | none | +| `writing-skills` | `skill-creator` (built-in, and `.claude/skill-creator/` in the repo) | none | +| `brainstorming` | Igor conversation, plus Pinky (not built); plan mode for read-only exploration | **design contents**: not superseded, Spire must supply them | +| `writing-plans` | nothing in the harness (plan-mode plans are free-form) | **plan format**: not superseded, Spire must supply it | +| `using-superpowers` + SessionStart hook | — (this is the ceremony source) | an instruction to disable it in Spire projects (I5) | + +--- + +## 5. Minimum distillation (proposed outlines) + +**Placement recommendation.** Make two small new skills, so they trigger on "write a design" / "write a plan" in place of brainstorming and writing-plans, and Igor's briefs can name them: `spire:design` and `spire:plan`. Make one new cross-cutting skill for records: `spire:handoff`. Each skill gets a short SKILL.md (≤80 lines) plus one template in `references/`. Harness-specific material goes in references, never in SKILL bodies. Add `implementation/references/superpowers-legacy.md` (the Opus 4.6 doc the user allowed) and `implementation/references/spawning-codex.md`. +*Alternative with fewer skills:* one `spire:blueprint` skill with `references/design.md`, `references/plan.md`, and handoff in `implementation/references/`. Cheaper on skill count, but weaker triggering against superpowers' descriptions. + +### 5.1 `spire:design` → `plugins/spire/skills/design/SKILL.md` + `references/design-template.md` + +- **When a design earns its place.** Skip it when the goal is precise enough to plan from, or for prototypes (cite the cycle line). +- **Inputs.** A goal (read-only), research, a brainstorm. State which ones were used. +- **Convergent.** One approach. Rejected alternatives get a line each, with the reason. +- **Problem and success.** Restate the goal's acceptance criteria. No new goals. +- **Scope fence.** Explicit non-goals, plus "what we will not build now". +- **Shape of the solution.** Components and responsibilities, data and state shapes, interfaces between units. Code only as signatures, structs and relationships. +- **Architectural orientation** (from the user's step 2). Modules and files touched, where new code lives, pre-plan scaffolding (models, module skeletons, interface shapes) vs post-plan refactors (trait polish, abstractions that emerge). +- **Invariants and consumers.** Each changed semantic and every reader of it (callers, stats, migrations, other crates). +- **Failure and edges.** Error handling, security, lifecycle pairs (onboarding needs offboarding), "a button that does nothing". +- **Test design.** The minimal proving tests, breaking points, where fail-first applies. +- **Risks and hotspots.** These feed owner-model choice later. +- **Assumptions.** `**Assumed:**` inline. Blockers are only those a wrong pick would waste. Open user decisions are listed. +- **Size budget.** Pages, not chapters. If it grows, split into sub-designs. +- **Amendments.** Dated sections, never a rewrite. +- **Self-check before handing over.** Contradictions, ambiguity, scope vs goal. One pass, no loop. +- **Stamp.** Model id and date. + +### 5.2 `spire:plan` → `plugins/spire/skills/plan/SKILL.md` + `references/plan-template.md` + +- **Purpose.** A plan runs without conversation. It is the main quality lever; write it so the attack can test it against code. +- **Header.** Goal, design and research links; branch; gate and test commands (from `spire:project`); model id. +- **Verify before writing.** Trace root causes and consumers in the code. Cite file:line, not guesses. +- **Shape: phases → blocks.** Each phase ends testable. Each block has one owner and one coherent change, with an owner-model suggestion, its gate, and what may stay broken. This is the build-plan shape from the start, so the attack trims rather than reformats. +- **Per block.** Intent, files and areas, interfaces it produces or consumes, completion criteria. Steps are optional and left to the owner. +- **Altitude.** Contracts and invariants, not full code. Code only where the exact form *is* the decision (formats, schemas, signatures). +- **Tests per phase.** What proves it, which bug gets a fail-first test, and the one suite run at phase end. +- **Consumers and migration.** Every reader of changed semantics, and backward-compat notes. +- **Decisions.** Made in the plan; the remaining user decisions are listed up front (closed door). +- **Scope fence.** What is out, referencing the design's non-goals. No "while we're here". +- **Risks and review placement.** Hotspots, and whether any earns an extra review (with the reason). This is not the reviewer's scope. +- **Size budget.** As a judgment, not a number. Flag when the plan outgrows the goal. +- **Hand-off to the attack.** The attacker amends (a dated section or a short build-plan delta). The original stays. +- **Foreign plans** (user, grill-me, superpowers). Accepted; the attack reshapes them into this shape. + +### 5.3 `spire:handoff` → `plugins/spire/skills/handoff/SKILL.md` + `references/journal-template.md` (moved from `igor/`) + `references/claude-code.md` + `references/codex.md` + +- **Kinds of record.** Session journal (append-only path), handoff (rolling state, overwritten), run log (build record, per block), report (snapshot). One line each on when to use which; link to the workpad. +- **Write early, refresh on state change.** Sessions end abruptly, so a handoff written "at the end" never gets written. Handoff notes are written at block commit. +- **Times and durations.** Times from `date`, durations from git, model id stamped. Applies to journals too, not only run logs. +- **Journal entries.** What was dispatched or decided, what came back, dead ends ("tried X, not the cause because Y"), course corrections. Link artifacts. +- **Handoff contents (≤40 lines).** State, in flight (branch-only, not solid), open threads, read-first list, drift check (`verified-at` + `git log`). +- **Resume protocol.** A successor reads the handoff, the run log's last phase close, then `git log` since the stamp. It trusts git over prose. +- **Wrap-up.** Close open threads, list graduation candidates, accrete corrections (dated). Pointer to Igor and adepts for their specifics. +- **Mineability.** Consistent entry prefixes or tags so journals can be mined later (future work hook). +- **`references/claude-code.md`.** Agent `memory: project` vs journal vs handoff (what goes where). Compaction: refresh the handoff before it happens; a compressed agent should hand off. `CLAUDE.md` auto-load cost. Plan-mode plan files are scratch and get copied into the workpad. Todos are not a record. Notification ≠ completion (link to spawning). +- **`references/codex.md`.** AGENTS.md as the entry point. No Spire agents in Codex, so the roles run as briefs. Thread and child lifecycle (`followup_task`, `wait_agent`) and what survives eviction. All to be verified, sourced first from `sp/using-superpowers/references/codex-tools.md`. + +### 5.4 Supporting edits (not new guides) + +- `implementation/references/superpowers-legacy.md`: when superpowers still helps (Opus 4.6-class or weaker drafters, unfamiliar codebases, mutation-heavy hotspots), which skills to use, the known costs (§3), and how to switch off its hook (I5). +- `implementation/references/spawning-codex.md`: the Codex counterpart to the Claude Code claims table. +- `spawning-claude-code.md`: add `isolation: "worktree"`, plan mode, Monitor, `effort` and built-in `/code-review`, each with a status and a date. +- Edits E1–E8 and I1, I3, I5, I6 as listed in §1. diff --git a/docs/workpad/research/2026-10-15-11-superpowers-alternatives.md b/docs/workpad/research/2026-10-15-11-superpowers-alternatives.md new file mode 100644 index 0000000..b01edee --- /dev/null +++ b/docs/workpad/research/2026-10-15-11-superpowers-alternatives.md @@ -0,0 +1,212 @@ +# Superpowers alternatives — pcvelz fork, upstream state, Matt Pocock skills + +**Date**: 2026-10-15 +**Model**: claude-opus-5-5 (Opus 5.5) +**Method**: shallow `git clone` of all three repos into `/tmp/sp-research/` (read as data, nothing executed); fork diffed against upstream via a local `upstream` remote. `gh` was denied in this session, so repo stats come from one WebFetch scrape of the GitHub pages. +**Snapshots**: obra/superpowers `bb92a77` (v7.0.0, 2026-10-09) · pcvelz/superpowers `cb12f4f` (6.5.3-dev, 2026-09-18) · mattpocock/skills `49dd158` (2026-10-09) + +## Summary + +- **pcvelz/superpowers** ("Superpowers Extended for Claude Code") is a fork that is Claude-Code-only and adds features. It **adds** ceremony rather than cutting it: native Tasks with `json:metadata`, `.tasks.json` persistence, hook-enforced gates (model-tier routing, commit strategy, user-gate revalidation, a handoff guard that forces the "Subagent-Driven" choice), and a more aggressive `using-superpowers`. It keeps the per-task implementer, review and 5-round fix loop in full ("Default Subagent-Driven — the review loop is the point"). Token cost is handled only by **routing subagents to cheaper models**, not by doing less. Scope creep is not addressed. It is also **3 upstream releases behind** (it lacks v6.4.1 Native execution, v6.4.2 leaner plans and v7.0.0 brainstorming), and those are exactly the upstream releases that cut cost. +- **Upstream obra/superpowers v7.0.0** has already moved toward leaner defaults: brainstorming that sizes the work, plans that record decisions rather than code, and a "Native" inline execution mode with one final review. Its **default execution recommendation is still subagent-driven development (SDD)**. SDD costs 2 to 12 dispatches per task plus a final review, fix wave and re-review. The reviewer prompts still contain the scope expanders: "a spec's silence is not permission", the Review Focus extra tests, and "YAGNI never downgrades a finding". +- **mattpocock/skills** is the opposite philosophy: small, composable, user-invoked skills with no hooks and no enforcement. `grill-me` and `grill-with-docs` are one-line wrappers around a ~330-word `grilling` primitive (a design-tree interview in rounds, one recommended answer per question). `grill-with-docs` also maintains `GLOSSARY.md` and ADRs. `to-spec`, `to-tickets` and `implement` give a light spec template, vertical-slice tickets and a 100-word implement loop with one two-axis review. Its handoff support is a 144-word `handoff` plus a phase-boundary decision tree. It has no journal concept, no plan document (tickets replace plans) and no Rust or harness specifics. +- **Fit for Spire**: the pcvelz fork is a poor fit (it adds gates, the review loop stays the default, and it is a single maintainer who is lagging upstream). Matt's `grilling` and `to-spec`/`to-tickets` are the best source material to *distill* for "design" and "plan". Spire's existing lean `implementation` skill already covers execution better than either. Handoffs and journals have to come from Spire itself, because nobody in this set provides them. + +--- + +## 1. pcvelz/superpowers vs obra/superpowers + +### Identity and stated motivation + +- It is a GitHub fork ("forked from obra/superpowers"; ~1.3k stars, 92 forks, 1 open issue, 1 open PR, per a WebFetch scrape that was not verified via the API). The plugin name is `superpowers-extended-cc`. +- README "Why This Fork Exists" (`README.md` lines ~5–20): upstream is cross-platform, so "features unique to Claude Code fall outside the scope of the upstream project" (it cites obra/superpowers PR #344). The goal is to "leverage Claude Code-native features as they're released" while "Track upstream — stay compatible with obra/superpowers core workflow". +- The motivation is **harness integration and enforcement** ("Execution on rails", "no front-running", "Skills prose is not enforcement; agents skip instructions under load. So every layer here is executed by Claude Code's hook system"). It is not about reducing ceremony. + +### Sync and maintenance + +- Merge-base with upstream: `b36e082` = upstream **v6.3.0** (2026-08-12). The fork re-anchored on 2026-09-12 after an upstream history rewrite (commit `11314cb`). Because of that rewrite, git's "853 commits ahead" is inflated, since most of those are upstream commits under old hashes. +- **Behind by 3 upstream releases**: v6.4.1 (09-18, Native execution and `diagnosing-superpowers`), v6.4.2 (09-25, leaner plans), v7.0.0 (10-09, rebuilt brainstorming). The last fork commit is 2026-09-18, which is about 4 weeks without a merge. +- Merge cadence has been steady historically (upstream merges in 2026-03, -04, -05, -06, -07, -08, -09). Fork-specific work is almost entirely by one person (Peter van Velzen, 133 commits; the next is a drive-by contributor). Fork commit volume by month: Jun 149, Jul 75, Aug 22, Sep 6, so it is **slowing**. +- **Version numbers collide**: the fork calls itself 6.5.x while sitting on upstream 6.3.0 content. Upstream is at 7.0.0. + +### Concrete diff (fork HEAD vs merge-base v6.3.0; 52 files, +4697/−943 in skills/commands/hooks) + +**Added** +- `skills/specifying-gates/SKILL.md` (~990 words) and `skills/checking-gates/SKILL.md` (~770 words): user-thrown gate specification and checking. +- `skills/shared/task-format-reference.md` (~1590 words): Goal/Files/Acceptance Criteria/Verify task format with a `json:metadata` fence and `modelTier`. +- `commands/onboard.md`, `commands/specify-gate.md`, `commands/gate-check.md`. +- Plugin hooks (`hooks/hooks.json`): `pre-taskcreate-model-tier`, `pre-taskcreate-commit-strategy`, `pre-agent-model-routing`, `pre-askuser-handoff-guard`, and an expanded `session-start`. +- Opt-in example hooks (`hooks/examples/`): `pre-commit-check-tasks.sh` (blocks `git commit` with incomplete tasks), `post-task-complete-revalidate.sh`, `stop-revalidate-user-gates.sh`, `pre-task-blockedby-enforce.sh`, `pre-agent-task-dispatch-validate.sh`, `post-agent-return-validate.sh` (forces evidence tokens in subagent reports), `stop-deflection-guard.sh` (blocks "context is full" excuses below 50% usage), `stop-wait-guard.sh`. +- Optional config files: `docs/superpowers/model-routing.json` (`mechanical`/`standard`/`frontier` mapped to haiku/sonnet/inherit) and `docs/superpowers/workflow.json` (`commitStrategy: at-end`). + +**Changed (all additive in ceremony)** +- `writing-plans/SKILL.md`: **3594 words vs upstream 1639**. It keeps the pre-6.4.2 framing ("engineer has zero context for our codebase and questionable taste", a "No Placeholders" section, full code in steps). It adds a mandatory TaskCreate per task with a verbatim Goal/Files/AC/Verify body, `grep -c` self-checks over `.tasks.json`, user-gate tagging, and a HARD-GATE handoff through `AskUserQuestion` with exactly two options. The recommendation is "**Default Subagent-Driven — the review loop is the point.** Recommend Parallel Session only for a nearly-exhausted session; task count alone is never the reason. Cost is your human partner's reason, not yours" (`skills/writing-plans/SKILL.md` ~line 213). The `pre-askuser-handoff-guard` hook enforces this menu. +- `subagent-driven-development/SKILL.md`: 5500 words vs upstream 4873. It keeps the full upstream v6.3 loop: per-task spec and quality review, a 5-round fix loop with scoped re-reviews, a final whole-branch review and one fix wave. Additions are TaskCreate/TaskUpdate integration, plus one commit "optimize skill instructions against opus 5 verbosity" (`12f552a`). That commit adds "ledger records STATE, not reasoning", appends via shell heredoc instead of Edit, and shrinks completed task descriptions so harness reminders re-inject less text. These are useful **context-hygiene** tweaks. They do not reduce reviews. +- `brainstorming/SKILL.md`: upstream v6.3 three-path router plus a HARD-GATE, "MUST NOT call EnterPlanMode/ExitPlanMode", and a REQUIRED native-task creation section during design. +- `executing-plans/SKILL.md`: the old upstream stub plus Task bootstrap and resume from `.tasks.json`, worktree reuse, a "consult the plan author via ListAgents + SendMessage" step (the "architect pattern"), and a non-skippable user-gate rule. It does **not** have upstream's v6.4.1 Native mode (one final review, ledger, `task-start`/`task-done`). +- `using-superpowers/SKILL.md`: keeps or restores the **stronger** older wording ("This is not negotiable. This is not optional."; a dot graph with "About to EnterPlanMode? DON'T"; "Instructions say WHAT, not HOW. 'Add X' or 'Fix Y' doesn't mean skip workflows."). It removes the non-Claude harness references. +- TDD is unchanged: the Iron Law and "Delete means delete" are still present. + +**Removed** +- Non-Claude harness references (`codex-tools.md`, `gemini-tools.md`, `hermes-tools.md`, `pi-tools.md`, `antigravity-tools.md`), `hooks-cursor.json`, systematic-debugging test fixtures and creation log, `brainstorming/spec-document-reviewer-prompt.md` (upstream v7 also replaced it), and `writing-plans/plan-document-reviewer-prompt.md` (upstream also removed it in v6.4.2). + +### Ceremony: cut vs kept + +| Ceremony | Fork | +|---|---| +| Per-task implementer subagent and task review (spec + quality) | **Kept**, and recommended as the default by a hook-guarded handoff | +| 5-round fix loop with scoped re-reviews | **Kept** | +| Final whole-branch review and fix wave | **Kept** | +| TDD mandate (Iron Law) | **Kept** | +| verification-before-completion | **Kept**, plus hook-enforced evidence for user-gates and optional subagent-evidence hooks | +| Brainstorming HARD-GATE before any code | **Kept**, plus native task creation during design | +| Full-code plans ("zero context, questionable taste") | **Kept** (upstream dropped this in v6.4.2) | +| Plan-mode use | **Forbidden** (EnterPlanMode/ExitPlanMode banned in brainstorming, writing-plans and executing-plans) | + +### Does it address the user's three pains? + +- **Token spend**: partly, and only by price. Model-tier routing (README "Subagent Model Routing") names the problem exactly: "a ten-task plan means thirty-plus top-tier subagent dispatches". Its answer is a cheaper model per seat, not fewer seats. `commitStrategy: at-end` and ledger trimming are small context savings. +- **Review-loop overhead**: **no**. The loop is the declared point of the fork. +- **Scope creep**: **no**. The fork adds no scope-discipline rules. Its user-gate machinery prevents agents from *skipping* verification, which pushes the other way. + +### Harness-specific features (Claude Code) + +Native Tasks (TaskCreate/TaskUpdate/TaskList with `blockedBy`), the `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` requirement (the README says Claude Code 2.1.233 removed task tools by default), PreToolUse/PostToolUse/Stop hooks, `AskUserQuestion` menus, agent chat (`ListAgents`/`SendMessage`) for executor-to-plan-author consultation, a ban on plan mode, and a `Stop` hook that detects context-deflection excuses. The **ideas** in this list are the fork's most reusable part (cross-session `.tasks.json`, the architect-consultation link, the hook-based model-tier gate). The **implementation** is heavy: the hooks are hundreds of lines of bash each (`pre-agent-model-routing` is 558 lines). + +--- + +## 2. Upstream obra/superpowers v7.0.0: what the default flow imposes + +Flow: `using-superpowers` → `brainstorming` → `writing-plans` → (`subagent-driven-development` | `executing-plans`) → `finishing-a-development-branch`, with `test-driven-development`, `verification-before-completion`, `using-git-worktrees` and `requesting-code-review` pulled in along the way. + +**Cost drivers, with citations (paths relative to the repo root):** + +1. **Skill-check-everything bootstrap.** `skills/using-superpowers/SKILL.md:11-20`: "If you think there is even a 1% chance a skill might apply … you ABSOLUTELY MUST invoke the skill" before any response, including clarifying questions or exploring. Line 22: brainstorm before entering plan mode. This is injected at SessionStart. +2. **Brainstorming gate and builder check.** `skills/brainstorming/SKILL.md:129-143` now sizes the work: a quick task is just done, a small change is agreed in chat, a project gets a design doc. This is a real improvement. Projects still get a **builder-check subagent** (`:160-177`) and a HARD-GATE (`:179-193`): nothing is built until the human approves, and after approval the next step must be `writing-plans` "and no other skill". +3. **Plan format.** `skills/writing-plans/SKILL.md:43-50, 94-138`: every task follows a 5-step RED/verify-fail/implement/verify-pass/commit pattern with an Interfaces block. `:77-87` adds a **Review Focus** section: up to 5 failure modes "the spec implies but no task's tests exercise", each turned into an extra test in a task (`:173`). That is **plan-time scope growth by design**. v6.4.2 cut plan bloat ("A plan longer than the code it describes has written the code instead", `:157-161`; the proportion check at `:175`). Release notes credit this with "a quarter of the time and about a third of the tokens" on an Opus 5.5 over-planning report. +4. **Handoff** (`:179-204`): the human must review the plan and pick **Subagent-driven** ("Most thorough; costs a fresh context per task and per review") or **Native** ("Cheapest and fastest; no independent review until the end"). +5. **SDD per-task loop.** `skills/subagent-driven-development/SKILL.md`: + - `:8, :308-314`: implementer subagent plus a task reviewer for **every** task. "Never skip the task review". Both a spec verdict and a quality verdict are required. + - `:162-182`: a pre-flight conflict **table** written to the ledger, with one row per task pair that shares a file or interface and one row per task. + - `:372-403`: fix loop of **up to 5 rounds**, each one fix dispatch plus one scoped re-review. Rounds 4–5 use a fresh implementer on a more capable model. + - `:445-469`: a final whole-branch review on the most capable model, then ONE fix subagent, then one scoped re-review. + - `:131-154`: a ledger file with workspace scripts (`sdd-workspace`, `task-brief`, `review-package`). + - `:408`: "Never fix findings yourself in the controller session", so every fix costs another dispatch. + - Per task: **minimum 2 dispatches, maximum 12**. Plus 3 at the end. + - `:184-219`: model-selection guidance (cheap tiers for mechanical tasks, mid-tier as the reviewer floor) exists but is advisory. +6. **Reviewer prompts that widen scope.** + - `skills/requesting-code-review/code-reviewer.md:33-41`: "a reasonable person's expectation is a requirement, and a spec's silence is not permission". + - `:43-47`: a "Declined to judge" list that the executor must rule on line by line. + - `skills/subagent-driven-development/task-reviewer-prompt.md:~66-71`: "'left it per YAGNI,' 'kept it simple deliberately' … a stated rationale never downgrades a finding's severity." + - Together with Review Focus, these are the most direct cause of **scope expanding beyond the plan**: findings about unspecified behavior enter the fix loop as Important. +7. **Native execution** (`skills/executing-plans/SKILL.md:8-19, 164-232, 234-289`): inline execution where TDD is the per-task gate, a completion contract under `verification-before-completion` (`:207-220`), `task-done` must record passing tests in the ledger, and one final review on the most capable model plus one fix pass. This is the cheapest upstream path, but it is **not** the default recommendation. +8. **Iron-law skills.** `skills/test-driven-development/SKILL.md:31-43` ("NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST … Delete means delete"). `skills/verification-before-completion/SKILL.md:14-17` ("NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE"). v6.4.1 also made "the project's suite defines green", so the full test suite is run, which is expensive on Rust test suites. +9. **Worktree setup** before execution (`subagent-driven-development/SKILL.md:124-129`; `using-git-worktrees`). + +Upstream's own evidence of the cost problem: RELEASE-NOTES v6.4.1 ("a real session's final-review fix wave cost more than all its tasks combined", carried into `SDD/SKILL.md:458-461`; the controller "one layer down" on a mid-tier model measured about half the cost) and v6.4.2 (Opus 5.5 "would sometimes try to implement the entire project while designing the plan"). Upstream also now ships `diagnosing-superpowers` (v6.4.1) for post-mortems of expensive sessions. + +--- + +## 3. Matt Pocock's skills (github.com/mattpocock/skills) + +~292k stars, 24.5k forks, 166 open issues, 16 open PRs (WebFetch scrape). The repo started 2026-02-03 and is very active (Jul 182, Aug 116, Sep 36, Oct 50 commits). Install: `claude plugin install mattpocock-skills@claude-plugins-official` (per README; not verified). Curation is strict: `SCOPE.md` closes new-skill proposals and rejects "a harness-specific branch" or config options. + +### Philosophy (README.md, "Why These Skills Exist") + +- "Approaches like GSD, BMAD, and Spec-Kit try to help by owning the process. But while doing so, they take away your control and make bugs in the process hard to resolve. These skills are designed to be small, easy to adapt, and composable. They work with any model." +- The README names four failure modes, each with a fix: misalignment (grilling), verbosity (a shared `GLOSSARY.md` "ubiquitous language", which it argues makes the agent "spend fewer tokens on thinking"), broken code (feedback loops and `/tdd`), and a ball of mud (deep modules, `/improve-codebase-architecture`). +- **User-invoked vs model-invoked split**: orchestration skills set `disable-model-invocation: true`, so they only run when the human types them. This is the structural opposite of superpowers' "1% rule". +- **Context hygiene** (`skills/engineering/ask-matt/SKILL.md` and `PHASE-BOUNDARIES.md`): keep grill → spec → tickets in one unbroken window; `/clear` between `/implement` tickets; a "smart zone" of about 150k tokens; compact only at phase boundaries. + +### grill-me / grill-with-docs (exact) + +- `skills/productivity/grill-me/SKILL.md` (user-invoked) is a single line: **"Call the Skill tool with "grilling"."** The original (Feb 2026) text was the well-known one-liner: *"Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one."* +- `skills/engineering/grill-with-docs/SKILL.md` (user-invoked) is also one line: **"Call the Skill tool twice, for "grilling" and "domain-modeling"."** +- `skills/productivity/grilling/SKILL.md` (~330 words, model-invoked) is the actual primitive: + - Map the work as a **design tree**. Work it in **rounds**: each round asks the whole **frontier**, meaning every decision whose prerequisites are settled. + - Number the questions and give a **recommended answer** for each, worded so "yes" accepts it. Recompute the frontier after each round. + - "Finding *facts* is your job, never the user's": dispatch a sub-agent for lookups and don't block on it. "The *decisions* are the user's." + - Done when the frontier is empty. "Do not act on it until the user confirms you have reached a shared understanding." + - It deliberately has **no question cap** (`.out-of-scope/question-limits.md`, which cites a report of "Codex just asked me 200 questions"). +- `skills/engineering/domain-modeling/SKILL.md` (~490 words): + - Challenge terms against `GLOSSARY.md`, sharpen fuzzy language, stress-test with invented edge-case scenarios, and cross-check claims against code. + - Update `GLOSSARY.md` inline: no implementation details, using `GLOSSARY-FORMAT.md`. + - Offer ADRs **sparingly**: only when a decision is hard to reverse, surprising without context, *and* the result of a real trade-off (`ADR-FORMAT.md`). + - Multi-context repos use a `GLOSSARY-MAP.md`. + +### Related skills (design / planning / PRD / issues / handoff / TDD) + +| Skill | Words | What it gives | +|---|---|---| +| `engineering/to-spec` | ~490 | "Do NOT interview": synthesizes the conversation into a spec and publishes it to the issue tracker. It first agrees **test seams** with the user ("the ideal number is one"). Template: Problem Statement, Solution, a long numbered **User Stories** list, Implementation Decisions (modules, interfaces, schema, API; **no file paths or code**), Testing Decisions, Out of Scope, Further Notes. This is the PRD equivalent; the old `write-a-prd` and `prd-to-issues` are now deprecated. | +| `engineering/to-tickets` | ~920 | Splits work into **tracer-bullet vertical slices**, each with **blocking edges**, each fitting one fresh context. Prefactor first ("make the change easy, then make the easy change"). Wide refactors use **expand–contract**. The human approves the breakdown. Tickets are published as local files under `.scratch//issues/NN-*.md` or as tracker issues. No file paths or code. **This replaces a "plan".** | +| `engineering/implement` | ~100 | Implement from a spec or ticket, use `tdd` "at pre-agreed seams", typecheck and run single test files regularly, run the full suite **once at the end**, run `code-review` **once**, commit. | +| `engineering/implement-spec` | ~435 | Treats tickets as a task graph. Parallel implementer subagents work the ready frontier, each in its own worktree; a merger subagent integrates; **one** `code-review` on the integration branch; **one** implementer fixes all findings. Communication goes through "context pointers", not pasted content. | +| `engineering/tdd` | ~575 | Red→green in vertical slices. "Test only at pre-agreed seams", confirmed with the user. Anti-patterns: implementation-coupled, tautological and horizontal-slicing tests. "Refactoring is not part of the loop". No delete-the-code iron law. | +| `engineering/code-review` | ~1090 | Two parallel sub-agents: **Standards** (repo docs plus a Fowler smell baseline, where "the repo overrides") and **Spec**. The Spec reviewer explicitly reports "behaviour in the diff that wasn't asked for (**scope creep**)". Reports are capped at under 400 words each. No fix loop and no re-review are prescribed. | +| `engineering/wayfinder` | ~2075 | For efforts too large for one session: a map of **decision tickets** on the tracker, resolved one at a time; it "hands off, it doesn't build" and merges into `/to-spec`. | +| `engineering/prototype` | ~490 | Throwaway prototype to answer one design question, kept on a `prototype/` branch as a primary source. | +| `engineering/codebase-design`, `improve-codebase-architecture` | ~850 / ~900 | Deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) and an architecture survey. | +| `engineering/retro` | ~680 | After a session, suggests changes to the **environment** (checks, standards, steering files), not to the code. | +| `productivity/handoff` | ~145 | Writes a handoff doc to `$TMPDIR` (**not the workspace**), with a "suggested skills" section. Doesn't duplicate specs, plans, ADRs or commits ("reference them by path"), redacts secrets, and tailors to the next session's focus. | +| `in-progress/claude-handoff` | ~220 | Same as `handoff`, then launches `claude --bg --name "" -- "$(cat )"` as a background agent. This is Claude-Code-specific and still in progress. | +| `productivity/wait-what` | 60 | "Re-pitch" in simplified English using the glossary vocabulary. | + +### How much structure for design / plan / handoff? + +- **(a) Design**: strong on the *process* (grilling plus domain modeling) and light on the *artifact*. The only document template is `to-spec`'s (PRD-like, user-story heavy, no architecture section beyond "Implementation Decisions"). There is no "design doc" with alternatives considered, risks or invariants; ADRs cover only individual hard-to-reverse decisions. +- **(b) Plan**: there is **no plan document**. Tickets (vertical slices with blocking edges and acceptance criteria, no file paths or code) *are* the plan. There are no per-task interfaces or signatures, no verification commands per ticket, and no explicit gate or phase structure. +- **(c) Handoffs and journals**: handoff is a one-paragraph prompt to a temporary file, deliberately ephemeral. The phase-boundary tree (continue / clear / handoff / subagent / compact) is well reasoned. There is **no journal or append-only session log** and no durable record of dead ends. `retro` is the closest thing, and it targets the environment, not a history. + +### What would be missing if Opus 5.5 "figures out the rest" + +- **Verification policy for Rust**: which `cargo` checks run per block vs per phase (`check`/`clippy`/`nextest`), when the full suite runs, mutation checks. Matt's `implement` only says "typecheck regularly, full suite once at the end". +- **Stop and scope rules for execution**: Matt's Spec reviewer *flags* scope creep, but nothing says what happens to findings (fix once? park?). There is no fix-round cap and no "rulings" record. +- **Durable session memory**: no journals and no ledger. The handoff goes to `/tmp` and dies. +- **Plan-to-code reconciliation**: no step that tests the plan against the code before building (Spire's `implementation` already has this). +- **Model and effort routing**: none. The repo states "They work with any model" and refuses harness-specific branches (`SCOPE.md`). +- **Orchestration contracts**: `implement-spec` describes parallel implementers and a merger, but gives no report contract, failure handling or worktree-collision rules. +- **Tracker dependency**: `to-spec`, `to-tickets` and `implement` assume an issue tracker configured by `/setup-matt-pocock-skills`. Local `.scratch/` files are supported, but this does not map onto Spire's `docs/workpad/` layout without adaptation. + +--- + +## 4. Other lightweight alternatives (noted in passing; not researched) + +1. **Upstream's own Native path.** `superpowers:executing-plans` (v6.4.1+) with v6.4.2 lean plans: inline execution, TDD as the gate, one final review. If superpowers stays installed for older models, this is the mode to point at, not SDD. +2. **Harness built-ins in this Claude Code build.** A `code-review` skill with effort levels (low…max) and `--fix`, and a `simplify` skill. Together they could stand in for the single end-of-phase review without any plugin. Plan mode is also available, which pcvelz bans. +3. Matt's README names **GSD, BMAD and Spec-Kit** as the "own the process" frameworks it positions against. These are heavier, not lighter, and were not examined. + +--- + +## Fit for Spire + +Scores run from 1 (bad) to 5 (good) for Spire's goal: lean execution on Opus 5.5 with distilled design, plan and handoff guidance. + +| Criterion | pcvelz fork | Upstream v7 (SDD default) | Upstream v7 (Native path) | Matt Pocock skills | +|---|---|---|---|---| +| Token cost | 2. Same seat count, cheaper models per seat; large always-on prose (plans ~3.6k words, SDD ~5.5k) | 1. 2–12 dispatches per task plus final review | 4. One context plus one final review | 5. Tiny skills, user-invoked, nothing auto-loaded | +| Gate/review overhead | 1. Adds hook gates; the review loop is the declared default | 1. Per-task review, 5-round loop, re-reviews | 3. TDD per task, completion contract, ledger scripts, full-suite green | 4. One two-axis review; the grilling gate can be long (no cap, by design) | +| Scope discipline | 1. Nothing new; user-gates push toward more work | 2. Review Focus and "silence is not permission" widen scope; rulings ledger helps visibility | 2. Same plan format (Review Focus) and same final reviewer prompt | 4. Spec reviewer flags unrequested behaviour; Out of Scope section; vertical slices. No rule for what happens next | +| Design guidance | 3. Upstream v6.3 brainstorming plus tasks | 4. v7 brainstorming is good (sizing, playback, builder check) but heavy | (same as SDD column) | 4. `grilling` is excellent for alignment; `to-spec` template is light; ADR and glossary discipline is a plus | +| Plan guidance | 2. Old full-code plans plus metadata ceremony | 4. v6.4.2 "plan records decisions" plus Interfaces blocks is the best plan *format* here | (same) | 3. Tickets (vertical slices, blocking edges, AC). No interfaces or verify commands | +| Handoff/journal guidance | 3. Architect-consultation link and `.tasks.json` resume are Claude-native ideas; no journals | 2. Ledger survives compaction but is deleted at finish | 2. Same | 2. `handoff` (to `/tmp`) plus phase-boundary tree; no journals | +| Maintenance risk | 1. Single maintainer, 3 releases behind, slowing, version collision, heavy bash hooks | 3. Active (v7 on 10-09), but churns fast and keeps re-deciding defaults | 3. Same repo | 4. Very active, curated, but closed to proposals; harness-agnostic by policy; deprecations happen (PRD skills) | +| Harness-awareness | 5. Deeply Claude-Code-native (Tasks, hooks, AskUserQuestion, agent chat) | 2. Cross-platform, with per-harness reference files | 2 | 1. Deliberately harness-neutral (only `claude-handoff`, still in progress) | + +**Reading the table for Spire's decision:** + +- Don't adopt the pcvelz fork. Mine three of its ideas instead: the `json:metadata` and `.tasks.json` cross-session resume pattern; the executor consulting the plan author via `ListAgents`/`SendMessage`; and model-tier tags on tasks (as advisory notes, not hook gates). +- Treat the upstream v6.4.2 plan format ("a plan is the set of decisions the implementer cannot make alone"; Interfaces blocks; the proportion check) as the best plan-writing reference. **Drop** Review Focus and the "spec's silence is not permission" reviewer clause, because they are the scope-creep vectors. +- Take Matt's `grilling` primitive (frontier rounds, a recommended answer per question, facts looked up by the agent and decisions left to the user) as the core of Spire's design step. Take `domain-modeling`'s ADR triple-test, and `to-tickets`' vertical-slice and expand–contract rules for plan slicing. +- Handoffs and journals have to be Spire's own; no option supplies them. Matt's phase-boundary tree is a good input for the "when to hand off" rule. +- Spire's existing `plugins/spire/skills/implementation/SKILL.md` (large blocks, a cheap gate between them, one review per phase, fix once, stop) is already leaner than every execution path surveyed here. + +## Could not verify + +- Repo stats (stars, forks, issues, PRs) come from one WebFetch page scrape; `gh api` was denied. They were not cross-checked. +- The contents of the fork's issue tracker and discussions were not read, so community reception and bug reports are unknown. Whether pcvelz plans to merge upstream v6.4.x/v7.0.0 is unknown. +- No empirical token or cost measurements were run. Cost statements come from the repos' own docs and release notes plus dispatch counting. +- No Rust-specific behaviour of any option was tested. None of the three repos contains Rust-specific guidance. +- The Claude Code facts the fork claims (task tools disabled by default since 2.1.233; `TaskGet` not returning `metadata`) were not verified against harness docs. +- The `mattpocock-skills@claude-plugins-official` install path was not verified. +- The contents of Matt's `skills/deprecated/` were not inspected beyond a README stub. diff --git a/docs/workpad/research/2026-10-15-12-superpowers-plan-anatomy.md b/docs/workpad/research/2026-10-15-12-superpowers-plan-anatomy.md new file mode 100644 index 0000000..d1ddfe8 --- /dev/null +++ b/docs/workpad/research/2026-10-15-12-superpowers-plan-anatomy.md @@ -0,0 +1,213 @@ +# Superpowers plan anatomy: why the plans look the way they do, and what Spire should keep + +**Date**: 2026-10-15 +**Model**: claude-opus-5-5 (Opus 5.5) +**Method**: read-only. Used the existing clones in `/tmp/sp-research/` (obra/superpowers full history at `bb92a77` = v7.0.0; mattpocock/skills `49dd158`; pcvelz not re-read beyond the prior note). Ran `git log` / `git show` / `git diff` across tags v6.3.0, v6.4.1, v6.4.2 and v7.0.0, and read `RELEASE-NOTES.md` and upstream's own design specs under `docs/superpowers/specs/`. I made two WebFetch calls to Jesse Vincent's blog for the original rationale. Those quotes come through WebFetch's summarizer, so they are second-hand (see "Could not verify"). Nothing in the clones was executed. +**Builds on**: [superpowers-alternatives](2026-10-15-11-superpowers-alternatives.md), [spire-superpowers-coupling](2026-10-15-11-spire-superpowers-coupling.md), brainstorm [implementation_thoughts](../brainstorm/2026-11-15-implementation_thoughts.md). +**Paths**: `sp:` = `/tmp/sp-research/obra/`, `mp:` = `/tmp/sp-research/mattpocock/`. Line numbers are at v7.0.0 unless a tag is given. + +## Summary + +1. Superpowers' plan format started as a **human-relayed, two-session setup**. An "architect" session wrote a plan for an implementer assumed to have "zero context and questionable taste". The human pasted batches of 3–4 tasks across with "DO NOT DEVIATE FROM THE PLAN". The detail exists so that nobody has to supervise execution. +2. From 2026-01 the format was re-purposed for **SDD's thesis: "a fresh subagent per task with precisely curated context, gated per task"** (stated in upstream's own spec). Tasks became the review unit. Each task had to be self-contained because a script cuts out one task per implementer, so tasks repeated code ("Similar to Task N" is banned), and each task got Interfaces blocks and its own five-step TDD cycle. +3. v6.4.2 (2026-09-25) removed "zero context/questionable taste", the 2–5-minute steps, complete code and "No Placeholders". The stated trigger was Opus 5.5 trying "to implement the entire project while designing the plan". Plans got 4× faster and used about ⅓ of the tokens, with equal planted-defect results on Sonnet 5. v7.0.0 did **not** touch writing-plans. Per-task structure, the TDD cycle, Review Focus and the SDD/Native handoff all remain. +4. **Mechanism of the 11×** (my judgement, based on cited facts): spacecraft's plans predate v6.4.2. A complete-code plan *is* the program, and every concrete line becomes a requirement that the per-task reviewer enforces. Per-task self-containment duplicates content, Review Focus adds tests by design, and the plan's self-review only ever adds. Nothing in the loop subtracts. +5. **Altitude that avoids it** (judgement): the plan carries what the code cannot tell the builder: intent, decisions, contracts and invariants, consumers of changed semantics (with file:line *as evidence*), scope fence, and the proof per phase. It has no bodies and no prescriptive "modify x:123-145". Module and file placement lives in the user's architectural orientation. Code appears only where the form *is* the decision (schema, wire format, state machine), which matches Matt Pocock's prototype exception. +6. **Keep / adapt / drop**: keep Global Constraints, Spec pointer, "a plan is the decisions the builder can't make alone", and a short self-check. Adapt Interfaces (cross-owner only), file paths (evidence and areas), verification (gate per block, tests per phase) and right-sizing (moved to phases). Drop 2–5-minute steps, complete code, the per-task TDD cycle, No Placeholders, checkboxes, the commit step, Review Focus-as-tests, and the execution handoff. +7. §4 gives a **proposed** lean skeleton (for the user to judge), annotated with which fields the attack and the phase reviewer consume. + +--- + +## 1. Why superpowers plans look the way they do + +### 1.1 Timeline (facts) + +| When | Commit / release | What changed in the plan format | Stated reason | +|---|---|---|---| +| ≤2025-10-09 | `dd013f6` (initial plugin; skill already "version: 2.0.0") | Overview "zero context … questionable taste", 2–5-min steps, TDD five-step task template, exact paths, `Remember: Complete code in plan` | Blog (2025-10-05, via WebFetch): the plan is detailed so "at execution time, I usually don't need to provide tight step by step oversight". Two actors (architect and implementer sessions), with the human relaying batches: "Please execute the first 3-4 tasks … DO NOT DEVIATE FROM THE PLAN." | +| 2025-10-16 | `9c9547c` | Handoff offered "Subagent-Driven (this session) … review between tasks" or "Parallel Session … batch execution with checkpoints" (`git show 9c9547c:skills/writing-plans/SKILL.md:97-116`) | — | +| 2026-01-22 | `5e51c3e` | "Subagent-driven-development is now mandatory when harness supports it"; header names both executors | commit message | +| 2026-03-06 | `7b99c39`, `f3083e5`, `daa3fb2` | Checkbox steps "for tracking progress", "For agentic workers" header, File Structure / architecture sizing | commit messages | +| 2026-03-20/24 | `e6221a4` / `3f80f1c` | Plan reviewer subagent loop replaced by an inline Self-Review, and the **"No Placeholders"** section added | The review loop "doubled execution time (~25 min overhead) without measurably improving plan quality" across 5 versions × 5 trials | +| 2026-06-10 | `8e1262a` (+ spec `sp:docs/superpowers/specs/2026-06-10-strict-cost-sdd-design.md`) | **Task Right-Sizing**, **Global Constraints**, per-task **Interfaces** blocks | Fidelity and variance, "not dollars": constraints 0/5→5/5, Interfaces 0→100% of tasks, 9.4→8.4 tasks, 1 fix wave vs 2–4 | +| 2026-06-10 | `4298eac` | SDD `task-brief` script: cuts **one task** out of the plan for the implementer | (file handoffs, eval-tuned) | +| 2026-07-05 | `1e14b23` | "Remember" recap dropped as redundant | commit message | +| 2026-08-12 | v6.3.0 | `Spec:` pointer in header; SDD batches small same-shape tasks | RELEASE-NOTES.md:142-144 | +| 2026-09-18 | v6.4.1 | **Review Focus** section plus self-review item 4. Handoff becomes Subagent-driven vs **Native**, with a recommendation. The user must review the saved plan. | RELEASE-NOTES.md:82, 86-87 | +| 2026-09-25 | v6.4.2 (`8ca22db`, PR #2333) | "zero context" → "capable engineer"; 2–5 min → "one action with a checkable result"; Step 3 is now a signature plus one line, not a body; "No Placeholders" → **"What a Step Contains"**; **Proportion** check; plan reviewer prompt deleted | RELEASE-NOTES.md:53-61 (quoted in §1.3) | +| 2026-10-09 | v7.0.0 | **No writing-plans change** (`git diff v6.4.2 v7.0.0 -- skills/writing-plans/` is empty). Brainstorming rebuilt: the design now covers intent/goals/non-goals/constraints/"what's left to the builder" and hands to writing-plans "and no other skill" | RELEASE-NOTES.md:11-14; `sp:skills/brainstorming/SKILL.md:145-154, 179-193` | + +### 1.2 Element by element: the assumption each one encodes (facts, with the assumption phrased by me) + +| Element | v6.3 (`git show v6.3.0:…`) | v6.4.2 / v7.0 (current) | Assumption it encodes | Where the rationale is stated | +|---|---|---|---|---| +| **Overview / reader model** | "zero context for our codebase and questionable taste … don't know good test design" (:10-12) | "has not seen this codebase or this spec … writes idiomatic code once they know the exact interface and the exact test" (:10) | v6.3: the executor is a weak, untrusted outsider (originally a second human-relayed session). v6.4.2: the executor is capable but **sees only the plan**, not the conversation or the design discussion. | Blog 2025-10-05 (via WebFetch); RELEASE-NOTES.md:59 | +| **Header** (Goal / Architecture / Tech Stack / Spec, REQUIRED SUB-SKILL line) | :58-80 | :54-89 | The executor is a *different agent* that must be routed into SDD/executing-plans, and needs a 3-line orientation because it never saw the design. `Spec:` exists so "conflicts get resolved against the design instead of guessed at". | RELEASE-NOTES.md:144 (#2086); `5e51c3e` | +| **Global Constraints** | :72-77 | :70-75 | Constraints get lost when a controller pastes per-task briefs. A fixed heading makes them "mechanically extractable" into every brief. | strict-cost spec:97-103 ("a `go 1.26.1` floor violation shipped because none did"); `8e1262a` | +| **Review Focus** | — | :77-87, self-review :173 | The spec is a "vision document"; "its silence on an input is not permission for that input to break the program"; implementers ship the same crash on implied inputs. Encodes: **the plan should widen test coverage beyond the spec**. | RELEASE-NOTES.md:87 ("every implementer shipped the same crash on an input the spec implied but never named", #2319) | +| **File Structure** | :25-34 | :23-32 | Decomposition gets locked in at plan time. "You reason best about code you can hold in context at once" (smaller files help agents). | `daa3fb2` | +| **Task right-sizing** | :36-43 | :34-41 | **"A task is the smallest unit that … is worth a fresh reviewer's gate"; split only "where a reviewer could meaningfully reject one task while approving its neighbor."** The task *is* the per-task review unit. | strict-cost spec:54-62 (the thesis guardrail: "a fresh subagent per task … gated per task"; batching is "counter-thesis"), :89-95 (each micro-task costs "~$0.60-1.00 fixed overhead") | +| **2–5 min steps** | :45-52 | :43-50 renamed "one action with a checkable result" | The executor needs micro-checkpoints, i.e. supervision by plan text instead of by a human. | Original 2025 text; dropped in RELEASE-NOTES.md:59 | +| **Complete code in steps** | Step 3 has a code block (:111-116); "code blocks required for code steps" (:139); `Remember: Complete code in plan` (9c9547c:92) | Step 3 = signature in heading plus one line of approach; a body "only for an algorithm they do not determine" (:121-125, :146-155) | The executor cannot be trusted to choose an implementation, so the planner writes it. With SDD, complete code also meant **transcription work for the cheapest tier**: "When the task's plan text contains the complete code … use the cheapest tier for that implementer" (`sp:skills/subagent-driven-development/SKILL.md:212-214`). | RELEASE-NOTES.md:53, 57 (why it was dropped) | +| **TDD five-step cycle** | :98-128 | :108-137 | Every task carries its own red/green proof, so a per-task reviewer has evidence. The executor "doesn't know good test design", so the planner writes the test. | Overview :12 (v6.3); TDD skill iron law | +| **No Placeholders** | :131-139, including "'Similar to Task N' (repeat the code — the engineer may be reading tasks out of order)" | replaced by "What a Step Contains" (:140-161) | The executor sees **one task at a time** (later literalized by `task-brief`, `sp:skills/subagent-driven-development/scripts/task-brief:1-4, 30-36`; "A task's implementer sees only their own task", writing-plans :105-106). It also assumes weaker models write placeholders. | `e6221a4`. Note upstream's own test: "Current-generation opus does not produce plan placeholders even under deliberate pressure, with or without the banned-patterns list" (0/60 plans; `sp:docs/superpowers/specs/2026-06-10-positive-instruction-redesign-design.md:146-156`). The section was kept only because "it costs little". | +| **Exact file paths** (`Modify: exact/path:123-145`) | :87-90 | :97-100 | The executor doesn't know the codebase, and the controller should not have to re-derive locations per dispatch. | 2025 text ("which files to touch for each task") | +| **Interfaces (Consumes/Produces)** | :92-96 | :102-106 | Tasks are built by different, isolated agents, and the controller "re-derives cross-task interfaces per dispatch" while "implementers spend ~13 tool calls re-discovering context". | strict-cost spec:104-108; `8e1262a` | +| **Verification commands + expected output** | :106-121 | :116-130, :152-153 | Claims are not trusted; each step has a mechanical pass criterion, which the reviewer and the `task-done` ledger check. | executing-plans `task-done` (v6.4.1, RELEASE-NOTES.md:81) | +| **Commit step / checkboxes** | :123-128; "- [ ]" | same | One commit per task gives SDD a `BASE..HEAD` range per task review. Checkboxes are for tracking. | `7b99c39` | +| **Self-review** | 3 checks (:141-151) | 5 checks, adding Review Focus and Proportion (:163-177) | Replaces a subagent plan-review loop that cost ~25 min for no measurable gain. Note "If you find a spec requirement with no task, add the task": the review only adds, except for Proportion. | `e6221a4`; RELEASE-NOTES.md:58 | +| **Execution handoff** | "Subagent-Driven (recommended)" vs "Inline" (:153-171) | user reviews plan, then picks Subagent-driven or Native with a recommendation (:179-204) | The plan is a contract between two different execution modes, and a human must approve the *written* plan ("Approving an idea or a scope no longer counts as approving a plan you haven't seen"). | RELEASE-NOTES.md:82, 86 | + +### 1.3 The v6.4.2 turn in upstream's own words (fact) + +> "Some frontier models, including Opus 5.5, could get overzealous during plan writing and, with certain prompting, would sometimes try to implement the entire project while designing the plan. … When we reproduced the original report, the scratch builds went away, and plans took a quarter of the time and about a third of the tokens." (RELEASE-NOTES.md:53) +> "Every plan written by the new skill executed 9/9 against planted-defect probes on Sonnet 5, the same result as full-code plans." (:60) +> "A plan is the set of decisions the implementer cannot make alone. A plan longer than the code it describes has written the code instead." (`sp:skills/writing-plans/SKILL.md:157-158`) + +Upstream also measured earlier that **complete-code plans were cheaper to execute** under SDD than hand-written prose plans (strict-cost spec:73-77: "The cost win belongs to opus-written complete-code plans; the hand-written prose fixture plans … ~2× costlier to execute"). The economics flipped once the *planner* (Opus 5.5) became the expensive part. + +### 1.4 The brainstorming → plan → execution handoff (facts) + +- v6.3: brainstorming classified the work as spike/bounded/architectural. The architectural path produced a spec covering "architecture, components, data flow, error handling, testing", followed by writing-plans (`git show v6.3.0:skills/brainstorming/SKILL.md:186` for the coverage list, `:103, 230` for the handoff). +- v7.0: the design is deliberately **intent-level**: "intent and the why; goals, non-goals, anti-goals; constraints; the parts of the how they decided; what's left to the builder" (`sp:skills/brainstorming/SKILL.md:145-154`). A non-goal of the rebuild is "Designing architecture the human didn't ask to decide … the rest belongs to the builder" (`sp:docs/superpowers/specs/2026-10-05-brainstorming-rebuild-design.md:116-119`). The HARD-GATE then forces writing-plans (:191-192). +- Consequence (judgement): in v7 the **plan is where architecture gets decided** (Header "Architecture", File Structure, Interfaces), and it is decided at signature granularity, for an executor who "cannot know what you decided". Upstream has no layer between intent and signatures. That missing layer is the user's "architectural orientation" step. + +--- + +## 2. What is really useful for an Opus 5.5 builder in large blocks with one review per phase + +Context (facts): Spire builds in blocks of roughly 11–36 min of agent work (186k–344k tokens; `plugins/spire/skills/implementation/references/models.md:48`), with a cheap gate between blocks, tests once per phase and one fresh adversarial review per phase (`plugins/spire/skills/implementation/SKILL.md:34-55`). The attack happens before the build (`:24-30`). The evidence that the per-task model was costly: 1.8 verification seats per build seat (`reports/2026-10-05-21-implementation-skill-redesign.md:22`); 11/13 re-reviews only confirmed the fix; active time per task went from ~10 to ~70 min, then halved under lean (`docs/workpad/research/2026-10-05-21-athanor-usage-spacecraft.md:32-33, 42, 50`). Lean was 35–40% faster with +1,417 vs +3,439 fix lines (`…-dirigent.md:84-86`). "About 4 of the 6 [Important findings] were plan gaps" (`models.md:37`). + +**Judgement**, one line each: + +| Element | Verdict | Reason (evidence) | +|---|---|---| +| "A plan is the set of decisions the implementer cannot make alone" | **Keep** (as the principle) | It is the right test for a capable builder. Apply it honestly: with the code available, many signatures are the *builder's* decision, not the plan's. | +| Header: Goal / Spec pointer | **Keep, as links** (goal, design, orientation, research) | The attack and reviewer must argue from the same sources (upstream #2086 had the same reason). | +| Header: Architecture / Tech Stack | **Drop** | The code and orientation doc say this. Restating it goes stale. | +| REQUIRED SUB-SKILL line, checkboxes | **Drop** | Spire routes execution itself, and the run log is the tracker (`run-log.md`). | +| Global Constraints | **Keep** | Cheap, measured (0/5→5/5, and one version-floor catch). The attack and reviewer check exact values. | +| Review Focus (5 failure modes → added tests) | **Adapt**: list "inputs/edges the design implies", and let the attack rule in or out (out goes to the scope fence). Not automatic tests. | The motivating eval finding is real (RELEASE-NOTES.md:87), but auto-adding tests is a scope vector by design, and Spire says the risk list is not the reviewer's scope (`implementation/SKILL.md:30`). | +| File Structure | **Move** to the architectural orientation; the plan references it | It is orientation, not sequencing. Duplicating it bloats the plan. | +| Task right-sizing ("worth a fresh reviewer's gate") | **Adapt to phases**: a phase boundary is where a reviewer could reject this phase while approving the previous one | The criterion is sound; Spire's review unit is the phase, not the task. | +| 2–5 min / one-action steps | **Drop** | Upstream dropped them too. Steps inside a block are the owner's business (coupling note I3). | +| Complete code in steps | **Drop** | 11× scope (spacecraft); upstream's 9/9 probes passed without bodies even on Sonnet 5; Opus 5.5 builds from contracts. | +| TDD five-step cycle per task | **Drop as structure; keep the intent** as "Proves:" per phase plus fail-first for bugs | Per-task red/green exists to give a per-task reviewer evidence. Spire runs the suite once per phase, and v6.4.1's "the project's suite defines green" makes per-task cycles expensive in Rust. | +| No Placeholders | **Drop the section; keep one line** ("every line decides something") | Upstream measured 0/60 placeholder plans from current Opus even under pressure (positive-instruction spec:146-156). | +| Exact file paths with line ranges as instructions | **Adapt**: paths only as *evidence pointers* (file:line backing a claim about a root cause or consumer) and as *areas* (modules a block owns) | The attack needs pointers it can check against the code. Prescriptive line ranges go stale within the run and pre-decide the builder's job. | +| Interfaces (Consumes/Produces) | **Adapt**: only where two owners or two phases meet, at contract level (type shape, invariant, error semantics) | Measured value comes from isolated per-task agents (the 13 re-discovery tool calls). Inside one owner's block it is noise. | +| Verification commands + expected output | **Adapt**: gate command per block and test command per phase, from `spire:project`; no expected-output transcripts | Cheap, and the reviewer runs the gates (`implementation/SKILL.md:52`). | +| Commit step per task | **Drop** (blocks commit) | `implementation/SKILL.md:38`. | +| Self-review | **Keep, short, and add a subtractive item** ("what can be cut against the goal?") | Upstream's checks are additive except Proportion. Spire's scope problem needs a cutting question. | +| Execution handoff (user picks SDD/Native) | **Drop** | Spire's cycle fixes the route: plan → attack → user sees the build plan once. The v6.4.1 lesson ("approve the written plan, not the idea") survives as that single checkpoint. | +| Per-task model tier (upstream L1 item 4, pcvelz `modelTier`) | **Keep as owner model per block** | Already in Spire's build plan (`implementation/SKILL.md:30`). | + +**What only makes sense under per-task fresh subagent + per-task review** (judgement, from §1.2): task right-sizing as "a reviewer's gate", per-task self-containment (repeat code, Interfaces on every task), the per-task TDD cycle and commit, checkboxes, complete code as cheap-tier transcription, and the SDD/Native handoff. All of these exist so an isolated agent can execute and an isolated reviewer can judge **one task without the rest of the plan**. Spire's builder holds a whole phase, and its reviewer reviews a whole phase. + +--- + +## 3. Plan size → code size + +### 3.1 The mechanism (judgement, built from cited facts) + +1. **The plan is written in the code's own medium.** With complete code (spacecraft's R1 plans were written 2026-09-24 and earlier, before v6.4.2 shipped on 09-25), plan length and code length are the same quantity. Upstream says so: "A plan longer than the code it describes has written the code instead" (`writing-plans/SKILL.md:158`), and Opus 5.5 "would sometimes try to implement the entire project while designing the plan" (RELEASE-NOTES.md:53). +2. **Every concrete line becomes an obligation.** The original contract was "DO NOT DEVIATE FROM THE PLAN" (blog). Under SDD the per-task reviewer checks spec compliance against the task text (`SDD/SKILL.md:8, 311`). The reviewer prompt adds "a spec's silence is not permission" (`requesting-code-review/code-reviewer.md:39`). Whatever the planner enumerated gets built *and enforced*. A thorough planner therefore produces a large program. +3. **Forbidding vagueness forces enumeration.** "No Placeholders" bans "handle edge cases" and "add validation" (v6.3 :133-139). The only allowed alternative is to write each case out as code and tests. A 5.5 planner, which "catches more, decides boldly" (`models.md:15`), writes every case it can think of. +4. **Self-containment duplicates.** Each task must stand alone because the implementer sees only its task ("repeat the code — the engineer may be reading tasks out of order"). Shared logic therefore appears N times in the plan, and tends to be built N times. This is the "functions that almost do the same" failure the user's orientation note warns about (`brainstorm/…implementation_thoughts.md:15`). +5. **Structural growth by design.** Every task has its own test cycle. Review Focus adds up to 5 extra tests. Self-review says "if you find a spec requirement with no task, add the task". No step removes anything except the late Proportion check, which compares against the *spec* and not the *goal*. +6. **Early freezing of the derived structure.** Exact signatures for every task fix abstractions before the code reveals the true data shape. This is the user's "some abstractions are derivative" point (`implementation_thoughts.md:14-15`). Later refactors then add code instead of replacing it. +7. **The review loop amplifies.** Per-task findings on behaviour the spec didn't cover go into the fix loop, and the fixer seat "often cost more than the draft" (spacecraft retrospective, `…-spacecraft.md:42`). + +Attribution caveat (fact): spacecraft says "Superpowers supplies only the skeleton … Most of the weight is ours" (`…-spacecraft.md:31`). So the 11× is plan format × Opus 5.5 thoroughness × spacecraft's own additions. It is not the plan format alone. + +### 3.2 Altitude that avoids it while keeping the attack effective (judgement) + +The attack exists to find **blockers, design errors, wrong root causes, missed consumers** (`implementation/SKILL.md:26`). The user adds the "button that does nothing", the onboarding with no offboarding, error handling, security, and missed early abstraction (`implementation_thoughts.md:23`). None of these hide in function bodies. They hide in **contracts, lifecycles and consumers**. Code-level plans actually *hurt* the attack: the blunders sit under thousands of lines of transcription, and the attacker spends its budget reading bodies. + +The altitude that serves the attack: + +| Put in the plan | Keep out of the plan | +|---|---| +| Intent per phase as an **observable end state** ("Done when") | Function bodies; test bodies | +| **Contracts and invariants**: type *shapes* at owner boundaries, state transitions, error semantics, persistence/wire formats (code only where the form *is* the decision) | Every signature inside a block | +| **Consumers of changed semantics**, each with a **file:line evidence pointer** | Prescriptive "Modify x.rs:123-145" | +| **Areas** (modules/crates) each block owns, for ownership and collision only | Per-step file lists | +| **Proof**: named seams/tests and what each asserts, in a phrase; fail-first for bugs | The red/green/commit choreography | +| Decisions made, open user decisions, and `**Assumed:**` picks | Rationale essays (they belong in the design) | +| Scope fence: in / out / not now; deferred refactors | "While we're here" items | +| Lifecycle pairs and failure paths the design implies (create↔delete, onboard↔offboard, error/security) as **one line each** | Their implementation | + +**Relation to Matt Pocock's `to-tickets` (fact, then judgement).** `to-tickets` says: "avoid specific file paths or code snippets: they go stale fast", with an exception for prototype snippets that encode a decision "more precisely than prose can (state machine, reducer, schema, type shape)" (`mp:skills/engineering/to-tickets/SKILL.md:105`). Tickets describe end-to-end behaviour, not "a layer-by-layer implementation list" (:73). `to-spec`'s "Implementation Decisions" lists modules, interfaces, schema and API contracts without paths or code (`mp:skills/engineering/to-spec/SKILL.md:43-57`), and agrees test seams up front, where "the ideal number is one" (:15). *Judgement*: Spire should take the altitude and the decision exception verbatim. It should diverge on file paths in one specific way. Matt's tickets live on a tracker for weeks, while a Spire plan is transitional and consumed within hours by an attacker *reading the code*. So file:line is fine **as evidence** for a claim (the attack checks it, and it is allowed to go stale after landing, consistent with "code is truth"). It is not fine **as an instruction**. + +**Relation to the user's "architectural orientation" (judgement).** Orientation is the layer upstream v7 lacks (§1.4). It places the solution in the code (modules, files, structs/traits, approach) and separates pre-plan scaffolding (models, module skeletons, interface shapes) from post-plan refactors (trait polish, derived abstractions). If orientation carries the *where* and the *shape*, the plan only has to carry **order, contracts at boundaries, proof and fence**. That is what keeps it small. Two consequences: +- The plan should *reference* orientation, not repeat it. "Post-plan" items from orientation go into the plan's **Deferred** list, so neither the builder nor the reviewer treats them as missing. +- The attack checks the plan against **code and orientation** together: a block that freezes something orientation marked "derive later" is a finding. + +Size guard (judgement; deliberately no number, consistent with the redesign report's "not encoded as numbers" ruling, `reports/2026-10-05-21-implementation-skill-redesign.md:141`): if the plan contains function bodies outside the decision exception, it is at the wrong altitude. If a phase can't be stated as one observable end state, it is too big or too vague. Proportion is judged against the **goal**, not the design. + +--- + +## 4. Lean skeleton: **PROPOSAL for the user to judge, not a decision** + +One line per heading. Consumers: **A** = attack, **R** = phase reviewer, **B** = builder/Athanor. Fields marked A are what the attack verifies against code. Fields marked R are what the reviewer answers or checks. Per `implementation/SKILL.md:30`, the risk list is deliberately *not* R. + +```markdown +# plan +Stamp: model id, date. Links: goal · design · orientation · research. [A R B] + +## Intent +Two or three lines: what changes for the user and why; the goal's bar. [A: scope baseline · R: what "done" means] + +## Decisions +Made (one line each, with `**Assumed:**` where picked) · Open for the user. [A: verifies against code · user sees once] + +## Constraints +Global values verbatim (versions, formats, naming, platform). [A · R: exact check · B] + +## Scope fence +In · Out · Not now (incl. edges the design implies that we chose not to cover). [A: cuts · R: flags creep and omissions] + +## Evidence +Current behaviour / root cause, each claim with file:line. [A: re-traces each] + +## Consumers of changed semantics +Every reader (callers, stats, migrations, other crates), each with file:line. [A: completes the list · R: checks each] + +## Contracts and invariants +Shapes at owner/phase boundaries, state transitions, error semantics, formats. +Code only where the form is the decision. [A · R · B] + +## Phases +### Phase N: +- Proves: named seams/tests and what each asserts (fail-first if a bug). [R: runs and judges · B] +- Blocks: N.a · area · produces/consumes (cross-owner only) · + owner model (suggested) · gate · may stay broken. [A: reshapes · B] +- Done when: observable criteria. [R] + +## Deferred +Post-plan refactors from orientation; follow-ups. [R: not "missing" · A: checks nothing frozen early] + +## Risks and hotspots +Where it can go wrong; whether one earns an extra review, and why. [A: review placement, owner models · not R] + +## Self-check +Goal coverage · cross-block contract consistency · lines that decide nothing · +what can be cut · bodies outside the decision exception. [planner only] +``` + +Notes on the proposal (judgement): +- It is already in **build-plan shape** (phases → blocks), so the attack can *amend* (a dated section or a short delta) instead of rewriting. That addresses the duplication gap in the coupling note §2.2. +- The fields the attack consumes most are Decisions, Evidence, Consumers, Contracts, Scope fence and Risks. The reviewer consumes Done when, Proves, Contracts, Constraints, Scope fence and Deferred, plus the run log's handoff flags. +- Deliberately absent: steps, function bodies, per-block test code, checkboxes, commit steps, execution-mode choice, and a "Review Focus" that adds tests. +- Open question for the user: should Contracts and Areas live in the orientation doc (and the plan only references them), or should orientation fold into the plan as a section for small work? The brainstorm treats orientation as its own step; for small changes, a separate doc may cost more than it saves. + +--- + +## Could not verify + +- **Blog quotes** (blog.fsck.com 2025-10-05 "How I'm using coding agents in September 2025", and 2025-10-09 "Superpowers") came through WebFetch's summarizing model. They are presented as verbatim but I did not see the raw page. +- **The pre-repo origin** of "zero context / 2–5 min / complete code" lives in obra/superpowers-skills or earlier; the skill was already "version: 2.0.0" at `dd013f6`. Not inspected. +- **PR #2333 and #2319 discussions**, Harper Reed's session bundle and the `superpowers-evals` experiment log cited by `8e1262a` were not read (outside the clone; `gh` not tried). All eval numbers are upstream's self-reports. +- **Which superpowers version spacecraft ran** when its R1 plans were written is not verified. I infer it was pre-v6.4.2 from dates only (plans ≤2026-09-24, v6.4.2 released 2026-09-25). The 11× metric (bytes? lines?) and the 77k-line figure are second-hand via the 2026-10-05 survey. Spacecraft and dirigent are not on this machine. +- **v7.0.0 brainstorming's effect on plan size** is untested: no runs were made. +- **The skeleton in §4 is untested.** No plan was written or attacked with it. diff --git a/docs/workpad/research/2026-10-15-14-claude-code-tasks-and-pcvelz.md b/docs/workpad/research/2026-10-15-14-claude-code-tasks-and-pcvelz.md new file mode 100644 index 0000000..87b4384 --- /dev/null +++ b/docs/workpad/research/2026-10-15-14-claude-code-tasks-and-pcvelz.md @@ -0,0 +1,201 @@ +# Claude Code native Tasks, and how pcvelz/superpowers uses them + +- Model: claude-opus-5-5 (Claude Code 2.1.296 on this machine) +- Date: 2026-10-15 13:16 CEST +- Sources: Claude Code docs at code.claude.com (fetched 2026-10-15), `anthropics/claude-code` CHANGELOG.md (main, top entry 2.1.300) with npm publish dates, a local read of `~/.claude/tasks/`, and the pcvelz fork clone at `/tmp/sp-research/pcvelz` (HEAD `cb12f4f`, 2026-09-18). Cloned content was read only; nothing from it was run. +- Labels: **[fact]** is cited. **[observed]** was seen on this machine. **[inferred]** is reasoned from cited facts. **[judgement]** is my opinion. + +## Summary + +1. **[fact]** Claude Code's native Tasks are four tools: `TaskCreate`, `TaskGet`, `TaskList` and `TaskUpdate`. They arrived in 2.1.16 (2026-01-22) and replaced `TodoWrite`. Each task is a JSON file under `~/.claude/tasks//`. Tasks survive compaction and `--resume`. A new session gets an empty list unless `CLAUDE_CODE_TASK_LIST_ID` names a shared one. +2. **[fact]** In 2.1.233 (2026-08-14), Claude Code stopped offering the task tools on Opus 4.8, Sonnet 5, Fable 5 and newer models. In 2.1.268 (2026-09-10) it changed to an allowlist of older models. On Opus 5.5 they are **off** unless `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` is set. Anthropic's stated reason: newer models track multi-step work without a written checklist, and the tools' definitions and reminders cost context. +3. **[fact]** The fork's cross-session resume is **not native**. `.md.tasks.json` is a mirror that the model writes by hand, because skill prose tells it to (Read, edit, Write after every status change). A new session rebuilds the native tasks from that file. Its hooks never read the task store. They rebuild task state by replaying the session transcript. +4. **[judgement]** The parts that make it "work better with Claude" are (a) a live checklist that the harness re-injects into context, which keeps the model on track after compaction, and (b) a structured event (`TaskCreate`/`TaskUpdate`) that hooks can gate on. Persistence is no better than a markdown file. In practice it is the same thing: a file the model keeps current. +5. **[judgement]** For Spire and grotto, a native Task list is at best a **complement**, never the handoff substrate. It is per-user and outside the repo, swept by retention, invisible to Codex and to background subagents, and it cannot hold what the run log holds (deviations, flags, expected-broken areas). The ideas worth taking are the compact task shape (Goal/Files/AC/Verify plus `blockedBy`) and "status lives in the plan file, the harness list is a view". + +--- + +## 1. Claude Code native Tasks today + +### What they are + +| Claim | Source | +|---|---| +| Tools: `TaskCreate` (create), `TaskGet` (full details of one task), `TaskList` (all tasks with status), `TaskUpdate` (status, dependencies, details, delete). None of them needs permission. | **[fact]** docs `tools-reference` table, lines 54–59 | +| "Added new task management system, including new capabilities like dependency tracking". | **[fact]** CHANGELOG 2.1.16 (npm 2026-01-22) | +| `CLAUDE_CODE_ENABLE_TASKS=false` (later `0`) keeps the old `TodoWrite` system. | **[fact]** CHANGELOG 2.1.19 (2026-01-23); docs `env-vars` line 298 | +| Tasks can be deleted via `TaskUpdate`. | **[fact]** CHANGELOG 2.1.20 (2026-01-27) | +| `TaskCreated` hook event (fires on `TaskCreate`; exit 2 or `{"decision":"block"}` deletes the task and returns the message as a tool error). `TaskCompleted` hook event (fires when a task is marked completed, or when a teammate ends its turn with in-progress tasks). Neither takes a matcher. | **[fact]** CHANGELOG 2.1.84 (2026-03-25); docs `hooks` §TaskCreated / §TaskCompleted. `TaskCompleted`/`TeammateIdle` were added earlier, for agent teams. | +| `TaskList` sorts by ID (2.1.119, 2026-04-23). Malformed `TaskCreate` input is repaired automatically (2.1.169, 2026-06-08). | **[fact]** CHANGELOG | +| `Ctrl+T` toggles the task list view, which shows up to five tasks. "Tasks persist across context compactions." The expanded view is restored on `--resume`/`--continue`. | **[fact]** docs `interactive-mode` §Task list, lines 697–700 | + +### Storage and lifetime + +| Claim | Source | +|---|---| +| `~/.claude/tasks/` holds "Task lists written by the task tools, one directory per list". It is listed as "Task lists that a resumed session would pick up". | **[fact]** docs `claude-directory` lines 1550, 1705 | +| On this machine each list is a directory named with the **full session UUID**. It contains a `.lock` and one `N.json` per task with exactly these keys: `id, subject, description, activeForm, status, blocks, blockedBy`. There is no `metadata` or `owner` key. 19 tasks in 3 lists, all `completed`, last written 2026-09-22. Each directory name matches a transcript under `~/.claude/projects/…`. | **[observed]** 2026-10-15. The Claude Code version that wrote them is unknown. | +| Agent-team task lists live in `~/.claude/tasks/session-/`. They "persist locally and [are] never uploaded, so resumed sessions keep their tasks". Retention follows `cleanupPeriodDays`. `claude purge` deletes per-session `tasks/`. | **[fact]** docs `agent-teams` lines 248–254; `claude-directory` line 1634 | +| `CLAUDE_CODE_TASK_LIST_ID=` makes sessions share a named list in `~/.claude/tasks//` ("coordinate on a shared task list"). | **[fact]** docs `interactive-mode` line 701; `env-vars` line 413 | +| Across compaction the list persists. On `--resume` the list is picked up. A **new session or `/clear`** starts a new session id and so an empty list, unless `CLAUDE_CODE_TASK_LIST_ID` is set. | Compaction and resume: **[fact]**. New session and `/clear`: **[inferred]** from per-session directories. The docs do not state it for `/clear`. | + +### Dependencies, subagents, teammates + +| Claim | Source | +|---|---| +| Tasks have `blocks`/`blockedBy`. In agent teams, "a pending task with unresolved dependencies cannot be claimed", claims use file locking, and completing a task unblocks its dependents automatically. | **[fact]** docs `agent-teams` §Assign and claim tasks | +| In a solo session, `blockedBy` is **advisory**: nothing stops `TaskUpdate status=in_progress` on a blocked task. | **[inferred]**. The fork ships `pre-task-blockedby-enforce.sh` because "skill prose that says 'respect dependencies' is not enforcement" (header, lines 1–4). Not tested here. | +| Subagents get the task tools only when the parent session has them. In-process teammates follow the session. Split-pane teammates follow their own model. | **[fact]** docs `tools-reference` line 596; `sub-agents` line 452 | +| **Background subagents lose the Task tools.** Their built-in allowlist includes `TodoWrite` but not `TaskCreate/Get/List/Update`. Agent-team teammates keep them. | **[fact]** docs `sub-agents` lines 444, 450 | +| Foreground subagents sometimes missed the task tools until 2.1.286 (2026-09-30). | **[fact]** CHANGELOG 2.1.286 | +| A foreground subagent's `TaskCreate` writes into the session's list, not a private one. | **[inferred]** from `TaskCreated` input carrying `agent_id` "identifies the subagent … creating the task" (docs `hooks`, requires 2.1.290). Not verified. | + +### Versus `TodoWrite` + +- **[fact]** `TodoWrite` "manages the session task checklist". It is off by default in favour of the four Task tools and can be selected with `CLAUDE_CODE_ENABLE_TASKS=0` (docs `tools-reference` line 60). `~/.claude/todos/` is a legacy directory that current versions no longer write (docs `claude-directory` line 1558). +- **[unverified, from memory]** `TodoWrite` rewrites the whole list in one call (`content/status/activeForm`, no ids, no dependencies). The Task tools address tasks one at a time by id, have dependencies, and keep the list in per-list files on disk. + +### The env flag and the version change + +- **[fact]** 2.1.233 (npm 2026-08-14): "Todo/task-tracking tools (TaskCreate/Get/Update/List, TodoWrite) are no longer available on Opus 4.8, Sonnet 5, Fable 5, Mythos 5, and newer models; set `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` to bring them back." +- **[fact]** 2.1.268 (2026-09-10) flips this to an allowlist: the tools are offered only on Claude 3.x, Opus 4.0–4.7, Sonnet 4.0–4.6 and Haiku 4.5. Unknown model ids (for example custom names behind a gateway) also get none. Docs: "The default set described here applies in Claude Code v2.1.268 and later" (`tools-reference` line 598). +- **[fact]** Ways to opt in: the env var (which "requires Claude Code v2.1.233 or later"), naming a task tool in `--allowedTools`, or listing it in `--tools`. Background sessions (agent view) and cloud sessions get the tools on every model regardless (`tools-reference` lines 589–594). +- **[fact]** Stated rationale: "On newer models, Claude keeps track of multi-step work without a written checklist, and the tools' definitions and reminders take up context" (`tools-reference` line 585). +- **[fact]** The fork's README claim ("2.1.233 removed the task tools by default", README:85) is correct for Opus 4.8+/Sonnet 5/Fable 5 at 2.1.233, and for every non-allowlisted model from 2.1.268 on. **On this setup (Opus 5.5, 2.1.296) the tools are off.** Spire's harness note "`TaskList` is the todo list" (`spawning-claude-code.md:33`, 2026-09-22) predates the allowlist flip. + +--- + +## 2. How the fork uses them + +### Task shape: `skills/shared/task-format-reference.md` + +- Subject at most 60 characters, because "the harness re-injects every task's subject line into context during periodic reminders" (`:7`). +- Required body sections: **Goal** (one sentence, what not how), **Files** (create/modify/delete with line ranges), **Acceptance Criteria** (checkboxes), **Verify** (exact command and expected output) (`:15–24`). Optional: **Context** and **Steps**. TDD happens inside a task, not as separate tasks (`:28–32`, `:144–146`). +- Metadata goes in a ` ```json:metadata ` fence **inside the description**, because "the `metadata` parameter on TaskCreate is accepted but **not returned by TaskGet**" (`:36`; README:143). Keys (`:38–55`): + - Core: `files`, `verifyCommand`, `acceptanceCriteria` (required); `estimatedScope`. + - Gates: `userGate`, `tags`, `requiresUserSpecification`, `gateScope`, `failurePolicy`, `subagentBrief`. + - Dispatch pins: `subagentType`, `model`, `modelTier` (`mechanical|standard|frontier`), `dispatchBrief`. + - Evidence: `requireEvidenceTokens`, `requireABCompare`. +- Granularity: one task produces one commit and one reviewable unit. Setup and docs fold into the task that needs them (`:117–150`). + +### Who writes what, and where + +| Artifact | Writer | Mechanism | +|---|---|---| +| Native tasks | the model | `writing-plans` "REQUIRED FIRST STEP": call `TaskList`, then `TaskCreate` per plan task with the full Goal/Files/AC/Verify body verbatim plus fence (`skills/writing-plans/SKILL.md:40–51, 303–340`). After that, `TaskUpdate addBlockedBy` (`:351–359`). | +| `.md.tasks.json` | **the model, by prose instruction** | Written "at plan completion … in the same directory as the plan" as `{planPath, tasks:[{id, subject, status, blockedBy, description}], lastUpdated}` (`writing-plans/SKILL.md:377–405`). The plan author checks it with `grep -c '**Goal:**'` etc. (`:309–318`). | +| `.tasks.json` status sync | the model (controller) | "Read the tasks file, update the task's status … set lastUpdated … write back" after every change (`executing-plans/SKILL.md:37, 79`; `subagent-driven-development/SKILL.md:599–608`; `dispatching-parallel-agents/SKILL.md:208–218`: "Controller is responsible for `.tasks.json` sync"). **No hook writes it.** | +| Context hygiene | the model | On completion, shrink the task description to its Goal line plus "Complete — see ledger", because "the harness re-injects every task's full description on periodic reminders". User-gate tasks are the exception (`subagent-driven-development/SKILL.md:445–452`). | + +### Resume across sessions + +`executing-plans/SKILL.md:26–37` ("Step 0: Load Persisted Tasks"): +1. Call `TaskList`. +2. Look for `.tasks.json`, or glob for one. +3. If the file exists and the native list is empty, recreate every task with `TaskCreate` (full description and metadata) and restore `blockedBy` with `TaskUpdate`. +4. If native tasks exist, check them against the plan and resume from the first `pending`/`in_progress`. +5. If neither exists, bootstrap from the plan's `### Task N:` headers (`:53–65`). + +Entry point: `/superpowers-extended-cc:executing-plans ` (`writing-plans/SKILL.md:407–414`). The `session-start` hook (`hooks/session-start`, 146 lines) injects `using-superpowers` plus routing and workflow notices. **It does not restore tasks.** Resume therefore depends on the model running Step 0 correctly. + +**[judgement]** This is the same reliability class as "read the run log and continue". The difference is a second copy (the native list) that must be kept in sync by hand. + +### Hooks + +Registered by the plugin (`hooks/hooks.json`): + +| Hook | Event / matcher | Enforces | Reads | +|---|---|---|---| +| `pre-taskcreate-model-tier` (205 lines) | PreToolUse `TaskCreate` | Only if `docs/superpowers/model-routing.json` or `~/.claude/superpowers/model-routing.json` exists. Then: a plan-shaped task (template headers or subjects like `Task 3:`/`Phase 0.1:`) must have a fence, and the fence needs a valid `modelTier` or a `model` pin. Exit 2 with a self-teaching message. Fails open; kill switch `SUPERPOWERS_ROUTING_GUARD=0` (`:51–125, 157–205`). | `tool_input.description` | +| `pre-taskcreate-commit-strategy` (152 lines) | PreToolUse `TaskCreate` | When `workflow.json` has `commitStrategy: at-end`, blocks plan tasks that carry per-task Commit steps (header `:1–18`). | `tool_input` | +| `pre-agent-model-routing` (558 lines) | PreToolUse `Agent` | Agent `model` must match the tiers of the in-progress tasks. | transcript replay, keyed by the `"Task #N created successfully"` tool_result (`:226–246`) | +| `pre-askuser-handoff-guard` (405 lines) | PreToolUse `AskUserQuestion` | Forces the two-option execution menu after `writing-plans`. | transcript | + +Opt-in examples (`hooks/examples/`, which the user pastes into settings, README:345–481): + +| Hook | Event | Enforces | +|---|---|---| +| `pre-commit-check-tasks.sh` (63 lines) | PreToolUse `Bash` matching `git commit` | Blocks while any task is `in_progress`. Pending tasks pass (`:1–10, 55–60`). | +| `pre-task-blockedby-enforce.sh` (210 lines) | PreToolUse `TaskUpdate` with `status=in_progress` | Refuses while any `blockedBy` entry is not completed. | +| `post-task-complete-revalidate.sh` (478 lines) | PostToolUse `TaskUpdate` with `completed` | User-gate tasks need evidence per AC. `requireEvidenceTokens` axes must appear. | +| `stop-revalidate-user-gates.sh`, `stop-wait-guard.sh`, `stop-deflection-guard.sh` | Stop | Block "done" claims without `AC: … PROVEN BY` evidence, turns that end on "waiting…", and "context is full" excuses. | +| `pre-agent-task-dispatch-validate.sh`, `post-agent-return-validate.sh` | Pre/PostToolUse `Agent` | Dispatch pins from metadata; evidence tokens in subagent reports. | + +Mechanism notes: +- **[fact]** Nearly every hook rebuilds task state by **replaying the transcript JSONL** (`TaskCreate` tool_use count, then later `TaskUpdate`s). It does not read `~/.claude/tasks/`. Example: `pre-commit-check-tasks.sh:33–54`. +- **[fact]** The only exception: `stop-wait-guard.sh` reads `~/.claude/tasks/session-/*.json` (`:35, 91`). On this machine the solo-session lists use full-UUID directory names, so that path may miss them (**[observed]**, version-dependent, not tested). +- **[fact]** The fork found that counting creates mis-keys ids ("the old 1..N create-count mis-keyed once earlier tasks shifted the numbering", `pre-agent-model-routing:226–230`; commit `3b5f5d2`, 2026-06-17). It fixed this **only in that hook**. `pre-commit-check-tasks.sh:35`, `post-agent-return-validate.sh:46` and `pre-agent-task-dispatch-validate.sh:59` still use `next_id = 1` counting. **[inferred]** A `TaskCreate` blocked by the tier gate still leaves a tool_use in the transcript, so those hooks can mis-key ids after any blocked create. +- **[fact]** The fork uses PreToolUse matchers on `TaskCreate`/`TaskUpdate` and does not use the native `TaskCreated`/`TaskCompleted` events (grep: no hits). +- **[fact]** The fork's design never touches `CLAUDE_CODE_TASK_LIST_ID`, the one native cross-session mechanism. `/onboard` writes only `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` (`commands/onboard.md:42–62`, added `becc0bd` 2026-08-16). + +--- + +## 3. Useful vs ceremony (judgement) + +### What actually helps the model + +1. **[judgement]** **A checklist the harness keeps in front of the model.** Task reminders are re-injected, and the docs confirm "reminders" exist (`tools-reference` line 585). After compaction or a long tool chain, the model still sees what is next and what is open. This is the "execution on rails" effect (README:51) and most of what "works better with Claude" means. Anthropic's position for Opus 4.8+ is that the model no longer needs it and it costs context. +2. **[judgement]** **A structured, hookable event.** "Task N is now in progress / completed" is a tool call, so a hook can block it. With a markdown run log you can only gate on Bash or Edit patterns. This is real, but it only pays off if you want hard gates, and Spire's lean doctrine deliberately does not. +3. **[judgement]** **The task shape.** Goal/Files/AC/Verify is a compact, checkable unit. "Verify = exact command + expected output" is the most useful field. Keep subjects short and shrink completed tasks, because reminders re-inject them. +4. **[judgement]** **Human visibility** (`Ctrl+T`). Nice when watching a session. Irrelevant for a closed-door Athanor. + +### What is ceremony + +- **[judgement]** Two sources of truth (native list plus `.tasks.json`) kept in sync by the model after every status change, with `grep -c` self-checks. This is overhead to make up for native lists not surviving new sessions. +- **[judgement]** Metadata stuffed into description fences (because `TaskGet` drops `metadata`), parsed by about 3,400 lines of bash and python that replay the transcript. +- **[judgement]** User-gate tagging, evidence-token axes, the handoff-menu guard and the wait/deflection Stop hooks. These enforce the SDD loop, which Spire has already rejected. + +### Spire Athanor (one phase per turn, run log, Igor resumes) + +What already exists: the run log (`implementation/references/run-log.md`: header, block table, per-block handoff note with deviations, flags, left-for-later, expected-broken and commits; phase close), trunk notes, and journals. Igor resumes the Athanor with `SendMessage`. + +- **[judgement]** The run log is the better handoff substrate. It is in the repo, versioned, readable by the reviewer, by Codex and by a human, and its fields carry judgement that the native schema cannot hold (`subject/description/status/blockedBy` only). +- **[judgement]** A native list could serve as a **within-turn block checklist** for the Athanor: blocks of the current phase, `blockedBy` mirroring the plan's order. That would give the reminder effect during a long phase. It would not replace any run-log content. +- What breaks or limits it: + - **[fact]** Igor and the Athanor run on Opus 5.5, so the tools are absent unless the user sets `CLAUDE_CODE_ENABLE_TODO_TOOLS=1`. That is session-wide, and subagents follow the session, so it cannot be enabled for the Athanor alone. + - **[fact]** If Igor ever dispatches or resumes the Athanor **in the background**, the Athanor has no Task tools at all (`sub-agents.md:444`). + - **[inferred]** Athanor-created tasks would land in Igor's session list and mix with Igor's own items. + - **[judgement]** The phase reviewer cannot read `~/.claude/tasks/` in a useful way, and the run log already has to exist for review. +- **[judgement]** Net: marginal. If a phase is so long that the Athanor loses its place, that is a block-size problem for the plan attack, not a tracking problem. + +### grotto (plans and handoffs that must survive drift and session death, standalone and harness-neutral) + +- **[judgement]** The plan file in the repo must be authoritative. Native lists are per-user, outside git, swept by `cleanupPeriodDays`, gone on `/clear` and new sessions (**[inferred]**), absent on Codex and on Opus 5.5 by default, and absent in background subagents. None of that survives "session death" better than a markdown file. The fork's own resume path is "read a JSON file the model kept current". +- **[judgement]** What grotto should take: + - The per-task fields (Goal, Files, AC, Verify, `blockedBy`) as a light, optional plan-task shape. + - A **status line per task in the plan or handoff file** (for example `- [x] T3 — done @`), updated at each completion. + - A **resume step**: read the plan's status, find the first open unblocked task, continue. + + This is the fork's Step 0 without the second copy. +- **[judgement]** Native Tasks as an optional **projection**: "if `TaskCreate` is in your tool list, mirror the open tasks of this plan into it for the session; the plan file stays the record." That gives the reminder effect where it exists and degrades to nothing elsewhere. +- **Codex**: **[unverified, from memory]** Codex CLI has its own session-local plan tool (`update_plan`: steps with status, no ids or dependencies). The same "file is the record, harness list is a view" rule covers it. + +### Is a native list plus a file mirror better than markdown run logs? + +**[judgement]** No. It is at best a complement. Markdown is the record. A native list is a session-local view that keeps the model on track while it works, and it is worth having only when the tools are present anyway. + +--- + +## 4. Smallest adoptions that could pay off (options, not decisions) + +| Option | Cost | Payoff | Notes | +|---|---|---|---| +| **A. Format only.** grotto plan tasks may use Goal/Files/AC/Verify plus `blockedBy`. The handoff file carries one status line per task. Resume = read status, take the first open unblocked task. | One page of skill text | Most of the fork's resume value, in any harness | No hooks, no env flag. Fits Spire's lean doctrine. | +| **B. A plus optional native projection.** One paragraph: "If `TaskCreate` is available, mirror open tasks for this session. Short subjects, shrink on completion. The file stays authoritative; update it at each completion." | One paragraph | The reminder effect when tools are on; no-op otherwise | Never write `.tasks.json`. The markdown status lines are the mirror. | +| **C. Measured experiment.** Run one Athanor phase with `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` in Igor's session and one without. Compare drift (skipped or reordered blocks, missing handoff notes) and tokens in the run logs. | One run each | Evidence on whether Opus 5.5 benefits, against Anthropic's claim that it does not | The flag is session-wide, so Igor gets the tools too. | +| **D. `CLAUDE_CODE_TASK_LIST_ID=` for one multi-session build.** | An env var per launch | Native cross-session list without `.tasks.json` | Per machine, outside git, swept by retention. Experimental, not a grotto dependency. | +| **E. One native hook, not transcript replay.** For example a `TaskCompleted` hook that appends "task X completed ``" to the run log, or a PreToolUse `git commit` check against the plan file's status lines. | Small script | A mechanical trail or gate | Only if a gate is ever wanted. Use `TaskCreated`/`TaskCompleted` (documented, carry `task_id`) rather than counting transcript creates, which the fork found unreliable. | +| **F. Do nothing.** | none | none | Fine if the run log plus phase-sized blocks already prevent drift. | + +--- + +## Could not verify + +- Whether `/clear` gives a fresh task list. Inferred from per-session directories; the docs do not say so explicitly. +- Whether a foreground subagent's `TaskCreate` writes into the parent session's list (inferred from `agent_id` in `TaskCreated` input) and whether the parent sees it in `TaskList`. +- Whether the solo-session list directory is now `session-` (as for teams, and as `stop-wait-guard.sh` assumes) or the full UUID (as observed here on 2026-09 files). The writing version is unknown. +- That `TaskGet` drops the `metadata` parameter (fork claim, README:143). The local task files have no `metadata` key, but those tasks may never have passed one. +- That the harness re-injects full task **descriptions**, not just subjects, in periodic reminders (fork claim, `subagent-driven-development/SKILL.md:447`). The docs only mention that "reminders take up context". +- That `blockedBy` is not enforced in solo sessions (inferred from the fork needing a hook). Not tested, since the tools are off in this session. +- `TodoWrite`'s exact schema and Codex's `update_plan` behaviour (from memory). +- Whether reminder-driven tracking measurably helps Opus 5.5. No data; option C would produce some.