zhongwei/gh-reqvire-org-reqvire-reqvire-claude-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:51:32 +08:00
commit 327f263708
19 changed files with 2538 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

104
commands/add-feature.md Normal file
View File

@@ -0,0 +1,104 @@
---
allowed-tools: Read, Write, Edit, Bash(reqvire:*), SlashCommand
argument-hint: [feature-name]
description: Add a complete feature by orchestrating requirement and verification creation following MBSE workflow
model: claude-sonnet-4-5-20250929
---
# Add Feature
Add a complete feature by orchestrating multiple commands to create requirements, verifications, and proper traceability.
## Current Model Context
- Total requirements: !`reqvire search --json | jq -r '.global_counters.total_elements'`
- Verification coverage: !`reqvire coverage --json | jq -r '.summary.leaf_requirements_coverage_percentage'`%
## User Request
${1:+Feature name: $1}
${1:-The user will provide feature details.}
## MBSE Workflow
This command orchestrates the complete workflow:
1. Define requirements (parent → children)
2. Create verifications for leaf requirements
3. Validate and check coverage
## Steps
1. **Understand the feature:**
- Ask user for feature description
- Identify if this derives from existing requirement
- Plan requirement hierarchy (parent → leaf requirements)
2. **Create parent requirement (if needed):**
```bash
/add-requirement
```
This creates the high-level feature requirement.
3. **Create leaf requirements:**
For each specific capability:
```bash
/add-requirement
```
Link each to the parent via `derivedFrom`.
4. **Create verifications for leaf requirements:**
For each leaf requirement:
```bash
/add-verification
```
This will:
- Check if verification is needed (leaf vs parent)
- Read all requirements in trace chain
- Create verification with comprehensive test criteria
- Link to tests if applicable
5. **Validate complete feature:**
```bash
reqvire validate
reqvire coverage --filter-name="<feature-name>"
reqvire traces --filter-name="<feature-name>"
```
6. **Clean up model:**
```bash
reqvire lint --fix
```
## Command Flow
```
/add-feature
├─> /add-requirement (parent)
├─> /add-requirement (leaf 1)
├─> /add-requirement (leaf 2)
├─> /add-requirement (leaf 3)
├─> /add-verification (for leaf 1)
├─> /add-verification (for leaf 2)
├─> /add-verification (for leaf 3)
└─> reqvire lint --fix
```
## Best Practices
- **Requirements first**: Create all requirements before verifications
- **Hierarchical**: Parent requirement → leaf requirements
- **Verify leaves only**: Use `/add-verification` for leaf requirements
- **Delegate**: Let individual commands handle their specific logic
- **Validate often**: Run validation after each major step
## Notes
- This is an orchestration command - it calls other commands
- Follow MBSE methodology: requirements → verifications → tests
- Each step uses specialized commands for consistency
- Run `reqvire coverage` at the end to confirm complete feature coverage

159
commands/add-requirement.md Normal file
View File

@@ -0,0 +1,159 @@
---
allowed-tools: Read, Bash(reqvire:*)
argument-hint: [requirement-name]
description: Add a new requirement to the Reqvire model with proper structure and traceability
model: claude-sonnet-4-5-20250929
---
# Add New Requirement
Add a new requirement to the Reqvire model following MBSE best practices.
## Current Model Context
- Total requirements: !`reqvire search --json | jq -r '.global_counters.total_elements'`
- Verification coverage: !`reqvire coverage --json | jq -r '.summary.leaf_requirements_coverage_percentage'`%
- Unverified leaf requirements: !`reqvire coverage --json | jq -r '.summary.unverified_leaf_requirements'`
## User Request
${1:+Requirement name: $1}
${1:-The user will provide requirement details.}
## Steps
1. **Understand the context:**
- Ask user for requirement details (name, description) if not provided
- Identify parent requirement if this is a derived requirement
- Identify target file (user specifies or follows project conventions)
2. **Draft the requirement content:**
Follow EARS patterns for requirement statements:
- **Ubiquitous**: "The system shall [capability]"
- **Event-driven**: "when [trigger] the system shall [response]"
- **State-driven**: "while [state] the system shall [capability]"
- **Unwanted**: "if [condition] then the system shall [response]"
- **Optional**: "where [feature] the system shall [capability]"
Template:
```markdown
### Requirement Name
The system shall [capability/constraint following EARS patterns].
#### Metadata
* type: requirement
#### Relations
* derivedFrom: [Parent Requirement](path/to/parent.md#parent-requirement)
```
Optional details section for clarifications:
```markdown
#### Details
<details>
<summary>Additional Context</summary>
- Clarification points
- Rationale
- Examples
</details>
```
3. **Add the requirement using reqvire add command:**
```bash
reqvire add "<file-path>" <<'EOF'
### Requirement Name
The system shall [capability].
#### Metadata
* type: requirement
#### Relations
* derivedFrom: [Parent](path.md#parent)
EOF
```
Optional: Insert at specific position (0-based index):
```bash
reqvire add "<file-path>" 0 <<'EOF'
...
EOF
```
Alternative using pipe:
```bash
cat element.md | reqvire add "<file-path>"
```
The add command automatically:
- Validates markdown format
- Checks element name uniqueness
- Validates relation format
- Updates the file
4. **Check if verification is needed:**
- **Leaf requirement** (no derived children): Needs verification
- **Parent requirement** (has derived children): Verification rolls up from children
Run traces to check hierarchy:
```bash
reqvire traces --filter-name="<requirement-name>"
```
5. **Check coverage:**
```bash
reqvire coverage --filter-name="<requirement-name>"
```
6. **Next steps:**
- If **leaf requirement**: Suggest `/add-verification` to create verification
- If **parent requirement**: Explain verification will roll up from child requirements
## Element Manipulation
After adding requirements, you may need to reorganize:
**Move element to different file:**
```bash
reqvire mv "<element-name>" "<target-file>"
```
**Move element with specific position (0-based index):**
```bash
reqvire mv "<element-name>" "<target-file>" 0
```
**Remove element:**
```bash
reqvire rm "<element-name>"
```
## Best Practices
- **Atomic requirements**: One capability per requirement
- **Refinement in Details**: Clarifications go in `#### Details`, not new requirements
- **Leaf verification**: Only leaf requirements need direct verification
- **Roll-up coverage**: Parent requirements inherit verification from children
- **Clear**: Use ears patterns for consistency
- **Traceable**: Always link to parent via derivedFrom
- **Unique names**: Element names must be unique within each file
## Verification Philosophy
Reqvire uses **bottom roll-up verification coverage**:
- **Leaf requirements** must be verified directly
- **Parent requirements** inherit verification from their children
- High-level requirements are rarely verified directly
- Run `reqvire traces` to see verification roll-up structure
## Notes
- Element names become URL fragments (spaces → hyphens, lowercase)
- Use two-space indentation for Relations entries
- Use `#### Details` for refinements that don't add capabilities
- For complete feature (requirement + verification + test), use `/add-feature`

228
commands/add-verification.md Normal file
View File

@@ -0,0 +1,228 @@
---
allowed-tools: Read, Edit, Bash(reqvire:*)
argument-hint: [requirement-id]
description: Add a verification for an existing requirement, checking if verification is needed based on requirement hierarchy
model: claude-sonnet-4-5-20250929
---
# Add Verification
Add a verification for an existing requirement following Reqvire's bottom roll-up verification philosophy.
## Current Model Context
- Total verifications: !`reqvire search --json | jq -r '.global_counters.verifications'`
- Verification coverage: !`reqvire coverage --json | jq -r '.summary.leaf_requirements_coverage_percentage'`%
- Unverified leaf requirements: !`reqvire coverage --json | jq -r '.summary.unverified_leaf_requirements'`
## User Request
${1:+Requirement ID: $1}
${1:-The user will specify which requirement needs verification.}
## Steps
1. **Identify the requirement:**
- Ask user which requirement needs verification if not provided
- Get the requirement identifier or name
2. **Check if verification is needed:**
```bash
reqvire traces --filter-name="<requirement-name>"
```
Analyze the trace tree:
- **Leaf requirement** (no children): Needs direct verification
- **Parent requirement** (has children): Verification rolls up from children - usually no direct verification needed
3. **Check current coverage:**
```bash
reqvire coverage --filter-name="<requirement-name>"
```
4. **If leaf requirement needs verification:**
Choose verification type:
- **verification** (or test-verification): Automated testing
- **analysis-verification**: Mathematical/computational analysis
- **inspection-verification**: Manual inspection/review
- **demonstration-verification**: Operational demonstration
5. **Read all requirements in trace chain:**
For each requirement this verification will verify:
```bash
reqvire search --filter-id="<requirement-id>"
```
Extract:
- Requirement content (capabilities and constraints)
- All requirements in derivedFrom chain up to root
- Build complete understanding of what needs verification
6. **Draft verification content:**
Template for verification:
```markdown
### Verification Name
[Description of how ALL requirements in the trace chain will be verified]
#### Details
##### Acceptance Criteria
- [Criterion for leaf requirement 1]
- [Criterion for leaf requirement 2]
- [Criterion that verifies parent capabilities through leaf tests]
##### Test Criteria
- [How to test criterion 1]
- [How to test criterion 2]
- [Expected outcomes]
#### Metadata
* type: test-verification
#### Relations
* verify: [Leaf Requirement 1](../path/to/req1.md#leaf-requirement-1)
* verify: [Leaf Requirement 2](../path/to/req2.md#leaf-requirement-2)
* satisfiedBy: [test.sh](../../tests/test-name/test.sh)
```
Note: Only test-verification type can have satisfiedBy relations to test files.
7. **Add verification using reqvire add command:**
```bash
reqvire add "requirements/Verifications/<file>.md" <<'EOF'
### Verification Name
[Description of verification approach]
#### Details
##### Acceptance Criteria
- [What must be satisfied]
- [Functional criteria]
##### Test Criteria
- [How to verify]
- [Expected behavior]
#### Metadata
* type: test-verification
#### Relations
* verify: [Requirement](../path.md#requirement)
EOF
```
Optional: Insert at specific position (0-based index):
```bash
reqvire add "requirements/Verifications/<file>.md" 0 <<'EOF'
...
EOF
```
Alternative using pipe:
```bash
cat element.md | reqvire add "requirements/Verifications/<file>.md"
```
The add command automatically:
- Validates markdown format
- Checks element name uniqueness
- Validates relation format
- Updates the file
8. **Update the requirements with verifiedBy relations:**
Add `verifiedBy` relation to each verified requirement:
```markdown
#### Relations
* derivedFrom: [Parent](...)
* verifiedBy: [Verification Name](../Verifications/file.md#verification-name)
```
9. **Check updated coverage:**
```bash
reqvire coverage --filter-name="<requirement-name>"
```
10. **Verify roll-up and check for redundancies:**
```bash
reqvire traces --filter-name="<verification-name>"
reqvire lint --json > /tmp/lint.json
```
Check if verification creates redundant verify relations (verifying both leaf and parent).
## Element Manipulation
After adding verifications, you may need to reorganize:
**Move verification to different file:**
```bash
reqvire mv "<verification-name>" "requirements/Verifications/<file>.md"
```
**Move verification with specific position (0-based index):**
```bash
reqvire mv "<verification-name>" "<target-file>" 0
```
**Remove verification:**
```bash
reqvire rm "<verification-name>"
```
## Decision Logic
**If parent requirement with children:**
- Explain verification rolls up from children
- Show trace tree demonstrating coverage
- Usually no direct verification needed
**If leaf requirement without verification:**
- Read ALL requirements in trace chain
- Create verification with test criteria covering entire chain
- Link to requirement(s)
- Add test linkage ONLY if type is test-verification AND test exists
**If existing verification needs update:**
- Read all requirements currently verified
- Read all requirements in their trace chains
- Update test criteria to cover all requirements comprehensively
## Best Practices
- **Read trace chain**: Always read full requirement hierarchy to understand scope
- **Comprehensive criteria**: Test criteria must cover all verified requirements
- **Verify leaf requirements**: Focus on leaf-level verification
- **Roll-up coverage**: Parent requirements inherit from children
- **Avoid redundancy**: Don't verify both leaf and parent directly
- **Use traces**: Run `reqvire traces` to understand verification structure
- **Test links for test-verification only**: Only test-verifications link to test files
## Verification Types
- **test-verification**: Links to automated test files via satisfiedBy
- **analysis-verification**: No test linkage, verified through analysis
- **inspection-verification**: No test linkage, verified through manual inspection
- **demonstration-verification**: No test linkage, verified through demonstration
## Verification Philosophy
Reqvire uses **bottom roll-up verification**:
1. Verify leaf requirements directly
2. Parent requirements inherit coverage from children
3. One verification can verify multiple leaf requirements
4. Verification traces automatically propagate upward
5. Test criteria must cover ALL requirements in the trace chain
## Notes
- Verifications go in `requirements/Verifications/` directory
- Use two-space indentation for Relations entries
- Always read full trace chain before writing test criteria
- Run `reqvire lint --fix` after adding to remove redundancies
- Check `reqvire coverage` to confirm improvement

75
commands/analyze-coverage.md Normal file
View File

@@ -0,0 +1,75 @@
---
allowed-tools: Read, Bash(reqvire:*)
description: Analyze verification coverage and identify unverified requirements
model: claude-sonnet-4-5-20250929
---
# Analyze Verification Coverage
Analyze verification coverage to identify gaps and unverified requirements.
## Current Coverage
- Total requirements: !`reqvire coverage --json | jq -r '.summary.total_leaf_requirements'`
- Verified: !`reqvire coverage --json | jq -r '.summary.verified_leaf_requirements'`
- Coverage: !`reqvire coverage --json | jq -r '.summary.leaf_requirements_coverage_percentage'`%
- Unverified: !`reqvire coverage --json | jq -r '.summary.unverified_leaf_requirements'`
## Steps
1. **Generate coverage report:**
```bash
reqvire coverage
reqvire coverage --json > /tmp/coverage.json
```
2. **Analyze coverage statistics:**
- Extract total requirements count
- Calculate verification percentage
- Identify unverified requirements count
3. **Identify unverified leaf requirements:**
From coverage JSON:
```bash
jq '.unverified_leaf_requirements' /tmp/coverage.json
```
Focus on leaf requirements (requirements without derived children).
4. **Check if parent requirements need verification:**
For each unverified requirement:
```bash
reqvire traces --filter-name="<requirement-name>"
```
Determine:
- Is this a leaf requirement? (needs verification)
- Is this a parent requirement? (should inherit from children)
5. **Present findings:**
**Coverage Summary:**
- Total requirements: X
- Verified requirements: Y
- Coverage percentage: Z%
**Unverified Leaf Requirements:**
- [Requirement Name](file.md#requirement-name) - needs verification
- [Another Requirement](file.md#another) - needs verification
**Parent Requirements (OK - coverage rolls up):**
- [Parent Requirement](file.md#parent) - covered by children
6. **Provide recommendations:**
- List leaf requirements needing verifications
- Suggest using `/add-verification` for each
- Explain which parents are OK (inherit from children)
## Notes
- Focus on leaf requirements for verification
- Parent requirements inherit coverage from children
- Use `/add-verification` to create missing verifications
- Run `reqvire coverage` after adding verifications to confirm improvement

92
commands/analyze-impact.md Normal file
View File

@@ -0,0 +1,92 @@
---
allowed-tools: Read, Bash(reqvire:*), Bash(git:*)
argument-hint: [commit-hash]
description: Analyze change impact for modified requirements using git commit history
model: claude-sonnet-4-5-20250929
---
# Analyze Change Impact
Analyze how changes to requirements propagate through the model.
## Comparison Target
${1:+Comparing against: $1}
${1:-Comparing against: HEAD~1 (previous commit)}
## Steps
1. **Get base commit:**
${1:+Using provided commit: $1}
${1:-Ask user for commit hash or use default:}
```bash
# Compare against HEAD~1 (previous commit)
BASE_COMMIT="${1:-HEAD~1}"
# Or compare against specific commit
BASE_COMMIT="<commit-hash>"
# Or compare against base branch
BASE_COMMIT=$(git merge-base main HEAD)
```
2. **Run change impact analysis:**
```bash
reqvire change-impact --git-commit=${1:-HEAD~1}
reqvire change-impact --git-commit=${1:-HEAD~1} --json > /tmp/impact.json
```
3. **Analyze the results:**
Extract from JSON:
- `added_elements[]` - New requirements/verifications
- `modified_elements[]` - Changed requirements/verifications
- `affected_elements[]` - Elements impacted by changes
4. **For each modified requirement:**
```bash
reqvire search --filter-id="<requirement-id>"
reqvire traces --filter-id="<requirement-id>"
```
Identify:
- What changed in the requirement
- Which verifications verify this requirement
- Which implementations satisfy this requirement
- Which children derive from this requirement
5. **Present impact findings:**
**Added Elements:**
- [New Requirement](file.md#new-req) - type: requirement
**Modified Elements:**
- [Changed Requirement](file.md#changed) - review needed
**Affected Elements (propagation):**
- Verifications needing review: X
- Implementations needing update: Y
- Child requirements affected: Z
6. **Provide recommendations:**
- Review and update affected verifications
- Update test criteria if requirements changed
- Review implementations marked with satisfiedBy
- Run tests for affected verifications
- Update child requirements if parent semantics changed
## Change Propagation Rules
- **Parent → Child**: Parent changes propagate to all derived children
- **Requirement → Verification**: Requirement changes invalidate verifications
- **Requirement → Implementation**: May need implementation updates
- **Verification changes**: Generally don't propagate upward
## Notes
- Use for understanding impact before making changes
- Run after making changes to identify affected elements
- Focus on verifications - they need review when requirements change
- Use `/generate-tasks` to create implementation tasks from impact

71
commands/analyze-model.md Normal file
View File

@@ -0,0 +1,71 @@
---
allowed-tools: Read, Bash(reqvire:*)
description: Analyze the current Reqvire model structure, identify issues, coverage gaps, and provide improvement recommendations
model: claude-sonnet-4-5-20250929
---
# Analyze Reqvire Model
Perform comprehensive analysis of the current Reqvire model.
## Current Model State
- Validation status: !`reqvire validate 2>&1 | head -1`
- Total elements: !`reqvire search --json | jq -r '.global_counters.total_elements'`
- Verification coverage: !`reqvire coverage --json | jq -r '.summary.leaf_requirements_coverage_percentage'`%
- Test satisfaction: !`reqvire coverage --json | jq -r '.summary.test_verifications_satisfaction_percentage'`%
## Steps
1. **Remove diagrams to save tokens:**
```bash
reqvire remove-diagrams
```
2. **Run validation:**
```bash
reqvire validate --json > /tmp/validation.json
```
3. **Generate model search:**
```bash
reqvire search --short --json > /tmp/search.json
```
Use `--short` to get model structure without full content.
4. **Check coverage:**
```bash
reqvire coverage --json > /tmp/coverage.json
```
5. **Run lint checks:**
```bash
reqvire lint --json > /tmp/lint.json
```
6. **Analyze the results:**
- Review validation errors and warnings
- Identify unverified requirements from coverage report
- Check for model quality issues from lint report
- Calculate coverage percentages and statistics
7. **Provide recommendations:**
- List specific issues found with file locations
- Suggest improvements prioritized by impact
- Recommend commands to fix issues (e.g., `reqvire lint --fix`)
- Identify requirements needing verifications
## Output Format
Present findings in clear sections:
- **Validation Results**: Errors and warnings
- **Coverage Analysis**: Verification coverage statistics
- **Model Quality**: Lint findings (auto-fixable vs needs review)
- **Recommendations**: Prioritized action items
## Notes
- Always run `remove-diagrams` first to save context tokens
- Use `/tmp` for JSON outputs
- Focus on actionable recommendations

334
commands/consolidate.md Normal file
View File

@@ -0,0 +1,334 @@
---
allowed-tools: Read, Edit, Bash(reqvire:*)
description: Consolidate refinement-only child requirements into their parent requirements' Details sections to improve model organization
model: claude-sonnet-4-5-20250929
---
# Consolidate Requirements Model
Consolidate child requirements that only refine their parents (without introducing new capabilities) into the parent requirement's Details section. This improves model readability by merging implementation-level details into their conceptual parents while maintaining full traceability.
## When to Use
Use this command when:
- Model has grown with many small refinement requirements
- Child requirements only elaborate on implementation details of parents
- You want to reduce model clutter while preserving all information
- Requirements are split via derivedFrom relations but don't add new capabilities
## Consolidation Heuristics
A child requirement is a candidate for consolidation if it meets **multiple** of these criteria:
1. **Very similar names to parent** - e.g., parent: "HTML Export", child: "HTML Export Verification" or "Export Related System Elements"
2. **Short content** - Less than 200 words of requirement text (excluding relations)
3. **No verifications** - Has no verifiedBy relations of its own
4. **Implementation-level details** - Mentions specific technical details, file formats, parameters, or procedural steps
5. **Leaf requirement** - No children of its own, derives from only one parent
6. **Procedural/step-by-step details** - Contains "how-to" information that expands on parent
7. **Refinement keywords** - Contains phrases like "shall support", "shall provide", "shall include", "formatting", "structure", "output", "options", "flags"
## Process Overview
The consolidation follows this systematic approach:
1. **Identify Candidates**: Find parent-child pairs where child is refinement-only
2. **Merge Content**: Move child requirement content into parent's Details section
3. **Move Relations**: Transfer all child relations (satisfiedBy, verifiedBy, etc.) to parent
4. **Remove Child**: Delete the child requirement element entirely
5. **Update References**: Find and update all references to child to point to parent
6. **Validate**: Ensure no broken relations after consolidation
## Steps
### 1. Analyze Model for Candidates
First, analyze the model to identify consolidation candidates:
```bash
# Remove diagrams to save tokens
reqvire remove-diagrams
# Get model structure
reqvire search --short --json > /tmp/search.json
```
Review the model structure and identify parent-child requirement pairs based on:
- derivedFrom relationships
- Requirement naming patterns
- Content length and complexity
- Presence of verifications
### 2. Review and Prioritize Candidates
For each candidate family, document:
- **Parent requirement**: File location, section, heading
- **Child requirements**: List of elements to consolidate
- **Justification**: Which heuristics apply (similar names, short content, etc.)
- **Relations to move**: All satisfiedBy, verifiedBy, trace relations from children
- **References to update**: Other elements that reference the children
Prioritize by:
- **High priority**: Clear refinement patterns, minimal relations, obvious implementation details
- **Medium priority**: Mixed signals, moderate impact
- **Low priority**: Substantial content, many verifications, borderline cases
### 3. Execute Consolidation (Per Requirement Family)
For each requirement family to consolidate:
#### 3.1 Read Parent and Children
```bash
# Read the parent requirement file
Read requirements/path/to/ParentFile.md
# Read sections containing children if in different files
Read requirements/path/to/ChildFile.md
```
#### 3.2 Create Enhanced Parent Details
Edit the parent requirement to add consolidated content from children:
**Structure for consolidated Details section:**
```markdown
#### Details
[Existing parent details content]
**[Child 1 Heading]:**
[Child 1 description and key details]
[Child 1 specific details as subsections or bullets]
**[Child 2 Heading]:**
[Child 2 description and key details]
[Child 2 specific details as subsections or bullets]
```
**Example:**
```markdown
#### Details
The system shall provide formatting capability...
**Excess Whitespace:**
- Detect and fix excess whitespace after element headers
- Maintain consistent formatting across all requirements documents
**Inconsistent Newlines:**
- Detect and fix excess or missing newlines before element headers
- Normalize to exactly two newlines before subsections
```
#### 3.3 Merge Relations to Parent
Add all relations from children to the parent's Relations section:
```markdown
#### Relations
* derivedFrom: [Existing Parent Relations]
* satisfiedBy: [parent-file.rs]
* satisfiedBy: [child1-file.rs] # Moved from Child 1
* satisfiedBy: [child2-file.rs] # Moved from Child 2
* verifiedBy: [Parent Verification]
* verifiedBy: [Child Verification] # Moved from Child 1
```
#### 3.4 Remove Child Requirements
Delete each child requirement entirely (full H3 section including heading, content, metadata, relations, separator):
```markdown
### Child Requirement Name
[DELETE THIS ENTIRE SECTION]
---
```
#### 3.5 Update References to Children
Search for any elements that reference the removed children:
```bash
# Search for references to the child
reqvire search --filter-name="Child.*Name" --json
```
For each reference found, update it to point to the parent:
**Before:**
```markdown
* verifiedBy: [Child Requirement](File.md#child-requirement)
```
**After:**
```markdown
* verifiedBy: [Parent Requirement](File.md#parent-requirement)
```
#### 3.6 Validate After Each Family
```bash
# Validate model after consolidating each family
reqvire validate
# If validation passes, continue to next family
# If validation fails, fix broken references before continuing
```
### 4. Final Validation and Formatting
After all consolidations:
```bash
# Validate entire model
reqvire validate
# Format all files
reqvire format --fix
# Regenerate diagrams
reqvire generate-diagrams
# Final validation
reqvire validate
```
## Consolidation Examples
### Example 1: Format Implementation Family
**Before Consolidation:**
```markdown
### Format Consistency Enforcement
The system shall provide formatting capability...
#### Relations
* derivedFrom: [Model Formatting]
---
### Excess Whitespace Format Implementation
Detect and fix excess whitespace...
#### Relations
* derivedFrom: [Format Consistency Enforcement]
* satisfiedBy: [format.rs]
---
### Missing Separators Format Implementation
Detect consecutive element sections...
#### Relations
* derivedFrom: [Format Consistency Enforcement]
* satisfiedBy: [format.rs]
```
**After Consolidation:**
```markdown
### Format Consistency Enforcement
The system shall provide formatting capability...
#### Details
**Excess Whitespace:**
- Detect and fix excess whitespace after element headers
- Maintain consistent formatting
**Missing Separators:**
- Detect consecutive element sections that lack separators
- Insert separators to maintain consistent visual separation
#### Relations
* derivedFrom: [Model Formatting]
* satisfiedBy: [format.rs]
```
### Example 2: CLI Options Family
**Before:**
```markdown
### CLI Traces Command
The system shall implement traces subcommand...
#### Relations
* derivedFrom: [Verification Trace Builder]
---
### CLI Traces Filter Options
Support filtering verification traces...
#### Relations
* derivedFrom: [CLI Traces Command]
---
### CLI Traces From-Folder Option
Support --from-folder option...
#### Relations
* derivedFrom: [CLI Traces Command]
```
**After:**
```markdown
### CLI Traces Command
The system shall implement traces subcommand...
#### Details
[Original command details]
**Filter Options:**
The system shall support filtering verification traces by:
- --filter-id=<id>: Filter by verification element ID
- --filter-name=<regex>: Filter by name pattern
- --filter-type=<type>: Filter by verification type
**From-Folder Option:**
Support --from-folder option that specifies relative path for portable links:
- Accept relative path parameter
- Adjust clickable links in diagrams to be relative
- Work with both Markdown and JSON output
#### Relations
* derivedFrom: [Verification Trace Builder]
* satisfiedBy: [cli.rs]
```
## Best Practices
1. **Work incrementally**: Consolidate one requirement family at a time
2. **Validate frequently**: Run `reqvire validate` after each consolidation
3. **Preserve all information**: Don't lose any technical details during consolidation
4. **Maintain traceability**: Move ALL relations from children to parent
5. **Update references**: Search and fix all references to removed children
6. **Test thoroughly**: Ensure model validates and all links work after consolidation
7. **Document decisions**: Keep notes on which families were consolidated and why
## Anti-Patterns (When NOT to Consolidate)
Do NOT consolidate if:
- Child introduces **new functional capability** beyond parent
- Child has **extensive content** (>300 words) that would overwhelm parent Details
- Child has **many verifications** (3+) indicating significant independent functionality
- Child is referenced by **many other elements** as a key concept
- Child represents a **distinct abstraction level** (e.g., user requirement vs system requirement)
- There's **uncertainty** about whether child is truly refinement-only
## Expected Benefits
After consolidation, the model will have:
- **Reduced clutter**: Fewer top-level requirements to navigate
- **Better organization**: Implementation details nested under conceptual parents
- **Improved readability**: Related information grouped together
- **Maintained traceability**: All relations preserved through parent requirements
- **Cleaner structure**: Hierarchical organization matches conceptual dependencies
## Verification
After consolidation is complete, verify:
- ✅ Model validates with no errors: `reqvire validate`
- ✅ All relations are preserved (no missing targets)
- ✅ Verification coverage percentage unchanged or improved
- ✅ Test verifications still link correctly to requirements
- ✅ Diagrams generate without errors: `reqvire generate-diagrams`
- ✅ Documentation exports correctly: `reqvire export --html`

71
commands/find-redundant-verifications.md Normal file
View File

@@ -0,0 +1,71 @@
---
allowed-tools: Read, Bash(reqvire:*)
description: Find and analyze redundant verify relations in the Reqvire model
model: claude-sonnet-4-5-20250929
---
# Find Redundant Verify Relations
Analyze the verification traces to find redundant verify relations in the model.
## Current Status
- Auto-fixable issues: !`reqvire lint --json 2>&1 | jq -r '"\(if .auto_fixable then (.auto_fixable | length) else 0 end) (including redundant verifications)"'`
## Instructions
1. Run the lint command to find redundancies:
```bash
reqvire lint --json > /tmp/lint.json
```
2. Parse the JSON to find redundant verify relations:
```bash
jq -r '
.auto_fixable[] |
select(.type == "redundant_verify_relations") |
"## Verification: \(.verification.name)\n" +
"**File**: \(.verification.file)\n" +
"**Identifier**: `\(.verification.identifier)`\n\n" +
"**Redundant VERIFY Relations** (will be auto-removed with lint --fix):\n" +
(.redundant_relations[] | " * verify: \(.target)\n") +
"\n**Reason**: \(.rationale)\n\n" +
"---\n"
' /tmp/lint.json || echo "No redundant verify relations found."
```
3. Present the results to the user showing:
- Which verifications have redundant relations
- Which specific verify relations can be removed
- Explanation of why they're redundant
4. If no redundancies found, report: "No redundant verify relations found in the model."
5. **Auto-fix option:**
```bash
reqvire lint --fix
```
## Background
A verify relation is redundant when:
- A verification directly verifies both a child requirement AND its parent
- Since verification traces roll up automatically, verifying the child is sufficient
- The direct verification of the parent adds noise to the model
Example:
```
Verification "Password Test" verifies:
- "Password Strength" (leaf requirement)
- "Password Authentication" (parent of Password Strength)
→ The verify relation to "Password Authentication" is REDUNDANT
```
The system automatically detects this by building trace trees and checking if any ancestor requirements are also directly verified.
## Notes
- Use `reqvire lint --fix` to automatically remove redundant relations
- Redundant verify relations are always safe to remove
- Run `reqvire validate` after fixing to confirm model integrity

117
commands/generate-tasks.md Normal file
View File

@@ -0,0 +1,117 @@
---
allowed-tools: Read, Bash(reqvire:*), Bash(git:*)
argument-hint: [base-commit]
description: Generate implementation task plan from requirement changes using change-impact analysis
model: claude-sonnet-4-5-20250929
---
# Generate Tasks
Generate implementation task plan from requirement changes on a feature branch.
## Context
- Current branch: !`git rev-parse --abbrev-ref HEAD`
- Base commit: ${1:-!`git merge-base main HEAD 2>/dev/null || git merge-base master HEAD`}
## Steps
1. **Detect base branch:**
```bash
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
if git show-ref --verify --quiet refs/heads/main; then
BASE_BRANCH="main"
elif git show-ref --verify --quiet refs/heads/master; then
BASE_BRANCH="master"
else
echo "Specify base commit manually"
exit 1
fi
BASE_COMMIT="${1:-$(git merge-base $BASE_BRANCH HEAD)}"
```
2. **Run change impact:**
```bash
reqvire change-impact --git-commit=$BASE_COMMIT --json > /tmp/impact.json
```
3. **For each changed requirement:**
Get details:
```bash
reqvire search --filter-id="<requirement-id>" --json
```
Extract:
- Requirement content
- verifiedBy relations (tests to run)
- satisfiedBy relations (code to update)
- derivedFrom relations (context)
4. **For each verification:**
Get test paths:
```bash
reqvire search --filter-id="<verification-id>" --json
```
Extract satisfiedBy relations (test files).
5. **Generate TodoWrite task plan:**
**For new requirements:**
```
☐ Implement "{Requirement Name}" ({REQ-ID})
☐ Review requirement: [link to blob]
☐ Implement functionality
☐ Run tests: {test paths}
☐ Add satisfiedBy relation
☐ Validate: reqvire validate
```
**For modified requirements:**
```
☐ Update "{Requirement Name}" ({REQ-ID})
☐ Review changes: [link to blob]
☐ Review code: {satisfiedBy paths}
☐ Update implementation
☐ Run tests: {test paths}
☐ Validate: reqvire validate
```
6. **Generate git blob links:**
```bash
REPO_URL=$(git remote get-url origin | sed 's/\.git$//' | sed 's/git@github.com:/https:\/\/github.com\//')
BLOB_URL="${REPO_URL}/blob/${BASE_COMMIT}/${file_path}#${element-anchor}"
```
7. **Present task plan:**
- Phase 1: New requirements to implement
- Phase 2: Modified requirements to update
- Phase 3: Affected verifications to review
## Task Plan Structure
```markdown
# Implementation Task Plan
**Base**: {base_branch}@{base_commit}
**Feature**: {current_branch}
## Summary
- New requirements: X
- Modified requirements: Y
- Tests to run: Z
## Tasks
{TodoWrite formatted tasks}
```
## Notes
- Task plan uses TodoWrite format for tracking
- Links to exact requirement versions via git blob URLs
- Repository-agnostic: no technology assumptions
- Always read full requirements, not just summaries

74
commands/lint-model.md Normal file
View File

@@ -0,0 +1,74 @@
---
allowed-tools: Read, Bash(reqvire:*)
description: Lint and clean up the Reqvire model by fixing issues and identifying items needing review
model: claude-sonnet-4-5-20250929
---
# Lint Model
Lint the Reqvire model to fix quality issues and identify items needing manual review.
## Current Lint Status
- Auto-fixable: !`reqvire lint --json 2>&1 | jq -r '"\(if .auto_fixable then (.auto_fixable | length) else 0 end) issues"'`
- Manual review: !`reqvire lint --json 2>&1 | jq -r '"\(if .needs_manual_review then (.needs_manual_review | length) else 0 end) items"'`
## Steps
1. **Apply auto-fixes immediately:**
```bash
reqvire lint --fix
```
This automatically fixes:
- Syntax and formatting issues
- Redundant verify relations (verification verifying both leaf and parent)
- Safe redundant hierarchical relations (single-chain derivedFrom paths)
2. **Check for manual review items:**
```bash
reqvire lint --json > /tmp/lint.json
jq '.needs_manual_review' /tmp/lint.json
```
3. **For manual review items:**
Read affected specifications:
```bash
reqvire search --filter-id="<element-id>"
```
Provide recommendations:
- Show the potentially redundant relation
- Explain why it may be redundant
- Ask user if they want to remove it
4. **Validate after changes:**
```bash
reqvire validate
```
## Lint Categories
### Auto-Fixable (always safe to apply)
- **Redundant verify relations**: Verification verifies both leaf and parent requirement
- **Safe redundant hierarchical relations**: Single-chain derivedFrom paths that can be safely removed
### Needs Review (requires judgment)
- **Multi-branch convergence**: Element reaches ancestor through multiple distinct paths
- **Complex hierarchical relations**: Multi-path derivedFrom relations requiring human judgment
## Best Practices
- Run `reqvire lint --fix` after adding features
- Review manual items carefully before removing
- Validate model after manual changes
- Use after `/add-feature` or `/add-verification` to clean up
## Notes
- Auto-fixes are always safe - just apply them
- Manual review items need human judgment and context
- Run lint regularly to maintain model quality

151
commands/mv-file.md Normal file
View File

@@ -0,0 +1,151 @@
---
allowed-tools: Read, Bash(reqvire:*)
argument-hint: [source-file] [target-file]
description: Move entire specification file with all its elements to a new location
model: claude-sonnet-4-5-20250929
---
# Move File
Move an entire specification file with all its elements to a new location, automatically updating all relations that reference elements in the moved file.
## Current Model Context
- Total elements: !`reqvire search --json | jq -r '.global_counters.total_elements'`
## User Request
${1:+Source file: $1}
${2:+Target file: $2}
${1:-The user will provide source and target file paths.}
## Steps
1. **Understand the context:**
- Identify the source file to move
- Determine the target file location
- Verify source file exists in the model
2. **Preview the move operation:**
```bash
reqvire mv-file "<source-file>" "<target-file>" --dry-run
```
This shows:
- Which files will be modified
- How many elements will be moved
- What relations will be updated
- Git-style diffs for all affected files
3. **Apply the file move:**
```bash
reqvire mv-file "<source-file>" "<target-file>"
```
The mv-file command automatically:
- Moves all elements from source file to target file
- Updates all element identifiers to reflect new file path
- Updates all incoming relations (from other files) to reference new location
- Preserves all element content, metadata, and outgoing relations
- Deletes the source file after successful move
- Creates the target file with all moved elements
4. **Verify the changes:**
```bash
reqvire validate
```
## Important Notes
- **Path resolution**: File paths are resolved relative to current working directory
- **Automatic relation updates**: All relations pointing to moved elements are automatically updated throughout the model
- **Identifier updates**: Element identifiers change from `<source-file>#<slug>` to `<target-file>#<slug>`
- **Subdirectory support**: Works correctly when executed from subdirectories within git repository
- **Atomic operation**: Either all elements move successfully or none move (on validation failure)
## Squash Mode
When the target file already exists, use the **`--squash`** flag to merge all elements from source into the target file:
```bash
reqvire mv-file "<source-file>" "<existing-target-file>" --squash
```
**Squash behavior:**
- All source elements are appended to target file
- Target file's existing elements remain unchanged
- Source file is deleted after successful move
- All relations are updated throughout the model
**When to use --squash:**
- Consolidating multiple specification files into one
- Merging temporary/experimental specs back into main file
- Reorganizing model structure by combining related files
## Error Cases
The mv-file operation will fail with a clear error if:
- The source file does not exist or contains no elements
- The target file already exists in the model (unless --squash flag is provided)
- The operation would result in invalid model state
## Examples
**Move file within specifications directory:**
```bash
reqvire mv-file "requirements/OldFile.md" "requirements/NewFile.md"
```
**Move file to different directory:**
```bash
reqvire mv-file "requirements/Auth.md" "security/Authentication.md"
```
**Preview before moving:**
```bash
reqvire mv-file "specs/File.md" "requirements/File.md" --dry-run
```
**Get JSON output with element mappings:**
```bash
reqvire mv-file "old/path.md" "new/path.md" --json
```
**Works from subdirectories (paths relative to current directory):**
```bash
cd submodule/
reqvire mv-file "specs/File.md" "requirements/File.md"
```
**Squash elements from multiple files:**
```bash
# Merge experimental specs into main requirements
reqvire mv-file "temp/Experiments.md" "requirements/Requirements.md" --squash
```
**Preview squash before applying:**
```bash
reqvire mv-file "old/File.md" "requirements/MainFile.md" --squash --dry-run
```
## When to Use mv-file
Use mv-file when:
- Reorganizing specification file structure
- Moving all requirements for a feature to a different location
- Consolidating or splitting specification files
- Refactoring the model directory structure
Use mv-file with --squash when:
- Merging multiple specification files into one
- Consolidating temporary or experimental requirements back into main specs
- Simplifying model structure by reducing file count
**Note**: mv-file moves entire files with all their elements. To move individual elements between files, use `reqvire mv` instead.
## Related Commands
- **Move element**: `reqvire mv <element-name> <target-file>`
- **Rename element**: `reqvire rename <current-name> <new-name>`
- **Remove element**: `reqvire rm <element-name>`
- **Add element**: `reqvire add <file> < element.md`

115
commands/mv.md Normal file
View File

@@ -0,0 +1,115 @@
---
allowed-tools: Read, Bash(reqvire:*)
argument-hint: <element-name> <file> [index]
description: Move an element to a different file or position
model: claude-sonnet-4-5-20250929
---
# Move Element
Move an existing model element to a different file or position within the model.
## Current Model Context
- Total elements: !`reqvire search --json | jq -r '.global_counters.total_elements'`
## User Request
${1:+Element name: $1}
${1:-The user will provide element name and target location.}
## Steps
1. **Understand the context:**
- Identify the element to move (by name)
- Determine the target location (file and/or index)
- Verify element exists in the model
2. **Preview the move operation:**
```bash
reqvire mv "<element-name>" "<target-file>" --dry-run
```
This shows:
- Which files will be modified
- Where the element will be moved
- What relations will be updated
- Git-style diffs for all affected files
3. **Apply the move:**
```bash
reqvire mv "<element-name>" "<target-file>"
```
The mv command automatically:
- Removes element from source file
- Adds element to target file
- Updates the element identifier to reflect new location
- Updates all forward relations (from the element to others)
- Updates all backward relations (from other elements to this one)
- Maintains model consistency
4. **Verify the changes:**
```bash
reqvire validate
```
## Important Notes
- **Global uniqueness**: Element names are globally unique, so you only need the element name
- **Path resolution**: File paths are resolved relative to current working directory
- **Automatic relation updates**: All relations throughout the model are automatically updated
- **Identifier update**: Element identifier changes from `<old-file>#<slug>` to `<new-file>#<slug>`
## Move Options
- `<element-name>`: Name of element to move (required)
- `<file>`: Target file path (required)
- `[index]`: Position within target file (0-based, default: append to end)
- `--dry-run`: Preview changes without applying
- `--json`: Output results in JSON format
## Error Cases
The mv operation will fail with a clear error if:
- The element name does not exist
- The target file does not exist (must exist in git)
- The operation would result in invalid model state
## Examples
**Move element to different file:**
```bash
reqvire mv "User Authentication" "requirements/Security.md"
```
**Insert at specific position (index 0 = first element in file):**
```bash
reqvire mv "High Priority Req" "requirements/Critical.md" 0
```
**Preview before moving:**
```bash
reqvire mv "Feature X" "NewFile.md" --dry-run
```
**Get JSON output:**
```bash
reqvire mv "Element" "File.md" --json
```
## When to Use mv
Use mv when:
- Moving individual requirements or verifications between files
- Reorganizing elements within specification structure
- Reordering elements within files
**Note**: To move entire files with all their elements, use `reqvire mv-file` instead.
## Related Commands
- **Move file**: `reqvire mv-file <source-file> <target-file>`
- **Rename element**: `reqvire rename <current-name> <new-name>`
- **Remove element**: `reqvire rm <element-name>`
- **Add element**: `reqvire add <file> < element.md`

101
commands/rename-element.md Normal file
View File

@@ -0,0 +1,101 @@
---
allowed-tools: Read, Bash(reqvire:*)
argument-hint: [current-name] [new-name]
description: Rename an existing element while updating all relations that reference it
model: claude-sonnet-4-5-20250929
---
# Rename Element
Rename an existing model element while automatically updating all relation references throughout the model.
## Current Model Context
- Total elements: !`reqvire search --json | jq -r '.global_counters.total_elements'`
## User Request
${1:+Current element name: $1}
${2:+New element name: $2}
${1:-The user will provide element names.}
## Steps
1. **Understand the context:**
- Identify the element to rename (current name)
- Determine the new name
- Verify element exists in the model
2. **Preview the rename operation:**
```bash
reqvire rename "<current-name>" "<new-name>" --dry-run
```
This shows:
- Which files will be modified
- What relations will be updated
- The identifier change (old → new)
3. **Apply the rename:**
```bash
reqvire rename "<current-name>" "<new-name>"
```
The rename command automatically:
- Updates the element's heading text in the markdown file
- Updates the element identifier in the registry
- Updates all forward relations (from the element to others)
- Updates all backward relations (from other elements to this one)
- Maintains model consistency
4. **Verify the changes:**
```bash
reqvire validate
```
## Important Notes
- **Global uniqueness**: Element names are globally unique in Reqvire, so you only need the element name (not the full file path identifier)
- **Automatic relation updates**: All relations throughout the model are automatically updated
- **Identifier format**: The element identifier changes from `<file>#<old-name-slug>` to `<file>#<new-name-slug>`
- **Name slugification**: Element names are converted to slugs (lowercase, spaces → hyphens) for identifiers
## Error Cases
The rename operation will fail with a clear error if:
- The current element name does not exist
- The new name conflicts with an existing element
- Multiple elements have the same name (should not happen due to uniqueness constraint)
## Examples
**Rename a requirement:**
```bash
reqvire rename "User Authentication" "User Login Authentication"
```
**Preview before renaming:**
```bash
reqvire rename "Data Storage" "Persistent Data Storage" --dry-run
```
**Get JSON output:**
```bash
reqvire rename "Old Feature" "New Feature" --json
```
## When to Use Rename
Use rename when:
- A requirement or verification needs a better name
- Terminology changes in the project
- Consolidating or clarifying element names
- Refactoring the model structure
**Note**: Rename only changes the element name and heading. To move an element to a different file, use `reqvire mv` instead.
## Related Commands
- **Move element**: `reqvire mv <element-name> <target-file>`
- **Remove element**: `reqvire rm <element-name>`
- **Add element**: `reqvire add <file> < element.md`

113
commands/rm.md Normal file
View File

@@ -0,0 +1,113 @@
---
allowed-tools: Read, Bash(reqvire:*)
argument-hint: [element-name]
description: Remove an element from the model
model: claude-sonnet-4-5-20250929
---
# Remove Element
Remove an existing model element from the specifications.
## Current Model Context
- Total elements: !`reqvire search --json | jq -r '.global_counters.total_elements'`
## User Request
${1:+Element name: $1}
${1:-The user will provide element name to remove.}
## Steps
1. **Understand the context:**
- Identify the element to remove (by name)
- Verify element exists in the model
- Check if other elements have relations to this element
2. **Preview the remove operation:**
```bash
reqvire rm "<element-name>" --dry-run
```
This shows:
- Which file will be modified
- The element that will be removed
- Git-style diff showing the deletion
3. **Apply the removal:**
```bash
reqvire rm "<element-name>"
```
The rm command automatically:
- Removes the element from its markdown file
- Removes the element from the model registry
- Deletes all relations from this element
- **Note**: Does NOT automatically update relations FROM other elements TO this element (you may need to clean those up)
4. **Verify the changes:**
```bash
reqvire validate
```
**Important**: After removing an element, validation may show errors if other elements still reference the removed element. You'll need to manually update or remove those relations.
## Important Notes
- **Global uniqueness**: Element names are globally unique, so you only need the element name
- **Relations cleanup**: The removed element's outgoing relations are deleted, but incoming relations (from other elements) are NOT automatically removed
- **Validation warnings**: Removing elements that are referenced by others will cause validation errors
- **Breaking changes**: Removing requirements or verifications can break traceability chains
## Remove Options
- `--dry-run`: Preview changes without applying
- `--json`: Output results in JSON format
## Error Cases
The rm operation will fail with a clear error if:
- The element name does not exist
- Multiple elements have the same name (should not happen due to uniqueness constraint)
## Examples
**Remove a requirement:**
```bash
reqvire rm "Deprecated Feature"
```
**Preview before removing:**
```bash
reqvire rm "Old Requirement" --dry-run
```
**Get JSON output:**
```bash
reqvire rm "Obsolete Element" --json
```
## When to Use rm
Use rm when:
- Removing deprecated or obsolete requirements
- Cleaning up test elements
- Removing duplicate or incorrect entries
- Refactoring the model structure
**Warning**: Be careful when removing elements that are referenced by other elements, as this will break those relations and cause validation errors.
## Cleanup After Removal
After removing an element, you may need to:
1. Find elements that referenced the removed element (validation will show these)
2. Update or remove those relations manually
3. Re-run validation to ensure model consistency
## Related Commands
- **Move element**: `reqvire mv <element-name> <target-file>`
- **Rename element**: `reqvire rename <current-name> <new-name>`
- **Add element**: `reqvire add <file> < element.md`
- **Search elements**: `reqvire search --filter-name="<pattern>"`