| name | req-new |
| description | Create a Requirement spec. Use when adding a new feature, "I want to spec out X", "new feature request", "create REQ for this", or when ready to formalize a feature idea. Do NOT use for creating tasks (use task-new instead) or bulk importing from PRD (use prd-import instead). |
| argument-hint | [Feature Name] [--phase PHASE-NNN] [--minimal] |
| user-invocable | true |
| metadata | {"author":"APME Team","version":"1.0.0"} |
REQ New
Create a Requirement spec.
Arguments
If $ARGUMENTS is provided, parse for:
- Feature name in quotes → use as requirement name
--phase PHASE-NNN → assign to phase--status X → set initial status--minimal → create structure only--from-conversation → extract from current discussion
Usage
/req-new # Interactive mode
/req-new "Feature Name" # Start with name
/req-new "Feature" --phase PHASE-001 # Assign to phase
/req-new "Feature" --status draft # With status
/req-new --from-conversation # Extract from discussion
/req-new "Feature" --minimal # Just create structure
Behavior
1. Check for Conversation Context
If recent conversation discusses a feature idea:
I see you've been discussing [topic]. Create REQ from this?
- Feature: [extracted]
- Purpose: [extracted]
Confirm? (Y to use, N to start fresh)
2. Determine Next REQ Number
Scan .sdlc/specs/REQ-* directories for highest number, increment by 1.
3. Assign to Phase
If phases exist (.sdlc/phases/PHASE-*/):
Which phase does this requirement belong to?
| Phase | Name | Status |
|-------|------|--------|
| PHASE-001 | CLI Scanner | In Progress |
| PHASE-002 | Rewrite Engine | Not Started |
Enter phase number (or "none" for unassigned):
If --phase PHASE-NNN provided, skip prompt.
If no phases exist, skip this step.
4. Gather Information (Streamlined)
Feature name and purpose?
User stories (one per line, "As a X, I want Y so that Z"):
Acceptance criteria (Gherkin format or plain bullets):
Dependencies? (internal REQs, external tools, or "none")
Initial status? (1=Draft, 2=In Review, 3=Approved)
5. Architectural Compatibility Check
CRITICAL: Do this BEFORE creating the spec directory.
Read the Architectural Invariants section of AGENTS.md. Evaluate the
proposed requirement against the invariants and present:
## Architectural Compatibility
| Invariant | Impact |
|-----------|--------|
| Validators read-only | OK / CONFLICT: [describe] |
| gRPC between services | OK / CONFLICT: [describe] |
| Async + executor | OK / CONFLICT: [describe] |
| Unified Validator contract | OK / CONFLICT: [describe] |
| Stateless engine | OK / CONFLICT: [describe] |
| Scale pods not services | OK / CONFLICT: [describe] |
| Session venvs are Engine-owned | OK / CONFLICT: [describe] |
| Rule ID conventions | OK / CONFLICT: [describe] |
| OPA subprocess | OK / CONFLICT: [describe] |
| FixSession unified path | OK / CONFLICT: [describe] |
| Engine never queries out | OK / CONFLICT: [describe] |
| Built-in bundles closed | OK / CONFLICT: [describe] |
Dependency direction preserved: [Y/N]
Engine remains caller-agnostic: [Y/N]
Detection/mutation separation maintained: [Y/N]
If conflict detected:
⚠ This requirement conflicts with architectural invariant(s): [list]
This REQ cannot be created until the conflict is resolved:
1. Redesign the requirement to work within the architecture
2. Create an ADR first (/adr-new) that justifies the exception
3. Abandon the requirement
Which approach? (1/2/3)
If option 2 chosen: Create the ADR first, then return to /req-new with
the ADR reference as a dependency.
If clean: Include in the requirement's Dependencies section:
- Architectural compatibility: Verified (no invariant conflicts)
6. Create Directory Structure
.sdlc/specs/REQ-NNN-feature-slug/
├── requirement.md # Filled with gathered info
├── design.md # Placeholder
├── contract.md # Placeholder
└── tasks/ # Empty directory
Slug: 2-4 words from feature name, lowercase, hyphens.
In requirement.md, include phase metadata:
# REQ-NNN: Feature Name
## Metadata
- **Phase**: PHASE-001 - CLI Scanner
- **Status**: Draft
- **Created**: YYYY-MM-DD
7. Update Indexes
Update .sdlc/specs/README.md:
| REQ-NNN | Feature Name | Phase | Status |
Update phase file (if assigned):
Add REQ to phase's requirements table in .sdlc/phases/PHASE-NNN/phase.md.
8. Find Related Artifacts
Search for related REQs, ADRs, open DRs. Show top 3-5.
9. Summary
Done!
- Created: .sdlc/specs/REQ-NNN-slug/
- Phase: PHASE-001 - CLI Scanner
- Status: Draft
Next: /task-new REQ-NNN to create implementation tasks
Quick Mode
| Provided | Skip |
|---|
| Feature name in quotes | Name prompt |
--phase PHASE-NNN | Phase prompt |
--status X | Status prompt |
--minimal | All detail prompts |
--from-conversation | Name + purpose if extractable |
Phase Integration
When Phases Exist
REQs should be assigned to phases. The phase provides:
- Scope context (what's in/out for this phase)
- Priority guidance (current phase = priority)
- Progress tracking (phase progress = REQ completion)
When No Phases Exist
REQs work standalone (legacy mode). Consider running /prd-import to set up phases from a PRD.
Phase Status Derivation
Phase status is derived from its REQs:
- Not Started: All REQs are Draft
- In Progress: At least one REQ is In Progress
- Complete: All REQs are Implemented
Parsing Freeform Input
User stories — accept variations:
As a Platform Engineer, I want terminal output so that I get quick feedback
- Platform Engineer: view violations in terminal → quick feedback
Acceptance criteria — accept:
GIVEN scan with violations WHEN terminal requested THEN shows file/line/rule
- Terminal output shows file path, line number, rule ID
Edge Cases
| Situation | Handling |
|---|
| No phases exist | Skip phase assignment |
| Phase not found | Warn and list available phases |
| REQ reassignment | Update old and new phase files |
| Unassigned REQ | Mark as "Unassigned" in indexes |
