requirements-framework-usage

What this skill does

# Requirements Framework Usage

Help users configure, customize, and troubleshoot the **Claude Code Requirements Framework** - a hook-based system that enforces development workflow practices.

**Repository**: https://github.com/HarmAalbers/claude-requirements-framework
**Documentation**: `~/.claude/hooks/README-REQUIREMENTS-FRAMEWORK.md`

## Core Capabilities

1. **Configuration Guidance** - Help set up global, project, and local configs
2. **Checklist Customization** - Add/modify checklists for requirements
3. **CLI Usage** - Explain `req` command and session management
4. **Troubleshooting** - Debug hooks, permissions, and sync issues
5. **Best Practices** - Recommend workflows and patterns

## Quick Reference

### Essential CLI Commands

```bash
req status                  # Check requirement status
req satisfy commit_plan     # Mark requirement satisfied
req clear commit_plan       # Clear a requirement
req list                    # List all requirements
req sessions                # View active sessions
req init                    # Interactive project setup
req config commit_plan      # View/modify configuration
req doctor                  # Verify installation
```

**→ Full CLI reference**: See `references/cli-reference.md`

### Configuration Locations

1. **Global** (`~/.claude/requirements.yaml`) - Defaults for all projects
2. **Project** (`.claude/requirements.yaml`) - Shared team config (committed)
3. **Local** (`.claude/requirements.local.yaml`) - Personal overrides (gitignored)

### Requirement Scopes

| Scope | Lifetime | Use Case |
|-------|----------|----------|
| `session` | Until Claude session ends | Daily planning, ADR review |
| `branch` | Persists across sessions | GitHub ticket linking |
| `permanent` | Never auto-cleared | Project setup |
| `single_use` | Cleared after action | Pre-commit review (each commit) |

## Common Tasks

### Task: Add Checklist to Requirement

```yaml
# In .claude/requirements.yaml
requirements:
  commit_plan:
    enabled: true
    scope: session
    checklist:
      - "Plan created via EnterPlanMode"
      - "Atomic commits identified"
      - "TDD approach documented"
```

### Task: Create Custom Requirement

```yaml
requirements:
  my_requirement:
    enabled: true
    scope: session
    trigger_tools:
      - Edit
      - Write
    message: |
      🎯 **Custom Requirement**

      Explain what needs to be done.

      **To satisfy**: `req satisfy my_requirement`
    checklist:
      - "First step"
      - "Second step"
```

**→ More examples**: See `examples/custom-requirement.yaml`

### Task: Block Specific Bash Commands

```yaml
requirements:
  pre_commit_review:
    enabled: true
    scope: single_use
    trigger_tools:
      - tool: Bash
        command_pattern: "git\\s+commit"
    message: "Review required before commit"
```

**Pattern Tips**:
- `\\s+` matches whitespace
- `|` for OR: `git\\s+(commit|push)`
- Case-insensitive by default

**→ More patterns**: See `examples/bash-command-trigger.yaml`

### Task: Temporarily Disable Requirements

**Option 1**: Local override
```yaml
# .claude/requirements.local.yaml
enabled: false
```

**Option 2**: Environment variable
```bash
export CLAUDE_SKIP_REQUIREMENTS=1
```

**Option 3**: Disable specific requirement
```bash
req config commit_plan --disable --local
```

## Interactive Setup

Use `req init` for guided project setup:

```bash
req init                    # Interactive wizard
req init --preset strict    # Use preset (non-interactive)
req init --yes              # Non-interactive with defaults
```

**Presets**:
- `strict` - All requirements, session scope (teams)
- `relaxed` - Basic requirements, branch scope
- `minimal` - Only commit_plan (learning)
- `advanced` - All features + branch limits + guards
- `inherit` - Inherit from global config

## Configuration Management

View and modify settings without editing YAML:

```bash
# View
req config                   # All requirements
req config commit_plan       # Specific requirement

# Modify
req config commit_plan --enable
req config commit_plan --disable
req config commit_plan --scope branch
req config adr_reviewed --set adr_path=/custom/path
```

**→ Full config options**: See `references/cli-reference.md`

## Session Management

Sessions are auto-detected. Manual override when needed:

```bash
req sessions                           # List active sessions
req satisfy commit_plan --session ID   # Explicit session
```

## Troubleshooting Quick Guide

### Hook Not Triggering?

1. Check if on main/master (skipped by design)
2. Verify config enabled: `req config`
3. Check hook registration: `req doctor`
4. Check permissions: `ls -la ~/.claude/hooks/*.py`
5. Verify no skip flag: `echo $CLAUDE_SKIP_REQUIREMENTS`

### Session Not Found?

```bash
req sessions                # Find session ID
req satisfy NAME --session ID
req prune                   # Clean stale sessions
```

**→ Full troubleshooting guide**: See `references/troubleshooting.md`

## Advanced Features

### Auto-Satisfaction via Skills

Skills can automatically satisfy requirements:

```
1. git commit → Blocked by pre_commit_review
2. /requirements-framework:pre-commit runs
3. Auto-satisfies pre_commit_review
4. git commit → Success!
5. single_use clears → Next commit requires review again
```

**Built-in mappings (review skills)**:
- `requirements-framework:pre-commit` → `pre_commit_review`
- `requirements-framework:deep-review` → `pre_pr_review`
- `requirements-framework:arch-review` → `commit_plan`, `adr_reviewed`, `tdd_planned`, `solid_reviewed`
- `requirements-framework:codex-review` → `codex_reviewer`

**Built-in mappings (process skills)**:
- `requirements-framework:brainstorming` → `design_approved`
- `requirements-framework:writing-plans` → `plan_written`, `commit_plan`
- `requirements-framework:test-driven-development` → `tdd_planned`
- `requirements-framework:systematic-debugging` → `debugging_systematic`
- `requirements-framework:verification-before-completion` → `verification_evidence`
- `requirements-framework:requesting-code-review` → `pre_commit_review`

### Process Skills (Development Lifecycle)

The framework includes process skills that guide the full development lifecycle:

| Skill | Purpose |
|-------|---------|
| `brainstorming` | Design-first development (explore → design → approve) |
| `writing-plans` | Create bite-sized implementation plans |
| `executing-plans` | Execute plans with batch checkpoints |
| `test-driven-development` | RED-GREEN-REFACTOR cycle enforcement |
| `systematic-debugging` | 4-phase root-cause investigation |
| `verification-before-completion` | Fresh evidence before claiming done |
| `subagent-driven-development` | Parallel task execution with review |
| `finishing-a-development-branch` | Branch completion and merge options |
| `using-git-worktrees` | Isolated workspace creation |
| `dispatching-parallel-agents` | Concurrent problem solving |
| `receiving-code-review` | Technical evaluation of feedback |
| `requesting-code-review` | Dispatching review agents |
| `writing-skills` | TDD-for-documentation (meta-skill) |

Use `/brainstorm`, `/write-plan`, `/execute-plan` commands to invoke process skills directly.

For large multi-layer refactors that exceed a single session, use `/requirements-framework:refactor-orchestrate` — multi-layer top-down refactor workflow (produces plan + orchestrator-prompt for fresh-session execution).

### Single-Use Scope

Requires satisfaction before EACH action:

```yaml
pre_commit_review:
  scope: single_use  # Must satisfy before EVERY commit
```

### Dynamic Requirements

Auto-calculated conditions (e.g., branch size):

```yaml
branch_size_limit:
  type: dynamic
  threshold: 400
```

### Guard Requirements

Condition checks (e.g., protected branches):

```yaml
protected_branch:
  type: guard
  branches: [main, master]
```

**→ Advanced features details**: See `references/advanced-features.md`

## Checklist Best Practices

1. **Keep items concise** - 5-10