nuzlocke-tracker/.beans/archive/nuzlocke-tracker-1y09--enforce-feature-branch-workflow-for-agents.md

title, status, type, priority, created_at, updated_at

title	status	type	priority	created_at	updated_at
Enforce feature branch workflow for agents	completed	task	high	2026-03-20T20:48:21Z	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

{
  "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 "...")