Skip to content
Skills Library
Programming · Testing

requirements-framework-development

/requirements-framework-development

This skill should be used when the user asks to "develop requirements framework", "fix requirements framework bug", "rebuild the plugin bundle", "update framework code", "test framework changes", or needs help with the framework development workflow including the hooks/ → bundle build, live-reload testing, TDD for the framework itself, and contributing changes.

Licence
MIT
Last repository change
09.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 09.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

This skill should be used when the user asks to "develop requirements framework", "fix requirements framework bug", "rebuild the plugin bundle", "update framework code", "test framework changes", or needs help with the framework development workflow including the hooks/ → bundle build, live-reload testing, TDD for the framework itself, and contributing changes.

Triggers from the description

develop requirements frameworkfix requirements framework bugrebuild the plugin bundleupdate framework codetest framework changes
Original author description

This skill should be used when the user asks to "develop requirements framework", "fix requirements framework bug", "rebuild the plugin bundle", "update framework code", "test framework changes", or needs help with the framework development workflow including the hooks/ → bundle build, live-reload testing, TDD for the framework itself, and contributing changes.

How it works

  1. Core Concept: Plugin-Owned Runtime + Build-Copy Bundle
  2. uv Is Required (ADR-021)
  3. Build Tools — The Essential Commands
  4. Live-Reload Testing
  5. Development Workflows
  6. Version Control: git (jj optional)
  7. Testing
  8. Workflow Gates (ADR-022)
  9. Common Agent Tasks
  10. Troubleshooting Quick Reference
Original SKILL.md headings · 309 lines, 1,196 words
SKILL.md preview
---
name: requirements-framework-development
description: This skill should be used when the user asks to "develop requirements framework", "fix requirements framework bug", "rebuild the plugin bundle", "update framework code", "test framework changes", or needs help with the framework development workflow including the hooks/ → bundle build, live-reload testing, TDD for the framework itself, and contributing changes.
git_hash: 307b927
---

# Requirements Framework Development

Guide for developing, fixing, and maintaining the **Claude Code Requirements Framework**.

**Repository**: `~/Tools/claude-requirements-framework` (git-controlled source of truth)
**Runtime**: the plugin at `plugins/requirements-framework/` (loaded by Claude Code)
**Remote**: https://github.com/HarmAalbers/claude-requirements-framework.git

## Core Concept: Plugin-Owned Runtime + Build-Copy Bundle

There is **no** `~/.claude/hooks` deployment and **no** `sync.sh` — both have been removed.
The framework runs entirely as a **self-contained plugin**:

| Piece | Path | Role |
|-------|------|------|
| **Hook source** | `hooks/` | Where you edit hook + lib code (source of truth) |
| **Plugin bundle** | `plugins/requirements-framework/hooks/` | Build-copy of `hooks/`, produced by `scripts/build_plugin_hooks.py` |
| **Hook registration** | `plugins/requirements-framework/hooks/hooks.json` | Single source of truth; registers all lifecycle hooks via `${CLAUDE_PLUGIN_ROOT}` |
| **Prompt templates** | `**/*.md.j2` | Rendered to `.md` by `scripts/render_prompts.py` |

Because the bundle is a **build-copy**, editing `hooks/` is not enough — you must
rebuild the bundle so the plugin runtime picks up your change.

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

## uv Is Required (ADR-021)

Every Python entrypoint runs through **`uv`** — never bare `python3` (the only
exception is `statusline.sh`). Run all tooling via `uv run …` so the synced env
(`PyYAML` + the `dev` group) is guaranteed.

```bash
uv sync                                    # one-time: materialize .venv
uv run python hooks/test_requirements.py   # run the test suite
uv run ruff check .                         # lint (pinned, matches CI)
```

## Build Tools — The Essential Commands

```bash
cd ~/Tools/claude-requirements-framework

# Rebuild the plugin bundle after editing anything in hooks/
uv run python scripts/build_plugin_hooks.py

# Report bundle drift without writing (use before committing / in CI)
uv run python scripts/build_plugin_hooks.py --check

# Re-render prompt templates (*.md.j2 → *.md) after editing a template
uv run python scripts/render_prompts.py
```

`build_plugin_hooks.py --check` exits non-zero when the bundle is stale relative
to `hooks/` — treat that as "rebuild before you commit."

## Live-Reload Testing

Load the plugin straight from the repo so edits are picked up on the next session:

```bash
claude --plugin-dir ~/Tools/claude-requirements-framework/plugins/requirements-framework
```

Rebuild the bundle (`build_plugin_hooks.py`) and re-render prompts
(`render_prompts.py`) as needed, then start a fresh session to load the changes.

## Development Workflows

### Workflow A: Standard Development

**Pattern**: Edit source → Rebuild bundle → Test → Commit

```bash
cd ~/Tools/claude-requirements-framework

# 1. Edit hook / lib source
$EDITOR hooks/lib/requirements.py

# 2. Rebuild the plugin bundle
uv run python scripts/build_plugin_hooks.py

# 3. Test
uv run python hooks/test_requirements.py

# 4. Commit (see below)
git add -p && git commit -m "fix(hooks): ..."
```

### Workflow B: Editing a Prompt Template

**Pattern**: Edit `.md.j2` → Render → Live-reload

```bash
# 1. Edit the template (never the rendered .md — it is regenerated)
$EDITOR plugins/requirements-framework/commands/some-command.md.j2

# 2. Render templates
uv run python scripts/render_prompts.py

# 3. Reload in a fresh --plugin-dir session
```

### Workflow C: Test-Driven Development

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

```bash
# 1. Write failing test
$EDITOR hooks/test_requirements.py

# 2. Rebuild + run (RED)
uv run python scripts/build_plugin_hooks.py
uv run python hooks/test_requirements.py   # fails

# 3. Implement feature
$EDITOR hooks/lib/requirements.py

# 4. Rebuild + run (GREEN)
uv run python scripts/build_plugin_hooks.py
uv run python hooks/test_requirements.py   # passes (green = 1544/1551)

# 5. Commit atomically
git add -p && git commit -m "feat: ..."
```

## Version Control: git (jj optional)

Plain git on a topic branch; jj works too, colocated (`jj git init --colocate`).

```bash
git checkout -b feat/your-branch
# ... edit files ...
git add -p && git commit -m "..."   # one logical change per commit, as you go
```

Keep commits atomic — one logical change each. When a commit touches plugin files,
bump `plugins/requirements-framework/.claude-plugin/plugin.json` **in the same
commit**.

## Testing

### Run Full Test Suite

```bash
uv run python hooks/test_requirements.py

# Expected: green = 1544/1551 (7 pre-existing failures are known/ignored)
```

### Run Specific Tests

```bash
# By name pattern
uv run python hooks/test_requirements.py -k "test_session"

# Verbose output
uv run python hooks/test_requirements.py -v
```

### Integration Testing

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

# 2. Start Claude (--plugin-dir), try editing → should block
# 3. Satisfy: req satisfy plan_validated
# 4. Try editing → should work
```

## Workflow Gates (ADR-022)

The typed 7-node backbone uses these gates:

| Gate | Node |
|------|------|
| `design_approved`      | design |
| `plan_written`         | plan |
| `plan_validated`       | validate (team) |
| `implementation_done`  | build |
| `pr_reviewed`          | review (team) |
| `verified`             | verify |
| — (gateless)           | ship |

**Retired** (do NOT reintroduce — no compat shims): `commit_plan`,
`adr_reviewed`, `tdd_planned`, `solid_reviewed`, `pre_pr_review`,
`pre_push_verification`, `codex_reviewer`. A config still naming an old gate gets
a validation error pointing at the new name.

## Common Agent Tasks

### Fix a Bug

```bash
cd ~/Tools/claude-requirements-framework

# 1. Edit source
$EDITOR hooks/lib/FILE.py

# 2. Rebuild + test
uv run python scripts/build_plugin_hooks.py
uv run python hooks/test_requirements.py

# 3. Commit
git add -p && git commit
```

### Add a Feature

```bash
cd ~/Tools/claude-requirements-framework

# 1. Edit source
$EDITOR hooks/lib/FILE.py

# 2. Rebuild + test
uv run python scripts/build_plugin_hooks.py && uv run python hooks/test_requirements.py

# 3. Commit
git add -p && git commit
```

### Before Committing

```bash
cd ~/Tools/claude-requirements-framework

# Confirm the bundle is not stale relative to hooks/
uv run python scripts/build_plugin_hooks.py --check

# Lint like CI does
uv run ruff check .
```

## Troubleshooting Quick Reference

### Changes Not Taking Effect

```bash
# Did you rebuild the bundle after editing hooks/?
uv run python scripts/build_plugin_hooks.py --check   # reports drift
uv run python scripts/build_plugin_hooks.py           # rebuild

# For prompt changes, did you re-render?
uv run python scripts/render_prompts.py

# Then start a fresh --plugin-dir session to reload.
```

### Tests Fail

```bash
# Rebuild first — a stale bundle can diverge from hooks/ source
uv run python scripts/build_plugin_hooks.py

# Run with verbose
uv run python hooks/test_requirements.py -v
```

### Hook Not Triggering

```bash
# Registration lives in the plugin, not settings.json
cat plugins/requirements-framework/hooks/hooks.json

# Confirm you launched with the plugin loaded
claude --plugin-dir ~/Tools/claude-requirements-framework/plugins/requirements-framework
```

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

## Best Practices

1. **Rebuild the bundle after editing `hooks/`** — `build_plugin_hooks.py`
2. **`--check` before committing** — catch a stale bundle early
3. **Test after every change** — `uv run python hooks/test_requirements.py`
4. **Everything via `uv run`** — never bare `python3` (except `statusline.sh`)
5. **Commit atomically** — one logical change per commit; bump `plugin.json` in the same commit when plugin files change

## Golden Rules

1. **`hooks/` is source of truth** — always edit there, never the bundle copy
2. **The bundle is a build artifact** — regenerate it with `build_plugin_hooks.py`
3. **Prompts are `.md.j2` → `.md`** — edit the template, render with `render_prompts.py`
4. **`uv run` for all Python** — the synced env guarantees deps (ADR-021)
5. **Small atomic commits as you go** — git, or jj colocated

## Resources

- **CLAUDE.md**: `~/Tools/claude-requirements-framework/CLAUDE.md` (authoritative build/test commands)
- **DEVELOPMENT.md**: Full development guide
- **Bundle build**: `uv run python scripts/build_plugin_hooks.py [--check]`
- **Prompt render**: `uv run python scripts/render_prompts.py`
- **Tests**: `uv run python hooks/test_requirements.py`

## Reference Files

- `references/sync-workflow-details.md` - Detailed bundle-build / render / live-reload workflow and scenarios
- `references/troubleshooting-development.md` - Development troubleshooting
Files in this package (4)
  • SKILL.md 9 KB
  • SKILL.md.j2 9 KB
  • references/sync-workflow-details.md 7 KB
  • references/troubleshooting-development.md 7 KB

Versions

The database has no other skills named requirements-framework-development.

Database snapshot: 13.11.2026 · package version 5f9715841e2f (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90tdd-workflow
    Implements features and bug fixes test-first using the red, green, refactor cycle, detecting the project's existing test framework and conventions. Use when the user asks for TDD, test-first development, to "add tests", or to implement behavior that must be reliably verified.
  • 100requirements-framework-status
    This skill should be used when the user asks to "requirements framework status", "show requirements project context", "what's the state of requirements framework", "requirements framework overview", or wants a comprehensive status report of the requirements framework…
  • 100requirements-framework-usage
    This skill should be used when the user asks about "using requirements framework", "how to configure requirements", "add requirement checklist", "customize requirements", "requirements not working", "bypass requirements", "satisfy requirements", or needs help with the…
  • 100tdd
    Test-driven development workflow. Use when the user asks to "write tests first", "TDD", "add test coverage", "test this function", or wants to develop a feature test-first.
  • 100tdd-workflow
    Implement features using TDD workflow with requirements-first approach. Use when implementing new features, adding functionality, or when user asks to build something.
  • 95tdd-workflow
    Test-Driven Development workflow enforcement skill. Use when explicitly asked for TDD methodology, test-first development, red-green-refactor cycle, or TDD implementation. Triggers on keywords like "start TDD", "test-driven development", "write tests first", or in Chinese "開始…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.