powerups-requirements: Instructions file for Claude Code

powerups-requirements

Requirements management toolkit for Claude Code — skills, agent, and hook for structured requirements elicitation, extraction, and maintenance.

The Problem

LLM coding sessions drift. Over a long session, Claude forgets what the system is supposed to do, conflates implementation details with requirements, re-proposes ideas that were already rejected, and lets requirements rot while the code evolves. The longer the session, the worse it gets.

This toolkit makes requirements a durable, structured artifact that survives across sessions and keeps the LLM honest.

This Is Opinionated

This isn't a generic requirements framework. It encodes specific beliefs about how requirements should work with LLM-assisted development:

Requirements are user-observable capabilities, not implementation details. The litmus test: "If I changed this, would the user notice a different capability?" If no, it's a design decision or style choice, not a requirement. Most requirements docs fail here — they're full of implementation spec masquerading as requirements. This toolkit enforces the distinction.

Flat atomic requirements over nested hierarchies. Each testable behaviour gets its own ID (FR-01, FR-02, FR-03). No FR-01.1, FR-01.2. Nesting creates ambiguity about status and completeness.

Requirements have three layers: narrative, rules, and examples. Each FR has an Actor (who benefits), Intent (why it matters), Description (what it does), Acceptance Criteria (abstract business rules), and Scenarios (concrete examples with specific data). The acceptance criteria say what the rule is; the scenarios illustrate it with real data. Scenarios are required for must-priority FRs. Format is author's choice: Given/When/Then for behaviour-oriented specs, examples tables for data-rule specs.

Scenarios are specifications, not scripts. They describe what the system does in business language, not click-by-click UI flows. They should survive a complete platform rewrite unchanged. This makes them human-readable descriptions of functional expectations that can be translated into automated tests — by an LLM or traditional test tooling.