feat(skills): add worktree-agent skill with router and template integration (ADR-126)

pipelines/INDEX.json

@@ -1,6 +1,6 @@
 {
   "version": "2.0",
-  "generated": "2026-03-28T04:29:43Z",
+  "generated": "2026-03-28T04:44:21Z",
   "generated_by": "scripts/generate-skill-index.py",
   "pipelines": {
     "agent-upgrade": {

pipelines/toolkit-improvement/references/adr-template.md

@@ -151,6 +151,11 @@ worktree branches afterward.
 3. All agents commit to that branch (or their worktree branch merges to it)
 4. Orchestrator verifies convergence after all agents complete
 
+**Worktree agent rules** (from ADR-126): When dispatching worktree agents, include the
+`worktree-agent` skill rules in each prompt. See `skills/worktree-agent/SKILL.md`. Key
+rules: verify CWD contains `.claude/worktrees/`, create branch before edits, ignore
+auto-plan hooks, stage specific files only, never touch the main worktree.
+
 ## Router Integration Checklist
 
 _Required for any ADR that creates or modifies a skill, pipeline, or agent._

skills/INDEX.json

@@ -1,6 +1,6 @@
 {
   "version": "2.0",
-  "generated": "2026-03-28T04:29:42Z",
+  "generated": "2026-03-28T04:44:21Z",
   "generated_by": "scripts/generate-skill-index.py",
   "skills": {
     "adr-consultation": {
@@ -2190,6 +2190,17 @@
       "user_invocable": true,
       "version": "2.0.0"
     },
+    "worktree-agent": {
+      "file": "skills/worktree-agent/SKILL.md",
+      "description": "Mandatory rules for agents running in git worktree isolation to prevent leaks, branch confusion, and cross-contamination",
+      "triggers": [
+        "worktree-agent",
+        "worktree",
+        "agent"
+      ],
+      "user_invocable": false,
+      "version": "1.0.0"
+    },
     "x-api": {
       "file": "skills/x-api/SKILL.md",
       "description": "Post tweets, build threads, upload media, and read timelines via the X API.",

skills/do/SKILL.md

@@ -195,6 +195,8 @@ Route to agents that create branches; never allow direct main/master commits, be
 
 When dispatching agents for file modifications, explicitly include "commit your changes on the branch" in the agent prompt, because otherwise the agent completes file edits but changes sit unstaged — the orchestrator assumes committed work and moves on, and changes are lost.
 
+When dispatching agents with `isolation: "worktree"`, inject the `worktree-agent` skill rules into the agent prompt. The skill at `skills/worktree-agent/SKILL.md` contains mandatory rules that prevent worktree isolation failures (leaked changes, branch confusion, auto-plan hook interference). At minimum include: "Verify your CWD contains .claude/worktrees/. Create feature branch before edits. Do NOT create task_plan.md. Stage specific files only."
+
 For repos without organization-gated workflows, run up to 3 iterations of `/pr-review` → fix before creating a PR, because post-merge fixes cost 2 PRs instead of 1. For repos under protected organizations (via `scripts/classify-repo.py`), require user confirmation before EACH git action — never auto-execute or auto-merge, because organization-gated repos have compliance requirements that automation must not bypass.
 
 **Step 3: Handle multi-part requests**

skills/worktree-agent/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: worktree-agent
+description: Mandatory rules for agents running in git worktree isolation to prevent leaks, branch confusion, and cross-contamination
+version: 1.0.0
+user-invocable: false
+context: fork
+tags: [worktree, isolation, parallel, agent]
+---
+
+# Worktree Agent Rules
+
+Mandatory rules for any agent dispatched with `isolation: "worktree"`.
+
+## Rule 1: Verify Your Working Directory
+
+On start, run `pwd`. Your path MUST contain `.claude/worktrees/`.
+If your CWD is the main repo path, **STOP** and report the error.
+
+## Rule 2: Create Feature Branch First
+
+```bash
+git checkout -b <branch-name>
+```
+
+Never commit on the default `worktree-agent-*` branch. Create your feature branch FIRST.
+
+## Rule 3: Use Worktree-Relative Paths
+
+Never hardcode absolute paths from the main repo. Use `$(git rev-parse --show-toplevel)/path`.
+**Exception**: Reading gitignored ADR files requires the main repo absolute path.
+
+## Rule 4: Ignore Auto-Plan Hooks
+
+Do NOT create or modify `task_plan.md`. If auto-plan hook fires, ignore it.
+Focus exclusively on your implementation tasks.
+
+## Rule 5: Stage Specific Files Only
+
+```bash
+git add path/to/specific/file.py
+```
+
+Never `git add .`, `git add -A`, or `git add --all`. Verify with `git diff --cached --stat`.
+
+## Rule 6: Do Not Touch the Main Worktree
+
+Never write to paths outside your worktree directory. Never run `git checkout` in the main repo.
+
+## Rule 7: Commit with Conventional Format
+
+Use the commit message specified in your prompt. No attribution lines.
+
+## Failure Modes This Prevents
+
+| Failure | Rule | Without It |
+|---------|------|-----------|
+| Agent edits main repo files | 1, 6 | Changes leak to main, get stashed/lost |
+| Context wasted on task_plan.md | 4 | Implementation budget consumed by planning |
+| Commit on wrong branch | 2 | Orchestrator merges wrong content |
+| PR has changes from 2 ADRs | 5, 6 | Cross-contamination between agents |
+| Branch locked by worktree | 2 | Fatal error on checkout |