From ae2546d5ee606071050a50f7ab698e000dce1ac9 Mon Sep 17 00:00:00 2001 From: Bryan Soares Date: Thu, 18 Jun 2026 18:36:02 -0300 Subject: [PATCH] fix(skills): promote using-git-worktrees into executor process flows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In executing-plans and subagent-driven-development, using-git-worktrees was referenced only in the trailing ## Integration footer. using-superpowers tells the model to follow the structural Process (numbered steps / graphviz), so the footer reference is reliably skipped and the executor stays in the main checkout, where parallel agents collide. Promote it into a Step 0 inside the structural Process of both skills, before the plan is read — mirroring finishing-a-development-branch as a required node at the end. Additive only (new Step 0 section/node, one Red Flag bullet, one Remember bullet); footers and existing tuned content unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/executing-plans/SKILL.md | 18 ++++++++++++++++ skills/subagent-driven-development/SKILL.md | 24 +++++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index 78d8854066..f53d5a46ab 100644 --- a/skills/executing-plans/SKILL.md +++ b/skills/executing-plans/SKILL.md @@ -15,6 +15,23 @@ Load plan, review critically, execute all tasks, report when complete. ## The Process +### Step 0: Ensure an Isolated Workspace + +**REQUIRED SUB-SKILL — before loading the plan:** Use +superpowers:using-git-worktrees to create or verify an isolated workspace. + +This mirrors the required sub-skill at the *end* of this process +(finishing-a-development-branch): isolation is a hard gate at the start, not +an optional footnote. Executing a plan means many edits and commits in the +current directory — if that is the main checkout, a parallel agent or your +human partner collides with your branch and uncommitted state. Create the +worktree *before* the first edit; doing it afterward does not isolate work +already in progress. + +Do not proceed to Step 1 until you have confirmed you are in an isolated +workspace, or your human partner has explicitly told you to run in the +current checkout. + ### Step 1: Load and Review Plan 1. Read plan file 2. Review critically - identify any questions or concerns about the plan @@ -61,6 +78,7 @@ After all tasks complete and verified: - Reference skills when plan says to - Stop when blocked, don't guess - Never start implementation on main/master branch without explicit user consent +- Never start executing before Step 0 — create/verify the worktree first ## Integration diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index d8ca081570..0cf0efd08c 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -60,11 +60,13 @@ digraph process { "Mark task complete in todo list and progress ledger" [shape=box]; } + "Ensure isolated workspace (superpowers:using-git-worktrees)" [shape=box style=filled fillcolor=lightgreen]; "Read plan, note context and global constraints, create todos" [shape=box]; "More tasks remain?" [shape=diamond]; "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" [shape=box]; "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen]; + "Ensure isolated workspace (superpowers:using-git-worktrees)" -> "Read plan, note context and global constraints, create todos"; "Read plan, note context and global constraints, create todos" -> "Dispatch implementer subagent (./implementer-prompt.md)"; "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?"; "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"]; @@ -82,6 +84,25 @@ digraph process { } ``` +## Step 0: Isolated Workspace (do this first) + +**REQUIRED SUB-SKILL — before reading the plan or creating todos:** Use +superpowers:using-git-worktrees to ensure an isolated workspace exists +(create one, or verify you are already in one). This is the first node in +the flowchart above, not an optional footnote. + +Why this is a hard gate, not a suggestion: this skill dispatches many +subagents that edit and commit in the current working directory. If that +directory is the main checkout, a second agent (or the human) working in +parallel collides with your commits, branch state, and uncommitted changes. +The isolation has to exist *before* the first edit — creating a worktree +after work has begun does not retroactively isolate it. + +Do not proceed to the Pre-Flight review until you have confirmed (e.g. with +`git rev-parse --git-dir` vs `--git-common-dir`, or your platform's +worktree tool) that you are working in an isolated workspace, or your human +partner has explicitly told you to run in the current checkout. + ## Pre-Flight Plan Review Before dispatching Task 1, scan the plan once for conflicts: @@ -368,6 +389,9 @@ Done! **Never:** - Start implementation on main/master branch without explicit user consent +- Begin dispatching subagents before an isolated workspace exists — Step 0 + (superpowers:using-git-worktrees) runs before the plan is read, not as an + afterthought. Working in the main checkout lets parallel agents collide. - Skip task review, or accept a report missing either verdict (spec compliance AND task quality are both required) - Proceed with unfixed issues - Dispatch multiple implementation subagents in parallel (conflicts)