Correct the two Claude Code hooks to the worktree flow (closes #3724)

.claude/hooks/check-feature-branch.ts

@@ -1,13 +1,15 @@
 #!/usr/bin/env bun
 /**
- * PreToolUse hook: warns when editing files on the main branch.
+ * PreToolUse hook: reminds the agent of the startup sequence when it edits
+ * files on the `main` branch.
  *
- * The startup sequence requires creating a feature branch before modifying
- * any files. Being on `main` is a reliable signal that the sequence was skipped.
+ * Issue work happens in an isolated worktree, whose branch is never `main`, so
+ * the hook is silent there. On `main` it prints the sequence, because being on
+ * `main` often means the sequence was skipped. Not every edit on `main` is issue
+ * work, so the reminder does not tell the agent to stop.
  *
- * Exits 0 in all cases (never blocks), but prints a warning to stderr when on
- * `main` so Claude Code surfaces it as a message to the agent — prompting
- * self-correction without hard-blocking legitimate operations.
+ * Exits 0 in all cases (never blocks). The reminder goes to stderr so Claude
+ * Code surfaces it as a message to the agent.
  */
 
 import { execSync } from 'child_process';
@@ -25,19 +27,22 @@ const branch = getCurrentBranch();
 
 if (branch === 'main') {
   process.stderr.write(`
-⚠️  WARNING: You are on the \`main\` branch.
-
-Have you completed the startup sequence before editing files?
-
-  1. git fetch origin && git pull origin main
-  2. bun install
-  3. bun run test  (record baseline)
-  4. bun run gh:comment <N> "Frontend: X passed"
-  5. git checkout -b feature/issue-<N>-description
-  6. bun run gh:assign <N> "@me"
-  7. bun run gh:status <N> "In Progress"
-
-If not, STOP and complete the sequence first, then create a feature branch.
+⚠️  REMINDER: You are editing on the \`main\` branch of the primary checkout.
+
+Work on an issue belongs in an isolated worktree. If this edit is issue work,
+complete the startup sequence first, then make the edit inside the worktree.
+If it is not issue work, ignore this reminder.
+
+  1. git status  (commit any pending changes)
+  2. git fetch origin && git pull origin main
+  3. EnterWorktree({name: "issue-<N>-brief-desc"})
+  4. bun install
+  5. bun run test  (record baseline)
+  6. bun run gh:comment <N> "Frontend: X passed"
+  7. bun run gh:assign <N> "@me"
+  8. bun run gh:status <N> "In Progress"
+
+Detail: AGENTS.md, "Mandatory Startup Sequence".
 `);
 }
 

.claude/hooks/remind-plan-startup-sequence.ts

@@ -1,33 +1,45 @@
 #!/usr/bin/env bun
 /**
- * PreToolUse hook: reminds the agent to embed the startup sequence in any plan.
+ * PreToolUse hook: reminds the agent to embed the startup sequence and the
+ * final steps in any plan.
  *
  * Fires before EnterPlanMode. Prints a reminder to stderr so Claude Code
  * surfaces it as a message — ensuring the agent includes the startup sequence
- * as Step 0 in the plan it is about to write.
+ * as Step 0 and the final steps at the end of the plan it is about to write.
  *
  * Exits 0 always (non-blocking).
  */
 
 process.stderr.write(`
-⚠️  PLAN MODE REMINDER: Your plan MUST include the startup sequence as Step 0.
+⚠️  PLAN MODE REMINDER: Your plan MUST include the startup sequence as Step 0
+and the final steps at its end.
 
 Because context clears between planning and implementation, the implementing
-agent will ONLY see the plan — not CLAUDE.md or this conversation.
+agent will ONLY see the plan, not this conversation.
 
 Include this as Step 0 in your plan:
   Step 0: Complete startup sequence
-    - git status (commit any pending changes)
+    - git status (commit any pending changes), on the primary checkout
     - git fetch origin && git pull origin main
+    - EnterWorktree({name: "issue-<N>-brief-desc"})  (the tool owns the location and branch name)
     - bun install
     - bun run test  →  record baseline
     - bun run gh:comment <N> "Frontend: X passed"
-    - git checkout -b feature/issue-<N>-description
     - bun run gh:assign <N> "@me"
     - bun run gh:status <N> "In Progress"
 
 Also include at the end of the plan:
-  Final steps: bun run test:all (no new failures), bun run quality:fix, bun run gh:pr <N>
+  Final steps:
+    - bun run test:changed
+    - bun run quality:fix, then commit
+    - git push origin HEAD:issue-<N>-brief-desc  (lint only)
+    - gh pr create --head issue-<N>-brief-desc
+    - after the user approves the merge: bun run merge <PR#>,
+      then ExitWorktree({action: "remove", discard_changes: true})
+
+Inline the standards the implementing agent needs as well.
+
+Detail: AGENTS.md, "Plan Mode" and "Mandatory Startup Sequence".
 `);
 
 process.exit(0);