feat(plugin): improve worktree reliability with hybrid hook + skill approach

Enhance SubagentStart hook with "Subagent Discipline" section — universal
rules for commit-before-return, stay-in-scope, and prefer-absolute-paths
that fire for every subagent automatically.

Add "Worktree Dispatch" section to output styles with pre-dispatch and
post-return checklists, review agent worktree template, and squash-merge
ordering guidance.

Tighten implement skill: replace prose scoping rules with hook reference,
add review-in-worktree copy-paste template, add test baseline management
section for parallel dispatch contamination prevention.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jpicklyk

.claude/skills/implement/SKILL.md

@@ -187,6 +187,18 @@ actual changes. Include in the review agent prompt:
 - Instruction: "Run all commands and read all files from within the worktree at
   `<worktree-path>`. Do NOT read files from the main working directory."
 
+**Review agent worktree template (copy verbatim, fill placeholders):**
+
+```
+You are reviewing implementation work in an isolated worktree.
+- Worktree path: <WORKTREE_PATH>
+- Branch: <BRANCH_NAME>
+- Changed files: <OUTPUT OF git -C <WORKTREE_PATH> diff main --name-only>
+
+Run ALL commands from within the worktree at <WORKTREE_PATH>.
+Read ALL files from that directory. Do NOT read from the main working directory.
+```
+
 **If NOT using worktree isolation**, the review agent reads from the current
 working branch as normal.
 
@@ -370,12 +382,16 @@ Agent(
 )
 ```
 
-**Scoping rules — include in every worktree subagent prompt:**
-- "Only modify files directly related to your task"
-- "Do not bump versions, modify shared config, or edit files outside your scope"
-- "Commit your changes before returning"
-- Cross-cutting changes (version bumps, shared config) are handled by the
-  orchestrator after all agents return
+**Scoping rules:** The `subagent-start` hook automatically injects commit, scope,
+and cd-discipline rules into every subagent. You do NOT need to include these in
+delegation prompts. Focus prompts on task-specific context:
+- Item UUID and what to implement
+- Which files to modify (explicit list when possible)
+- Test expectations
+- Return format
+
+Cross-cutting changes (version bumps, shared config) are handled by the
+orchestrator after all agents return.
 
 ### Worktree lifecycle
 
@@ -417,6 +433,20 @@ When multiple agents return from parallel worktrees:
 5. Run the full test suite after all merges to catch integration issues
 6. Delete worktree branches after successful squash-merge
 
+### Test baseline management
+
+When dispatching parallel worktree agents, check if any task modifies shared
+code (domain models, enums, database schema, test infrastructure). If so:
+
+1. Dispatch the shared-code task **first** (not in parallel)
+2. After it returns, run `./gradlew :current:test` on main to establish a clean baseline
+3. **Then** dispatch the remaining independent tasks in parallel
+
+**Symptom of contamination:** Multiple agents report "N pre-existing test
+failures unrelated to our changes" on the same tests. That's contamination
+from a parallel task, not pre-existing failures. Always verify agent test
+reports with a direct test run after all agents complete.
+
 ---
 
 ## Resuming In-Progress Work

claude-plugins/task-orchestrator/hooks/subagent-start.mjs

@@ -26,7 +26,13 @@ const output = {
 
 6. **Return results.** Report: (1) files changed with line counts, (2) test results summary, (3) any blockers. Do not echo back the task description.
 
-**CRITICAL:** Do NOT call \`advance_item(trigger="start")\` a second time — that would skip your phase. Do NOT call \`advance_item(trigger="complete")\` — the orchestrator handles terminal transitions.`
+**CRITICAL:** Do NOT call \`advance_item(trigger="start")\` a second time — that would skip your phase. Do NOT call \`advance_item(trigger="complete")\` — the orchestrator handles terminal transitions.
+
+## Subagent Discipline
+
+1. **Commit before returning.** After making all file changes, stage and commit with a descriptive message. The orchestrator needs committed changes to squash-merge your branch.
+2. **Stay in scope.** Only modify files directly related to your assigned task. Do NOT bump versions, modify shared config, edit CI files, or touch files outside your scope. Cross-cutting changes are handled by the orchestrator after all agents return.
+3. **Use absolute paths or \`git -C\` where possible.** If you are working in an isolated worktree, you may need to \`cd\` into the worktree path — that is fine. But avoid unnecessary \`cd <project-root> &&\` prefixes when your working directory is already correct.`
   }
 };
 process.stdout.write(JSON.stringify(output));

claude-plugins/task-orchestrator/output-styles/workflow-orchestrator.md

@@ -71,6 +71,31 @@ After dispatching a subagent and receiving its return, optionally record delegat
 
 This is orchestrator-side data that agents cannot self-report. The `/session-retrospective` skill uses it for delegation alignment analysis when present.
 
+## Worktree Dispatch
+
+When dispatching agents with `isolation: "worktree"`:
+
+**Pre-dispatch checklist:**
+- Verify tasks are independent — no dependency edges between items dispatched in parallel
+- If any task changes shared domain models, enums, or test infrastructure, dispatch it **first** and run `./gradlew test` after it returns before dispatching the parallel wave (prevents test baseline contamination)
+- Focus prompts on task-specific context (item UUID, files to modify, test expectations) — the `subagent-start` hook injects commit, scope, and cd-discipline rules automatically
+
+**Post-return checklist — for each worktree agent:**
+1. Capture **worktree path** and **branch name** from Agent return metadata
+2. Record in tracking table: `| Item UUID | Worktree Path | Branch | Status |`
+3. Spot-check diff: `git -C <worktree-path> diff main --stat`
+
+**Review agent worktree template — include ALL of the following:**
+- Worktree path: `<path from implementation agent return>`
+- Branch name: `<branch from implementation agent return>`
+- Changed files: output of `git -C <path> diff main --name-only`
+- Instruction: "Run all commands and read all files from within the worktree at `<path>`. Do NOT read files from the main working directory."
+
+**Post-review — squash-merge each worktree sequentially:**
+1. `git merge --squash <worktree-branch>` into local `main`
+2. Run full test suite after each merge to catch integration issues
+3. Delete worktree branch after successful merge
+
 ## Retrospective Nudge
 
 When items reach terminal after an implementation run — whether via `advance_item`, `complete_tree`, or auto-cascade — suggest running `/session-retrospective` to capture learnings.