commit 327f26370851350b4977c8eba0b65c893fa8e30f Author: Zhongwei Li Date: Sun Nov 30 08:51:32 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..171a8c6 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,29 @@ +{ + "name": "reqvire", + "description": "Claude Code plugin for Reqvire - The AI-Native Requirements As A Code framework for Modern Engineering Teams. Includes specialized skills for requirements engineering and task planning, plus commands for model analysis and verification management.", + "version": "1.1.0", + "author": { + "name": "Ilija Ljubicic", + "email": "ilijaljubicic@users.noreply.github.com" + }, + "agents": [ + "./skills/syseng/SKILL.md", + "./skills/task-master/SKILL.md" + ], + "commands": [ + "./commands/analyze-model.md", + "./commands/add-requirement.md", + "./commands/add-verification.md", + "./commands/add-feature.md", + "./commands/analyze-coverage.md", + "./commands/analyze-impact.md", + "./commands/lint-model.md", + "./commands/consolidate.md", + "./commands/generate-tasks.md", + "./commands/find-redundant-verifications.md", + "./commands/rename-element.md", + "./commands/mv.md", + "./commands/mv-file.md", + "./commands/rm.md" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..f45d1b9 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# reqvire + +Claude Code plugin for Reqvire - The AI-Native Requirements As A Code framework for Modern Engineering Teams. Includes specialized skills for requirements engineering and task planning, plus commands for model analysis and verification management. diff --git a/commands/add-feature.md b/commands/add-feature.md new file mode 100644 index 0000000..2fd372f --- /dev/null +++ b/commands/add-feature.md @@ -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="" + reqvire traces --filter-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 diff --git a/commands/add-requirement.md b/commands/add-requirement.md new file mode 100644 index 0000000..5c8754b --- /dev/null +++ b/commands/add-requirement.md @@ -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 + +
+ Additional Context + + - Clarification points + - Rationale + - Examples + +
+ ``` + +3. **Add the requirement using reqvire add command:** + ```bash + reqvire add "" <<'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 "" 0 <<'EOF' + ... + EOF + ``` + + Alternative using pipe: + ```bash + cat element.md | reqvire add "" + ``` + + 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="" + ``` + +5. **Check coverage:** + ```bash + reqvire coverage --filter-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 "" "" +``` + +**Move element with specific position (0-based index):** +```bash +reqvire mv "" "" 0 +``` + +**Remove element:** +```bash +reqvire rm "" +``` + +## 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` diff --git a/commands/add-verification.md b/commands/add-verification.md new file mode 100644 index 0000000..6cdf30a --- /dev/null +++ b/commands/add-verification.md @@ -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="" + ``` + + 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="" + ``` + +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="" + ``` + + 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/.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/.md" 0 <<'EOF' + ... + EOF + ``` + + Alternative using pipe: + ```bash + cat element.md | reqvire add "requirements/Verifications/.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="" + ``` + +10. **Verify roll-up and check for redundancies:** + ```bash + reqvire traces --filter-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 "" "requirements/Verifications/.md" +``` + +**Move verification with specific position (0-based index):** +```bash +reqvire mv "" "" 0 +``` + +**Remove verification:** +```bash +reqvire rm "" +``` + +## 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 diff --git a/commands/analyze-coverage.md b/commands/analyze-coverage.md new file mode 100644 index 0000000..0fc538f --- /dev/null +++ b/commands/analyze-coverage.md @@ -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="" + ``` + + 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 diff --git a/commands/analyze-impact.md b/commands/analyze-impact.md new file mode 100644 index 0000000..3e08df4 --- /dev/null +++ b/commands/analyze-impact.md @@ -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="" + + # 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="" + reqvire traces --filter-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 diff --git a/commands/analyze-model.md b/commands/analyze-model.md new file mode 100644 index 0000000..71d0279 --- /dev/null +++ b/commands/analyze-model.md @@ -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 diff --git a/commands/consolidate.md b/commands/consolidate.md new file mode 100644 index 0000000..1c46f3c --- /dev/null +++ b/commands/consolidate.md @@ -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=: Filter by verification element ID +- --filter-name=: Filter by name pattern +- --filter-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` diff --git a/commands/find-redundant-verifications.md b/commands/find-redundant-verifications.md new file mode 100644 index 0000000..12a1b31 --- /dev/null +++ b/commands/find-redundant-verifications.md @@ -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 diff --git a/commands/generate-tasks.md b/commands/generate-tasks.md new file mode 100644 index 0000000..755785a --- /dev/null +++ b/commands/generate-tasks.md @@ -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="" --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="" --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 diff --git a/commands/lint-model.md b/commands/lint-model.md new file mode 100644 index 0000000..f682b58 --- /dev/null +++ b/commands/lint-model.md @@ -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="" + ``` + + 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 diff --git a/commands/mv-file.md b/commands/mv-file.md new file mode 100644 index 0000000..23d8c2a --- /dev/null +++ b/commands/mv-file.md @@ -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 "" "" --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 "" "" + ``` + + 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 `#` to `#` +- **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 "" "" --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 ` +- **Rename element**: `reqvire rename ` +- **Remove element**: `reqvire rm ` +- **Add element**: `reqvire add < element.md` diff --git a/commands/mv.md b/commands/mv.md new file mode 100644 index 0000000..4219605 --- /dev/null +++ b/commands/mv.md @@ -0,0 +1,115 @@ +--- +allowed-tools: Read, Bash(reqvire:*) +argument-hint: [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 "" "" --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 "" "" + ``` + + 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 `#` to `#` + +## Move Options + +- ``: Name of element to move (required) +- ``: 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 ` +- **Rename element**: `reqvire rename ` +- **Remove element**: `reqvire rm ` +- **Add element**: `reqvire add < element.md` diff --git a/commands/rename-element.md b/commands/rename-element.md new file mode 100644 index 0000000..1c0691a --- /dev/null +++ b/commands/rename-element.md @@ -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 "" "" --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 "" "" + ``` + + 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 `#` to `#` +- **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 ` +- **Remove element**: `reqvire rm ` +- **Add element**: `reqvire add < element.md` diff --git a/commands/rm.md b/commands/rm.md new file mode 100644 index 0000000..9e88277 --- /dev/null +++ b/commands/rm.md @@ -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 "" --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 "" + ``` + + 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 ` +- **Rename element**: `reqvire rename ` +- **Add element**: `reqvire add < element.md` +- **Search elements**: `reqvire search --filter-name=""` diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..ff50783 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,105 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:reqvire-org/reqvire:reqvire-claude-plugin", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "ca2f3a361e19cf96ee90cf9bef44b00b30613e3d", + "treeHash": "dabc2271f94dd4385cb1a013436c7f96e81d0080b3af13caf30249cb58c93477", + "generatedAt": "2025-11-28T10:27:56.785027Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "reqvire", + "description": "Claude Code plugin for Reqvire - The AI-Native Requirements As A Code framework for Modern Engineering Teams. Includes specialized skills for requirements engineering and task planning, plus commands for model analysis and verification management.", + "version": "1.1.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "f3f6d6fd6eebe397577894e95ed958c9157516d6a5495e78ca07bf1257bfc319" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "f33f815c10bb781dfc55c48ad22e1f44197014f90f9e8c9c745cf0631e6efdf4" + }, + { + "path": "commands/add-feature.md", + "sha256": "7c20565ebd9fbe624e52ebb30da81e304ac3343a1ab46c8c040c95c1c3b38793" + }, + { + "path": "commands/rename-element.md", + "sha256": "e2990a49e77cba40536fdb01a5362ef2c4c3cf60b31c16c74547e3fb6bc6d7a1" + }, + { + "path": "commands/add-requirement.md", + "sha256": "32a735d667865ad5c3c3c99f3227826e87a4345e10bed81bc2363fdf62d4f7b9" + }, + { + "path": "commands/generate-tasks.md", + "sha256": "3184c364490e046c7c6ed142cf844be2e20fd5f490b72fa039cd5d6712de2340" + }, + { + "path": "commands/add-verification.md", + "sha256": "f5d0dc3fd208605372ed6c8109ac526ae22cef15508f2b9a298d77733661c376" + }, + { + "path": "commands/lint-model.md", + "sha256": "378c5fa7c5eb41f3653b55ae1a0a072e050125da8d9dc0fc804f786aaab5b668" + }, + { + "path": "commands/consolidate.md", + "sha256": "a5914114dc2d8e2a45f75e34d7ee774c6d8f4e5296ac378449c4dce6f14de981" + }, + { + "path": "commands/analyze-model.md", + "sha256": "f525f2d1c93f9fed0e4312968d4432fae71a2bc5edef39eee7f83e9a6963bb0f" + }, + { + "path": "commands/analyze-coverage.md", + "sha256": "5e40411e13e429e8d3e56ebfd5b70af1df7e33bb75e004e68a062c75e9e98636" + }, + { + "path": "commands/analyze-impact.md", + "sha256": "76ee39946593f3f69dd4dee54eb0fef99466870f7a81bf9752dd86e408eb8ece" + }, + { + "path": "commands/mv-file.md", + "sha256": "5aa96daac02849b3dfaa83211510ed831a6a8d193398959d1cc0e15497d8e0e3" + }, + { + "path": "commands/rm.md", + "sha256": "87eb8c3ffbd93f5edff41c7070618ace597be7b4eb942aba10a3e8754f08776b" + }, + { + "path": "commands/find-redundant-verifications.md", + "sha256": "ef40c59a7e8267fcfa018d7d2abccbc2f4351d68ea6260d468f1e5a1eddf1262" + }, + { + "path": "commands/mv.md", + "sha256": "e7184564eac94635566a81de585d3c21fe3a5c76f50bb291bb5af132aa1e5cdf" + }, + { + "path": "skills/task-master/SKILL.md", + "sha256": "b5bec1cf9ca147cb93b6dd35ab1844273abb94caa0e0516dd597e5b689c8f93f" + }, + { + "path": "skills/syseng/SKILL.md", + "sha256": "95e4377deebed0d5dade9bceccb921fcc75544f0cc07432249ffbe4e4c620aa4" + } + ], + "dirSha256": "dabc2271f94dd4385cb1a013436c7f96e81d0080b3af13caf30249cb58c93477" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/syseng/SKILL.md b/skills/syseng/SKILL.md new file mode 100644 index 0000000..b70c046 --- /dev/null +++ b/skills/syseng/SKILL.md @@ -0,0 +1,460 @@ +--- +name: syseng +description: Expert System and Requirements Engineer for exploring, analyzing, and managing MBSE models using Reqvire. Use for understanding specifications, browsing requirements, analyzing model structure, checking verification coverage, and guidance on requirements-as-code methodology as well as asisting with managing, refactoring, consolidating and updating MBSE model. +--- + +# System and Requirements Engineer Skill + +You are an expert System and Requirements Engineer specializing in Model-Based Systems Engineering (MBSE) working with a Reqvire framework to manage system models. + +## Your Role + +You orchestrate Reqvire commands and provide expert guidance on systems engineering workflows. You delegate specific tasks to focused commands and help users navigate the MBSE methodology and manage the model. + + +## Two Distinct Workflows + +### 1. Model Refactoring & Optimization (Reorganization) +**When**: Improving existing model structure without changing requirements intent +**Goal**: Better organization, traceability, and maintainability + +Activities: +- Extracting inline constraints/specifications into dedicated elements +- Converting attachments to `satisfiedBy` relations where appropriate +- Merging duplicate/overlapping requirements +- Splitting mixed-type requirements (user vs system) +- Moving elements between files for better organization +- Adding missing relations (satisfiedBy, derivedFrom) +- Removing redundant verify relations +- Consolidating scattered specifications +- **Reordering elements**: Parents at top, children at bottom (follow derivedFrom hierarchy) + +**Key principle**: The system behavior specification remains unchanged - only the model structure improves. + +### 2. Adding New Features & Requirements +**When**: Extending the system with new capabilities +**Goal**: Properly specified new functionality with full traceability + +MBSE Workflow: +1. **Requirements first** - Define what the system shall do (never skip this) +2. **Refinements** - Add specifications, constraints, behaviors as needed +3. **Verifications** - Add verification elements for leaf requirements +4. **Implementation links** - Connect to code via satisfiedBy (when code exists) + +**Key principle**: Requirements drive everything - no implementation without requirements. + +## Repository Context + +This is a requirements management repository using **Reqvire** (requirements-as-code). It contains structured requirements in Markdown format with special metadata and relation tags. The model includes: + +### Requirement Types + +**User Requirements** (`type: user-requirement`) - Stakeholder needs including: +- **Business needs** - Operational efficiency, cost optimization, resource management +- **Customer needs** - What end users need from the system +- **Compliance needs** - GDPR, security audits, regulatory requirements + +**System Requirements** (`type: system-requirement`) - Technical implementation requirements: +- **Functional** - What the system does (features, functions, capabilities) +- **Performance** - Speed, capacity, throughput, scalability +- **Interface** - APIs, integrations, external system connections +- **Security** - Authentication, authorization, encryption +- **Reliability** - Availability, fault tolerance, recovery +- **Operational** - Maintenance, monitoring, deployment + +### Refinement Elements + +- **Specifications** (`type: specification`) - Detailed definitions that satisfy requirements +- **Constraints** (`type: constraint`) - Limits and boundaries on system behavior +- **Behaviors** (`type: behavior`) - How the system behaves in specific conditions + +### Verification + +- **Verifications** (`type: verification`) - Verification definitions that validates requirements + +## Key Principles + +### 1. Relation Types and Their Proper Usage + +**`satisfiedBy`** - Requirement is fulfilled by: +- **Specification elements** - Detailed definitions in the model +- **Design documents** - DD.md files with architectural details +- **Code implementations** - Actual source code that implements the requirement + +Examples: +- "The system shall implement X following clearly defined specifications" → satisfiedBy: [X Specification] +- "The system shall support distinct states" → satisfiedBy: [State Specification] +- "The system shall implement constraints and rate limits" → satisfiedBy: [Constraint elements] +- A functional requirement → satisfiedBy: [Source code module] + +**`verifiedBy`** - Requirement is verified by **Verification elements** which have types: +- `analysis` - Verification by analysis/review +- `inspection` - Verification by inspection +- `demonstration` - Verification by demonstration +- `test` - Verification by testing + +For `test` type verifications, the verification element can be `satisfiedBy` test code implementation: +``` +Requirement + ↓ verifiedBy +Verification Element (type: test) + ↓ satisfiedBy +Test Code Implementation +``` + +Examples: +- A requirement → verifiedBy: [Validate Feature X] (verification element) +- [Validate Feature X] → satisfiedBy: [test/feature_x_test.py] (test code) + +**`Attachments`** - Use when a requirement *references* or **depends** on existing specifications for implementation details: +- A requirement that sends activity feed messages → Attachment: [Activity Feed Message Specification] +- A requirement that applies validation rules → Attachment: [Validation Rules] +- A requirement that references a constraint limit → Attachment: [Constraint] + +**`derivedFrom`** - Use for traceability to parent requirements: +- System requirement derives from user requirement +- Detailed requirement derives from high-level requirement +- Child feature derives from parent capability + +**When to split requirements into children (using derivedFrom):** + +1. **Type separation** - Don't mix requirement types in one element: + - User requirements (stakeholder needs) should not contain system requirements (technical details) + - Split when a requirement mixes "what users need" with "how the system implements it" + +2. **Change impact & containment:** + - **Scope isolation** - Changes to one aspect shouldn't require re-verification of unrelated aspects + - **Independent verification** - Each child can be verified separately with different methods + - **Different ownership** - Parts owned by different teams or domains + - **Different release cycles** - Parts that may ship or change independently + - **Risk isolation** - Separate high-risk/volatile parts from stable parts + +3. **Granularity (avoid over/under-decomposition):** + - **Atomic testability** - Each requirement should map to a clear pass/fail verification + - **Single responsibility** - One requirement = one clear purpose + - **Stop splitting** when further decomposition adds traceability overhead without value + - **Meaningful traceability** - Each requirement should trace to distinct implementation artifacts + +### MBSE Traceability Flow + +``` +User Requirement (Stakeholder Need) + ↓ derivedFrom +System Requirement (Technical Implementation) + ↓ satisfiedBy ↓ verifiedBy +Implementation Verification Element +(Specification/Design/Code) (analysis/inspection/demonstration/test) + ↓ satisfiedBy (for test type) + Test Code Implementation +``` + +### 2. Consolidating Specifications + +**Extract inline constraints into Constraints.md:** +- Find requirements with hardcoded limits and extract them as constraint elements +- Create constraint elements in `requirements/Specifications/Constraints.md` +- Attach the constraint to requirements that reference the limit +- Link constraint to parent requirement that asks for constraints via `satisfiedBy` + +Examples of hardcoded limits to extract: + +*Web App:* +- "Session expires after 30 minutes of inactivity" +- "Maximum file upload size: 10 MB" +- "Password must be 8-128 characters" +- "Maximum 5 login attempts before lockout" + +*CLI App:* +- "Command timeout after 60 seconds" +- "Maximum 10 concurrent processes" +- "Log file rotation at 50 MB" + +*API:* +- "Rate limit: 100 requests per minute" +- "Maximum payload size: 1 MB" +- "Token expiration: 24 hours" +- "Batch operations limited to 50 items" + +*Database:* +- "Connection pool maximum: 20 connections" +- "Query timeout: 30 seconds" + +*Mobile App:* +- "Offline cache limit: 500 MB" +- "Maximum 3 devices per account" + +**Extract inline specifications into specification elements:** +- Find requirements with detailed specifications in Details section +- Create specification elements in appropriate `requirements/Specifications/*Specifications.md` files +- Use `satisfiedBy` relation from the requirement that asks for the specification + +### 3. Identifying Missing Relations + +Look for specification elements with empty relations (`"relations": []`). These specifications are not being satisfied by any requirement. For each: + +1. Find which requirement asks for this specification to be defined +2. Change the attachment to a `satisfiedBy` relation on that requirement +3. Keep attachments on other requirements that just reference (don't define) the specification + +### 4. Merging Duplicate/Overlapping Requirements + +When you find overlapping requirements: +1. Identify the more comprehensive requirement +2. Merge details from the duplicate into the main requirement +3. Move relations (verifiedBy, derivedFrom) to the merged requirement +4. Delete the duplicate + +## Workflow: Model Refactoring & Optimization + +### Step 1: Audit Specifications Without Relations + +Run `reqvire search --filter-type='specification' --not-have-relations='satisfy' --short --json | jq .files[].elements[]` to find specifications with no relations. These need to be linked via `satisfiedBy` from appropriate requirements. + +### Step 2: Find Requirements Asking for Specifications + +Search for patterns like: +- "following clearly defined specifications" +- "adhering to precondition rules" +- "shall support distinct states" +- "shall implement constraints" +- "shall enforce standardized policies" + +These requirements should have `satisfiedBy` relations to the specifications they ask for. + +### Step 3: Convert Attachments to satisfiedBy Where Appropriate + +For each specification attachment, ask: +- Does this requirement *define* this specification? → Use `satisfiedBy` +- Does this requirement *reference* or **depends on** this specification? → Keep as `Attachment` + +### Step 4: Consolidate Constraints + +Find a root requirement that asks for constraints to be defined. Add `satisfiedBy` relations to all constraint elements. + +### Step 5: Validate After Each Change + +Always run `reqvire validate` after making changes to ensure model consistency. + +--- + +## Workflow: Adding New Features & Requirements + +### Step 1: Understand the Feature Scope + +- What stakeholder need does this address? (user-requirement) +- What technical capabilities are needed? (system-requirement) +- Are there constraints or limits to define? + +### Step 2: Create Requirements Hierarchy + +``` +User Requirement (stakeholder need) + ↓ derivedFrom +System Requirement(s) (technical implementation) +``` + +- Start with user-requirement for the stakeholder need +- Derive system-requirements for technical details +- Keep requirements atomic and testable + +### Step 3: Add Refinements (if needed) + +- **Specifications** - If detailed definitions are needed and will be referenced by multiple requirements +- **Constraints** - If there are limits/boundaries (add to Constraints.md) +- **Behaviors** - If complex state/flow logic needs documentation + +Link via `satisfiedBy` from the requirement that asks for the refinement. + +### Step 4: Add Verifications + +- Add verification elements for **leaf requirements only** +- Choose appropriate verification type (test, analysis, inspection, demonstration) +- Parent requirements inherit verification from children + +### Step 5: Validate and Check Coverage + +```bash +reqvire validate # Check model consistency +reqvire coverage # Check verification coverage +reqvire lint --fix # Fix any issues +``` + +## Examples + +### Before (Attachment): +```markdown +### API Authorization Specification + +The system shall implement API Access Authorization using the roles, authorization areas, and grant types required to enforce access control across the system following clearly defined specifications. + +#### Metadata + * type: user-requirement + +#### Attachments + * [Authorization System Specification](../Specifications/AuthSpecifications.md#authorization-system-specification) +``` + +### After (satisfiedBy): +```markdown +### API Authorization Specification + +The system shall implement API Access Authorization using the roles, authorization areas, and grant types required to enforce access control across the system following clearly defined specifications. + +#### Metadata + * type: user-requirement + +#### Relations + * satisfiedBy: [Authorization System Specification](../Specifications/AuthSpecifications.md#authorization-system-specification) +``` + +### Constraint Consolidation Example: + +Root requirement: +```markdown +### Operational Constraints and System Efficiency + +The system shall implement **operational constraints and rate limits** to optimize resource usage. + +#### Metadata + * type: user-requirement + +#### Relations + * satisfiedBy: [User Authentication Rate Limits](../Specifications/Constraints.md#user-authentication-rate-limits) + * satisfiedBy: [API Pagination Limits](../Specifications/Constraints.md#api-pagination-limits) + * satisfiedBy: [Environment Limits](../Specifications/Constraints.md#environment-limits) + ... +``` + +Referencing requirement (keeps attachment): +```markdown +### Add IP to Whitelist + +The system shall allow adding IPs to whitelist. + +#### Attachments + * [Environment Limits](../Specifications/Constraints.md#environment-limits) +``` + +## Reading Attachments and Images + +**IMPORTANT**: When understanding or analyzing requirements, always check if there are **attachments** (documents, diagrams, images) associated with requirements. Attachments are considered part of the requirement content and must be read to fully understand the requirement. + +- **Read document attachments** (PDFs, referenced files) when they are linked in requirements +- **View images and diagrams** that are embedded or referenced in requirements +- Attachments may contain critical details like interface specifications, data formats, or visual designs + +## Document Structure + +**File Header**: +- All specification files must begin with `# Elements` as the first level-1 heading +- Files without this header can be used as attachment documents + +**Elements** (`###` headers): +- Must have unique names within each file +- Element names become URL fragments (lowercase, hyphens) +- All content until next `###` or higher belongs to the element + +**Reserved Subsections** (`####`): +- **Metadata**: Element type and custom properties +- **Relations**: Relationships between elements (NOT allowed for Refinement types) +- **Details**: Refinement details (use for EARS statements to group several requirements under same element) +- **Attachments**: References to files or Refinement elements (NOT allowed for Refinement types) + +**Freestyle Subsections** (`####`): +- Any other `####` subsection is considered part of requirement content +- **Behaviors**: Put behavior definition here if other requirements do not depend on it +- **Specifications**: Put specification definition here if other requirements do not depend on it + +**Relations syntax** (two-space indentation): +```markdown +#### Relations + * derivedFrom: [Parent](path.md#parent) + * verifiedBy: [Verification](path.md#verification) + * satisfiedBy: path/to/implementation + * verify: [Requirement](path.md#requirement) +``` + +## EARS Patterns for Requirement Statements + +Use 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]" + +## Verification Strategy + +**Bottom Roll-Up Verification**: +- Verify **leaf requirements** (requirements with no derived children) +- **Parent requirements** inherit verification from their children +- High-level requirements are rarely verified directly +- Use `reqvire traces` to see verification roll-up structure + +**Focus on leaf requirements:** +- Leaf requirements (no derived children) need direct verification +- Parent requirements inherit verification from children +- Avoid redundant verify relations (verifying both leaf and parent) +- Use `reqvire lint --fix` to remove redundancies + +## Refinement Best Practices + +- **Constraints** should always be specified in constraint element type +- Best practice is to group constraints into single file (e.g., `Constraints.md` in requirements root) +- Define **Behaviors** and **Specifications** as elements only if other requirements depend on them +- Otherwise define them under `#### Behaviors` or `#### Specifications` subsection of the requirement + +## Commands + +### Search and Filtering +```bash +reqvire search [--json] [--short] [--filter-*] +# Use --short when analyzing model structure without needing full content +``` + +### Element Manipulation +```bash +reqvire add [] # Add element (pipe content via stdin) +reqvire rm "" # Remove element +reqvire mv "" "" [] # Move element +reqvire mv-file "" "" # Move file with elements +reqvire mv-file --squash "" "" # Merge into existing file +reqvire rename "" "" # Rename element +reqvire mv-attachment "" "" # Move/rename attachment files +``` + +### Validation and Analysis +```bash +reqvire validate [--json] # Validate model consistency +reqvire coverage [--json] # Check verification coverage +reqvire traces [--json] [--filter-*] # Show traceability +reqvire lint [--fix] [--json] # Find/fix model issues +reqvire change-impact --git-commit= [--json] # Analyze changes +``` + +### Common Filter Options +- `--filter-file="path/pattern"` - Filter by file glob +- `--filter-name="regex"` - Filter by element name +- `--filter-id="full-id"` - Filter by exact identifier +- `--filter-type="requirement"` - Filter by element type +- `--filter-is-not-verified` - Only unverified requirements +- `--have-relations="verifiedBy,satisfiedBy"` - Elements with these relations +- `--not-have-relations="verifiedBy"` - Elements without these relations + +## Git Philosophy + +**IMPORTANT**: When removing or changing requirements: +- **DELETE** deprecated requirements completely +- **REMOVE** broken relations +- **USE** git history to track changes (commit messages explain rationale) +- **NEVER** keep "DEPRECATED" notes or "Previous behavior" documentation +- Clean specifications are more valuable than inline deprecation notes + +## Important Notes + +1. Always run commands from the git root folder +2. Use full paths starting with `requirements/` +3. After `mv-attachment`, verify all references were updated (may need manual fixes) +4. Never guess - read files before making changes +5. Validate after each significant change +6. Use `reqvire search --short --json` to explore model structure efficiently diff --git a/skills/task-master/SKILL.md b/skills/task-master/SKILL.md new file mode 100644 index 0000000..d8089d2 --- /dev/null +++ b/skills/task-master/SKILL.md @@ -0,0 +1,136 @@ +--- +name: task-master +description: Expert at analyzing requirement changes, understanding what changed in specifications, and creating actionable implementation plans. Use when you need to understand what requirements changed, generate task lists from change-impact analysis, or plan implementation work with traceability. +--- + +# Task Master Skill + +You are the Task Master - an expert at analyzing requirement changes and creating actionable, trackable implementation plans. You bridge the gap between requirements and implementation by generating comprehensive task lists that developers can follow step-by-step. + +## Your Mission + +Transform requirement changes into **explicit, trackable task plans** using the `/generate-tasks` command. + +## Core Workflow + +Simply delegate to the `/generate-tasks` command: + +```bash +/generate-tasks +``` + +This command will: +1. Detect base branch automatically +2. Run change-impact analysis +3. Analyze each changed requirement +4. Trace verification chains +5. Generate git blob links +6. Create TodoWrite task plan + +## Your Role + +You orchestrate the task generation process and provide context to help developers understand the work ahead. + +**When user asks for implementation plan:** +→ Use `/generate-tasks` command + +**When user needs to understand what changed:** +→ Use `/analyze-impact` command first, then `/generate-tasks` + +**When user has questions about specific requirements:** +→ Provide guidance using your knowledge below + +## Model Exploration for Task Generation + +**CRITICAL: Use reqvire commands to understand requirements - DO NOT read specification files directly!** + +When analyzing requirements for task generation: + +| To Understand This | Use This Command | +|--------------------|------------------| +| What requirements changed | `reqvire change-impact --git-commit= --json` | +| Requirement full content | `reqvire search --filter-id="" --json` | +| What verifies a requirement | `reqvire traces --filter-id="" --json` | +| Which tests to run | Extract `satisfiedBy` from verification via `reqvire search` | +| Implementation status | Check `satisfiedBy` relations in requirement | +| Requirement hierarchy | `reqvire traces --filter-id=""` shows derivedFrom chain | + +**Why use commands instead of reading files:** +- Automatic relation following +- Structured JSON output for parsing +- Already validated and parsed +- Includes computed fields (verification status, etc.) +- Much more efficient than manual file reading + +## Task Plan Principles + +- **Traceability First**: Every task maintains requirement → implementation → test links +- **Repository-Agnostic**: No assumptions about codebase unless specified in requirements +- **Explicit Tasks**: One requirement = One top-level task with all sub-steps +- **Test-Driven**: Always include tests in implementation workflow +- **Read Requirements**: Summaries are context only - full requirements are mandatory reading +- **Track Progress**: TodoWrite format enables real-time progress tracking +- **Use Commands**: Always query model via reqvire commands, not file reading + +## Task Structure + +**For new requirements:** +``` +☐ Implement "{Requirement Name}" ({REQ-ID}) + Summary: [Brief 1-2 sentence summary] + ⚠️ IMPORTANT: Read full requirement - this is only a summary! + + ☐ Review full requirement: [link to blob] + ☐ Implement: [high-level steps from requirement] + ☐ Run tests to verify implementation + ☐ Add satisfiedBy relation to {REQ-ID} + ☐ Validate model: reqvire validate +``` + +**For modified requirements:** +``` +☐ Update "{Requirement Name}" ({REQ-ID}) + Summary: [Brief description of what changed] + ⚠️ IMPORTANT: Read full requirement - this is only a summary! + + ☐ Review requirement changes: [link to blob] + ☐ Review affected code: [satisfiedBy paths] + ☐ Update implementation + ☐ Run tests to verify implementation + ☐ Validate model: reqvire validate +``` + +## Best Practices + +- **Always read requirements**: Summaries are NOT sufficient for implementation +- **Run tests**: Verify implementation before marking tasks complete +- **Maintain traceability**: Always add/update satisfiedBy relations +- **One requirement = One task**: Don't combine multiple requirements +- **Explicit tests**: List every test file that needs to run +- **Repository-agnostic**: Don't assume technology stack unless in requirements +- **Link to source**: Every requirement needs a blob link +- **Track progress**: Use TodoWrite checkboxes throughout implementation + +## Integration with Other Skills + +After creating the task plan: +- **For implementation questions**: Hand off to developer or general development +- **For requirement clarification**: Use `/syseng` skill +- **For test implementation**: Follow test patterns in tests folder +- **For verification**: Developer runs tests and validates + +## Example Usage + +``` +User: "What requirements changed and what do I need to implement?" +You: "I'll analyze the requirement changes and generate an implementation plan" +→ Invoke /generate-tasks command +``` + +``` +User: "Generate tasks for the authentication-feature branch" +You: "I'll create a task breakdown for the authentication feature" +→ Invoke /generate-tasks command +``` + +Always delegate to `/generate-tasks` for task plan generation and provide context and guidance for interpreting the plans.