Claude Code Requirements Framework
A powerful hook-based system for enforcing development workflow requirements in Claude Code. Ensures critical steps like commit planning, ADR review, and test-driven development are completed before code modifications.
Features
- 🔒 PreToolUse Hook: Blocks file modifications until requirements are satisfied
- 🛑 Stop Hook: Verifies all requirements before Claude finishes (prevents incomplete work)
- 🚀 SessionStart Hook: Injects full requirement status at session start
- 🧹 SessionEnd Hook: Cleans up session state when session ends
- 📋 Customizable Checklists: Display reminder checklists in requirement blocker messages
- 🎯 Session & Branch Scoping: Requirements can be session-specific, branch-specific, or permanent
- ⚡ CLI Tool: Simple
req command for managing requirements
- 🔄 Session Auto-Detection: Automatically finds the correct session without manual configuration
- 🚫 Message Deduplication: Prevents spam when Claude makes parallel tool calls
- 🧪 Comprehensive Tests: 447 passing tests with full TDD coverage
- 📦 Project Inheritance: Cascade configuration from global → project → local
- 🔧 Development Tools: Bidirectional sync.sh for seamless development workflow
Quick Start
Installation
# Clone the repository
git clone <repository-url> ~/tools/claude-requirements-framework
cd ~/tools/claude-requirements-framework
# Run the installation script
./install.sh
The installer will:
- Copy hooks to
~/.claude/hooks/
- Install the global configuration to
~/.claude/requirements.yaml
- Register all hooks (PreToolUse, PostToolUse, SessionStart, Stop, SessionEnd) in your Claude Code settings
- Display marketplace installation instructions for the plugin
Install Plugin via Marketplace
Option A: GitHub Marketplace (for users)
# In Claude Code session:
/plugin marketplace add https://github.com/HarmAalbers/claude-requirements-framework
/plugin install requirements-framework@requirements-framework
Option B: Local Marketplace (for developers)
After running install.sh, register the local clone:
# In Claude Code session:
/plugin marketplace add ~/Tools/claude-requirements-framework
/plugin install requirements-framework@requirements-framework
Verify Plugin Installation
Verify the plugin loaded successfully:
# Check plugin appears in Claude Code
# Start a new session and type:
/requirements-framework:
# Should autocomplete to:
# - /requirements-framework:pre-commit [aspects]
# - /requirements-framework:quality-check [parallel]
# - /requirements-framework:codex-review [focus]
# Check installed version:
/plugin list
# Should show: requirements-framework@2.0.5
For detailed installation, troubleshooting, and component reference:
Project Setup
After installation, initialize requirements for your project:
# Interactive wizard (recommended)
cd /your/project
req init
# Or non-interactively
req init --yes --preset relaxed
Initialization Modes
The interactive wizard offers three configuration approaches:
1. Quick Preset (Recommended)
Choose from context-aware presets optimized for your setup:
-
advanced - All features (recommended for global config)
- 7 requirements showcasing every capability
- Dynamic checks (branch_size_limit with calculator)
- Single-use requirements (pre_pr_review, codex_reviewer)
- Guard requirements (protected_branch)
- Perfect for discovering what the framework can do
-
inherit - Use global defaults (recommended for projects)
- Sets
inherit: true
- Empty requirements (relies on global config)
- Perfect for projects when you have global config
-
relaxed - Baseline requirements
- commit_plan only
- Good for standalone projects or trying the framework
-
strict - Full enforcement
- commit_plan + protected_branch
- Good for team projects with protected branches
-
minimal - Framework enabled, no requirements
2. Custom Selection
Interactive checkbox to pick specific features:
- Choose from: commit_plan, adr_reviewed, protected_branch, branch_size_limit, pre_pr_review, codex_reviewer
- Perfect for power users who know exactly what they want
3. Manual Setup
Starts with minimal config - configure everything yourself later
Context-Aware Behavior
req init automatically detects your context:
HarmAalbers