---
# nuzlocke-tracker-1y09
title: Enforce feature branch workflow for agents
status: completed
type: task
priority: high
created_at: 2026-03-20T20:48:21Z
updated_at: 2026-03-20T21:01:47Z
---

## Problem

Agents sometimes commit directly to `develop` instead of creating feature branches. The CLAUDE.md branching strategy documents the intent but isn't enforced — agents can ignore it.

## Solution

Add a Claude Code `PreToolCall` hook that blocks `git commit` when the current branch is `develop` or `main`, forcing agents to always work on `feature/*` branches. Also update CLAUDE.md to document the stricter workflow.

**Scope:** Agent-only enforcement (humans can still commit on `develop` if needed).

## Changes

### 1. Claude Code hook (`.claude/settings.json`)

Add a `PreToolCall` hook that:
- Triggers on `Bash` tool calls containing `git commit`
- Checks the current branch name via `git branch --show-current`
- **Blocks** if branch is `develop` or `main` with a clear error message
- **Allows** if branch matches `feature/*` or any other pattern

```json
{
  "hooks": {
    "PreToolCall": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if echo \"$TOOL_INPUT\" | grep -q \"git commit\"; then BRANCH=$(git branch --show-current); if [ \"$BRANCH\" = \"develop\" ] || [ \"$BRANCH\" = \"main\" ]; then echo \"BLOCK: Cannot commit directly to $BRANCH. Create a feature branch first: git checkout -b feature/<name>\"; exit 2; fi; fi'"
          }
        ]
      }
    ]
  }
}
```

> Note: Exit code 2 blocks the tool call. The hook should parse `$TOOL_INPUT` (JSON) to check for git commit commands.

### 2. CLAUDE.md update

Update the "Branching Strategy" section to add:

- **Never commit directly to `develop` or `main`.** Always create a `feature/*` branch first.
- When starting an **epic**, create `feature/<epic-title-slug>` off `develop`
- When starting a **standalone task/bug** (no parent epic), create `feature/<task-title-slug>` off `develop`
- Each task within an epic gets its own commit(s) on the epic's feature branch
- Branch naming: use a kebab-case slug of the bean title (e.g., `feature/add-auth-system`)
- When the epic/task is complete, squash merge into `develop`

## Checklist

- [ ] Add `PreToolCall` hook to `.claude/settings.json` that blocks commits on `develop`/`main`
- [ ] Test hook by verifying it blocks a commit attempt on `develop`
- [ ] Test hook by verifying it allows a commit on a `feature/*` branch
- [ ] Update CLAUDE.md branching strategy with new workflow rules
- [ ] Verify hook handles edge cases (e.g., `git commit --amend`, `git commit -m "..."`)