rpi-kit 2.2.2 → 2.5.0

package/.gemini/commands/rpi/research.toml

@@ -0,0 +1,265 @@
+description = "Analyze feasibility with Atlas (codebase) and Scout (external). Nexus synthesizes."
+
+prompt = """
+# /rpi:research — Research Phase
+
+Run Atlas (codebase analysis) and Scout (external research) in parallel. Nexus synthesizes their outputs into RESEARCH.md with a GO / GO with concerns / NO-GO verdict.
+
+---
+
+## Step 1: Load config and validate
+
+1. Read `.rpi.yaml` for config. Apply defaults if missing:
+   - `specs_dir`: `rpi/specs`
+   - `solutions_dir`: `rpi/solutions`
+   - `context_file`: `rpi/context.md`
+2. Parse `$ARGUMENTS` to extract `{slug}` and optional `--force` flag.
+3. Validate `rpi/features/{slug}/REQUEST.md` exists. If not:
+   ```
+   Feature '{slug}' not found. Run /rpi:new {slug} to start.
+   ```
+   Stop.
+
+## Step 2: Check existing research
+
+1. Check if `rpi/features/{slug}/research/RESEARCH.md` already exists.
+2. If it exists and `--force` was NOT passed:
+   - Ask the user: "RESEARCH.md already exists for '{slug}'. Overwrite? (yes/no)"
+   - If no: stop.
+3. If `--force` was passed or user confirms: proceed (will overwrite).
+
+## Step 3: Gather context
+
+1. Read `rpi/features/{slug}/REQUEST.md` — store as `$REQUEST`.
+2. Read `rpi/context.md` (project context) if it exists — store as `$CONTEXT`.
+3. Scan `rpi/specs/` for any specs relevant to the feature described in REQUEST.md — store as `$RELEVANT_SPECS`.
+4. Scan `rpi/solutions/` for any past solutions relevant to this feature — store as `$RELEVANT_SOLUTIONS`.
+
+## Step 4: Launch Atlas and Scout in parallel
+
+Use the Agent tool to launch both agents simultaneously.
+
+### Atlas (codebase analysis)
+
+Launch Atlas agent with this prompt:
+
+```
+You are Atlas. Analyze the codebase for feature: {slug}
+
+## Request
+{$REQUEST}
+
+## Project Context
+{$CONTEXT}
+
+## Relevant Specs
+{$RELEVANT_SPECS}
+
+## Relevant Past Solutions
+{$RELEVANT_SOLUTIONS}
+
+Your task:
+1. Analyze the codebase for patterns, conventions, and architecture relevant to this feature
+2. Check rpi/specs/ for existing specifications that overlap or relate
+3. Check rpi/solutions/ for past solutions that could be reused
+4. Identify files likely affected, patterns to follow, and risks
+5. Output using your standard format: [Atlas -- Codebase Analysis]
+
+6. After your analysis, append your activity to rpi/features/{slug}/ACTIVITY.md:
+
+### {current_date} — Atlas (Research)
+- **Action:** Codebase analysis for {slug}
+- **Scope:** {list files you actually read}
+- **Key decisions:** {for each <decision> tag you emitted: "summary (rationale)", separated by semicolons. If none: "No decisions in this phase."}
+- **Patterns found:** {count and summary}
+- **Quality:** {your quality gate result}
+```
+
+### Scout (external research)
+
+Launch Scout agent with this prompt:
+
+```
+You are Scout. Research technical feasibility for feature: {slug}
+
+## Request
+{$REQUEST}
+
+## Project Context
+{$CONTEXT}
+
+## Relevant Past Solutions
+{$RELEVANT_SOLUTIONS}
+
+Your task:
+1. FIRST check rpi/solutions/ for relevant past solutions before any external research
+2. Research technical feasibility of the proposed approach
+3. Evaluate alternative libraries/tools with trade-off comparison
+4. Identify risks: breaking changes, security issues, maintenance status
+5. Find relevant benchmarks, examples, or case studies
+6. Output using your standard format: [Scout -- Technical Investigation]
+
+7. After your investigation, append your activity to rpi/features/{slug}/ACTIVITY.md:
+
+### {current_date} — Scout (Research)
+- **Action:** External research for {slug}
+- **Key decisions:** {for each <decision> tag you emitted: "summary (rationale)", separated by semicolons. If none: "No decisions in this phase."}
+- **Sources consulted:** {count and list}
+- **Recommendations:** {count and summary}
+- **Quality:** {your quality gate result}
+```
+
+## Step 5: Wait for completion
+
+Wait for both Atlas and Scout agents to complete. Store their outputs:
+- `$ATLAS_OUTPUT` — Atlas's codebase analysis
+- `$SCOUT_OUTPUT` — Scout's technical investigation
+
+## Step 6: Detect disagreements
+
+Compare Atlas and Scout outputs for contradictions:
+- Atlas says feasible but Scout says risky (or vice versa)
+- Different recommendations on approach, libraries, or architecture
+- Conflicting risk assessments
+
+If disagreements are detected, launch Nexus for a mini-debate:
+
+```
+You are Nexus. Atlas and Scout disagree on key points for feature: {slug}
+
+## Atlas Output
+{$ATLAS_OUTPUT}
+
+## Scout Output
+{$SCOUT_OUTPUT}
+
+Identify the specific disagreements. For each one:
+1. State what Atlas argues
+2. State what Scout argues
+3. Evaluate the evidence for each position
+4. Declare the stronger position with reasoning
+
+Output as: [Nexus -- Debate Summary]
+```
+
+Store the debate result as `$DEBATE_OUTPUT`.
+
+## Step 7: Nexus synthesis
+
+Launch Nexus agent to produce the final RESEARCH.md:
+
+```
+You are Nexus. Synthesize research for feature: {slug}
+
+## Request
+{$REQUEST}
+
+## Atlas Output
+{$ATLAS_OUTPUT}
+
+## Scout Output
+{$SCOUT_OUTPUT}
+
+## Debate Results (if any)
+{$DEBATE_OUTPUT or "No disagreements detected."}
+
+Produce a single RESEARCH.md with this structure:
+
+# Research: {Feature Title}
+
+## Summary
+5 lines: verdict, complexity, risk, recommendation, key finding.
+
+## Atlas Findings
+{Key findings from Atlas's codebase analysis — preserve strongest evidence}
+
+## Scout Findings
+{Key findings from Scout's technical investigation — preserve strongest evidence}
+
+## Consensus
+{Points where Atlas and Scout agree}
+
+## Resolved Disagreements
+{For each disagreement: what Atlas said, what Scout said, resolution with reasoning}
+(or "No disagreements detected.")
+
+## Risks and Mitigations
+{Combined risk assessment from both agents}
+
+## Relevant Solutions
+{Past solutions from rpi/solutions/ that apply — for knowledge reuse}
+(or "No relevant past solutions found.")
+
+## Open Questions
+{Unresolved items that need user input}
+
+## Verdict
+{GO | GO with concerns | NO-GO}
+Confidence: {HIGH | MEDIUM | LOW}
+
+Rules for verdict:
+- Any BLOCK finding = NO-GO
+- No BLOCK + 2 or more CONCERN findings = GO with concerns
+- Otherwise = GO
+- NO-GO requires an Alternatives section
+
+After synthesis, append your activity to rpi/features/{slug}/ACTIVITY.md:
+
+### {current_date} — Nexus (Research Synthesis)
+- **Action:** Synthesized Atlas + Scout findings for {slug}
+- **Key decisions:** {for each <decision> tag you emitted: "summary (rationale)", separated by semicolons. If none: "No decisions in this phase."}
+- **Consensus points:** {count}
+- **Disagreements resolved:** {count}
+- **Quality:** {your quality gate result}
+```
+
+## Step 8: Write RESEARCH.md and populate delta baselines
+
+1. Ensure directory exists: `rpi/features/{slug}/research/`
+2. Write the Nexus output to `rpi/features/{slug}/research/RESEARCH.md`
+3. If Nexus identified relevant existing specs in `rpi/specs/`:
+   - Ensure `rpi/features/{slug}/delta/` directory structure exists (ADDED/, MODIFIED/, REMOVED/)
+   - Copy relevant spec baselines into `delta/MODIFIED/` so the plan phase has reference copies
+   - This gives Mestre (plan phase) the current state of specs that will be changed
+
+## Step 9: Consolidate decisions to DECISIONS.md
+
+1. Read `rpi/features/{slug}/ACTIVITY.md`.
+2. Extract all `<decision>` tags from entries belonging to the Research phase (Atlas, Scout, Nexus entries from this run).
+3. If no decisions found, skip this step.
+4. Write `rpi/features/{slug}/DECISIONS.md`:
+
+```markdown
+# Decision Log — {slug}
+
+## Research Phase
+_Generated: {current_date}_
+
+| # | Type | Decision | Alternatives | Rationale | Impact |
+|---|------|----------|-------------|-----------|--------|
+| {N} | {type} | {summary} | {alternatives} | {rationale} | {impact} |
+```
+
+5. Number decisions sequentially starting from 1.
+
+## Step 10: Output summary
+
+```
+Research complete: rpi/features/{slug}/research/RESEARCH.md
+
+Verdict: {GO | GO with concerns | NO-GO}
+
+Next: /rpi {slug}
+Or explicitly: /rpi:plan {slug}
+```
+
+If NO-GO:
+```
+Research complete: rpi/features/{slug}/research/RESEARCH.md
+
+Verdict: NO-GO
+
+Review the RESEARCH.md for details and alternatives.
+To override: /rpi:plan {slug} --force
+```
+"""

package/.gemini/commands/rpi/review.toml

@@ -0,0 +1,443 @@
+description = "Adversarial review with Hawk + Shield + Sage in parallel. Nexus synthesizes."
+
+prompt = """
+# /rpi:review — Review Phase
+
+Adversarial review with three parallel agents: Hawk (code review), Shield (security audit), Sage (test coverage). Nexus synthesizes findings into a final verdict.
+
+---
+
+## Step 1: Load config and validate
+
+1. Read `.rpi.yaml` for config. Apply defaults if missing:
+   - `folder`: `rpi/features`
+   - `context_file`: `rpi/context.md`
+   - `solutions_dir`: `rpi/solutions`
+   - `auto_learn`: `true`
+2. Parse `$ARGUMENTS` to extract `{slug}`.
+3. Validate `rpi/features/{slug}/implement/IMPLEMENT.md` exists. If not:
+   ```
+   IMPLEMENT.md not found for '{slug}'. Run /rpi:implement {slug} first.
+   ```
+   Stop.
+
+## Step 2: Gather all artifacts
+
+1. Read `rpi/features/{slug}/REQUEST.md` — store as `$REQUEST`.
+2. Read `rpi/features/{slug}/plan/PLAN.md` — store as `$PLAN`.
+3. Read `rpi/features/{slug}/plan/eng.md` if it exists — store as `$ENG`.
+4. Read `rpi/features/{slug}/implement/IMPLEMENT.md` — store as `$IMPLEMENT`.
+5. Read `rpi/context.md` (project context) if it exists — store as `$CONTEXT`.
+
+## Step 3: Get implementation diff
+
+1. Read `$IMPLEMENT` to extract all commit hashes from the Execution Log (including simplify commit if present).
+2. Use git to get the combined diff:
+   ```bash
+   git diff {first_commit}^..{last_commit}
+   ```
+3. Store the diff as `$IMPL_DIFF`.
+4. Collect the list of all files changed — store as `$CHANGED_FILES`.
+
+## Step 4: Launch Hawk, Shield, and Sage in parallel
+
+Use the Agent tool to launch all three agents simultaneously.
+
+### Hawk (adversarial review)
+
+Launch Hawk agent with this prompt:
+
+```
+You are Hawk. Perform an adversarial code review for feature: {slug}
+
+## Implementation Diff
+{$IMPL_DIFF}
+
+## Changed Files
+{$CHANGED_FILES}
+
+## Engineering Spec
+{$ENG}
+
+## Implementation Plan
+{$PLAN}
+
+## Project Context
+{$CONTEXT}
+
+Your task — ultra-thinking deep dive from 5 perspectives:
+
+1. **Developer**: Code quality, maintainability, readability, patterns
+2. **Ops**: Deployability, monitoring, logging, failure modes
+3. **User**: Edge cases in user-facing behavior, error messages, UX
+4. **Security**: Input validation, auth checks, data exposure
+5. **Business**: Does it solve the stated problem? Missed requirements?
+
+CRITICAL RULES:
+1. You MUST find problems. Zero findings is not acceptable — re-analyse.
+2. Read ALL changed files thoroughly before writing findings.
+3. Each finding must reference specific file and line.
+4. Classify every finding:
+   - P1 (blocker): Must fix before merge. Bugs, data loss, security holes, broken contracts.
+   - P2 (should fix): Important but not blocking. Performance, naming, missing validation.
+   - P3 (nice-to-have): Suggestions, style, minor improvements.
+
+Output format:
+## Findings
+
+### P1 — Blockers
+- [{file}:{line}] {description} — Impact: {impact}
+(or "None found.")
+
+### P2 — Should Fix
+- [{file}:{line}] {description} — Impact: {impact}
+
+### P3 — Nice to Have
+- [{file}:{line}] {description} — Suggestion: {suggestion}
+
+## Summary
+- P1: {N} | P2: {N} | P3: {N}
+- Overall: {assessment}
+
+After your review, append your activity to rpi/features/{slug}/ACTIVITY.md:
+
+### {current_date} — Hawk (Review)
+- **Action:** Adversarial code review for {slug}
+- **Key decisions:** {for each <decision> tag you emitted: "summary (rationale)", separated by semicolons. If none: "No decisions in this phase."}
+- **Findings:** P1={count} P2={count} P3={count}
+- **Perspectives covered:** {list of 5 perspectives}
+- **Quality:** {your quality gate result}
+```
+
+Store the output as `$HAWK_OUTPUT`.
+
+### Shield (security audit)
+
+Launch Shield agent with this prompt:
+
+```
+You are Shield. Perform a security audit for feature: {slug}
+
+## Implementation Diff
+{$IMPL_DIFF}
+
+## Changed Files
+{$CHANGED_FILES}
+
+## Engineering Spec
+{$ENG}
+
+## Project Context
+{$CONTEXT}
+
+Your task — systematic security audit:
+
+### OWASP Top 10 Check
+For each applicable category, check the implementation:
+1. Injection (SQL, NoSQL, OS command, LDAP)
+2. Broken Authentication
+3. Sensitive Data Exposure
+4. XML External Entities (XXE)
+5. Broken Access Control
+6. Security Misconfiguration
+7. Cross-Site Scripting (XSS)
+8. Insecure Deserialization
+9. Using Components with Known Vulnerabilities
+10. Insufficient Logging & Monitoring
+
+### Additional Checks
+- Hardcoded secrets, API keys, tokens
+- Missing input validation or sanitization
+- Auth bypass possibilities
+- Race conditions
+- Edge cases and boundary conditions (overflow, empty input, null)
+- Error messages leaking internal details
+
+RULES:
+1. Read ALL changed files before auditing
+2. Each finding must reference specific file and line
+3. Classify: P1 (blocker) | P2 (should fix) | P3 (nice-to-have)
+4. If no security issues found, explicitly state which checks passed
+
+Output format:
+## Security Findings
+
+### P1 — Critical
+- [{file}:{line}] {vulnerability} — Risk: {risk description}
+(or "None found.")
+
+### P2 — Important
+- [{file}:{line}] {vulnerability} — Risk: {risk description}
+
+### P3 — Hardening
+- [{file}:{line}] {suggestion} — Benefit: {benefit}
+
+## OWASP Coverage
+- {category}: PASS | FAIL | N/A — {notes}
+
+## Summary
+- P1: {N} | P2: {N} | P3: {N}
+
+After your audit, append your activity to rpi/features/{slug}/ACTIVITY.md:
+
+### {current_date} — Shield (Review)
+- **Action:** Security audit for {slug}
+- **Key decisions:** {for each <decision> tag you emitted: "summary (rationale)", separated by semicolons. If none: "No decisions in this phase."}
+- **Findings:** P1={count} P2={count} P3={count}
+- **OWASP categories checked:** {count}
+- **Quality:** {your quality gate result}
+```
+
+Store the output as `$SHIELD_OUTPUT`.
+
+### Sage (coverage check)
+
+Launch Sage agent with this prompt:
+
+```
+You are Sage. Verify test coverage for feature: {slug}
+
+## Implementation Diff
+{$IMPL_DIFF}
+
+## Changed Files
+{$CHANGED_FILES}
+
+## Engineering Spec
+{$ENG}
+
+## Implementation Plan
+{$PLAN}
+
+## Project Context
+{$CONTEXT}
+
+Your task — check what is tested and what is not:
+
+1. For each changed file, find the corresponding test file(s)
+2. Identify modules/functions with NO tests at all
+3. Identify tested modules with MISSING edge cases:
+   - Error paths not tested
+   - Boundary values not tested
+   - Null/empty/invalid inputs not tested
+   - Concurrent/race condition scenarios not tested
+4. Check that acceptance criteria from the plan have test coverage
+5. Suggest specific tests that should be added
+
+RULES:
+1. Read ALL changed files and their test files before reporting
+2. Be specific — name the function/module and the missing test case
+3. Classify: P1 (no tests at all) | P2 (missing critical paths) | P3 (missing edge cases)
+
+Output format:
+## Coverage Analysis
+
+### Untested Modules (P1)
+- {file}:{function/class} — No tests found
+(or "All modules have tests.")
+
+### Missing Critical Paths (P2)
+- {file}:{function} — Missing: {description of untested path}
+
+### Missing Edge Cases (P3)
+- {file}:{function} — Missing: {description of edge case}
+
+## Suggested Tests
+1. {test description} — covers {what it covers}
+2. ...
+
+## Summary
+- Modules without tests: {N}
+- Missing critical paths: {N}
+- Missing edge cases: {N}
+
+After your analysis, append your activity to rpi/features/{slug}/ACTIVITY.md:
+
+### {current_date} — Sage (Review)
+- **Action:** Test coverage analysis for {slug}
+- **Key decisions:** {for each <decision> tag you emitted: "summary (rationale)", separated by semicolons. If none: "No decisions in this phase."}
+- **Untested modules:** {count}
+- **Missing critical paths:** {count}
+- **Missing edge cases:** {count}
+- **Quality:** {your quality gate result}
+```
+
+Store the output as `$SAGE_OUTPUT`.
+
+## Step 5: Wait for completion
+
+Wait for all three agents (Hawk, Shield, Sage) to complete.
+
+## Step 6: Launch Nexus — synthesize findings
+
+Launch Nexus agent to produce the final review report:
+
+```
+You are Nexus. Synthesize the review findings for feature: {slug}
+
+## Hawk Output (Code Review)
+{$HAWK_OUTPUT}
+
+## Shield Output (Security Audit)
+{$SHIELD_OUTPUT}
+
+## Sage Output (Coverage)
+{$SAGE_OUTPUT}
+
+## Request
+{$REQUEST}
+
+Your task:
+1. Merge all findings from Hawk, Shield, and Sage
+2. Deduplicate — if multiple agents flagged the same issue, combine into one finding
+3. Classify every finding: P1 (blocker) | P2 (should fix) | P3 (nice-to-have)
+4. Determine verdict based on findings
+
+Verdict rules:
+- Any P1 finding → FAIL
+- No P1 but has P2/P3 → PASS with concerns
+- No findings → PASS
+
+Output format:
+## Review Report: {slug}
+
+### Verdict: {PASS | PASS with concerns | FAIL}
+
+### P1 — Blockers (must fix)
+- [{source}] [{file}:{line}] {description}
+(or "None.")
+
+### P2 — Should Fix
+- [{source}] [{file}:{line}] {description}
+
+### P3 — Nice to Have
+- [{source}] [{file}:{line}] {description}
+
+### Coverage Summary (Sage)
+- {summary of test coverage status}
+
+### Totals
+- P1: {N} | P2: {N} | P3: {N}
+- Sources: Hawk {N} | Shield {N} | Sage {N}
+```
+
+Store the output as `$NEXUS_OUTPUT`.
+
+## Step 7: Handle verdict
+
+### If FAIL (P1 findings exist):
+
+1. Output to the user:
+   ```
+   Review FAILED for '{slug}'. {N} P1 blockers must be fixed.
+
+   {list P1 findings with file:line and description}
+
+   Fix all P1 issues and re-run: /rpi:review {slug}
+   ```
+2. Do NOT proceed to docs phase.
+
+### If PASS with concerns (P2/P3 only):
+
+1. Output to the user:
+   ```
+   Review PASSED with concerns for '{slug}'.
+   P2: {N} | P3: {N}
+
+   {list P2 findings}
+
+   These are non-blocking but should be addressed.
+   ```
+2. Proceed to Step 8.
+
+### If PASS (no findings):
+
+1. Output to the user:
+   ```
+   Review PASSED for '{slug}'. No issues found.
+   ```
+2. Proceed to Step 8.
+
+## Step 8: Auto-learn to solutions
+
+If `auto_learn` is `true` in config (default):
+
+1. Review all P1 and P2 findings that were particularly insightful or represent reusable knowledge.
+2. For each solution worth saving, write to `rpi/solutions/{category}/{slug}.md` using this format:
+   ```markdown
+   # {Title}
+
+   ## Problem
+   {symptoms, how it manifests}
+
+   ## Solution
+   {code, approach, what worked}
+
+   ## Prevention
+   {how to avoid in the future}
+
+   ## Context
+   Feature: {slug} | Date: {YYYY-MM-DD}
+   Files: {list}
+   ```
+3. Categories are auto-detected: `performance/`, `security/`, `database/`, `testing/`, `architecture/`, `patterns/`
+4. If no findings are worth saving, skip this step.
+
+## Step 9: Update IMPLEMENT.md
+
+Append a review section to `rpi/features/{slug}/implement/IMPLEMENT.md`:
+
+```markdown
+## Review
+
+Date: {YYYY-MM-DD}
+Agents: Hawk + Shield + Sage → Nexus
+Verdict: {PASS | PASS with concerns | FAIL}
+
+### Findings
+- P1: {N} | P2: {N} | P3: {N}
+
+### Details
+{$NEXUS_OUTPUT summary}
+
+### Solutions Saved
+- {path to solution file}: {title}
+(or "No solutions saved.")
+```
+
+## Step 10: Consolidate decisions to DECISIONS.md
+
+1. Read `rpi/features/{slug}/ACTIVITY.md`.
+2. Extract all `<decision>` tags from entries belonging to the Review phase (Hawk, Shield, Sage entries from this run).
+3. If no decisions found, skip this step.
+4. Read `rpi/features/{slug}/DECISIONS.md` if it exists (to get the last decision number for sequential numbering).
+5. Append a new section to `rpi/features/{slug}/DECISIONS.md`:
+
+```markdown
+## Review Phase
+_Generated: {current_date}_
+
+| # | Type | Decision | Alternatives | Rationale | Impact |
+|---|------|----------|-------------|-----------|--------|
+| {N} | {type} | {summary} | {alternatives} | {rationale} | {impact} |
+```
+
+6. Number decisions sequentially, continuing from the last number in DECISIONS.md.
+
+## Step 11: Output summary
+
+```
+Review complete: {slug}
+
+Verdict: {PASS | PASS with concerns | FAIL}
+Findings: P1={N} P2={N} P3={N}
+Agents: Hawk({N}) Shield({N}) Sage({N})
+
+{If PASS or PASS with concerns:}
+Next: /rpi {slug}
+Or explicitly: /rpi:docs {slug}
+
+{If FAIL:}
+Fix P1 blockers and re-run: /rpi:review {slug}
+```
+"""