Requirements Framework Development

Guide for developing, fixing, and maintaining the Claude Code Requirements Framework with proper sync workflow.

Repository: ~/Tools/claude-requirements-framework (git-controlled source of truth) Deployed: ~/.claude/hooks/ (active runtime) Remote: https://github.com/HarmAalbers/claude-requirements-framework.git

Core Concept: Two-Location Architecture

The framework lives in TWO places that must stay synchronized:

Location	Purpose	When Changes Take Effect
Repository	Git source of truth	After ./sync.sh deploy
Deployed	Active runtime	Immediately

→ Full sync details: See references/sync-workflow-details.md

sync.sh - The Essential Tool

cd ~/Tools/claude-requirements-framework

./sync.sh status  # Check sync (ALWAYS run first)
./sync.sh deploy  # Repository → ~/.claude/hooks
./sync.sh diff    # Show differences

Status Symbols

Symbol	Meaning	Action
✓	In sync	None needed
↑	Out of sync	Run ./sync.sh deploy
⚠	Not deployed	Run ./sync.sh deploy
✗	Missing in repo	Copy or delete

Development Workflows

Workflow A: Standard Development

Pattern: Edit in repo → Deploy → Test → Commit

cd ~/Tools/claude-requirements-framework

# 1. Edit in repository
vim hooks/lib/requirements.py

# 2. Deploy
./sync.sh deploy

# 3. Test
python3 ~/.claude/hooks/test_requirements.py

# 4. Commit
git add . && git commit -m "feat: Add feature" && git push

Workflow B: Emergency Fix

Pattern: Fix in deployed → Test → Copy back → Commit

# 1. Fix directly (immediate effect)
vim ~/.claude/hooks/check-requirements.py

# 2. Test immediately
python3 ~/.claude/hooks/test_requirements.py

# 3. Copy to repo
cd ~/Tools/claude-requirements-framework
cp ~/.claude/hooks/check-requirements.py hooks/

# 4. Deploy and commit
./sync.sh deploy
git add . && git commit -m "fix: Bug description" && git push

Workflow C: Claude-Driven Development

Pattern: Claude edits deployed → Copy back → Commit

# 1. Claude edited ~/.claude/hooks/lib/some_module.py

# 2. Copy to repo
cd ~/Tools/claude-requirements-framework
cp ~/.claude/hooks/lib/some_module.py hooks/lib/

# 3. Deploy and commit
./sync.sh deploy
git add . && git commit -m "feat: Description" && git push

→ Example script: See examples/claude-driven-workflow.sh

Workflow D: Test-Driven Development

Pattern: Test (RED) → Implement → Test (GREEN) → Commit

# 1. Write failing test in repo
vim hooks/test_requirements.py

# 2. Deploy and run (RED)
./sync.sh deploy
python3 ~/.claude/hooks/test_requirements.py  # Fails

# 3. Implement feature
vim hooks/lib/requirements.py

# 4. Deploy and run (GREEN)
./sync.sh deploy
python3 ~/.claude/hooks/test_requirements.py  # Passes

# 5. Commit
git add . && git commit -m "feat: TDD feature" && git push

→ Example script: See examples/tdd-workflow.sh

Testing

Run Full Test Suite

python3 ~/.claude/hooks/test_requirements.py

# Expected: 1079/1079 tests passed ✓

Run Specific Tests

# By name pattern
python3 ~/.claude/hooks/test_requirements.py -k "test_session"

# Verbose output
python3 ~/.claude/hooks/test_requirements.py -v

Integration Testing

# 1. Enable in a project
cd ~/some-project
cat > .claude/requirements.yaml <<EOF
version: "1.0"
enabled: true
requirements:
  commit_plan:
    enabled: true
    scope: session
EOF

# 2. Start Claude, try editing → Should block
# 3. Satisfy: req satisfy commit_plan
# 4. Try editing → Should work

Common Agent Tasks

Fix a Bug

# 1. Edit in deployed (immediate effect)
vim ~/.claude/hooks/lib/FILE.py

# 2. Test
python3 ~/.claude/hooks/test_requirements.py

# 3. Copy to repo
cd ~/Tools/claude-requirements-framework
cp ~/.claude/hooks/lib/FILE.py hooks/lib/

# 4. Deploy and commit
./sync.sh deploy
git add . && git commit -m "fix: Bug description" && git push

Add a Feature

# 1. Check sync first
cd ~/Tools/claude-requirements-framework
./sync.sh status

# 2. Edit in repo
vim hooks/lib/FILE.py

# 3. Deploy and test
./sync.sh deploy && python3 ~/.claude/hooks/test_requirements.py

# 4. Commit
git add . && git commit -m "feat: Feature description" && git push

After ANY Changes

# ALWAYS check sync before committing
cd ~/Tools/claude-requirements-framework
./sync.sh status
# If not clean, reconcile before committing

Troubleshooting Quick Reference

Changes Not Taking Effect

# Check where you edited
pwd

# If in repo, deploy
./sync.sh deploy

# Check file exists
ls -la ~/.claude/hooks/your-file.py

Tests Fail After Deploy

# Check permissions
chmod +x ~/.claude/hooks/*.py

# Check sync status
./sync.sh status

# Run with verbose
python3 ~/.claude/hooks/test_requirements.py -v

Hook Not Triggering

# Check registration
cat ~/.claude/settings.local.json | grep hooks

# Check file exists and is executable
ls -la ~/.claude/hooks/check-requirements.py

→ Full troubleshooting: See references/troubleshooting-development.md

Best Practices

1. Check sync BEFORE committing - ./sync.sh status
2. Test after every change - python3 ~/.claude/hooks/test_requirements.py
3. Deploy after editing in repo - ./sync.sh deploy
4. Commit atomically - One logical change per commit
5. Use conventional commits - feat:, fix:, docs:, test:

File Sync Reference

Hook Files Synced

check-requirements.py
handle-session-start.py
handle-prompt-submit.py
handle-permission-request.py
handle-plan-exit.py
auto-satisfy-skills.py
clear-single-use.py
handle-tool-failure.py
handle-subagent-start.py
handle-pre-compact.py
handle-stop.py
handle-session-end.py
handle-teammate-idle.py
handle-task-completed.py
requirements-cli.py
test_requirements.py
test_branch_size_calculator.py
ruff_check.py

Library Files Synced

All *.py files in hooks/lib/ directory.

NOT Synced

• examples/ - Example files
• docs/ - Documentation
• plugin/ - Plugin (symlinked separately)
• .git/ - Git files

Golden Rules

1. Repository is source of truth - Always commit from here
2. Deployed is active - Changes take effect immediately
3. sync.sh keeps them aligned - Use it liberally
4. Check sync before push - Reconcile differences first
5. Test after every sync - Run test suite to verify

Resources

• README: ~/Tools/claude-requirements-framework/README.md
• DEVELOPMENT.md: Full development guide
• Sync Tool: ./sync.sh status|deploy|diff
• Tests: python3 ~/.claude/hooks/test_requirements.py

Reference Files

• references/sync-workflow-details.md - Detailed sync.sh usage and scenarios
• references/troubleshooting-development.md - Development troubleshooting
• examples/tdd-workflow.sh - TDD workflow example script
• examples/claude-driven-workflow.sh - Claude development workflow script