rpi-kit 2.2.2 → 2.5.0

package/.gemini/commands/opsx/sync.toml

@@ -0,0 +1,131 @@
+description = "Sync delta specs from a change to main specs"
+
+prompt = """
+Sync delta specs from a change to main specs.
+
+This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
+
+**Input**: Optionally specify a change name after `/opsx:sync` (e.g., `/opsx:sync add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have delta specs (under `specs/` directory).
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Find delta specs**
+
+   Look for delta spec files in `openspec/changes/<name>/specs/*/spec.md`.
+
+   Each delta spec file contains sections like:
+   - `## ADDED Requirements` - New requirements to add
+   - `## MODIFIED Requirements` - Changes to existing requirements
+   - `## REMOVED Requirements` - Requirements to remove
+   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
+
+   If no delta specs found, inform user and stop.
+
+3. **For each delta spec, apply changes to main specs**
+
+   For each capability with a delta spec at `openspec/changes/<name>/specs/<capability>/spec.md`:
+
+   a. **Read the delta spec** to understand the intended changes
+
+   b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
+
+   c. **Apply changes intelligently**:
+
+      **ADDED Requirements:**
+      - If requirement doesn't exist in main spec → add it
+      - If requirement already exists → update it to match (treat as implicit MODIFIED)
+
+      **MODIFIED Requirements:**
+      - Find the requirement in main spec
+      - Apply the changes - this can be:
+        - Adding new scenarios (don't need to copy existing ones)
+        - Modifying existing scenarios
+        - Changing the requirement description
+      - Preserve scenarios/content not mentioned in the delta
+
+      **REMOVED Requirements:**
+      - Remove the entire requirement block from main spec
+
+      **RENAMED Requirements:**
+      - Find the FROM requirement, rename to TO
+
+   d. **Create new main spec** if capability doesn't exist yet:
+      - Create `openspec/specs/<capability>/spec.md`
+      - Add Purpose section (can be brief, mark as TBD)
+      - Add Requirements section with the ADDED requirements
+
+4. **Show summary**
+
+   After applying all changes, summarize:
+   - Which capabilities were updated
+   - What changes were made (requirements added/modified/removed/renamed)
+
+**Delta Spec Format Reference**
+
+```markdown
+## ADDED Requirements
+
+### Requirement: New Feature
+The system SHALL do something new.
+
+#### Scenario: Basic case
+- **WHEN** user does X
+- **THEN** system does Y
+
+## MODIFIED Requirements
+
+### Requirement: Existing Feature
+#### Scenario: New scenario to add
+- **WHEN** user does A
+- **THEN** system does B
+
+## REMOVED Requirements
+
+### Requirement: Deprecated Feature
+
+## RENAMED Requirements
+
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+```
+
+**Key Principle: Intelligent Merging**
+
+Unlike programmatic merging, you can apply **partial updates**:
+- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
+- The delta represents *intent*, not a wholesale replacement
+- Use your judgment to merge changes sensibly
+
+**Output On Success**
+
+```
+## Specs Synced: <change-name>
+
+Updated main specs:
+
+**<capability-1>**:
+- Added requirement: "New Feature"
+- Modified requirement: "Existing Feature" (added 1 scenario)
+
+**<capability-2>**:
+- Created new spec file
+- Added requirement: "Another Feature"
+
+Main specs are now updated. The change remains active - archive when implementation is complete.
+```
+
+**Guardrails**
+- Read both delta and main specs before making changes
+- Preserve existing content not mentioned in delta
+- If something is unclear, ask for clarification
+- Show what you're changing as you go
+- The operation should be idempotent - running twice should give same result
+"""

package/.gemini/commands/opsx/verify.toml

@@ -0,0 +1,161 @@
+description = "Verify implementation matches change artifacts before archiving"
+
+prompt = """
+Verify that an implementation matches the change artifacts (specs, tasks, design).
+
+**Input**: Optionally specify a change name after `/opsx:verify` (e.g., `/opsx:verify add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have implementation tasks (tasks artifact exists).
+   Include the schema used for each change if available.
+   Mark changes with incomplete tasks as "(In Progress)".
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifacts exist for this change
+
+3. **Get the change directory and load artifacts**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns the change directory and context files. Read all available artifacts from `contextFiles`.
+
+4. **Initialize verification report structure**
+
+   Create a report structure with three dimensions:
+   - **Completeness**: Track tasks and spec coverage
+   - **Correctness**: Track requirement implementation and scenario coverage
+   - **Coherence**: Track design adherence and pattern consistency
+
+   Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
+
+5. **Verify Completeness**
+
+   **Task Completion**:
+   - If tasks.md exists in contextFiles, read it
+   - Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete)
+   - Count complete vs total tasks
+   - If incomplete tasks exist:
+     - Add CRITICAL issue for each incomplete task
+     - Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
+
+   **Spec Coverage**:
+   - If delta specs exist in `openspec/changes/<name>/specs/`:
+     - Extract all requirements (marked with "### Requirement:")
+     - For each requirement:
+       - Search codebase for keywords related to the requirement
+       - Assess if implementation likely exists
+     - If requirements appear unimplemented:
+       - Add CRITICAL issue: "Requirement not found: <requirement name>"
+       - Recommendation: "Implement requirement X: <description>"
+
+6. **Verify Correctness**
+
+   **Requirement Implementation Mapping**:
+   - For each requirement from delta specs:
+     - Search codebase for implementation evidence
+     - If found, note file paths and line ranges
+     - Assess if implementation matches requirement intent
+     - If divergence detected:
+       - Add WARNING: "Implementation may diverge from spec: <details>"
+       - Recommendation: "Review <file>:<lines> against requirement X"
+
+   **Scenario Coverage**:
+   - For each scenario in delta specs (marked with "#### Scenario:"):
+     - Check if conditions are handled in code
+     - Check if tests exist covering the scenario
+     - If scenario appears uncovered:
+       - Add WARNING: "Scenario not covered: <scenario name>"
+       - Recommendation: "Add test or implementation for scenario: <description>"
+
+7. **Verify Coherence**
+
+   **Design Adherence**:
+   - If design.md exists in contextFiles:
+     - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
+     - Verify implementation follows those decisions
+     - If contradiction detected:
+       - Add WARNING: "Design decision not followed: <decision>"
+       - Recommendation: "Update implementation or revise design.md to match reality"
+   - If no design.md: Skip design adherence check, note "No design.md to verify against"
+
+   **Code Pattern Consistency**:
+   - Review new code for consistency with project patterns
+   - Check file naming, directory structure, coding style
+   - If significant deviations found:
+     - Add SUGGESTION: "Code pattern deviation: <details>"
+     - Recommendation: "Consider following project pattern: <example>"
+
+8. **Generate Verification Report**
+
+   **Summary Scorecard**:
+   ```
+   ## Verification Report: <change-name>
+
+   ### Summary
+   | Dimension    | Status           |
+   |--------------|------------------|
+   | Completeness | X/Y tasks, N reqs|
+   | Correctness  | M/N reqs covered |
+   | Coherence    | Followed/Issues  |
+   ```
+
+   **Issues by Priority**:
+
+   1. **CRITICAL** (Must fix before archive):
+      - Incomplete tasks
+      - Missing requirement implementations
+      - Each with specific, actionable recommendation
+
+   2. **WARNING** (Should fix):
+      - Spec/design divergences
+      - Missing scenario coverage
+      - Each with specific recommendation
+
+   3. **SUGGESTION** (Nice to fix):
+      - Pattern inconsistencies
+      - Minor improvements
+      - Each with specific recommendation
+
+   **Final Assessment**:
+   - If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
+   - If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
+   - If all clear: "All checks passed. Ready for archive."
+
+**Verification Heuristics**
+
+- **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
+- **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
+- **Coherence**: Look for glaring inconsistencies, don't nitpick style
+- **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
+- **Actionability**: Every issue must have a specific recommendation with file/line references where applicable
+
+**Graceful Degradation**
+
+- If only tasks.md exists: verify task completion only, skip spec/design checks
+- If tasks + specs exist: verify completeness and correctness, skip design
+- If full artifacts: verify all three dimensions
+- Always note which checks were skipped and why
+
+**Output Format**
+
+Use clear markdown with:
+- Table for summary scorecard
+- Grouped lists for issues (CRITICAL/WARNING/SUGGESTION)
+- Code references in format: `file.ts:123`
+- Specific, actionable recommendations
+- No vague suggestions like "consider reviewing"
+"""

package/.gemini/commands/rpi/archive.toml

@@ -0,0 +1,140 @@
+description = "Merge delta specs into main specs and clean up the feature directory."
+
+prompt = """
+# /rpi:archive — Archive Feature
+
+Merge the feature's delta specs into the main `rpi/specs/` directory, preserve any solutions worth saving, and delete the feature directory. History is preserved in git.
+
+---
+
+## Step 1: Load config and validate
+
+1. Read `.rpi.yaml` for config. Apply defaults if missing:
+   - `folder`: `rpi/features`
+   - `specs_dir`: `rpi/specs`
+   - `solutions_dir`: `rpi/solutions`
+2. Parse `$ARGUMENTS` to extract `{slug}`.
+3. Validate `rpi/features/{slug}/` exists. If not:
+   ```
+   Feature '{slug}' not found. Nothing to archive.
+   ```
+   Stop.
+
+## Step 2: Validate review verdict
+
+1. Read `rpi/features/{slug}/implement/IMPLEMENT.md`.
+2. Look for a `## Review` section with a verdict of `PASS` or `PASS with concerns`.
+3. If verdict is `FAIL`:
+   ```
+   Review verdict is FAIL for '{slug}'.
+   Fix the issues and re-run: /rpi:review {slug}
+   Cannot archive a feature that hasn't passed review.
+   ```
+   Stop.
+4. If no review section or verdict is found:
+   ```
+   No review verdict found for '{slug}'.
+   Run /rpi:review {slug} before archiving.
+   ```
+   Stop.
+
+## Step 3: Read delta contents
+
+1. Scan `rpi/features/{slug}/delta/ADDED/` for all files — store as `$ADDED_FILES`.
+2. Scan `rpi/features/{slug}/delta/MODIFIED/` for all files — store as `$MODIFIED_FILES`.
+3. Scan `rpi/features/{slug}/delta/REMOVED/` for all files — store as `$REMOVED_FILES`.
+4. Read the contents of each file found.
+
+If all three directories are empty:
+```
+No delta specs found for '{slug}'. Skipping specs merge.
+```
+Proceed to Step 5.
+
+## Step 4: Launch Nexus to merge delta into specs
+
+Use the Agent tool to launch Nexus for the merge:
+
+```
+You are Nexus. Merge the delta specs for feature '{slug}' into the main specs directory.
+
+## ADDED Files (copy to rpi/specs/)
+{for each file in $ADDED_FILES: filename and full contents}
+
+## MODIFIED Files (apply changes to existing rpi/specs/ files)
+{for each file in $MODIFIED_FILES: filename, delta contents, and current contents of the target spec file in rpi/specs/}
+
+## REMOVED Files (delete from rpi/specs/)
+{for each file in $REMOVED_FILES: filename}
+
+Your task:
+1. For each ADDED file: determine the correct path under rpi/specs/ and write the file there.
+   - Use the file's content as-is. Preserve the directory structure (e.g. delta/ADDED/auth/oauth.md → rpi/specs/auth/oauth.md).
+2. For each MODIFIED file: read the current spec at rpi/specs/{path}, apply the changes from the delta version.
+   - The delta file contains the updated version of the spec. Merge it intelligently:
+   - Preserve any sections in the original that aren't addressed by the delta
+   - Update sections that the delta modifies
+   - Add new sections from the delta
+3. For each REMOVED file: note the path under rpi/specs/ that should be deleted.
+
+Output format:
+## Merge Plan
+### Files to Write
+- {path}: {action: created | updated} — {brief description}
+
+### Files to Delete
+- {path} — {reason}
+
+### Warnings
+- {any conflicts or issues detected}
+(or "No warnings.")
+```
+
+Store the output as `$NEXUS_MERGE`.
+
+After Nexus responds, execute the merge plan:
+1. **ADDED**: Write each file to `rpi/specs/{path}` (create directories as needed).
+2. **MODIFIED**: Write the merged content to `rpi/specs/{path}`.
+3. **REMOVED**: Delete the files from `rpi/specs/`.
+
+## Step 5: Check for solutions worth saving
+
+1. Read `rpi/features/{slug}/implement/IMPLEMENT.md` for the review section.
+2. If the review flagged solutions saved to `rpi/solutions/`:
+   - Verify each referenced solution file exists in `rpi/solutions/`.
+   - If any are missing, warn:
+     ```
+     Warning: Solution '{path}' referenced in review but not found.
+     ```
+
+## Step 6: Delete feature directory
+
+Remove the entire feature directory:
+
+```bash
+rm -rf rpi/features/{slug}
+```
+
+## Step 7: Commit
+
+Stage all changes and commit:
+
+```bash
+git add -A
+git commit -m "chore: archive {slug} — delta merged, feature complete"
+```
+
+## Step 8: Output summary
+
+```
+Archive complete: {slug}
+
+Specs merged:
+- Added: {N} files
+- Modified: {N} files
+- Removed: {N} files
+
+Feature directory deleted: rpi/features/{slug}/
+History preserved in git.
+```
+"""

package/.gemini/commands/rpi/docs-gen.toml

@@ -0,0 +1,210 @@
+description = "Analyze the codebase and generate a CLAUDE.md with project rules, conventions, and architecture."
+
+prompt = """
+# /rpi:docs-gen — Generate CLAUDE.md
+
+Standalone utility command — uses Atlas for codebase analysis and Quill for writing. Does not require the RPI feature pipeline.
+
+---
+
+## Step 1: Load config
+
+Read `.rpi.yaml` from the project root. Extract:
+- `commit_style` (default: `conventional`)
+
+If `.rpi.yaml` does not exist, use defaults silently.
+
+## Step 2: Check for existing CLAUDE.md
+
+Check if `CLAUDE.md` exists at the project root.
+
+- If it exists: read it and store as `$EXISTING_CLAUDE_MD`. Proceed to Step 3.
+- If it does not exist: set `$EXISTING_CLAUDE_MD` to empty. Skip to Step 4.
+
+## Step 3: Handle existing CLAUDE.md
+
+Ask with AskUserQuestion:
+
+```
+CLAUDE.md already exists ({line_count} lines). What would you like to do?
+A) Overwrite — generate a new CLAUDE.md from scratch (existing content will be replaced)
+B) Cancel — keep the existing file unchanged
+```
+
+- If A (overwrite): proceed to Step 4.
+- If B (cancel): output "No changes made." and stop.
+
+## Step 4: Launch Atlas for codebase analysis
+
+Launch Atlas agent with the following prompt:
+
+```
+You are Atlas. Analyze this entire codebase and produce a structured analysis for generating a CLAUDE.md file.
+
+Your task:
+1. Read config files first: package.json, tsconfig.json, pyproject.toml, Cargo.toml, go.mod, Gemfile, composer.json, Makefile, Dockerfile, or whatever exists
+2. Scan the directory structure to understand architecture and layering
+3. Find 5-10 representative source files across different directories
+4. Detect naming conventions, component patterns, import style, error handling
+5. Check for existing CLAUDE.md, .cursorrules, .clinerules, or similar project rules files — if found, note their content for reference
+6. Identify the testing framework and test patterns
+7. Identify styling/CSS approach if frontend
+8. List the 10-15 most important files in the project with one-line descriptions
+9. Detect useful developer commands: scripts in package.json, Makefile targets, common commands for running, testing, building, linting
+
+Produce your analysis with this EXACT structure:
+
+## Stack
+- Language: {language} {version}
+- Framework: {framework} {version}
+- Database: {db} via {orm} (or "None detected")
+- Testing: {test_framework}
+- Styling: {approach} (or "N/A")
+- Build: {build_tool}
+- Package Manager: {package_manager}
+
+## Architecture
+- Pattern: {description — e.g., "layered MVC", "monorepo with packages/", "plugin system"}
+- Key directories:
+  - {directory}: {purpose}
+  - {directory}: {purpose}
+  - ...
+- Entry points: {list}
+
+## Conventions
+- File naming: {pattern — e.g., "kebab-case.ts", "PascalCase.tsx for components"}
+- Components: {pattern} (or "N/A")
+- Import style: {pattern — e.g., "absolute imports via @/", "relative imports"}
+- Error handling: {pattern — e.g., "try/catch with custom AppError class", "Result types"}
+- API: {pattern} (or "N/A")
+- Commits: {pattern detected from git log — e.g., "conventional commits", "freeform"}
+
+## Key Files
+- {file}: {one-line description}
+- {file}: {one-line description}
+- ...
+
+## Commands
+- {command}: {what it does}
+- {command}: {what it does}
+- ...
+
+## Rules
+- {rule 1 derived from codebase analysis or existing rules files}
+- {rule 2}
+- ...
+
+RULES:
+- Be specific — cite actual patterns you found, not generic advice
+- Only include what you can verify from the code
+- If a section doesn't apply (e.g., no database), write "N/A" and move on
+- Keep each section concise
+- For Rules: derive actionable rules from what you observed, not generic software engineering advice
+- If you found an existing CLAUDE.md or similar rules file, incorporate its rules (they are the team's explicit preferences)
+```
+
+Wait for Atlas to complete. Store the output as `$ATLAS_ANALYSIS`.
+
+## Step 5: Launch Quill to generate CLAUDE.md
+
+Launch Quill agent with the following prompt:
+
+```
+You are Quill. Generate a CLAUDE.md file for this project based on the codebase analysis below.
+
+## Codebase Analysis (from Atlas)
+{$ATLAS_ANALYSIS}
+
+## Project Config
+- Commit style: {commit_style from .rpi.yaml or "conventional"}
+
+{If $EXISTING_CLAUDE_MD is not empty:}
+## Previous CLAUDE.md (being replaced)
+{$EXISTING_CLAUDE_MD}
+Note: The user chose to overwrite. You may incorporate relevant rules from the previous version if they are still valid based on Atlas's analysis.
+{End if}
+
+Your task: generate a complete CLAUDE.md file. Output only the file content — the command will handle writing to disk after user confirmation.
+
+Target structure:
+
+# Project Rules
+
+## Behavior
+{3-6 rules about development behavior: how to handle errors, when to ask vs assume, commit practices.
+Derive these from the codebase analysis — e.g., if conventional commits are used, state it.
+If an existing CLAUDE.md had behavior rules, preserve the ones still relevant.}
+
+## Code
+{3-6 rules about code style: naming, patterns, imports, error handling.
+These come directly from Atlas's Conventions section.
+Be specific — "Use kebab-case for file names" not "Follow naming conventions."}
+
+## Stack
+{Direct copy of Atlas's Stack section, formatted as a concise list.}
+
+## Architecture
+{Direct copy of Atlas's Architecture section.
+Include directory map with purposes.}
+
+## Conventions
+{Merge of Atlas's Conventions section with any additional patterns.
+Focus on things another developer or AI assistant would need to know to write consistent code.}
+
+## Commands
+{Useful developer commands from Atlas's Commands section.
+Format: `command` — description
+Include: run, test, build, lint, format, deploy — whatever exists.}
+
+Rules for writing:
+- Every rule must be actionable — "Use X" not "Consider X"
+- No generic software engineering advice — only project-specific rules
+- If a convention is obvious from the language/framework default, omit it
+- Keep the file under 80 lines total — CLAUDE.md is read on every AI invocation, brevity matters
+- Match the tone of existing project documentation if any exists
+- If the code says WHAT, the docs should say WHY
+```
+
+Wait for Quill to complete. Store the output as `$CLAUDE_MD_CONTENT`.
+
+## Step 6: Preview and confirm
+
+Output the generated content to the user:
+
+```
+Generated CLAUDE.md preview:
+
+---
+{$CLAUDE_MD_CONTENT}
+---
+```
+
+Ask with AskUserQuestion:
+
+```
+Write this to CLAUDE.md at the project root?
+A) Yes — write the file
+B) No — discard (you can copy the content above manually if you want)
+```
+
+- If A (yes): proceed to Step 7.
+- If B (no): output "No changes made." and stop.
+
+## Step 7: Write CLAUDE.md
+
+Write `$CLAUDE_MD_CONTENT` to `CLAUDE.md` at the project root.
+
+## Step 8: Output summary
+
+```
+CLAUDE.md generated ({line_count} lines)
+
+Sections: Behavior, Code, Stack, Architecture, Conventions, Commands
+
+{If $EXISTING_CLAUDE_MD was not empty:}
+Previous CLAUDE.md was replaced.
+{End if}
+
+Tip: Review and edit CLAUDE.md to add project-specific rules that automated analysis might miss.
+```
+"""