feat: add workflow skills

skills/dispatch-worktree-task/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: dispatch-worktree-task
+description: "Use when a task has a clear implementation plan and should be executed by a subagent in an isolated git worktree. Triggers on phrases like: dispatch this, send to a subagent, work on this in a worktree, dispatch to worktree, background task, isolated execution."
+---
+
+# Dispatch Worktree Task
+
+## Overview
+
+Packages a task with a clear plan, creates an isolated git worktree, and dispatches a subagent to implement, validate, verify, and commit in the background. The main session reviews, pushes, and creates the PR.
+
+**Core principle:** Plan in the main session, execute in isolation, verify before pushing.
+
+## When to Use
+
+- Implementation plan is written and approved
+- Task is self-contained (no back-and-forth needed)
+- You want background execution while continuing other work
+
+**When NOT to use:**
+- Task requires interactive clarification mid-implementation
+- Changes span multiple repos or need coordination with other branches
+- Quick single-file fix (just do it inline)
+
+## Workflow
+
+```dot
+digraph dispatch {
+  rankdir=TB;
+  node [shape=box];
+
+  plan [label="1. Prepare implementation plan"];
+  worktree [label="2. Create git worktree\non new branch"];
+  dispatch [label="3. Dispatch subagent\n(implement, verify, commit)"];
+  review [label="4. Review diff,\npush + PR"];
+  cleanup [label="5. Remove worktree"];
+
+  plan -> worktree -> dispatch -> review -> cleanup;
+}
+```
+
+### 1. Prepare the implementation plan
+
+Write a detailed plan that includes:
+- **Context** — why this change, what was tried/rejected
+- **Step-by-step plan** — numbered, specific files and code patterns
+- **Pre-commit validation** — exact commands to run (read from project's CLAUDE.md)
+- **Reproduction command** — a command that exercises the original scenario (bug or feature). Adapt paths, use temp dirs, etc., but exercise the same behavior. The subagent must run it after implementing and confirm the fix works.
+- **What NOT to do** — anti-patterns to avoid
+
+### 1b. Verify plan completeness
+
+Before proceeding, confirm the plan includes all required sections:
+
+- [ ] **Context** — why this change, what was tried/rejected
+- [ ] **Step-by-step plan** — numbered, specific files and code patterns
+- [ ] **Pre-commit validation** — exact commands from project's CLAUDE.md
+- [ ] **Reproduction command** — a command that exercises the original scenario. For refactorings or structural changes where there's no behavioral scenario, reproduction = "existing tests pass and restructured code compiles" — state this explicitly rather than omitting reproduction.
+- [ ] **Anti-patterns** — what NOT to do
+
+If any section is missing or vague, fill it in before creating the worktree.
+
+### 2. Create worktree
+
+```bash
+git worktree add .worktrees/<branch-name> -b <branch-name> main
+```
+
+Use `.worktrees/` directory. Check that `.worktrees/` is in `.gitignore`. If not, add it before creating the worktree. Branch name should match the work (e.g., `fix/cache-lock-fs4`).
+
+> **Stale worktree/branch:** If the branch or worktree already exists from a previous attempt, remove them first (`git worktree remove .worktrees/<branch-name>` and `git branch -D <branch-name>`) or reuse after verifying the worktree state is clean (`git status` in the worktree).
+
+> **Why manual worktrees instead of `isolation: "worktree"`?** The branch is the deliverable — it gets pushed and PR'd. You need a named branch you control. For fan-out/fan-in where you cherry-pick temporary commits back, see `review-and-fix`.
+
+### 3. Dispatch subagent
+
+Use the Task tool with these settings:
+
+| Parameter | Value |
+|-----------|-------|
+| `subagent_type` | `general-purpose` |
+| `mode` | `bypassPermissions` |
+| `run_in_background` | `true` |
+
+**Prompt must include:**
+- Worktree path and branch name
+- **Explicit `cd <worktree-absolute-path>` as the subagent's first action.** The Task tool starts subagents in the parent's working directory, not the worktree.
+- Full implementation plan
+- Pre-commit validation commands (from project CLAUDE.md)
+- **Reproduction command** — a command that exercises the same scenario as the original report. Adapt for the worktree context (temp output dirs, etc.) but verify the same behavior.
+- Commit message to use (conventional commits)
+- Project conventions (no co-authored-by lines, etc.)
+
+**Subagent execution order:**
+1. Implement the change
+2. Run pre-commit validation (from project CLAUDE.md)
+3. **Reproduce the original scenario** — build and run a command that exercises the same behavior from the original report. Adapt for safety (temp dirs, non-destructive variants) but verify the same scenario.
+4. Commit (do NOT push — the main session handles push after review)
+
+**On failure:** If the implementation is incomplete, the plan doesn't match reality, or validation/reproduction fails — the subagent must NOT commit. Instead, report what happened: what was attempted, what failed, and what state the worktree is in. The main session will decide next steps.
+
+If reproduction fails but the fix is otherwise correct, the subagent should fix the issue and re-verify. If it cannot fix it, do not commit — report the failure.
+
+### 4. Review, push, and create PR
+
+When the agent reports back:
+- Show `git log main..<branch> --oneline` and `git diff --stat main..<branch>`
+- Read the actual diff for the files listed in the implementation plan
+- Confirm the reproduction command passed in the agent's output
+- Push the branch: `git push -u origin <branch>`
+- Create the PR (or remind the user)
+
+### 5. Clean up worktree
+
+After the PR is created, remove the worktree:
+
+```bash
+git worktree remove .worktrees/<branch-name>
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| No reproduction command in prompt | Always include a command that exercises the original scenario |
+| Reproduction command is just "run tests" | Tests verify correctness; reproduction verifies the original complaint is resolved |
+| Reproduction command is destructive | Adapt for safety — use temp dirs, non-destructive variants — but verify the same behavior |
+| Vague subagent prompt | Paste the full plan — subagents have no prior context |
+| Not verifying the diff | Always read the key file diffs before creating the PR |
+| Skipping pre-commit in prompt | Agent won't know to run validation unless told |
+| Forgetting the PR | Always create or remind about PR after reviewing |

skills/iterative-review-fix/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: iterative-review-fix
+description: "Use when code needs repeated review-fix cycles until clean. Dispatches a reviewer agent, then a fixer agent, commits, and repeats until findings converge to zero or a cap is reached. Triggers on: iterate until clean, review fix loop, converge, repeated review, keep fixing until done, iterative review."
+---
+
+# Iterative Review-Fix Loop
+
+## Overview
+
+Serial review-fix loop: dispatch a read-only reviewer, then a fixer, commit, repeat until findings hit zero, plateau, or an iteration cap. Designed for convergence, not throughput.
+
+**Core principle:** One reviewer, one fixer, per iteration. Each pass commits directly on the current branch. Commits are revert points.
+
+## When to Use
+
+- Code needs multiple rounds of review to converge on clean
+- User says "iterate until clean", "keep fixing", or "review fix loop"
+- A single review-and-fix pass is insufficient (findings cascade)
+
+**When NOT to use:**
+- Single-pass review with parallel dispatch — use `review-and-fix`
+- Research-backed review — use `review-with-research`
+- One specific bug fix — just fix it inline
+
+## Workflow
+
+### 1. Capture Inputs
+
+Determine three things before starting the loop:
+
+**Review focus** — what to look for. The user provides criteria inline or as a file path. Read the file if a path is given.
+
+**Scope** — what to review. Default: branch diff vs main.
+```bash
+git diff main --stat
+git log main..HEAD --oneline
+```
+If the user specifies a directory or file list, use that instead.
+
+**Iteration cap** — default 5. The user can override.
+
+Read the project's `CLAUDE.md` for pre-commit validation commands — the fixer needs these.
+
+### 2. Loop (iterations 1..cap)
+
+#### 2a. Dispatch reviewer
+
+Launch a read-only subagent:
+
+| Parameter | Value |
+|-----------|-------|
+| `subagent_type` | `Explore` |
+| `run_in_background` | `true` |
+
+**Reviewer prompt:**
+
+```
+You are performing review pass {N} of an iterative review-fix cycle.
+
+## Review Focus
+{criteria — inline text or file contents}
+
+## Scope
+{branch diff output, directory listing, or file list}
+
+## Output Format
+For each issue found, produce:
+
+### Finding: [stable title — same title if same issue persists across passes]
+**Severity:** high | medium | low
+**File:** `path/to/file:line`
+**Description:** [what's wrong and why]
+**Fix approach:** [specific steps to fix]
+
+If no issues found, respond with exactly: NO_FINDINGS
+```
+
+**Stable titles are critical.** The main session compares findings across passes to detect plateaus. If the reviewer uses a different title for the same issue, plateau detection breaks. Instruct the reviewer to title findings by the problem, not the pass number.
+
+#### 2b. Parse findings
+
+Three outcomes:
+
+1. **Zero findings** (`NO_FINDINGS`) — break the loop, report clean.
+2. **Same findings as previous pass** — plateau detected. The fixer is stuck on these issues. Break the loop, report the stuck findings.
+3. **New or different findings** — proceed to fixer.
+
+**Plateau detection:** Compare finding titles (not full descriptions) between consecutive passes. If the set of titles is identical, it's a plateau. If a subset overlaps but new findings appeared, it's not a plateau — the fixer made partial progress.
+
+#### 2c. Dispatch fixer
+
+Launch a general-purpose subagent:
+
+| Parameter | Value |
+|-----------|-------|
+| `subagent_type` | `general-purpose` |
+| `mode` | `bypassPermissions` |
+| `run_in_background` | `true` |
+
+**Fixer prompt:**
+
+```
+You are fixing issues found during review pass {N}.
+
+## Findings
+{paste all findings from reviewer — full text, not just titles}
+
+## Validation
+After making all fixes, run these commands and confirm they pass:
+{pre-commit validation commands from project CLAUDE.md}
+
+## Commit
+If all fixes are made and validation passes, create a single commit:
+fix: address review findings (pass {N})
+
+Do NOT add co-authored-by lines.
+Do NOT modify files beyond what the findings require.
+Do NOT commit if validation fails — report the failure instead.
+```
+
+**If the fixer reports validation failure:** stop the loop immediately. Report the failure to the user with the fixer's output. Do not continue to the next pass — a broken build state will cascade.
+
+#### 2d. Increment and continue
+
+After a successful fixer pass, increment the counter and loop back to 2a.
+
+### 3. Report
+
+When the loop exits (clean, plateau, or cap), produce a summary:
+
+**Clean exit:**
+```
+Review-fix loop completed in {N} passes.
+Pass 1: {count} findings — fixed and committed
+Pass 2: {count} findings — fixed and committed
+Pass 3: clean — no findings
+```
+
+**Plateau exit:**
+```
+Review-fix loop plateaued after {N} passes.
+Pass 1: {count} findings — fixed and committed
+Pass 2: {count} findings — fixed and committed (partial overlap with pass 1)
+Pass 3: {count} findings — same as pass 2 (plateau)
+
+Stuck findings:
+- [Finding title]: [brief description]
+- [Finding title]: [brief description]
+
+These issues may require manual intervention or a different approach.
+```
+
+**Cap exit:**
+```
+Review-fix loop hit iteration cap ({cap}) with {count} findings remaining.
+[Per-pass summary as above]
+
+Remaining findings:
+[List findings from the last pass]
+```
+
+## Key Conventions
+
+- **Serial, not parallel.** One reviewer, one fixer per iteration. Simplicity over throughput.
+- **Direct on branch.** No worktrees. Each iteration commits directly. Commits are revert points.
+- **Fully autonomous.** No user gate between iterations. Runs until a stopping condition.
+- **Fixer gets full findings each pass.** Not deltas. The fixer doesn't know what previous passes did.
+- **One commit per pass.** Keeps history clean and gives one revert point per iteration.
+- **Pre-commit validation is the fixer's job.** If validation fails, the fixer does NOT commit.
+- **No co-authored-by lines.** Encode this in every fixer prompt.
+
+## Stopping Conditions
+
+| Condition | Action |
+|-----------|--------|
+| Reviewer returns `NO_FINDINGS` | Break — report clean |
+| Finding titles identical to previous pass | Break — report plateau with stuck findings |
+| Iteration counter reaches cap | Break — report cap hit with remaining findings |
+| Fixer reports validation failure | Break — report failure with fixer output |
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Reviewer uses different titles for same issue across passes | Prompt reviewer to use stable titles based on the problem |
+| Fixer modifies unrelated code | Prompt explicitly: only fix what's in the findings |
+| Skipping plateau detection | Always compare finding titles between consecutive passes |
+| Continuing after validation failure | Stop immediately — broken builds cascade |
+| Not reading project CLAUDE.md first | Pre-commit commands vary per project |
+| Running in parallel with other work | This skill commits directly on the branch — no concurrent modifications |