Forem: Tom Howard

Stop your AI agent from ignoring your architecture

Tom Howard — Fri, 20 Mar 2026 12:38:44 +0000

An AI agent makes architectural decisions constantly. Add a dependency, change a build script, restructure a config file. Each choice is reasonable in isolation. None of them get written down.

This is the knowledge management version of technical debt. Six months later, someone asks why the project uses rehype-highlight instead of Shiki. The answer is in a conversation that no longer exists. The decision was sound. The reasoning is gone.

A hook-based gate can close this gap. This implementation uses Claude Code hooks (source code), but the pattern (detect, gate, review, unlock, reset) applies to any agent system that exposes lifecycle events.

Claude Code hooks are shell scripts that run at specific points in the agent's lifecycle. UserPromptSubmit fires when the user sends a message. PreToolUse fires before the agent calls a tool (Edit, Write, Bash). PostToolUse fires after a tool call completes. Stop fires when the agent finishes its turn. Each hook receives JSON on stdin describing the event, and can inject context, allow the action, or deny it.

The gate intercepts edits to project files and requires an architecture review before the edit proceeds. The reviewer checks proposed changes against existing decision records in docs/decisions/ and flags when a new decision should be documented.

The problem

Architecture Decision Records solve a known problem: decisions made verbally or in chat disappear. The MADR format (Markdown Any Decision Records) gives them structure. Context, options considered, rationale, consequences, reassessment criteria.

The format is not the hard part. The hard part is remembering to write them. An AI agent adding a dependency to package.json will not stop to ask itself whether this choice deserves a decision record. It will install the package and move on.

The same problem exists with compliance. If decision 001 says "use rehype-highlight for syntax highlighting," nothing stops the agent from adding @shikijs/rehype to package.json in a later session. The decision exists. The agent doesn't check it.

Five hooks, one gate

Five hooks enforce the gate. Four follow a cycle: detect that the project has an architect agent, block edits until the architect reviews them, unlock the block when the review passes, reset the block when the turn ends. A fifth hook blocks exiting plan mode without a review. This is a variation of the pattern used for voice and tone enforcement, with additional hardening.

Role	Hook event	Script	Purpose
Detect	`UserPromptSubmit`	`architect-detect.sh`	Inject review instructions on every prompt
Gate	`PreToolUse` (Edit\	Write)	`architect-enforce-edit.sh`
Plan gate	`PreToolUse` (ExitPlanMode)	`architect-plan-enforce.sh`	Block plan exit without review
Unlock	`PostToolUse` (Agent)	`architect-mark-reviewed.sh`	Create marker when architect passes
Reset	`Stop`	`architect-reset-marker.sh`	Remove marker so next turn starts locked

The gate

The code samples below are excerpts. The complete hook scripts are each under 40 lines. Common functions (portable mtime, hash computation, marker validation) are extracted into lib/architect-gate.sh, which the other scripts source.

The gate is fail-closed. It parses the hook input with jq, and if parsing fails, the edit is blocked. From architect-enforce-edit.sh:

INPUT=$(cat)

FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty') || true
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true

if [ -z "$SESSION_ID" ]; then
  # Fail-closed: block on parse failure
  cat <<'EOF'
{ "hookSpecificOutput": { "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "BLOCKED: Could not parse hook input." } }
EOF
  exit 0
fi

If the file is not excluded (CSS, images, lockfiles, fonts, memory files) and no valid session marker exists, the edit is denied. The same check runs on ExitPlanMode, sharing the marker.

The unlock

The unlock only fires after the architect agent returns. It reads a verdict file that the architect writes during its review. From architect-mark-reviewed.sh:

VERDICT_FILE="/tmp/architect-verdict"
VERDICT=""
if [ -f "$VERDICT_FILE" ]; then
  VERDICT=$(cat "$VERDICT_FILE")
  rm -f "$VERDICT_FILE"
fi

case "$VERDICT" in
  PASS)
    touch "/tmp/architect-reviewed-${SESSION_ID}" ;;
  FAIL)
    ;; # Do NOT create marker
  *)
    # No verdict file: allow to prevent permanent lockout
    touch "/tmp/architect-reviewed-${SESSION_ID}" ;;
esac

If the verdict is FAIL, no marker is created and edits stay blocked until the issues are resolved and the architect is re-run. The missing-verdict fallback defaults to PASS to prevent permanent lockout if the agent errors out.

Marker validity

A marker file in /tmp is not enough. Three checks run before the gate allows an edit through.

TTL. The marker has a configurable time-to-live, defaulting to 600 seconds. If the marker is older than this, it is removed and the gate blocks. The TTL is configurable via the ARCHITECT_TTL environment variable. From lib/architect-gate.sh:

TTL_SECONDS="${ARCHITECT_TTL:-600}"
NOW=$(date +%s)
MARKER_TIME=$(_mtime "$MARKER")
AGE=$(( NOW - MARKER_TIME ))
if [ "$AGE" -lt "$TTL_SECONDS" ]; then
  # Still valid, proceed to drift check
fi

Sliding window. Each successful gate pass refreshes the marker timestamp. A long editing session is not interrupted as long as edits are less than 10 minutes apart. The TTL catches abandoned markers, not active work.

Drift detection. When the unlock hook creates a marker, it also stores a content hash of all files in docs/decisions/. From architect-mark-reviewed.sh:

HASH=$(find docs/decisions -name '*.md' -not -name 'README.md' \
  -print0 | sort -z | xargs -0 cat 2>/dev/null \
  | _hashcmd | cut -d' ' -f1)
echo "$HASH" > "/tmp/architect-reviewed-${SESSION_ID}.hash"

Before allowing an edit, the gate recomputes the hash and compares it to the stored value. If a decision file changed since the review, the marker is invalidated and a re-review is required.

The reviewer

The architect agent is defined in .claude/agents/architect.md. It has read-only access (Read, Glob, Grep) plus Bash for writing the verdict file. It cannot edit project files.

It checks five things, in order of importance. The first three affect the PASS/FAIL verdict. The last two are advisory.

Existing decision compliance. For each decision in docs/decisions/, does the proposed change conflict with the decision's outcome? Does it violate documented constraints or consequences?

Confirmation criteria. Many decisions include a Confirmation section describing how to verify compliance (e.g. "Client JS does not contain hardcoded API URLs beyond the entry point"). The agent checks proposed code against these criteria and flags violations as [Confirmation Violation].

New decision detection. Does the change represent an undocumented architectural choice? The agent is told to be pragmatic. A version bump to an existing dependency is reversible and local: no flag. Adding a new ORM, switching from REST to GraphQL, or introducing a new CI workflow affects how the team works and how code flows to production: flag it.

Decision quality. When a change includes a new decision file, does it follow MADR 4.0 format? Required frontmatter, at least two considered options, reassessment criteria.

Decision staleness (advisory). If an accepted decision is older than 6 months, the agent flags [Stale Decision]. If a reassessment-date has passed, [Reassessment Overdue]. These do not affect the PASS/FAIL verdict.

A typical review:

Architecture Review: PASS
No conflicts with existing decisions. No new architectural decision required.

Or:

Architecture Review: ISSUES FOUND

[Undocumented Decision] - File: package.json

Issue: Adding @shikijs/rehype as a dependency. Decision 001 chose rehype-highlight over Shiki.

Existing Decision: 001-use-rehype-highlight-for-syntax-highlighting

Action: This conflicts with an accepted decision. Either update the decision or remove the dependency.

What gets gated

The gate excludes files by extension. From architect-enforce-edit.sh:

case "$FILE_PATH" in
  *.css|*.scss|*.sass|*.less)             exit 0 ;;  # Styles
  *.png|*.jpg|*.jpeg|*.gif|*.svg|*.ico)   exit 0 ;;  # Images
  *.woff|*.woff2|*.ttf|*.eot)             exit 0 ;;  # Fonts
  *package-lock.json|*yarn.lock)          exit 0 ;;  # Lockfiles
  *.map)                                  exit 0 ;;  # Sourcemaps
  *.changeset/*.md)                       exit 0 ;;  # Changesets
  */MEMORY.md|*/.claude/projects/*)       exit 0 ;;  # Memory files
  */.claude/plans/*.md)                   exit 0 ;;  # Plan files
esac

Everything else goes through the gate. Adjust the list for your project: if you want to gate only infrastructure files, narrow the exclusions. The architect agent is told to be pragmatic: a refactored function or a bug fix gets a quick PASS. A new API endpoint that skips an established pattern gets flagged.

Decisions as living documents

Decisions follow a lifecycle. They start as proposed, move to accepted after production validation, and eventually get deprecated or superseded. The status lives in the filename: 001-use-rehype-highlight.proposed.md becomes 001-use-rehype-highlight.accepted.md after the site ships with rehype-highlight and nothing breaks.

In this project, that decision started as proposed when the agent flagged rehype-highlight as an undocumented dependency. The MADR record captured why Shiki was rejected (bundle size, build complexity) and when to revisit (if rehype-highlight drops maintained status). Three deploys later, the decision moved to accepted. Now when the agent sees a new syntax highlighting dependency in package.json, it has context: not just what was chosen, but why, and under what conditions to reconsider.

Without automation, promotion does not happen. Decisions stay proposed indefinitely because nothing triggers the rename after a successful deploy. A post-release hook closes this gap. It runs after each deploy as a drop-in script in scripts/post-release.d/, receiving the list of changed files on stdin and the release date as an environment variable.

The hook works in two passes. From stamp-and-promote-decisions.sh:

# Pass 1: Stamp first-released on proposed decisions included in this release
for file in "$DECISIONS_DIR"/*.proposed.md; do
  if has_field "$file" "first-released"; then
    continue  # Already stamped
  fi
  if echo "$FILE_LIST" | grep -qF "$file"; then
    sed "s/^status: *\"*proposed\"*/status: \"proposed\"\nfirst-released: $RELEASE_DATE/" \
      "$file" > "$file.tmp" && mv "$file.tmp" "$file"
  fi
done

# Pass 2: Promote decisions past the 14-day threshold
for file in "$DECISIONS_DIR"/*.proposed.md; do
  FIRST_RELEASED=$(grep "^first-released:" "$file" | awk '{print $2}')
  AGE_DAYS=$(( (NOW_EPOCH - $(date_to_epoch "$FIRST_RELEASED")) / 86400 ))
  if [ "$AGE_DAYS" -ge "$PROMOTION_DAYS" ]; then
    sed "s/^status: *\"*proposed\"*/status: \"accepted\"/" "$file" > "$file.tmp" && mv "$file.tmp" "$file"
    git mv "$file" "$(echo "$file" | sed 's/\.proposed\.md$/.accepted.md/')"
  fi
done

Pass 1 stamps a first-released date on each proposed decision that shipped in the release. Pass 2 checks all stamped decisions and promotes any that have been in production longer than 14 days (configurable via DECISION_PROMOTION_DAYS). The promotion renames the file from .proposed.md to .accepted.md, updates the frontmatter status, and adds an accepted-date field. Any changes are committed and pushed as part of the release.

The 14-day grace period exists so that decisions can be reverted if they cause production issues. A decision that ships on Monday and breaks something on Wednesday can be rolled back before it gets promoted. The architect agent enforces compliance against both proposed and accepted decisions but ignores superseded ones. A rejected decision prevents re-proposing the same approach without new evidence.

Tradeoffs

The architect agent call adds 10-20 seconds per turn that touches project files. The sliding TTL means this cost is paid once per session, not once per edit, as long as edits are less than 10 minutes apart.

False negatives are more dangerous than false positives. The agent might miss a decision-worthy change because the pragmatism criteria were too generous, or because the change didn't match any detection patterns. There's no exhaustive list of what constitutes an architectural decision. The agent approximates.

The system now runs in two repos. A second project (bbstats) has 33 architecture decisions: 11 promoted from proposed to accepted via the release hook, 3 superseded, and 19 still proposed. The hooks and agent definition were copied to the second repo without changes. Every major feature in that project's changelog references an ADR. Decisions accumulate at the proposed stage and batch-promote when a release crosses the 14-day threshold.

Verdict gating

The verdict gating matters more than it looks. In an earlier version of this system (before the PASS/FAIL verdict file), the architect flagged issues but the gate unlocked regardless. The AI could proceed with edits while leaving the flagged issues unresolved.

A real example: the AI was removing an unused API endpoint. The architect flagged that a smoke test depended on it and recommended updating the smoke test to check something that validates the health of the system. Without verdict gating, the AI proceeded with the rest of the task, left the API in place, left the smoke test unchanged, and moved on. The architect caught the problem. The AI chose the path of least resistance: do nothing about it.

With verdict gating, the gate stays locked after ISSUES FOUND. The AI has two options: fix the smoke test and remove the API properly, or stop. No middle ground where you half-do the work and leave broken dependencies in place. The hook system cannot make the AI choose the right fix. But it can prevent the AI from ignoring the issue and continuing as if the review never happened.

The system has known edge cases. Marker files live in /tmp, which is world-writable and not shared across machines. Drift detection hashes file contents, not filenames, so renaming a decision file without changing its content won't trigger a re-review. Concurrent sessions share the verdict file, creating a small race window (the PostToolUse hook reads and deletes it immediately, so the window is the time between two architect agents finishing simultaneously).

The gate blocks the AI, not you. The hooks constrain the agent's workflow. You control the hooks, the agent definition, and the decisions. If the architect flags something you disagree with, adjust the decision or the agent's instructions. The system is yours to tune.

Adapting this for your project

Start with the agent file. Drop .claude/agents/architect.md into your repo. The embedded process works out of the box with an empty docs/decisions/ directory. The first time the agent flags an undocumented decision, create the directory and the first record.

Wire the five hooks (detection, gate, plan gate, unlock, reset) into .claude/settings.json. The full configuration, including matchers and hook scripts, is in the source repo.

Adjust the scope. The exclusion list matches this project's structure. If you want to gate only infrastructure files instead of everything, modify the case statement to match only the file types you care about. The pattern is the same.

Bootstrap your decisions. Once the hooks are wired, ask the AI to survey the codebase and document the existing architectural choices as decision records. The architect agent already knows the MADR 4.0 format and will create records for the technology choices, patterns, and conventions it finds. Review what it produces, fill in any context the agent missed (the "why" behind a choice is often not in the code), and add reassessment criteria. This gives you a populated docs/decisions/ directory in one session instead of building it incrementally over months.

Wire the release hook. Drop scripts/post-release.d/stamp-and-promote-decisions.sh into your repo and call it from your release script after deploy. It handles both normal runs (file list on stdin) and cold-start backfill (checks git history for first-release dates). The 14-day promotion threshold is configurable via DECISION_PROMOTION_DAYS.

The pattern works in any agent system that exposes lifecycle events. Cursor has Rules for AI that can inject context and constrain behavior. The key requirements are three: inject instructions before the agent acts, intercept file writes, and run a check after the agent finishes. The gate logic (marker files, TTL, drift detection) is plain shell and works anywhere.

The full configuration is in the public repo at github.com/windyroad/windyroad. The Claude Code hooks documentation covers the full event model.

The gate writes the decision down. The release hook tracks when it ships. Fourteen days later, the decision earns its place in the record. The reasoning that used to vanish in a chat thread now outlives the conversation that produced it.

Enforcing voice and tone with Claude Code hooks

Tom Howard — Mon, 09 Mar 2026 21:02:09 +0000

An AI agent writes fluent prose. It also writes whatever you ask for. Tell it to add a hero section and it will produce "We're passionate about leveraging cutting-edge solutions." Tell it to write an FAQ answer and it will open with "Great question!" Neither sounds like you.

Voice consistency is a constraint, and constraints need enforcement. This system blocks the AI from editing copy until a voice-and-tone reviewer has checked the proposed changes against a written guide.

The problem

A voice guide sitting in a markdown file is documentation. The AI reads it if you tell it to, ignores it if you don't, and drifts from it when generating long passages. A guide only describes the rules. Nothing enforces them.

The failure mode is subtle. The AI won't produce obviously wrong copy. It will produce copy that's slightly off: a hedging phrase here, an "actually" there, a sentence that positions you against a competitor instead of stating what you do. Each deviation is small. Over time, the site sounds like it was written by committee.

Here is what drift looks like in practice. An AI asked to write a CTA might produce:

We'd love to help you navigate the complexities of AI integration. Reach out today to learn how our team can support your journey.

The voice guide says: state what you do, let the reader decide. The reviewed version:

I review your AI coding setup and tell you what's working and what isn't. Book a call if that's useful.

The first version is fluent. It's also generic, hedging, and sounds like every other consulting site. The reviewer catches the pattern before it ships.

Four hooks, one gate

The pattern comes from accessibility-agents, which uses the same hook architecture to enforce WCAG compliance on web UI code. I adapted it for voice and tone: same gate mechanism, different reviewer, different scope, plus a reset hook that tightens the review cycle from per-session to per-turn.

Claude Code hooks are shell scripts that fire at defined points in the AI's workflow: before a prompt is processed, before a tool is called, after a tool completes, and when the AI finishes responding. They can inject context, block actions, or react to what just happened.

The system uses four Claude Code hooks that work together. One injects the instruction. One blocks the edit. One unlocks the block. One resets the lock so the next prompt starts clean.

Here is what a typical interaction looks like. The user asks for an edit. The gate blocks it. The AI delegates to the reviewer. The reviewer finds violations. The AI incorporates the fixes, and the edit goes through:

User: Add a CTA to the pricing page

Claude: [attempts to edit src/app/pricing/page.tsx]

Hook: BLOCKED: Cannot edit copy file 'page.tsx' without voice & tone
      review. You MUST first delegate to voice-and-tone-lead.

Claude: [delegates to voice-and-tone-lead]

voice-and-tone-lead:
  VIOLATIONS FOUND
  1. [Direct voice principle] "We'd love to help you navigate the
     complexities" -- hedging. Fix: "I review your AI coding setup
     and tell you what's working and what isn't."

Claude: [incorporates fix, edits page.tsx successfully]

1. Detection (UserPromptSubmit)

Every prompt, a hook checks whether VOICE-AND-TONE.md exists in the project root. If it does, the hook injects an instruction into the AI's context telling it to delegate to the voice-and-tone-lead agent before editing any copy file.

if [ -f "VOICE-AND-TONE.md" ]; then
  cat <<'HOOK_OUTPUT'
INSTRUCTION: MANDATORY VOICE & TONE CHECK. YOU MUST FOLLOW THIS.
DETECTED: VOICE-AND-TONE.md exists in this project.

This is a NON-OPTIONAL instruction. You MUST use the voice-and-tone-lead agent
before editing any user-facing copy in .tsx files under src/app/ or
src/components-next/, blog articles in src/articles/, or social posts in
src/social/. This is proactive. Do not wait for the user to ask.
HOOK_OUTPUT
fi

The instruction fires on every prompt, not just prompts that mention copy. The AI doesn't always know in advance whether a task will involve editing a copy file. A prompt like "fix the broken layout on the pricing page" might require changing text. The instruction ensures the reviewer is consulted regardless.

2. The gate (PreToolUse)

The detection hook is context injection. Context can be ignored. The gate cannot.

A PreToolUse hook fires before every Edit or Write call. It checks whether the target file is a copy-bearing file (.tsx in src/app/ or src/components-next/, .md in src/articles/ or src/social/). If it is, the hook checks for a session marker file. If the marker doesn't exist, the edit is denied:

IS_COPY=false
case "$FILE_PATH" in
  */src/app/*.tsx|*/src/components-next/*.tsx)
    IS_COPY=true ;;
  */src/articles/*.md)
    IS_COPY=true ;;
  */src/social/*.md)
    IS_COPY=true ;;
esac

if [ "$IS_COPY" = false ]; then
  exit 0
fi

MARKER="/tmp/voice-tone-reviewed-${SESSION_ID}"
if [ -n "$SESSION_ID" ] && [ -f "$MARKER" ]; then
  exit 0
fi

When denied, the hook outputs JSON that Claude Code interprets as a hard block:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "BLOCKED: Cannot edit copy file 'page.tsx' without voice & tone review. You MUST first delegate to voice-and-tone-lead using the Agent tool."
  }
}

The AI cannot proceed. The denial message tells it exactly what to do: delegate to voice-and-tone-lead first.

3. The unlock (PostToolUse)

After the AI calls the Agent tool, a PostToolUse hook checks whether the subagent was voice-and-tone-lead. If so, it creates the session marker:

case "$SUBAGENT" in
  *voice-and-tone-lead*)
    touch "/tmp/voice-tone-reviewed-${SESSION_ID}" ;;
esac

The marker is a file in /tmp named with the session ID. Once the voice-and-tone-lead has reviewed, all subsequent edits to copy files in that turn are unblocked.

4. The reset (Stop)

A Stop hook fires when the AI finishes responding, before control returns to the user. It removes the session marker so the next prompt requires a fresh voice review:

if [ -n "$SESSION_ID" ]; then
  rm -f "/tmp/voice-tone-reviewed-${SESSION_ID}"
fi

Without the reset, one early review would cover every edit for the rest of the session. With it, each turn starts locked. Each edit gets checked against the guide instead of relying on a single early review to cover everything.

The reviewer

The voice-and-tone-lead is a Claude Code agent defined in .claude/agents/voice-and-tone-lead.md. It has read-only access to the codebase (Read, Glob, Grep) and no write permissions. It cannot edit files. It can only review.

The agent definition is a markdown file with YAML front matter. Here is a trimmed version:

---
name: voice-and-tone-lead
description: "Voice and tone reviewer for copy changes. Reads VOICE-AND-TONE.md"
  and reviews proposed changes against the guide's voice principles, tone guidance,
  banned patterns, and word list. Reports violations with suggested fixes.
tools:
  - Read
  - Glob
  - Grep
---

You are the Voice and Tone Lead. You review proposed copy changes against the
project's VOICE-AND-TONE.md guide before any user-facing text is edited. You are
a reviewer, not an editor.

## What You Check
- Voice principles (direct, confident, specific, empathetic)
- Tone guidance for the relevant section type
- Banned patterns
- Word list (prefer/avoid)
- Technical constraints (no em-dashes)

## Constraints
- You are read-only. You do not edit files.
- If the change is purely structural (no user-visible text changes), report PASS.

The tools list is the key constraint. Read, Glob, and Grep give the agent enough access to review code without the ability to change it.

If the copy passes, it reports PASS. If there are violations, it lists each one with the offending text, the rule it breaks, and a suggested fix. The AI then incorporates the fixes before writing.

A typical review looks like this:

Voice & Tone Review: VIOLATIONS FOUND

[Direct voice principle] Line 4

Issue: "We'd love to help you navigate the complexities" is hedging. The guide says "Say the thing. No preamble."

Copy: "We'd love to help you navigate the complexities of AI integration."

Fix: "I review your AI coding setup and tell you what's working and what isn't."

[Banned pattern: feature claims in fit checks] Line 5

Issue: "Reach out today to learn how our team can support your journey" sells the service instead of describing the visitor.

Fix: "Book a call if that's useful."

The reviewer is read-only by design. Separating the reviewer from the editor means the review happens before the edit, not after. The AI can't write first and review later.

What the guide looks like

The reviewer checks every proposed change against the VOICE-AND-TONE.md file. The more concrete the guide, the less room the reviewer has to drift. Here is what concreteness looks like in practice.

The banned patterns table lists specific phrases the AI must avoid, with the reason each one fails:

Pattern	Why it fails	Example
"actually" as emphasis	Signals you expect to be doubted	"I actually read your code"
Competitor bashing	Positions you as the cheap alternative	"Agencies charge $50k and take 8 weeks"
Feature claims in fit checks	Sells the service instead of describing the visitor	"You need someone who can implement guardrails"

Each section of the site gets its own tone guidance. Here is the objection handling section:

Tone: Respectful and substantive. The reader asked a real question. Answer it with real information, not a dismissal.

"You can. An AI audit will catch syntax and pattern issues. It won't catch the architectural gaps, the business logic that doesn't match your edge cases, or the dependencies that don't exist. That takes a human who's shipped production code."

Not: "You can. But Claude wrote the bugs in the first place."

The guide also includes tone sections for distribution channels: LinkedIn, Twitter, Reddit, Hacker News, Dev.to, Lobsters, and Bluesky. Each channel has its own constraints. Reddit gets the substance upfront. Twitter compresses to one idea. Lobsters titles read like paper abstracts.

Why a gate, not a nudge

A nudge injects a warning into the AI's context without blocking anything. The AI sees the message and can act on it, but nothing stops it from continuing. The WIP accumulation hooks use nudges. Voice enforcement uses a gate because the failure mode is different.

A missed WIP nudge means work accumulates longer than it should. That's recoverable. A missed voice review means off-brand copy ships to production. Fixing copy after the fact means noticing the drift, finding it, rewriting it, and redeploying. The cost of prevention (one agent call before editing) is lower than the cost of remediation.

The gate fires on Edit and Write to specific file paths. It doesn't fire on CSS changes, configuration files, or backend code. The scope is narrow: files that contain user-facing copy.

Other approaches exist. A post-commit linting step catches drift but only after the copy is written, meaning the AI has already moved on and a rewrite costs more context. A manual review checklist works but depends on the reviewer remembering to use it, which is the same problem the guide had. The gate catches drift at the point of edit, before the copy exists in the file, with no human discipline required.

Tradeoffs

The reviewer agent call adds 10-30 seconds per turn. For a single article or landing page edit, that's negligible. For bulk changes across many files in separate turns, it adds up.

The marker resets after each turn, so every turn that touches copy gets a fresh review. Within a single turn, one review covers all edits. If the AI edits multiple copy files in one turn, only the first triggers the reviewer. The later edits in that same turn ride on the same approval. For most workflows this is fine: a single turn rarely drifts mid-response. For high-stakes copy (pricing pages, legal text), splitting edits across turns forces a review on each one.

The reviewer itself is an AI agent, subject to the same drift it's checking for. It works because it re-reads the guide on every invocation rather than relying on memory, and because the guide is specific enough (banned patterns, a word list, concrete examples) to leave less room for interpretation.

False positives and false negatives still happen. The reviewer might flag a sentence that's fine, or miss a subtle drift the guide doesn't explicitly cover. There's no automated way to audit reviewer quality. The practical check is reading the reviewer's output: if its reasoning references specific guide sections and quotes the offending text, it's doing its job. If it produces vague approvals ("looks good, no issues"), the guide probably isn't specific enough.

When the reviewer flags something you disagree with, override it. The gate blocks the AI, not you. Claude Code prompts for confirmation on denied edits, and you can approve them directly. The reviewer is a check, not a veto.

Adapting this for your project

Start with the guide. Mailchimp's voice and tone guide is a good starting point. Ours began there and diverged as we identified patterns specific to this site. Write down how your site should sound. Be specific: include examples of what good copy looks like and what bad copy looks like. Banned patterns and a word list catch the most common drift.

A minimal guide might start here:

## Voice principles
- Direct: short sentences, no preamble
- Specific: use numbers and names, not adjectives

## Banned patterns
| Pattern | Why it fails |
|---------|-------------|
| "We're passionate about" | Generic, says nothing specific |
| "Leverage/utilize" | Jargon for "use" |

## Word list
| Use | Instead of |
|-----|-----------|
| use | leverage, utilize |
| help | empower, enable |

Define the scope. Which files contain user-facing copy? In this project, it's .tsx files in two directories and .md files in two directories. Your project might be different. If you publish to multiple channels (LinkedIn, Twitter, Reddit), add tone sections for each one. The guide captures how the voice adapts per context so the AI doesn't flatten everything to one register.

Create the agent. The voice-and-tone-lead agent definition is a markdown file in .claude/agents/. It describes the role, lists what to check, and defines the output format. Give it read-only tools so it reviews but doesn't edit.

Wire the four hooks. The detection hook goes in UserPromptSubmit. The gate goes in PreToolUse with a matcher for Edit and Write. The unlock goes in PostToolUse with a matcher for Agent. The reset goes in Stop.

The full configuration is in the public repo at github.com/windyroad/windyroad.

The Claude Code hooks documentation covers the full event model and the hook output format.

Making work-in-progress visible to your AI agent

Tom Howard — Mon, 09 Mar 2026 05:21:13 +0000

An AI agent has no visibility into accumulating work-in-progress. It works on the current prompt. Meanwhile, uncommitted changes grow, commits pile up without a push, changesets go unwritten, and a release PR sits open for days. The accumulation happens silently.

This matters because work-in-progress is risk. In Lean terms, it is internal inventory: work that has been started but has not yet delivered value to a customer. Uncommitted changes can be lost to a crash or a branch switch. Unpushed commits are invisible to the pipeline. Missing changesets mean no release PR will be created. A stale release PR means tested, reviewed code is sitting in a queue instead of running in production.

I built a Claude Code hook that surfaces all of this. Four checks monitor four queues where code accumulates on its way to production. Local checks run every prompt. Remote checks run on push. No blocking. The AI keeps working but both it and I can see the state of things.

Four queues

Code flows through four queues between your editor and production. Each queue is a place where work can stall. Each check monitors one queue.

The first two queues are local. Checking them requires only git commands against the local repo, which complete in milliseconds. The last two queues are remote. Checking them requires gh CLI calls that hit the GitHub API, taking 500ms to 2 seconds each. Running those on every prompt would add noticeable latency, so they run once on push. The remote state only changes when you push, so there's no need to re-check between pushes.

Local checks (every prompt)

The hook lives in .claude/hooks/wip-nudge.sh and fires on UserPromptSubmit, the same event used by the pipeline discipline hooks. Every check is independent. If one fails silently (no remote, no gh CLI), the others still run.

1. Uncommitted changes too large

DIFF_STAT=$(git diff HEAD --stat 2>/dev/null | tail -1)

git diff HEAD captures both staged and unstaged changes. The --stat summary line looks like 5 files changed, 180 insertions(+), 42 deletions(-). The script extracts the insertion and deletion counts and adds them. If the total is 200 or more:

WIP: ~222 lines of uncommitted changes. Consider committing before continuing.

The threshold of 200 is a judgment call. Below that, you're mid-task. Above it, you have enough work that losing it would hurt.

The check also counts lines in untracked files (excluding .DS_Store and node_modules) and adds them to the total. A 250-line file you haven't staged yet still counts toward the threshold.

There's a related check for stale modifications. If a tracked file has been modified but not committed for more than 24 hours, the hook flags it:

WIP: 2 modified file(s) uncommitted for over 24h. Forgotten or should be reverted?

A day-old uncommitted change is either forgotten work or something that should be reverted. Either way, it shouldn't sit there silently.

2. Unpushed commits piling up

UNPUSHED=$(git rev-list --count origin/master..HEAD 2>/dev/null || echo "0")

If the count is 3 or more:

WIP: 5 unpushed commits on master. Consider running npm run push:watch.

One or two unpushed commits is normal mid-task flow. Three or more means multiple units of work are sitting locally. The pipeline can't run against them. The release PR can't include them. If the push eventually fails CI, you're debugging a larger delta than necessary.

The nudge suggests npm run push:watch rather than bare git push because of the pipeline discipline hooks already wired into this project. That script pushes, watches the pipeline, and surfaces the deploy URL.

Remote checks (on push)

Checks 3 and 4 run inside scripts/push-watch.sh after the push completes and the remote refs are updated. The warnings print to stdout alongside the pipeline status and deploy URLs. Since the remote state only changes when you push, running the checks at push time is both the right moment and the only moment they need to run.

3. No release preview

UNRELEASED=$(git rev-list --count origin/publish..origin/master 2>/dev/null || echo "0")
CHANGESET_COUNT=$(find .changeset -name '*.md' ! -name 'README.md' 2>/dev/null | head -20 | wc -l)
OLDEST_UNRELEASED=$(git log --format='%aI' --reverse origin/publish..origin/master 2>/dev/null | head -1)

If there are pushed commits ahead of publish, no changeset files, and the oldest of those commits is more than 24 hours old or there are 3 or more:

WIP: 8 unreleased commits with no changeset (oldest: 3 day(s) ago). Run npx changeset to describe what's shipping.

Without a changeset file, the changesets action won't create a release PR. Changes accumulate on trunk with no release preview, no version bump, no CHANGELOG entry. This is internal inventory: work that has been done but is not flowing toward a release.

The check fires on either condition: the oldest pushed commit is over 24 hours old, or there are 3 or more pushed commits without a changeset. A single recent commit is normal mid-task flow. Three commits in one day without a changeset is accumulation worth flagging, even if everything is fresh.

The check compares origin/publish..origin/master rather than origin/publish..HEAD, limiting it to pushed commits and avoiding overlap with check 2. One changeset can cover multiple commits, so the check looks for the existence of any changeset file, not a 1:1 mapping. Writing a changeset is a product decision: what's the change worth calling out, and how should it be described?

4. Unreleased code

PR_JSON=$(timeout 10 gh pr list --base publish --state open --limit 1 \
  --json number,url,createdAt 2>/dev/null || echo "[]")

If an open PR targeting publish exists and was created more than 24 hours ago, the nudge reminds you that tested, pipeline-verified code is waiting. The output includes a CLAUDE: directive telling the AI to surface the release information and ask the user about it. The AI doesn't decide when to release, but it makes sure the human knows there's a release waiting:

WIP: Release PR #42 has been open for 3 day(s) with 5 changeset(s), ~1200 lines changed. https://github.com/...
CLAUDE: Tell the user about this release PR and ask if they want to review and merge it now.

The CLAUDE: prefix is a convention, not a feature of Claude Code. Any text the AI sees in its context can influence its behavior. A labelled directive just makes the intent explicit.

The check reports both changeset count and total diff size. A release with one changeset feels different from one with five, but a single changeset touching 2,000 lines is also worth knowing about. Both dimensions help decide whether to review now or keep working.

The gh CLI calls are wrapped in timeout 10 because they hit the network. If GitHub is slow or unreachable, the script fails with an error rather than silently skipping the check. A silent skip would mean you get no feedback about the release PR, with no indication that the check didn't run. Failing loudly means you know immediately if something is wrong with your GitHub token or network connectivity.

Informing without blocking

Every warning line is appended to a single additionalContext string in the hook's JSON output, alongside a systemMessage that prints directly in the terminal. The pattern is the same one used by other pipeline discipline hooks:

cat <<EOF
{
  "systemMessage": "WIP accumulation detected. See warnings below.",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": $ESCAPED
  }
}
EOF

There's no permissionDecision: "deny". systemMessage prints in your terminal every time the hook fires. additionalContext injects the detail into the AI's context. You see the warning. The AI has the detail. If multiple checks fire, all warnings stack into the same output.

The push gate in the pipeline discipline hooks is a hard block because git push without pipeline visibility is the specific action I want to prevent. WIP accumulation is different. It's state you want to be aware of, not an action you want to block. A gate that blocks every edit until you commit would be counterproductive during a multi-file change.

Wiring it up

The prompt-time hook goes in .claude/settings.json alongside the other UserPromptSubmit hooks:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/project-health-check.sh"
          }
        ]
      },
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/wip-nudge.sh"
          }
        ]
      }
    ]
  }
}

Each UserPromptSubmit entry runs independently. The health check and the WIP nudge don't know about each other. They both emit hook output if they have something to say, and stay silent if they don't.

The remote checks run inside push:watch, the same script that pushes and watches the pipeline. After the push completes and the remote refs are updated, the script runs checks 3-4 and prints any warnings to stdout. Since the AI is already watching the push output, the warnings are visible in the conversation without any caching mechanism.

The full hook

The complete local hook (.claude/hooks/wip-nudge.sh) and the remote checks in scripts/push-watch.sh are in the public repo at github.com/windyroad/windyroad. The key snippets are all shown above. The full scripts add error handling, JSON escaping for the additionalContext output, and the stale-file detection using python3 to compare file modification times against a 24-hour threshold.

Adapting this for your project

The specific checks here are tuned for a trunk-based workflow with changesets and a publish branch. The pattern works for any accumulation you want to track.

To build your own version, start by mapping your queues. Where does code accumulate on its way to production? Uncommitted changes, unpushed commits, and missing changesets are common. You might also check for TODO comments in uncommitted code, failing local tests, stale feature branches, or a growing number of skipped tests.

Split checks by cost. Anything that uses only local git commands belongs in the prompt-time hook. Anything that hits the network (GitHub API, CI status, deployment state) belongs in the script you use instead of bare git push. In this project, that's push:watch, which already pushes, watches the pipeline, and surfaces deploy URLs. Adding the remote WIP checks there means they run at the moment the remote state changes, without adding a separate mechanism.

Set thresholds that match your rhythm. The 200-line and 3-commit thresholds here reflect a workflow where commits are small and pushes are frequent. If your commits are larger or your pushes are batched, adjust accordingly.

Use additionalContext, not permissionDecision. The warning is in the AI's context when it generates its next response. The AI factors it into what it does next without being blocked.

Make every check independent. Each check should succeed or fail silently on its own. Use 2>/dev/null and || echo "0" so that a missing remote or absent CLI tool doesn't break the other checks.

Keep the prompt-time hook fast. It runs on every prompt. The git commands are local and near-instant. Network calls belong in the push script, not the prompt hook.

Wire it into UserPromptSubmit by adding an entry to the hooks object in your .claude/settings.json. The hook receives the prompt as JSON on stdin (which this script ignores) and emits the hook JSON on stdout.

The Claude Code hooks documentation covers the full event model: UserPromptSubmit for pre-prompt checks, PreToolUse for intercepting tool calls, and PostToolUse for post-action verification.

The full hook configuration for this site is in the public repo at github.com/windyroad/windyroad.