Flow inconsistency: brainstorming → writing-plans gap - missing worktrees step

[jd-aicc-agent]

• I searched existing issues and this is not a duplicate

Environment

Field	Value
Superpowers version	Latest (as of 2026-04-07)
Harness (Claude Code, Cursor, etc.)	N/A (documentation issue)
Harness version	N/A
Model	N/A
OS + shell	N/A

Is this a Superpowers issue or a platform issue?

• This is a Superpowers documentation/flow consistency issue

What happened?

Found inconsistency between skill dependency declarations and actual checklist steps in the brainstorming → using-git-worktrees → writing-plans flow.

Problem:

1. using-git-worktrees/SKILL.md says it's called by brainstorming (Phase 4):

   **Called by:**
   - **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows

brainstorming/SKILL.md checklist does NOT include using-git-worktrees step:

9. Transition to implementation — invoke writing-plans skill
   writing-plans/SKILL.md expects to run in worktree:

Context: This should be run in a dedicated worktree (created by brainstorming skill).
This creates a gap: brainstorming claims to call worktrees, but doesn't actually do it in its checklist.

Steps to reproduce
Read skills/brainstorming/SKILL.md - checklist step 9 goes directly to writing-plans
Read skills/using-git-worktrees/SKILL.md - claims to be called by brainstorming
Read skills/writing-plans/SKILL.md - expects worktree context
Observe missing link: worktrees creation step is not in brainstorming checklist
Expected behavior
brainstorming/SKILL.md checklist should include:

8.5. Create isolated workspace — invoke using-git-worktrees skill
9. Transition to implementation — invoke writing-plans skill
OR clarify the correct flow order in documentation.

Actual behavior
Checklist jumps from step 8 (user reviews spec) directly to step 9 (invoke writing-plans), skipping worktrees creation.

Suggested fix
Add explicit step in brainstorming checklist:

Checklist

1. Explore project context
2. Offer visual companion
3. Ask clarifying questions
4. Propose 2-3 approaches
5. Present design
6. Write design doc
7. Spec self-review
8. User reviews written spec
9. Create isolated workspace — invoke using-git-worktrees skill // <-- ADD THIS
10. Transition to implementation — invoke writing-plans skill // <-- Renumber
    This aligns the checklist with:

using-git-worktrees dependency declaration
writing-plans expectation of running in worktree
Impact
Users following the checklist will miss the worktrees isolation step, potentially causing:

Workspace pollution
Branch confusion
Context switching issues during implementation

[zerosrat]

Cross-reference audit and a design question

I did a full audit of using-git-worktrees references across all skills. Here's the complete inconsistency map — some of these aren't covered by any existing PR.

Inconsistencies found

Location	Current text	Problem
using-git-worktrees/SKILL.md:212	"Called by: brainstorming (Phase 4)"	Brainstorming has no Phase 4 and never calls this skill
writing-plans/SKILL.md:16	"This should be run in a dedicated worktree (created by brainstorming skill)"	Brainstorming doesn't create worktrees
brainstorming/SKILL.md	Terminal state: "Invoke writing-plans skill"	README puts using-git-worktrees between brainstorming and writing-plans (step 2 of 7)

What existing PRs miss

• fix: restore worktree handoff in brainstorming after spec approval #1097 (best eval quality): only modifies brainstorming/SKILL.md, doesn't fix the stale references in using-git-worktrees or writing-plans
• fix(skills): restore worktree step in brainstorming workflow #675 (best coverage): modifies brainstorming + using-git-worktrees, but still doesn't fix writing-plans/SKILL.md:16
• Neither addresses whether the worktree step should be mandatory or optional

Design question: should the worktree step be optional?

All existing PRs treat the worktree step as REQUIRED. But I think it should be offered as a choice after brainstorming, not forced. Reasons:

1. Not every project needs worktree isolation — solo work, small changes, single-branch workflows
2. The design doc (spec) is a document artifact, not implementation code — writing it on the current branch is fine
3. Issue Subagent-driven development should not auto-create worktrees without user consent #991 ("Subagent-driven development should not auto-create worktrees without user consent") shows the community already has concerns about forced worktree creation
4. executing-plans and subagent-driven-development both independently mark using-git-worktrees as REQUIRED in their Integration sections — so even if brainstorming doesn't force it, the execution phase still enforces isolation when it matters

The placement should stay between brainstorming and writing-plans, consistent with the README's workflow order. But brainstorming's terminal state could offer the choice rather than mandate it.

[fisherkuan]

Adding concrete evidence and noting this gap also affects the executor skills, not just brainstorming. Cross-linking #991 since the fix needs to thread both needles.

Evidence from a real session

Session on superpowers 5.0.7, Claude Code 2.1.107, in a clean git repo on main:

Time (UTC)	Skill invoked
09:16:44	superpowers:brainstorming
09:33:54	superpowers:writing-plans
09:38:33	superpowers:subagent-driven-development
09:48:42	eval-skill

superpowers:using-git-worktrees was never invoked; cwd stayed in the main repo on main. Right after subagent-driven-development was invoked, the model announced "I'm using Subagent-Driven Development to execute this plan. I've already extracted all 4 tasks from the plan. Let me set up tracking and start" and went straight to TodoWrite. No worktree prompt, no worktree creation, no announcement of the using-git-worktrees skill.

Scope is broader than brainstorming

The same gap exists in both executor skills — not only the brainstorming checklist:

• executing-plans/SKILL.md — "The Process" (Step 1 Load / Step 2 Execute / Step 3 Complete) has no worktree step. Worktree only appears in prose at line 68 under ## Integration labeled REQUIRED.
• subagent-driven-development/SKILL.md — the graphviz process diagram starts from "Read plan, extract all tasks… create TodoWrite". Worktree only appears in prose at line 268 under ## Integration labeled REQUIRED.

The meta-skill using-superpowers tells the model "Has checklist? yes → Create TodoWrite todo per item → Follow skill exactly". Prose in a trailing ## Integration section reliably loses to the structural diagram above it — hence the silent skip.

Two additional stale prose references pointing at the old flow:

• using-git-worktrees/SKILL.md:212 — "Called by: brainstorming (Phase 4) - REQUIRED when design is approved and implementation follows". There is no such phase in the current brainstorming/SKILL.md.
• writing-plans/SKILL.md:16 — "This should be run in a dedicated worktree (created by brainstorming skill)".

Suggested resolution that threads both issues

Given @obra's agreement in #991 that worktree creation should be opt-in rather than automatic, a fix that satisfies both issues:

1. Promote the worktree decision into the enforceable structure of both executor skills (add a node to the graphviz / a numbered step), not just brainstorming. That's what makes the model actually run it.
2. Make the step a prompt, not an auto-create, per Subagent-driven development should not auto-create worktrees without user consent #991 — e.g., "Step 1: Worktree decision — ask the user: create isolated worktree (recommended) or work on the current branch? Honor CLAUDE.md / settings preference if set, else ask."
3. Soften the REQUIRED wording in the ## Integration footer of both executor skills to match the opt-in reality (e.g., "Recommended: set up isolated workspace before starting — see using-git-worktrees").
4. Fix the two stale references above in using-git-worktrees/SKILL.md and writing-plans/SKILL.md.

This way the model reliably surfaces the decision (fixes the silent skip reported here) while respecting the user's agency (addresses #991).

Happy to open a PR if the direction matches what @obra has in mind.