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

* feat: add ktlint linting with Gradle integration, .editorconfig, and CI enforcement

Add ktlint (v12.1.2, engine v1.5.0) via jlleitschuh/ktlint-gradle plugin for
automated Kotlin code style enforcement. Includes .editorconfig with wildcard
import allowlist, disabled trailing comma rules, and 140-char line limit.
CI workflow gets a ktlintCheck step before tests. Applied ktlint formatting
across ~108 source files (mechanical whitespace/blank line changes only).

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

* fix: use HEX() for short UUID prefix lookup in SQLite

CAST(blob AS VARCHAR) produces raw bytes in SQLite, not a formatted UUID
string, causing prefix lookups to always return empty results. Switch to
LOWER(HEX(id)) for SQLite and LOWER(RAWTOHEX(id)) for H2, which both
produce dashless lowercase hex strings suitable for LIKE prefix matching.

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

* fix: ktlint formatting for multiline expression in findByIdPrefix

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

* 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>

---------

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.