fix(skills): restore worktree step in brainstorming workflow

[qishaoyumu]

Summary

• Restore the using-git-worktrees invocation lost during brainstorming skill
  simplification (8e38ab8, 7f2ee61) and still missing after the v5.0.0 rework
• Fix stale "Phase 4" cross-reference in using-git-worktrees Integration section
• Align actual workflow with writing-plans expectation that brainstorming
  creates a worktree (line 16)

Problem

brainstorming never invokes using-git-worktrees, despite writing-plans
expecting it (line 16: "This should be run in a dedicated worktree (created by
brainstorming skill).") and using-git-worktrees documenting it (line 212:
"Called by: brainstorming (Phase 4)").

In practice, after brainstorming completes, writing-plans runs directly in
the main working tree — no workspace isolation occurs.

Changes

skills/brainstorming/SKILL.md (4 edits):

• Checklist: insert step 7 Set up worktree between Write design doc
  and Transition to implementation
• Process flow diagram: add worktree node with correct edges
• Terminal state note: expand skill whitelist to include
  using-git-worktrees
• After the Design: add Workspace isolation section between Spec Review
  Loop and Implementation; adjust Implementation prohibition from
  "any other skill" to "any implementation skill (frontend-design,
  mcp-builder, etc.)" so using-git-worktrees is not blocked

skills/using-git-worktrees/SKILL.md (1 edit):

• Integration: fix stale "Phase 4" cross-reference → "Step 7"

Context

This is a re-implementation of #483 against the v5.0.0 codebase. The original
PR was closed as stale after v5.0.0 substantially reworked the brainstorming
skill (Visual Companion, Scope Assessment, Spec Review Loop). The core intent
is the same — restore the missing worktree step — but adapted to v5.0.0's
expanded checklist (step 7 instead of 6) and refined prohibition wording. All
v5.0.0 features are unaffected.

Related: #483 (original PR, closed as stale)
Closes #574
Ref #186

Test Plan

• Invoke brainstorming skill and verify worktree step appears in task
  checklist as step 7
• After design approval, verify using-git-worktrees is invoked before
  writing-plans
• Verify using-git-worktrees Integration section references "Step 7"
• Confirm v5.0.0 features (Visual Companion, Spec Review Loop) still
  work normally

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 49ef872d-0efa-4d67-8a41-f4a6a9b5280a

📥 Commits

Reviewing files that changed from the base of the PR and between 5d2079a and 6079cd2.

📒 Files selected for processing (1)

• skills/brainstorming/SKILL.md

🚧 Files skipped from review as they are similar to previous changes (1)

• skills/brainstorming/SKILL.md

---

📝 Walkthrough

Walkthrough

The PR inserts a mandatory "Set up worktree" step into the brainstorming flow after design-doc creation and before writing-plans, updates the process graph and terminal-state wording, and adds a "Workspace isolation" section explaining git worktree usage. Integration docs for using-git-worktrees are adjusted to this new positioning.

Changes

Cohort / File(s)	Summary
Brainstorming workflow skills/brainstorming/SKILL.md	Inserted new step "Set up worktree" before invoking writing-plans; promoted previous transition step; updated process graph and terminal-state wording; added "Workspace isolation" section and implementation guidance requiring isolation prior to plan-writing.
Git worktree integration skills/using-git-worktrees/SKILL.md	Updated Integration entry: relabeled positioning to "Step 7 - REQUIRED after writing design doc, before invoking writing-plans" to match the new brainstorming sequence.

Sequence Diagram(s)

sequenceDiagram
  participant User as User
  participant Brain as Brainstorming Skill
  participant WG as using-git-worktrees Skill
  participant WP as writing-plans Skill

  User->>Brain: Start brainstorming / write design doc
  Brain->>User: Ask "User reviews spec?"
  alt User approves
    Brain->>WG: Set up worktree (using-git-worktrees)
    WG-->>Brain: Worktree created
    Brain->>WP: Invoke writing-plans (in worktree)
    WP-->>Brain: Plans written (isolated)
  else User requests changes
    Brain->>User: Continue brainstorming
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Enforce brainstorming workflow with hard gates and process flow #462: Modifies brainstorming transition logic and gating around invoking writing-plans, overlapping sequencing changes.
• fix: require worktree setup before subagent-driven-development and executing-plans #382: Inserts/positions using-git-worktrees before implementation steps; similar integration adjustments.

Poem

🐰 I dug a little branch where designs can rest,
A worktree nursery, tidy and blessed,
Plans now sprout safe in a separate place,
No accidental seeds in the main tree's space. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: restoring the worktree step in the brainstorming workflow, which is the core objective of this PR.
Description check	✅ Passed	The description is well-related to the changeset, clearly explaining the problem, changes, and context with specific file modifications and references to related issues.
Linked Issues check	✅ Passed	The PR fully addresses issue #574 by restoring the using-git-worktrees invocation in the brainstorming workflow and aligning documentation to ensure worktree creation occurs after design is written and before plan writing begins.
Out of Scope Changes check	✅ Passed	All changes are within scope: brainstorming SKILL.md modifications add the worktree step and fix workflow documentation, and using-git-worktrees SKILL.md updates the stale cross-reference—both directly address the linked issue.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

skills/brainstorming/SKILL.md (1)

62-62: Approve with optional wording refinement suggestion.

The guidance correctly establishes the terminal state and skill invocation boundaries. The intent is clear: after design approval, only using-git-worktrees and writing-plans should be invoked, with no other implementation skills allowed.

📝 Optional wording refinement for precision

The phrase "after brainstorming" might be slightly ambiguous since using-git-worktrees is step 7 of the brainstorming checklist. Consider:

-**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skills you invoke after brainstorming are using-git-worktrees (for workspace isolation) then writing-plans.
+**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skills you invoke from brainstorming are using-git-worktrees (for workspace isolation) then writing-plans.

This clarifies that these skills are invoked as part of the brainstorming workflow, not after it completes.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@skills/brainstorming/SKILL.md` at line 62, Update the wording that currently
reads "The terminal state is invoking writing-plans. Do NOT invoke
frontend-design, mcp-builder, or any other implementation skill. The ONLY skills
you invoke after brainstorming are using-git-worktrees (for workspace isolation)
then writing-plans." to remove ambiguity around "after brainstorming":
explicitly state that within the brainstorming workflow (specifically step 7 of
the brainstorming checklist) the only allowed follow-up skills are
using-git-worktrees and then writing-plans, and that no other implementation
skills (e.g., frontend-design, mcp-builder) should be invoked at that point;
reference the exact phrase "The terminal state is invoking writing-plans." and
the skill names "using-git-worktrees" and "writing-plans" so reviewers can
locate and replace the sentence with a clearer version indicating these skills
are invoked as part of the brainstorming steps rather than only after
completion.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@skills/brainstorming/SKILL.md`:
- Line 62: Update the wording that currently reads "The terminal state is
invoking writing-plans. Do NOT invoke frontend-design, mcp-builder, or any other
implementation skill. The ONLY skills you invoke after brainstorming are
using-git-worktrees (for workspace isolation) then writing-plans." to remove
ambiguity around "after brainstorming": explicitly state that within the
brainstorming workflow (specifically step 7 of the brainstorming checklist) the
only allowed follow-up skills are using-git-worktrees and then writing-plans,
and that no other implementation skills (e.g., frontend-design, mcp-builder)
should be invoked at that point; reference the exact phrase "The terminal state
is invoking writing-plans." and the skill names "using-git-worktrees" and
"writing-plans" so reviewers can locate and replace the sentence with a clearer
version indicating these skills are invoked as part of the brainstorming steps
rather than only after completion.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 08bbb055-9fd5-4c70-878c-f1ef2971caca

📥 Commits

Reviewing files that changed from the base of the PR and between 33e55e6 and 5d2079a.

📒 Files selected for processing (2)

• skills/brainstorming/SKILL.md
• skills/using-git-worktrees/SKILL.md

[qishaoyumu]

Re: CodeRabbit nitpick on "after brainstorming" → "from brainstorming"

Thanks for the suggestion. I considered this but decided to keep "after brainstorming" because:

1. It matches the existing pattern — the original maintainer-written text uses the same phrase: "The ONLY skill you invoke after brainstorming is writing-plans."
2. "from brainstorming" could be misread as "the only skills brainstorming ever invokes," which is inaccurate — brainstorming also invokes elements-of-style and spec-document-reviewer during earlier steps.

Happy to revisit if the maintainer prefers different wording.

[qishaoyumu]

Rebased onto latest main to resolve conflicts. The upstream added spec review loop (steps 7-8) since this PR was opened. Updated this PR to insert the worktree step as step 9 (after spec review and user review gate), and updated the cross-reference in using-git-worktrees/SKILL.md accordingly.