rpi-kit 1.4.1 → 2.1.0

package/commands/rpi/review.md

@@ -1,159 +1,405 @@
 ---
 name: rpi:review
-description: Run code review against the implementation plan. Checks that all tasks are implemented, deviations are justified, and requirements are met.
-argument-hint: "<feature-slug>"
+description: Adversarial review with Hawk + Shield + Sage in parallel. Nexus synthesizes.
+argument-hint: "<feature-name>"
 allowed-tools:
   - Read
+  - Write
+  - Bash
   - Glob
   - Grep
-  - Bash
   - Agent
-  - Write
 ---
 
-<objective>
-Review the implementation against the plan. Check completeness, correctness, and plan alignment. Output PASS or FAIL with specific findings.
-</objective>
+# /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:
 
-<process>
+```
+You are Hawk. Perform an adversarial code review for feature: {slug}
+
+## Implementation Diff
+{$IMPL_DIFF}
+
+## Changed Files
+{$CHANGED_FILES}
 
-## 1. Load config and resolve feature path
+## Engineering Spec
+{$ENG}
 
-Read `.rpi.yaml` for folder path. Also read `profile` and `models` keys.
+## Implementation Plan
+{$PLAN}
 
-Parse `{feature-slug}` from arguments.
+## Project Context
+{$CONTEXT}
 
-**Resolution order:**
-1. Check if `{folder}/{feature-slug}/` exists → type = "feature", path = `{folder}/{feature-slug}`
-2. If not, Glob `{folder}/*/changes/{feature-slug}/` → if found, type = "change", path = matched path, parent_path = parent directory
-3. If multiple matches → AskUserQuestion listing all matches with full paths
-4. If no match → error: `Feature not found: {feature-slug}`
+Your task — ultra-thinking deep dive from 5 perspectives:
 
-If `type == "change"`:
-- Set `parent_path` to the parent feature directory
-- Read parent artifacts for agent context
+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?
 
-Validate that required files exist:
-- `{path}/plan/PLAN.md`
-- `{path}/plan/eng.md`
-- `{path}/implement/IMPLEMENT.md`
+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.
 
-If any missing, error with guidance on which command to run.
+Output format:
+## Findings
 
-## 2. Gather context
+### P1 — Blockers
+- [{file}:{line}] {description} — Impact: {impact}
+(or "None found.")
 
-Read all plan and implementation files:
-- REQUEST.md (original requirements)
-- RESEARCH.md (research findings)
-- PLAN.md (task checklist)
-- eng.md (technical spec)
-- pm.md (if exists — acceptance criteria)
-- ux.md (if exists — UX requirements)
-- IMPLEMENT.md (implementation record)
+### P2 — Should Fix
+- [{file}:{line}] {description} — Impact: {impact}
 
-## 2b. Resolve model
+### P3 — Nice to Have
+- [{file}:{line}] {description} — Suggestion: {suggestion}
+
+## Summary
+- P1: {N} | P2: {N} | P3: {N}
+- Overall: {assessment}
+```
 
-Resolve the model for the `review` phase following the Model Resolution Algorithm in the rpi-workflow skill. Store as `{resolved_model}`. If a model is resolved, output the status message before agent spawns.
+Store the output as `$HAWK_OUTPUT`.
 
-## 3. Launch code-reviewer agent
+### Shield (security audit)
 
-If a model was resolved in Step 2b, include `model: "{resolved_model}"` in the Agent tool call.
+Launch Shield agent with this prompt:
 
 ```
-You are the code-reviewer agent for the RPI workflow.
+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}
+```
 
-Read these files for the complete feature context:
-- {folder}/{feature-slug}/REQUEST.md
-- {folder}/{feature-slug}/research/RESEARCH.md
-- {folder}/{feature-slug}/plan/PLAN.md
-- {folder}/{feature-slug}/plan/eng.md
-{- {folder}/{feature-slug}/plan/pm.md (if exists)}
-{- {folder}/{feature-slug}/plan/ux.md (if exists)}
-- {folder}/{feature-slug}/implement/IMPLEMENT.md
+Store the output as `$SHIELD_OUTPUT`.
 
-Then review the actual code changes. Use Grep and Glob to find the files listed in the plan and verify the implementation.
+### Sage (coverage check)
 
-If `type == "change"`, also read parent feature files for context:
-- {parent_path}/REQUEST.md
-- {parent_path}/research/RESEARCH.md (if exists)
-- {parent_path}/plan/eng.md (if exists)
+Launch Sage agent with this prompt:
 
-This is a CHANGE to an existing feature. Additionally check:
-- Compatibility with parent feature's existing implementation
-- Whether breaking changes listed in the change REQUEST.md are properly handled
+```
+You are Sage. Verify test coverage for feature: {slug}
 
-Your review must check:
+## Implementation Diff
+{$IMPL_DIFF}
 
-### 1. Completeness
-- Are all tasks from PLAN.md implemented? List any missing tasks.
-- Are all files from eng.md created/modified as specified?
+## Changed Files
+{$CHANGED_FILES}
 
-### 2. Correctness
-- Does the implementation match the technical approach in eng.md?
-- If pm.md exists: are acceptance criteria met?
-- If ux.md exists: are user flows implemented correctly?
+## Engineering Spec
+{$ENG}
 
-### 3. Deviations
-- Read the Deviations section of IMPLEMENT.md
-- Are listed deviations justified?
-- Are there unlisted deviations (implementation differs from plan but not recorded)?
+## Implementation Plan
+{$PLAN}
 
-### 4. Test coverage
-- Does every task have at least one test?
-- Do tests exercise real code through public interfaces (no mocks unless external dependency)?
-- Do test names describe behavior clearly?
-- Are edge cases from eng.md covered?
-- If TDD was enabled: verify tests were written before implementation (check git log order)
+## Project Context
+{$CONTEXT}
 
-### 5. Code quality
-- Any obvious bugs or logic errors?
-- Security concerns (injection, auth bypass, data exposure)?
+Your task — check what is tested and what is not:
 
-### Output format:
+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
 
-## Review: {feature-slug}
+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)
 
-### Verdict: {PASS|FAIL}
+Output format:
+## Coverage Analysis
 
-### Completeness
-- {task_id}: {status} — {details}
+### Untested Modules (P1)
+- {file}:{function/class} — No tests found
+(or "All modules have tests.")
 
-### Correctness
-- {finding with file:line reference}
+### Missing Critical Paths (P2)
+- {file}:{function} — Missing: {description of untested path}
 
-### Deviations
-- {deviation}: {justified|unjustified} — {reason}
+### Missing Edge Cases (P3)
+- {file}:{function} — Missing: {description of edge case}
 
-### Issues (if any)
-- [{severity}] {file}:{line} — {description}
+## Suggested Tests
+1. {test description} — covers {what it covers}
+2. ...
 
-Follow code-reviewer rules from RPI agent guidelines:
-- Every finding cites a plan requirement or coding standard
-- No style nitpicks — focus on correctness, completeness, plan alignment
-- Verdict is PASS only if all requirements are met
+## Summary
+- Modules without tests: {N}
+- Missing critical paths: {N}
+- Missing edge cases: {N}
 ```
 
-## 4. Update IMPLEMENT.md
+Store the output as `$SAGE_OUTPUT`.
+
+## Step 5: Wait for completion
+
+Wait for all three agents (Hawk, Shield, Sage) to complete.
 
-Write the review results into the `## Review` section of IMPLEMENT.md.
+## Step 6: Launch Nexus — synthesize findings
 
-## 5. Present verdict
+Launch Nexus agent to produce the final review report:
 
-If PASS:
 ```
-Review: PASS
-All {N} tasks implemented. Requirements met.
-Feature {feature-slug} is complete.
+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}
 ```
 
-If FAIL:
+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.")
 ```
-Review: FAIL
-{list specific gaps}
 
-Options:
-- Fix the issues and re-run: /rpi:review {feature-slug}
-- Accept as-is: mark complete manually in IMPLEMENT.md
+## Step 10: 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})
 
-</process>
+{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}
+```

package/commands/rpi/rpi.md

@@ -0,0 +1,125 @@
+---
+name: rpi
+description: Auto-progress a feature to its next phase. Detects current state and runs the appropriate step.
+argument-hint: "<feature-name> [--skip=phase] [--from=phase] [--force]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+# /rpi — Auto-Flow
+
+Detects the current phase of a feature and runs the next step automatically.
+
+---
+
+## Step 1: Load config and parse arguments
+
+1. Read `.rpi.yaml` for config. Apply defaults if missing:
+   - `folder`: `rpi/features`
+2. Parse `$ARGUMENTS` to extract:
+   - `{slug}` — the feature name (required)
+   - `--skip=phase` — skip a specific phase and detect the next one
+   - `--from=phase` — override detection, start from this phase
+   - `--force` — pass through to the delegated command
+
+If `{slug}` is not provided, ask with AskUserQuestion: "Which feature? Provide the slug (e.g. 'oauth', 'dark-mode')."
+
+## Step 2: Validate feature exists
+
+Check if `rpi/features/{slug}/` exists and contains `REQUEST.md`.
+
+If the directory does not exist:
+```
+Feature '{slug}' not found. Run /rpi:new {slug} to start.
+```
+Stop.
+
+If the directory exists but `REQUEST.md` is missing:
+```
+Feature '{slug}' has no REQUEST.md. This shouldn't happen. Run /rpi:new {slug} to recreate it.
+```
+Stop.
+
+## Step 3: Detect current phase
+
+Check which artifacts exist to determine the next phase:
+
+1. Has `REQUEST.md`, no `research/RESEARCH.md` → next = **research**
+2. Has `research/RESEARCH.md`, no `plan/PLAN.md` → next = **plan**
+3. Has `plan/PLAN.md`, no `implement/IMPLEMENT.md` → next = **implement**
+4. Has `implement/IMPLEMENT.md` but NOT all tasks checked (`- [x]`) → next = **implement** (with `--resume`)
+5. Has `implement/IMPLEMENT.md` with all tasks complete, no "## Simplify" section in IMPLEMENT.md → next = **simplify**
+6. Has simplify done, no "## Review Verdict" section in IMPLEMENT.md → next = **review**
+7. Has "## Review Verdict" with PASS, no `docs/` output generated → next = **docs**
+8. Everything done → feature is complete
+
+### Detection details
+
+For step 4: Read `implement/IMPLEMENT.md` and check if any `- [ ]` (unchecked tasks) remain. If all tasks are `- [x]`, the implementation is complete.
+
+For step 5: Check if IMPLEMENT.md contains a `## Simplify` section. If not, simplify has not been run yet.
+
+For step 6: Check if IMPLEMENT.md contains a `## Review Verdict` section. If not, review has not been run yet.
+
+For step 7: Check if IMPLEMENT.md contains a `## Review Verdict` section with "PASS". Then check if docs have been generated (look for mention of docs completion in IMPLEMENT.md or a generated docs artifact).
+
+## Step 4: Apply --skip flag
+
+If `--skip=phase` was provided:
+- If the detected next phase matches the skipped phase, advance to the phase after it using the same detection logic.
+- Valid phase names: `research`, `plan`, `implement`, `simplify`, `review`, `docs`.
+- If the skip target is invalid, inform the user and stop.
+
+## Step 5: Apply --from flag
+
+If `--from=phase` was provided:
+- Override the detected phase. Set next = the specified phase.
+- Valid phase names: `research`, `plan`, `implement`, `simplify`, `review`, `docs`.
+- If the from target is invalid, inform the user and stop.
+- This is useful for re-running a phase (e.g., after fixing issues).
+
+## Step 6: Handle completion
+
+If no next phase was detected (everything is done):
+```
+{slug} is complete! All phases done.
+
+To archive: /rpi:archive {slug}
+To re-run a phase: /rpi {slug} --from=phase
+```
+Stop.
+
+## Step 7: Announce and delegate
+
+Output what is about to happen:
+
+```
+{slug} -> next: {phase}
+Starting {phase} phase...
+```
+
+Then delegate to the appropriate command:
+
+1. Read `commands/rpi/{phase}.md`
+2. Follow its process section exactly, passing through the `{slug}` and any relevant flags (like `--force`, `--resume`)
+
+The auto-flow command does NOT duplicate phase logic. It detects the state, announces the next step, and then executes the full process defined in the corresponding command file.
+
+### Phase-to-command mapping
+
+| Phase      | Command file          | Key artifacts                    |
+|------------|-----------------------|----------------------------------|
+| REQUEST    | `commands/rpi/new.md` | `REQUEST.md`                     |
+| RESEARCH   | `commands/rpi/research.md` | `research/RESEARCH.md`      |
+| PLAN       | `commands/rpi/plan.md`     | `plan/PLAN.md`              |
+| IMPLEMENT  | `commands/rpi/implement.md`| `implement/IMPLEMENT.md`    |
+| simplify   | `commands/rpi/simplify.md` | Simplify section in IMPLEMENT.md |
+| review     | `commands/rpi/review.md`   | Review Verdict in IMPLEMENT.md   |
+| docs       | `commands/rpi/docs.md`     | Generated documentation          |