requirements-framework

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:

1. Copy hooks to ~/.claude/hooks/
2. Install the global configuration to ~/.claude/requirements.yaml
3. Register all hooks (PreToolUse, PostToolUse, SessionStart, Stop, SessionEnd) in your Claude Code settings
4. 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:

• Plugin Installation Guide - Comprehensive reference
• Plugin README - Plugin-specific docs
• Plugin Components (below) - Agent/command/skill descriptions

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

  • Configure later manually

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: