From 128a02f47a2ead76494164de426d4f60c773c08c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86gir=20M=C3=A1ni=20Hauksson?= <54936225+sourcehawk@users.noreply.github.com> Date: Mon, 12 Oct 2026 21:41:47 +0100 Subject: [PATCH 1/2] fix(skills/planning-a-feature): stop the writing-plans handoff question Step 6 loads `superpowers:writing-plans`, and that skill ends with an "Execution Handoff" section. The section tells the agent to ask the user for an execution method, subagent-driven or native. Nothing in `planning-a-feature` said that the section does not apply. So an agent could ask that question after the plan and the state file were saved, and not invoke `feature-dev-workflow:developing-a-feature` as step 9 requires. Step 6 now says that the sub-skill ends at its self-review, and that step 9 replaces its handoff. A new Red flags row names the question and points to steps 7, 8, and 9. In a baseline on the unedited skill, agents wrote a real plan and state file in a scratch repository. The two runs on the smallest model both asked the execution-method question. Three runs on each of the two larger models did not. With the new text, five runs on the smallest model asked only the setup questions of `developing-a-feature`. Fixes #93 Co-Authored-By: Claude Opus 5.5 --- skills/planning-a-feature/SKILL.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/skills/planning-a-feature/SKILL.md b/skills/planning-a-feature/SKILL.md index 6b01b53..504c325 100644 --- a/skills/planning-a-feature/SKILL.md +++ b/skills/planning-a-feature/SKILL.md @@ -104,6 +104,8 @@ Sub-issues reference only the parent epic in their `## Context` section — GitH **REQUIRED SUB-SKILL:** Invoke `superpowers:writing-plans` to produce `docs/superpowers/plans/YYYY-MM-DD--plan.md`. The plan is HOW: ordered tasks, dependencies, review checkpoints, PR-by-PR breakdown. +**The sub-skill ends at its self-review.** Use `superpowers:writing-plans` for the plan and its self-review, then return here and continue with step 7. Its closing "Execution Handoff" section is replaced by step 9 of this workflow: do not ask the user to choose an execution method (subagent-driven or native), and do not invoke `superpowers:subagent-driven-development` or `superpowers:executing-plans`. `feature-dev-workflow:developing-a-feature` decides how the work runs and asks its own setup questions. + **During plan-writing, identify parallelism and define contracts.** For every pair of PRs that could run in parallel, ask: what does each side need to know about the other's wire shape, API surface, or data layout to start work without blocking? That's a contract. Document each in a `## Contracts` section of the plan: | Name | Producer (issue) | Consumer (issue) | Shape | Realization | @@ -167,4 +169,5 @@ Spec + plan + state file committed and pushed on `/`, issues aligned | "I'll skip user review on the spec, it's just an internal doc" | An unreviewed spec is a draft. Drafts don't get tickets filed against them. | | "The feature branch is created later in `feature-dev-workflow:developing-a-feature`, so the spec/plan/state commit to `main` first" | Planning owns the branch's birth. Create `/` in step 2 before the first commit; `feature-dev-workflow:developing-a-feature` reuses it. Nothing about the feature reaches `main` except through a PR. | | "This is running the feature-development flow, so the branch is `feature/…`" | The type comes from the change, not from the workflow. A bug fix planned through this flow is still `fix/…`. | +| "The plan is saved, so I ask the user: subagent-driven or native?" | That question is the handoff of `superpowers:writing-plans`, and step 9 replaces it. Continue with steps 7 and 8, then invoke `feature-dev-workflow:developing-a-feature`, which asks its own setup questions. | | "The slug can be refined once I see how the work lands" | Every sub-branch, worktree path, and state-file row derives from it. Name the subject and its effect now (step 2); renaming later touches all of them. | From 401302c2093e5bb7580ca814b9b94ffa87bbbb01 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86gir=20M=C3=A1ni=20Hauksson?= <54936225+sourcehawk@users.noreply.github.com> Date: Mon, 12 Oct 2026 21:46:47 +0100 Subject: [PATCH 2/2] fix(skills/planning-a-feature): limit the handoff rule to the end of the plan Step 6 said, with no limit, not to invoke `superpowers:subagent-driven-development` or `superpowers:executing-plans`. Step 4 of `developing-a-feature` requires `superpowers:subagent-driven-development` for a single PR with 2 or more independent tasks. An agent could carry the rule into that step and skip the required skill. Step 6 now names no execution skill. It says not to start execution from the "Execution Handoff" section, and that `developing-a-feature` decides which execution skill it uses. With the new text, five runs on the smallest model still asked only the setup questions of `developing-a-feature`. Co-Authored-By: Claude Opus 5.5 --- skills/planning-a-feature/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/planning-a-feature/SKILL.md b/skills/planning-a-feature/SKILL.md index 504c325..b7a77fe 100644 --- a/skills/planning-a-feature/SKILL.md +++ b/skills/planning-a-feature/SKILL.md @@ -104,7 +104,7 @@ Sub-issues reference only the parent epic in their `## Context` section — GitH **REQUIRED SUB-SKILL:** Invoke `superpowers:writing-plans` to produce `docs/superpowers/plans/YYYY-MM-DD--plan.md`. The plan is HOW: ordered tasks, dependencies, review checkpoints, PR-by-PR breakdown. -**The sub-skill ends at its self-review.** Use `superpowers:writing-plans` for the plan and its self-review, then return here and continue with step 7. Its closing "Execution Handoff" section is replaced by step 9 of this workflow: do not ask the user to choose an execution method (subagent-driven or native), and do not invoke `superpowers:subagent-driven-development` or `superpowers:executing-plans`. `feature-dev-workflow:developing-a-feature` decides how the work runs and asks its own setup questions. +**The sub-skill ends at its self-review.** Use `superpowers:writing-plans` for the plan and its self-review, then return here and continue with step 7. Step 9 of this workflow replaces its closing "Execution Handoff" section: when the plan is saved, do not ask the user to choose an execution method (subagent-driven or native), and do not start execution from that section. `feature-dev-workflow:developing-a-feature` decides how the work runs and which execution skill it uses, and it asks its own setup questions. **During plan-writing, identify parallelism and define contracts.** For every pair of PRs that could run in parallel, ask: what does each side need to know about the other's wire shape, API surface, or data layout to start work without blocking? That's a contract. Document each in a `## Contracts` section of the plan: