# Resource Evaluation: Hook-Driven Dev Workflows with Claude Code **Date**: 2026-03-16 **Evaluator**: Claude Sonnet 4.6 **Resource URL**: https://nick-tune.me/blog/2026-02-28-hook-driven-dev-workflows-with-claude-code/ **Resource Type**: Technical blog post **Author**: Nick Tune **Published**: 2026-02-28 --- ## Executive Summary Nick Tune (already cited 4 times in the guide for his earlier Medium article) presents a new pattern that treats Claude Code hooks as a **workflow enforcement engine** with a typed state machine, JSON persistence, and per-state context injection. The guide covers individual hook types in isolation and has a bash-based single-entry dispatcher (§7.5). This article adds a TypeScript state machine layer on top of hooks that the guide does not cover. The most immediately useful standalone pattern — identity re-injection after compaction — can be integrated now without the full state machine. **Recommendation**: **MODERATE (Score 3/5)** — Integrate the identity re-injection pattern immediately in §7.5. Stage the full state machine architecture as a Tier 3 workflow guide with explicit prerequisites. Re-evaluate the full integration at 4/5 in 60-90 days once community validation exists. --- ## Scoring Summary | Criterion | Score | Weight | Weighted Score | |-----------|-------|--------|----------------| | **Accuracy & Reliability** | 4 | 20% | 0.80 | | **Depth & Comprehensiveness** | 5 | 20% | 1.00 | | **Practical Value** | 4 | 25% | 1.00 | | **Originality & Uniqueness** | 3 | 15% | 0.45 | | **Production Readiness** | 2 | 10% | 0.20 | | **Community Validation** | 2 | 10% | 0.20 | | **TOTAL SCORE** | | | **3.65 → 3/5** | --- ## Content Summary The article introduces a hook-driven workflow pattern built on five core ideas: - **Hooks as state machine**: SubagentStart, SubagentStop, PreToolUse, and TeammateIdle hooks feed into a TypeScript workflow engine managing state transitions (SPAWN → PLANNING → RESPAWN → DEVELOPING → REVIEWING → COMMITTING → CR_REVIEW → PR_CREATION → FEEDBACK → COMPLETE) - **Single-entrypoint dispatch**: One hook handler for all events via a `HOOK_HANDLERS` map dispatching by `hook_event_name` — similar concept to guide §7.5 bash dispatcher, but TypeScript + stateful - **State-specific context injection**: SubagentStart reads `/states/.md` files and injects them into agent context — agents only see instructions relevant to the current state, avoiding bloated system prompts - **Respawn pattern**: After each iteration, developer and reviewer agents shut down and fresh instances spawn, giving each iteration a clean context window - **Identity re-injection after compaction**: Hooks detect when an agent has forgotten its identity prefix (after compaction) and re-inject identity instructions — the most standalone, transferable pattern in the article --- ## Gap Analysis vs. Claude Code Ultimate Guide | Pattern | This Article | Guide Coverage | |---------|-------------|----------------| | Single-entrypoint hook dispatch | ✅ TypeScript, stateful | ⚠️ §7.5 covers bash dispatcher concept | | State machine with typed transitions (Zod) | ✅ Full implementation | ❌ Not covered | | SubagentStart for context injection | ✅ State-specific file injection | ⚠️ Table mention only ("Subagent initialization") | | PreToolUse as per-state operation blocker | ✅ Blocks git commit during DEVELOPING | ⚠️ Covered as security pattern, not workflow state control | | Agent respawn for context window management | ✅ Explicit per-iteration respawn | ❌ Not covered | | Workflow state persistence (JSON + session ID) | ✅ Full example | ❌ Not covered | | Identity re-injection after compaction | ✅ Hook detects missing prefix, re-injects | ❌ Not covered | | Agent teams + hooks combined | ✅ Concrete end-to-end | ⚠️ Separate docs, not combined | **Note on originality**: The guide already references Nick Tune's earlier Medium article ("Coding Agent Development Workflows") 4 times at lines 4962, 8978, 13799, 15091, and 22527. This is a different, newer article. The single-entrypoint dispatch concept also exists in §7.5 as a bash pattern. The actual delta is: TypeScript state machine, per-state SubagentStart injection, respawn, JSON persistence, and identity re-injection. --- ## Detailed Analysis ### Accuracy & Reliability (4/5) Technical claims check out against Claude Code's documented hook behavior: - SubagentStart, SubagentStop, PreToolUse, TeammateIdle hooks are real and documented - `hook_event_name` field in hook input matches guide §7.4 docs - `exitCode: EXIT_ALLOW` / `EXIT_BLOCK` pattern is valid - Zod for schema validation is standard TypeScript practice - JSON file persistence keyed to session ID is a practical, correct approach One significant caveat: the author explicitly states "1 week of experimentation, cannot 100% recommend yet." That honest disclaimer is not a minor qualifier — it means this is unvalidated at any meaningful scale. ### Depth & Comprehensiveness (5/5) Full TypeScript code for the dispatcher, a worked `/states/developing.md` example, JSON persistence schema with real fields, Zod transition map, DDD framing. GitHub repo with complete code exists. This is the article's strongest dimension — not vaporware, genuinely implementable. ### Practical Value (4/5) The core problem is real: getting consistent workflows in codebases you don't fully control. The identity re-injection pattern alone is worth the read. The full state machine is more complex but still implementable. Barrier: the approach requires Node.js + TypeScript runtime (`npx tsx`). The guide's hooks section is bash-first by design. Any integration needs to address this friction explicitly. ### Originality & Uniqueness (3/5) The single-entrypoint dispatcher already exists in §7.5 as bash. The agent teams feature is already documented. What's genuinely novel: (1) attaching a typed state machine to hooks, (2) per-state SubagentStart context injection from files, (3) respawn for context window hygiene, (4) identity re-injection after compaction. Strong delta on 4 specific patterns, not on the overall approach. ### Production Readiness (2/5) 1 week of testing. Author's own words: "cannot fully recommend." Known wiring complexity ("ugly and fragile at times"). The hook JSON config requires repeating the same entry for each event type — acknowledged as a UX problem. This needs months of community validation before being presented as a recommended pattern. ### Community Validation (2/5) Nick Tune is a credible practitioner (established author, DDD community). No adoption metrics for this specific article. The GitHub repo exists but engagement data is not available from the article. --- ## Prerequisites (Not Mentioned in Evaluation v1) Any integration must flag these hard dependencies: 1. **Agent teams experimental flag**: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` — SubagentStart, SubagentStop, TeammateIdle are agent teams events. Without this flag, most of the patterns in the article are unavailable. 2. **Opus 4.6 required**: Agent teams require Opus 4.6+, which costs significantly more than Sonnet. 3. **Node.js + TypeScript toolchain**: `npx tsx` must be available in the project. Not a default Claude Code assumption. --- ## Recommended Integration ### Tier 1 — Integrate Now (Standalone Pattern) **Identity re-injection after compaction** → `guide/ultimate-guide.md` §7.5 (Hook Examples) This pattern is immediately useful to anyone using hooks with long sessions — no agent teams flag, no TypeScript required. Compaction-driven identity drift is a known pain point. The hook-based detection + re-injection workaround belongs in §7.5 regardless of the rest of the article. ``` ### Handling Identity Drift After Compaction When Claude's context compacts, agents in long sessions can "forget" their role. A hook can detect this and re-inject identity instructions. ``` ### Tier 2 — Integrate with Prerequisites Gate (3-4 weeks) **Per-state SubagentStart context injection** → Add to agent-teams.md as an advanced pattern section. Prerequisite: agent teams flag. Key insight: inject state-specific files at runtime rather than bundling everything in the system prompt — reduces system prompt bloat and keeps agents focused. ### Tier 3 — New Workflow Guide (60-90 days, pending community validation) **`guide/workflows/hook-driven-workflows.md`** — Full state machine architecture, once the pattern has more community validation. Clear prerequisites header (agent teams flag, Opus 4.6, Node.js + TypeScript). Frame as experimental / advanced. ### What NOT to Document The specific CodeRabbit + GitHub issue + 10-state workflow is too opinionated. Document the architectural patterns; readers define their own states. --- ## Challenge Findings (Technical Review) The challenge agent identified several issues with the initial v1 evaluation: **Score correction**: The initial 4/5 score ("integrate within 1 week") was too aggressive for something the author hasn't validated beyond 1 week. Correct score is 3/5 now, with a scheduled re-evaluation in 60-90 days. **Originality was overstated**: The single-entrypoint dispatcher already exists in §7.5 as bash. The guide already references this author's earlier work 4 times. The real delta is narrower: state machine, per-state injection, respawn, identity re-injection. **Missing prerequisites**: Agent teams flag, Opus 4.6, Node.js + TypeScript — none of these were in v1. Any integration without flagging these prerequisites would frustrate readers. **Identity re-injection is the most urgent pattern**: Standalone, no experimental flag required, directly solves a documented pain point (compaction-driven drift). The v1 evaluation mentioned it but didn't prioritize it as the immediate integration target. **Integration recommendation was vague**: "Integrate in hooks section + new workflow guide" without defining what goes where. The tiered approach (Tier 1 now / Tier 2 in 3-4 weeks / Tier 3 in 60-90 days) is more actionable. --- ## Fact-Check | Claim | Verified | Notes | |-------|----------|-------| | SubagentStart hook exists | ✅ | Confirmed in guide + official docs | | SubagentStop hook exists | ✅ | Confirmed | | PreToolUse hook exists | ✅ | Confirmed | | TeammateIdle hook exists | ✅ | Confirmed in guide hooks table | | `hook_event_name` field in hook input | ✅ | Documented in guide §7.4 | | Guide §7.5 already has single-entry dispatcher | ✅ | Bash version at line 9655 | | Guide cites Nick Tune's earlier article 4 times | ✅ | Lines 4962, 8978, 13799, 15091 (different URL) | | CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 required | ✅ | Confirmed in agent-teams.md | | Author: Nick Tune, published 2026-02-28 | ✅ | Byline + URL path + © 2026 | | GitHub repo with full code exists | ⚠️ | Article states it; not independently verified | | "1 week of experimentation" | ✅ | Direct quote from article | No invented statistics or unverified benchmarks. The author makes no quantitative performance claims — appropriate hedging throughout. --- ## Decision - **Final Score**: 3/5 — Moderate - **Action**: Partial integration (tiered) - **Immediate**: Identity re-injection pattern → §7.5 - **Short-term**: Per-state SubagentStart injection → agent-teams.md - **Deferred**: Full state machine workflow guide — re-evaluate 2026-05-16 - **Confidence**: High (patterns are technically sound, gap analysis is verified, framing is calibrated)