@rrgarciach/flow-spec 0.1.0

package/template/ai-specs/skills/commit/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: commit
+description: Create focused commits and pull requests following repository standards.
+author: Flow Spec
+version: 1.0.0
+---
+# commit Skill
+
+Use it when this workflow is required in the project.
+
+## Instructions
+
+# Role
+
+You are an expert in version control and release workflows. You create clear, comprehensive commits and Pull Requests that align with project standards and make review and traceability straightforward.
+
+# Arguments
+
+**Optional.** `$ARGUMENTS` may contain:
+
+- **Nothing (empty)**: Stage and commit all relevant changes in the working tree, then open a single PR.
+- **Feature/ticket identifiers**: e.g. ticket IDs (e.g. `SCRUM-123`), branch names, or short feature labels. When provided, stage and PR **only** the changes that belong to those features; leave all other changes unstaged and uncommitted.
+- **Description-only / no-git mode**: If the user **explicitly** says something like "no PR", "only commit" (meaning only produce the commit text), "only description", "don't touch git", "just the message", or "dry run", then do **not** run any git commands or create a PR. Only determine scope, list what would be staged, and output the proposed commit message (subject + body). The user can copy and run git commands themselves.
+
+# Goal
+
+1. Produce a **single, comprehensive commit** that accurately describes the relevant changes.
+2. **Push** the branch and **create (or update) a Pull Request** for review.
+3. If arguments were given: **stage and commit only** the changes tied to those features; do not touch other modified files.
+
+# Process and rules
+
+## 0. Description-only / no-git mode (check first)
+
+If the user **explicitly** requested no git operations (e.g. "no PR", "only commit", "only description", "don't touch git", "just the message", "dry run"):
+
+- Perform **only** steps 1–3: inspect state, resolve scope (which files/hunks would be staged), and write the full commit message (subject + body).
+- **Do not** run `git add`, `git commit`, `git push`, or `gh pr create`. Do not modify the repository in any way.
+- Output for the user:
+  1. List of files (and hunks, if partial) that would be staged.
+  2. The proposed commit message in a copy-pasteable block.
+- Then stop; skip steps 4, 5, and 6.
+
+## 1. Inspect current state
+
+- Run `git status` and `git diff` (and `git diff --staged` if needed) to list all modified, added, and deleted files.
+- Identify the current branch. If not on a feature branch, decide whether to create one from the base branch (e.g. `main` or `develop`) before committing.
+
+## 2. Resolve scope: full commit vs feature-scoped commit
+
+- **If `$ARGUMENTS` is empty or not provided**  
+  - Treat all relevant changes (excluding files that should not be committed, e.g. `.env`, build artifacts, local config) as the scope for this commit.  
+  - Stage all of those and proceed to step 3.
+
+- **If `$ARGUMENTS` is provided (e.g. ticket IDs or feature names)**  
+  - Map each argument to the changes that clearly belong to it (by path, ticket id in branch name, or context in diffs).  
+  - Stage **only** the files/hunks that belong to those features.  
+  - Leave any other modified files **unstaged** and do not include them in the commit.  
+  - If a file contains both feature-related and unrelated changes, use `git add -p` (or equivalent) to stage only the hunks that belong to the requested features.  
+  - If no changes clearly match the given arguments, report this and do not commit.
+
+## 3. Commit message
+
+- Write the commit message **in English** (per `docs/base-standards.md`).
+- Make it **descriptive** (per Git Workflow in `backend-standards.md` and `frontend-standards.md`).
+- Structure it so that:
+  - **Subject line**: Short, imperative summary (e.g. "Add candidate filters to position list", "Fix validation for application deadline"). Optionally prefix with a scope or ticket id (e.g. `SCRUM-123: Add candidate filters`).
+  - **Body** (if needed): Bullet points or short paragraphs describing what changed and why (areas touched, new behavior, fixes). Reference ticket IDs here if they apply.
+- Do not commit secrets, `.env`, or other sensitive or generated artifacts.
+
+## 4. Commit and push
+
+- Create the commit with the message from step 3.
+- Push the current branch to the remote (`git push origin <branch>`). If the branch does not exist on the remote, push with `-u` to set upstream.
+
+## 5. Pull Request
+
+- Use the **GitHub CLI (`gh`)** for all GitHub operations (per repository standards).
+- Create or update the PR for the current branch:
+  - **Title**: Clear, aligned with the commit (e.g. include ticket ID if applicable: `[SCRUM-123] Add candidate filters to position list`).
+  - **Description**: Summarize the change set, link to the ticket if relevant, and note any testing or follow-ups.
+- If the repo uses branch protection or required checks, mention that the PR is ready for review once checks pass.
+
+## 6. Summary for the user
+
+- Report what was committed (files and scope).
+- If arguments were provided: confirm which features/tickets were included and that other changes were left unstaged.
+- Provide the PR URL (from `gh` output).
+
+# References
+
+- `docs/base-standards.md`: English-only for commit messages and technical artifacts.
+- `docs/backend-standards.md` and `docs/frontend-standards.md`: Git Workflow (feature branches, descriptive commits, small focused branches).
+- Repository git workflow conventions: Use `gh` for GitHub and PR creation; optional ticket-based branch and PR linking.
+
+# Notes
+
+- **Description-only**: When the user asks for no PR or only the commit text, output the staging plan and message only; do not run any git or `gh` commands.
+- Do not run destructive git commands (e.g. `git push --force` without explicit user request).
+- If there are conflicts or the push is rejected, report the situation and suggest next steps (e.g. pull/rebase then push), but do not force-push unless the user asks.
+- When arguments are provided, **only** the changes tied to those features are staged and committed; everything else remains in the working tree for a separate commit or PR.

package/template/ai-specs/skills/enrich-us/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: enrich-us
+description: Analyze and enhance user stories with complete, implementation-ready technical detail from direct ticket input or monday.com.
+author: Flow Spec
+version: 1.0.0
+---
+# enrich-us Skill
+
+Use it when this workflow is required in the project.
+
+## Instructions
+
+Please analyze and enrich the ticket: $ARGUMENTS.
+
+Follow these steps:
+
+1. Determine the ticket input source:
+   - **Direct input mode (default when ticket text is provided):** Use the ticket content shared by the user in the prompt/chat.
+   - **Monday mode (optional):** If the user provides a monday.com item id/key, or asks to use monday (including references like "the one in progress"), use the Monday MCP to fetch the item details.
+     - Boards in this workflow store a custom **ID column** (a text column) holding a readable key such as `PROJ-123`. Resolve the item by looking it up via that column value (not the internal numeric item id) using the MCP's "find item by column value" capability.
+2. Act as a product expert with technical knowledge.
+3. Understand the problem described in the ticket.
+4. Decide whether or not the User Story is completely detailed according to product best practices. Validate that it includes:
+   - Full functionality description
+   - Comprehensive list of fields to update
+   - Required endpoints structure and URLs
+   - Files/modules to modify according to architecture and best practices
+   - Definition of done (implementation and delivery steps)
+   - Documentation and unit test updates
+   - Non-functional requirements (security, performance, observability, etc.)
+5. If the story lacks enough technical detail for autonomous implementation, provide an improved version that is clearer, more specific, and concise, aligned with step 4. Use project technical context from `@documentation`. Return the result in markdown.
+6. Output format must always include:
+   - `## Original`
+   - `## Enhanced`
+7. Monday write-back is optional and only applies in Monday mode:
+   - Update the monday.com item by appending the enhanced content after the original content (as an update/comment on the item), with clear `h2` sections `[original]` and `[enhanced]` and readable formatting (lists/code snippets when useful).
+   - If the item's status column indicates it needs refinement (e.g. a label like `To Refine`), move it to the label that indicates refinement is complete (e.g. `Pending refinement validation`), per the board's configured status labels.
+
+## Notes
+
+- Do not require monday.com when the user already provided full ticket content directly.
+- If input is ambiguous (for example, user gives a short reference without content), ask whether to resolve via monday.com or request the full ticket text.

package/template/ai-specs/skills/explain/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: explain
+description: Teach underlying concepts with clear mental models to close skill gaps behind user questions.
+author: Flow Spec
+version: 1.0.0
+---
+# explain Skill
+
+Use it when this workflow is required in the project.
+
+## Instructions
+
+# Instructions
+
+You are an expert learning facilitator. Your role is to help the user **understand the concepts behind their request**, not just answer the question. You do not optimize for speed or unblocking; you optimize for **skill acquisition**, **conceptual clarity**, **mental models**, and **transferable understanding**. Your purpose is to close the skill gap behind the user's question.
+
+When the user's prompt is clearly a question, identify the **skill gap** behind it (infer the type: fundamentals, mental model, tooling, systems interaction, or debugging methodology) and tailor the explanation accordingly. Do not expose your internal diagnosis; use it to shape depth and focus. Teach the underlying concepts so they can reason about similar problems later.
+
+**Never jump to fixes.** Explain the system before discussing behavior. Do not provide checklists, quick procedural steps, unexplained code, or shallow debugging advice without conceptual explanation.
+
+**Ground explanations** in official documentation and established design patterns. Do not speculate or invent APIs or parameters; if uncertain, state uncertainty. Reducing hallucination is part of your role.
+
+**Behavior and tone:** Structured, not verbose. No marketing tone, motivational fluff, or emojis. Do not say "as an AI" or similar. Do not provide direct fixes or code snippets unless the user explicitly asks for them in a follow-up.
+
+## Handling the topic
+
+- **If arguments are provided** ($ARGUMENTS): Use them as the user prompt (question or request to explain) and proceed with the response below.
+- **If no arguments are passed:** Use the **context of the conversation** as the topic to explain. If there is no prior conversation or no clear topic in context, **ask the user explicitly** what topic or concept they want explained; do not invent a topic.
+
+---
+
+## Your objective
+
+Given the topic (from arguments or conversation context), produce a **concept-focused learning response** that includes all of the following, in order. Adapt depth and examples to the question; keep each section concise but complete.
+
+### 1. Skill gap and concept summary
+
+- **If the prompt is a question**: State briefly what skill or concept gap the question reveals (e.g. "understanding of caching strategies", "familiarity with TDD", "how RAG differs from fine-tuning").
+- **Concept summary**: In 2–4 short paragraphs, explain the core concept(s) in plain language. Your explanation should answer:
+  - **What** is happening?
+  - **Why** does it behave this way?
+  - **Where** in the system does this effect originate? (when relevant)
+- Cover **technical concepts** when relevant: e.g. caching strategy, RAG, async execution, lazy loading, API design, state management, security (auth, CORS, etc.).
+- Cover **design and process concepts** when relevant: e.g. TDD, DDD, SOLID, design patterns (Factory, Repository, Observer…), separation of concerns, API versioning.
+- Use precise terms and one or two concrete examples tied to the user's context when possible.
+
+### 2. Alternatives to the solution
+
+- List **2–4 alternative approaches** to solving the same problem or achieving the same goal.
+- For each: name it, one-sentence description, and when it tends to be a better or worse fit (trade-offs: complexity, performance, maintainability, team familiarity).
+- **Deepen the section**: Also include, when relevant:
+  - Edge cases and failure modes.
+  - Common misconceptions and what experienced developers pay attention to.
+- Keep it scoped to what the user asked; avoid unnecessary breadth.
+
+### 3. Visual or mental model (when appropriate)
+
+- If the concept benefits from structure or flow, provide **one** of:
+  - A **mental model** (e.g. "Think of X as…", "The flow is: 1)… 2)…").
+  - A **diagram** in text (ASCII/Mermaid) or a short description of a diagram they could draw (boxes, arrows, layers).
+- Skip this section only if the topic is purely factual and a model would not add clarity.
+
+### 4. Quiz to validate learnings (interactive)
+
+- Provide **3–5 short quiz questions** (multiple choice or short answer) that check:
+  - Understanding of the main concept.
+  - When to choose one approach over another.
+  - Common pitfalls or misconceptions.
+- **Do not give the answers yet.** Present only the questions. Tell the user to answer them (in the chat), and that you will provide the answer key and feedback **after they submit their answers**. Wait for the user's response before revealing the correct answers or giving the answer key.
+
+### Adaptive strategies
+
+- **When the user is seeing the concept for the first time:** Start from first principles, define key terms precisely, contrast with adjacent concepts, use a minimal concrete example, then abstract.
+- **When the user says they don't get it (or similar):** Change explanatory strategy: use an analogy, a simpler example, or rebuild the abstraction step by step.
+
+### Success criterion
+
+A successful response should make the user feel: *"I understand how this system works and why it behaves that way."* Not: *"I applied a fix."*
+
+---
+
+# User prompt (question or request to explain)
+
+$ARGUMENTS

package/template/ai-specs/skills/meta-prompt/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: meta-prompt
+description: Rewrite prompts using prompt-engineering best practices for precise and complete results.
+author: Flow Spec
+version: 1.0.0
+---
+# meta-prompt Skill
+
+Use it when this workflow is required in the project.
+
+## Instructions
+
+# Instructions
+
+You are an expert in prompt engineering.
+Given the following prompt, prepare it using best practices for structure (role, objective...) and format to achieve a precise and exhaustive result. Stick only to the requested objective by carefully analyzing what is asked in the original prompt
+
+# Original prompt:
+[The prompt that the user introduces in the command]

package/template/ai-specs/skills/update-docs/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: update-docs
+description: Identify and update required technical documentation based on implemented changes.
+author: Flow Spec
+version: 1.0.0
+---
+# update-docs Skill
+
+Use it when this workflow is required in the project.
+
+## Instructions
+
+Use `docs/documentation-standards.md` to update whatever documentation is needed according to the changes made

package/template/ai-specs/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,375 @@
+---
+name: using-git-worktrees
+description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
+author: Flow Spec
+version: 1.0.0
+---
+
+# Using Git Worktrees
+
+## Overview
+
+Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.
+
+**Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
+
+## Step 0: Detect Existing Isolation
+
+**Before creating anything, check if you are already in an isolated workspace.**
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+**Submodule guard:** `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:
+
+```bash
+# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
+git rev-parse --show-superproject-working-tree 2>/dev/null
+```
+
+**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 3 (Project Setup). Do NOT create another worktree.
+
+Report with branch state:
+- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
+- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
+
+**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.
+
+Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:
+
+> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
+
+Honor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 3.
+
+## Step 1: Create Isolated Workspace
+
+**You have two mechanisms. Try them in this order.**
+
+### 1a. Native Worktree Tools (preferred)
+
+The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 3.
+
+Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.
+
+If the native flow does not propagate Claude/Cursor settings and the user expects parity with the main checkout, copy `.claude/settings.json` and `.claude/settings.local.json` from the primary workspace using the same loop as Step 1b **after** the native tool finishes—only when files exist on disk.
+
+Only proceed to Step 1b if you have no native worktree tool available.
+
+### 1b. Git Worktree Fallback
+
+**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
+
+#### Directory Selection
+
+Follow this priority order. Explicit user preference always beats observed filesystem state.
+
+1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
+
+2. **Check for an existing project-local worktree directory:**
+   ```bash
+   ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+   ls -d worktrees 2>/dev/null      # Alternative
+   ```
+   If found, use it. If both exist, `.worktrees` wins.
+
+3. **Check for an existing global directory:**
+   ```bash
+   project=$(basename "$(git rev-parse --show-toplevel)")
+   ls -d ~/.config/superpowers/worktrees/$project 2>/dev/null
+   ```
+   If found, use it (backward compatibility with legacy global path).
+
+4. **If there is no other guidance available**, default to `.worktrees/` at the project root.
+
+5. **Optional sibling-directory layout** (only when the user or project docs declare it): keep worktrees outside the repo tree next to the project folder:
+
+   ```bash
+   SOURCE_ROOT=$(git rev-parse --show-toplevel)
+   PROJECT_ROOT=$(basename "$SOURCE_ROOT")
+   LOCATION="../${PROJECT_ROOT}-worktrees"
+   # path="$LOCATION/$BRANCH_NAME"
+   ```
+
+   This avoids nesting worktrees under `SOURCE_ROOT`; `.gitignore` checks for `.worktrees` / `worktrees` under the repo do not apply here.
+
+#### Safety Verification (project-local directories only)
+
+**MUST verify directory is ignored before creating worktree:**
+
+```bash
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+**If NOT ignored:** Add to .gitignore, commit the change, then proceed.
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+Global directories (`~/.config/superpowers/worktrees/`) need no verification.
+
+#### Create the Worktree
+
+**Capture the main checkout root before `git worktree add`.** After `cd` into the new worktree, `git rev-parse --show-toplevel` points at the worktree directory, not the checkout where `.claude/settings*.json` usually lives.
+
+```bash
+project=$(basename "$(git rev-parse --show-toplevel)")
+SOURCE_ROOT=$(git rev-parse --show-toplevel)
+
+# Determine path based on chosen location
+# For project-local: path="$LOCATION/$BRANCH_NAME"
+# For global: path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
+
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.
+
+#### Copy Claude configuration (Step 1b only)
+
+After creating the worktree with git (Step 1b), copy local Claude settings from the **main checkout** so Cursor/Claude CLI behavior matches the primary workspace. These files are often untracked.
+
+Do **not** copy if the user declines or if a native tool (Step 1a) already propagates settings—respect the harness.
+
+Run **after** `cd "$path"` (still using `SOURCE_ROOT` captured above):
+
+```bash
+copied_claude_settings=false
+for claude_settings in ".claude/settings.json" ".claude/settings.local.json"; do
+    if [ -f "$SOURCE_ROOT/$claude_settings" ]; then
+        mkdir -p ".claude"
+        cp -p "$SOURCE_ROOT/$claude_settings" "./$claude_settings"
+        echo "Copied $claude_settings to worktree"
+        copied_claude_settings=true
+    fi
+done
+
+if [ "$copied_claude_settings" = false ]; then
+    echo "No local Claude settings found (.claude/settings.json or .claude/settings.local.json)"
+fi
+```
+
+**Symlinks:** If the source tree uses symlinks for `.claude` (e.g. `.claude/skills` → `../../ai-specs/skills`), copying only these JSON files does not recreate symlink targets. Either repeat the same symlink layout in the worktree or rely on project-relative paths inside `settings.json`.
+
+## Step 3: Project Setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+## Step 4: Verify Clean Baseline
+
+Run tests to ensure workspace starts clean:
+
+```bash
+# Use project-appropriate command
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+### Report
+
+```
+Worktree ready at <full-path>
+Claude settings copied (or none found / skipped per harness)
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## Step 5: Cleanup — Remove the Worktree When Done
+
+**Run cleanup once the work is complete.** "Done" means: branch merged, PR closed, the experiment was discarded, or the user has explicitly confirmed they no longer need the isolated workspace. Never remove a worktree that still contains uncommitted, unpushed, or unmerged changes the user may want.
+
+### 5.0 Detect Cleanup Mode
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+```
+
+- **If `GIT_DIR == GIT_COMMON`:** You were never in a linked worktree (Step 0 sent you straight to Step 3). There is nothing to clean up — skip Step 5 entirely.
+- **If `GIT_DIR != GIT_COMMON`:** You are inside a linked worktree. Continue with cleanup.
+
+### 5.1 Verify Work Is Saved
+
+Before removing anything, confirm there is no work to lose:
+
+```bash
+git status --porcelain                 # Must be empty (no uncommitted changes)
+git log @{u}.. 2>/dev/null             # Must be empty (no unpushed commits)
+```
+
+**If either command returns output:** Stop. Report the unsaved work to the user and ask how to proceed (commit/push, stash, or force discard). Never delete a worktree with unsaved work without explicit user confirmation.
+
+Capture the worktree path and branch name before leaving the directory:
+
+```bash
+WORKTREE_PATH=$(git rev-parse --show-toplevel)
+BRANCH_NAME=$(git branch --show-current)
+```
+
+### 5.2 Native Worktree Tools (preferred)
+
+If you used a native worktree tool in Step 1a (`EnterWorktree`, `WorktreeCreate`, `/worktree`, etc.), use the matching native command to remove the worktree (e.g. `LeaveWorktree`, `WorktreeRemove`, `/worktree remove`). Native tools clean up directories, branches, and harness state consistently.
+
+Only proceed to 5.3 if no native cleanup tool is available.
+
+### 5.3 Git Worktree Fallback Cleanup
+
+**Only use this if Step 5.2 does not apply** — you created the worktree manually in Step 1b.
+
+```bash
+# 1. Move out of the worktree before deleting it
+cd "$GIT_COMMON/.."   # or any path inside the main checkout
+
+# 2. Remove the worktree
+git worktree remove "$WORKTREE_PATH"
+
+# 3. If files are still present (e.g. ignored artifacts blocking removal),
+#    confirm with the user, then force-remove
+git worktree remove --force "$WORKTREE_PATH"
+
+# 4. Delete the local branch only if it was created for this worktree
+#    AND has been merged or is no longer needed
+git branch -d "$BRANCH_NAME"            # safe delete (refuses if unmerged)
+git branch -D "$BRANCH_NAME"            # force delete (only with user confirmation)
+
+# 5. Prune stale worktree metadata if the directory was deleted manually
+git worktree prune
+```
+
+**Sandbox fallback:** If removal fails due to permissions, report the failure and the path that needs manual cleanup. Do not retry destructively.
+
+### 5.4 Verify Cleanup
+
+```bash
+git worktree list                      # WORKTREE_PATH must no longer appear
+ls -d "$WORKTREE_PATH" 2>/dev/null     # Must return nothing
+```
+
+### Report
+
+```
+Worktree removed: <full-path>
+Branch <name> deleted (or kept, if still needed)
+Main checkout left untouched
+```
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| Already in linked worktree | Skip creation (Step 0) |
+| In a submodule | Treat as normal repo (Step 0 guard) |
+| Native worktree tool available | Use it (Step 1a) |
+| No native tool | Git worktree fallback (Step 1b) |
+| `.worktrees/` exists | Use it (verify ignored) |
+| `worktrees/` exists | Use it (verify ignored) |
+| Both exist | Use `.worktrees/` |
+| Neither exists | Check instruction file, then default `.worktrees/` |
+| User/project declares sibling worktrees | `../${PROJECT_ROOT}-worktrees` (Step 1b item 5) |
+| Global path exists | Use it (backward compat) |
+| Directory not ignored | Add to .gitignore + commit |
+| Permission error on create | Sandbox fallback, work in place |
+| Tests fail during baseline | Report failures + ask |
+| No package.json/Cargo.toml | Skip dependency install |
+| Work complete, in linked worktree | Run Step 5 cleanup |
+| Never created a worktree | Skip Step 5 |
+| Uncommitted/unpushed changes at cleanup | Stop and ask user |
+| Native cleanup tool available | Use it (Step 5.2) |
+| No native cleanup tool | `git worktree remove` (Step 5.3) |
+| Worktree directory deleted manually | `git worktree prune` |
+| Git fallback: clone Claude behavior into worktree | Copy `.claude/settings*.json` from `SOURCE_ROOT` (Step 1b) |
+| Repo uses `.claude` symlinks | Copy JSON only is not enough—recreate symlinks or paths |
+
+## Common Mistakes
+
+### Fighting the harness
+
+- **Problem:** Using `git worktree add` when the platform already provides isolation
+- **Fix:** Step 0 detects existing isolation. Step 1a defers to native tools.
+
+### Skipping detection
+
+- **Problem:** Creating a nested worktree inside an existing one
+- **Fix:** Always run Step 0 before creating anything
+
+### Skipping ignore verification
+
+- **Problem:** Worktree contents get tracked, pollute git status
+- **Fix:** Always use `git check-ignore` before creating project-local worktree
+
+### Assuming directory location
+
+- **Problem:** Creates inconsistency, violates project conventions
+- **Fix:** Follow priority: existing > global legacy > instruction file > default
+
+### Proceeding with failing tests
+
+- **Problem:** Can't distinguish new bugs from pre-existing issues
+- **Fix:** Report failures, get explicit permission to proceed
+
+### Removing a worktree with unsaved work
+
+- **Problem:** `git worktree remove --force` discards uncommitted/unpushed changes silently
+- **Fix:** Always run `git status --porcelain` and `git log @{u}..` before removal; stop and ask if either is non-empty
+
+### Deleting the branch before it is merged
+
+- **Problem:** `git branch -D` destroys commits that were never merged or pushed
+- **Fix:** Prefer `git branch -d` (safe delete); only force-delete after explicit user confirmation
+
+### Mixing native and manual cleanup
+
+- **Problem:** Running `git worktree remove` on a worktree created by a native tool leaves phantom harness state
+- **Fix:** Whatever created the worktree must remove it (native tool ↔ native tool, git ↔ git)
+
+### Copying Claude settings from the wrong directory
+
+- **Problem:** Using `git rev-parse --show-toplevel` after `cd` into the new worktree resolves to the worktree path, so copies find no settings or copy from the wrong place
+- **Fix:** Set `SOURCE_ROOT=$(git rev-parse --show-toplevel)` in the main checkout **before** `git worktree add`, then use `$SOURCE_ROOT` in the copy loop
+
+## Red Flags
+
+**Never:**
+- Create a worktree when Step 0 detects existing isolation
+- Use `git worktree add` when you have a native worktree tool (e.g., `EnterWorktree`). This is the #1 mistake — if you have it, use it.
+- Skip Step 1a by jumping straight to Step 1b's git commands
+- Create worktree without verifying it's ignored (project-local)
+- Skip baseline test verification
+- Proceed with failing tests without asking
+- Remove a worktree that still has uncommitted, unpushed, or unmerged work without explicit user confirmation
+- Force-delete a branch (`git branch -D`) without confirming it is merged or no longer needed
+- Run `git worktree remove` on a worktree created by a native tool
+
+**Always:**
+- Run Step 0 detection first
+- Prefer native tools over git fallback
+- Follow directory priority: existing > global legacy > instruction file > default
+- Verify directory is ignored for project-local
+- Auto-detect and run project setup
+- Verify clean test baseline
+- Run Step 5 cleanup once the work is done, using the same mechanism that created the worktree
+- Verify there is nothing to lose before removing a worktree (`git status --porcelain`, `git log @{u}..`)
+- Confirm with `git worktree list` and a directory check that cleanup actually completed
+- After Step 1b (git fallback), copy `.claude/settings.json` and `.claude/settings.local.json` from `SOURCE_ROOT` captured before `git worktree add`