Manages structured project requirements in requirements.md: create, update, resolve functional/non-functional reqs; track decisions, questions, constraints. Activates on 'requirements' mentions or file presence.
How this skill is triggered — by the user, by Claude, or both
Slash command
/powerups-requirements:requirements-managementThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A requirements document is the durable source of truth for what a project must do, what
A requirements document is the durable source of truth for what a project must do, what constrains it, and what decisions have been made. It exists so that any LLM session can re-ground itself on project intent without relying on chat history.
Requirements live in requirements.md (or requirements.yaml) in the project root,
version-controlled alongside code. The file is plain text that humans can edit directly —
the LLM is a convenience layer, not a gatekeeper.
Sections in order:
Requirement IDs (FR-01, C-01, NF-01, D-01, Q-01) never change once assigned. Reference them in code comments, commit messages, and conversations. Increment to the next available number for new items.
Requirements move through: draft → in-flux → settled. Only settled requirements
should be treated as ground truth during implementation. draft and in-flux items should
be flagged for discussion.
must = system is broken without this. should = significant value, strong expectation.
could = nice to have, implement if cheap.
Never delete or overwrite a decision. If a decision is reversed, add a new decision that supersedes it and reference the original. Decisions record Owner to indicate authority: a human's name, "LLM", or "client:Name". LLM decisions may be revisited freely; human and client decisions should be treated as given unless explicitly reopened.
Always use the canonical term from the glossary in requirements text. When encountering an alias in conversation or code, map it to the canonical term. Domain quirks capture the "actually means" and "except when" cases — these are high-value for preventing bugs.
When re-implementing existing systems, certain behaviours look like requirements but are actually artefacts of old platform constraints, workarounds, or accumulated cruft. Recording these as Non-Goals prevents every fresh reviewer (human or LLM) from rediscovering and re-proposing them. Each non-goal needs a brief rationale explaining why it's rejected.
When uncertainty is discovered, add an open question rather than making an assumption. Questions are resolved by converting them into requirements, constraints, or decisions. Never silently resolve a question — record the resolution.
The most common failure mode in requirements extraction is spec leaking into requirements. Three things get conflated:
Requirements describe behaviour observable from outside the system. "The task list must display custom ID, client name, and status" is a requirement — it says what information the user needs. A requirement answers "what does the system do?" or "what does the user see/get?"
Design decisions describe how the system achieves requirements. "Config stored at
~/.cu/config.json", "use Cobra framework", "detect custom IDs via regex [A-Z]+-\d+"
are decisions. They narrow the solution space but could be changed without changing what
the user experiences. Record these in the Decisions section with rationale and Owner.
Style/presentation describes formatting, layout, and cosmetic choices. Column widths, truncation characters ("..." vs "..."), exact timestamp formats ("5h ago" vs "5 hours ago"), credential masking rules (first 10 + last 4 chars). These belong in a style guide or code conventions, not in requirements.md.
Ask: "If I changed this, would the user notice a different capability?"
For CLI tools and APIs, the command/endpoint structure is a requirement when external
consumers depend on it. cu <resource> <verb> is an interface contract — scripts and
agents write against it. Flag names (--active vs --open) are design decisions.
Response field selection ("which fields appear in summary output") is a requirement
when it reflects what information users need; column order and formatting are style.
For internal interfaces (function signatures, module boundaries), these are design decisions, not requirements.
When building requirements.md from existing code, implementation details will dominate what you find. Resist the urge to transcribe the code into requirements. Instead:
Prefer flat atomic requirements (FR-01, FR-02, FR-03) over nested sub-requirements (FR-01.1, FR-01.2, FR-01.3). Nesting creates ambiguity: is FR-01 settled because all sub-items are? What if FR-01.3 changes status? Each testable behaviour gets its own ID.
If a group of requirements are related, use a short title on each and let the IDs be sequential — the reader can see they're related without nesting.
Each FR has an Actor field (referencing the Actors table) and an Intent line that captures the business value in a single sentence: "In order to [goal], [actor] needs to [capability]." This makes the "who benefits" and "why it matters" explicit without burying it in prose. The Actor field connects each FR to the Actors table — if an actor has no FRs, something is missing.
Acceptance criteria are abstract business rules ("VIP customers get free delivery on book orders"). Scenarios are concrete examples that illustrate those rules with specific data — they make the rule testable and unambiguous.
Scenarios are required for must-priority FRs. Encouraged but optional for
should and could.
The format is author's choice per FR:
Given/When/Then (Gherkin-style) — best for behaviour-oriented specs:
Scenario: The one where a VIP buys enough books for free delivery
Given a VIP customer with 5 books in their cart
When they proceed to checkout
Then they should be offered both Free and Standard delivery
Examples table — best for data-rule specs where inputs/outputs matter more than sequence:
| Customer type | Cart contents | Delivery |
|---------------|--------------|----------------|
| VIP | 5 books | Free, Standard |
| VIP | 4 books | Standard |
| Regular | 10 books | Standard |
Both formats are valid. Use whichever communicates the rule most clearly. Some FRs will use both — a GWT scenario for the happy path plus a table for variations.
Scenarios are designed to be human-readable descriptions that can be translated into automated tests (by an LLM or traditional test automation). The specification stays in business language; the automation layer handles the translation. Don't distort the scenario to make automation easier — solve technical testing challenges in the automation layer, not in the specification.
systems.md documents external system topology — what exists, where it lives, how to reach it. It is NOT an API reference, integration guide, or implementation spec.
Include:
Do not include:
The test: If the information describes how to reach an external system, it belongs. If it describes how your code uses the system, it doesn't.
requirements.md from the template (see Document Structure above)systems.md: server/hostname,
access method, credential location, and what the system is used for. Explicitly note
what is NOT where an LLM might guess.requirements.md before writing any codein-flux or draft requirements relevant to the current taskdraft.Resolves: Q-ID field in the new item
so the trail is preserved in git history. Don't keep resolved questions in the doc — they
waste context.Requirements drift when code changes happen without updating the requirements doc. This is the most common failure mode — over a long session, Claude forgets to check.
Three pieces work together:
Hook (hooks/req_change_hook.py) — fires on every UserPromptSubmit,
injects a lightweight reminder into the main agent's context to assess whether
the user's message implies a requirement change. Skips trivial prompts. Only activates
when the project has a requirements.md file.
Main agent — reads the injected reminder, decides if there's a requirement change, confirms with the user, then delegates the update.
requirements-editor subagent (agents/requirements-editor.md) —
receives a delegation like "resolve Q-24, add D-24, the rule is X, affects
FR-04 and FR-08." It edits requirements.md / systems.md / project config files
following all conventions (sequential IDs, append-only decisions, cross-references,
validation checklist). It never touches code.
This separation means the main agent stays in "understand the problem and write code" mode. The subagent stays in "maintain the requirements doc" mode with the full conventions in its system prompt. Neither forgets its role.
The main agent should delegate to requirements-editor when the user's message implies:
must-priority FR is missing scenariosThe main agent should also delegate when:
The main agent should NOT delegate for:
When the main agent detects a requirement change:
requirements-editor with a clear instructionThis should be fast — one exchange with the user, then a background delegation.
When asked to review requirements, check for:
must-priority FRs without scenarios (concrete examples)must-priority worknpx claudepluginhub njt/powerups-requirements --plugin powerups-requirementsAuthors, updates, and validates atomic functional and non-functional requirements with traceability matrices, validation packs, and explicit human-in-the-loop approvals. Use for creating or reviewing requirements as source of truth.
Transforms vague goals into structured requirements via systematic interview. Three phases: Interview, Extract, Cross-check. Outputs requirements.md consumed by /blueprint.
Gathers, organizes, and documents software requirements into Markdown catalogs with user stories, measurable NFRs, and constraints tables. Use for PRDs, feature specs, or requirements analysis.