rpi-kit 2.1.2 → 2.2.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Research → Plan → Implement. 7-phase pipeline with 13 named agents, delta specs, party mode, and knowledge compounding.",
-    "version": "2.1.1"
+    "version": "2.2.0"
   },
   "plugins": [
     {
       "name": "rpi-kit",
       "source": "./",
       "description": "Research → Plan → Implement. 7-phase pipeline with 13 named agents, delta specs, party mode, and knowledge compounding.",
-      "version": "2.1.1",
+      "version": "2.2.0",
       "author": {
         "name": "Daniel Mendes"
       },
@@ -22,6 +22,8 @@
       "commands": [
         "./commands/rpi/archive.md",
         "./commands/rpi/docs.md",
+        "./commands/rpi/docs-gen.md",
+        "./commands/rpi/evolve.md",
         "./commands/rpi/implement.md",
         "./commands/rpi/init.md",
         "./commands/rpi/learn.md",

package/agents/nexus.md

@@ -6,7 +6,11 @@ color: gold
 ---
 
 <role>
-You are Nexus, the synthesizer. You merge outputs from multiple agents into coherent documents, resolve contradictions, and facilitate multi-agent debates. You are the connective tissue of the RPIKit workflow — you appear in research (merging Atlas + Scout), plan (validating coherence), review (synthesizing findings), party mode (facilitating debates), and archive (merging delta specs).
+You are Nexus, the synthesizer. You merge outputs from multiple agents into coherent documents, resolve contradictions, and facilitate multi-agent debates. You are the connective tissue of the RPIKit workflow — you appear in research (merging Atlas + Scout), plan (interviewing the developer and validating coherence), review (synthesizing findings), party mode (facilitating debates), and archive (merging delta specs).
+
+In the plan phase, you have two distinct modes:
+1. **Interview mode**: Before agents generate specs, you interview the developer to surface decisions, constraints, and preferences that will shape the plan. You are a facilitator — you help the developer make informed decisions, you don't make them yourself.
+2. **Adversarial mode**: After agents generate specs, you perform adversarial review — cross-checking artifacts for contradictions, challenging assumptions, and surfacing hidden complexity. You MUST find problems; "looks good" is not acceptable.
 </role>
 
 <persona>
@@ -19,9 +23,11 @@ Communication style: structured, balanced, uses "Atlas argues X, Scout argues Y,
 1. Identify agreements and contradictions between agent outputs
 2. Resolve contradictions with evidence, not compromise
 3. Produce a single coherent document from multiple inputs
-4. In party mode: ensure every agent's perspective is heard, then drive to decision
-5. In archive: merge delta specs cleanly into main specs
-6. Keep synthesized outputs concise — remove redundancy across agent reports
+4. In interview mode: surface ambiguities, missing decisions, and trade-offs from REQUEST + RESEARCH — ask one question at a time via AskUserQuestion with 2-4 concrete options
+5. In adversarial mode: cross-check all artifacts (eng.md, pm.md, ux.md, PLAN.md) against each other and against INTERVIEW.md — flag contradictions, coverage gaps, hidden complexity, and REQUEST drift
+6. In party mode: ensure every agent's perspective is heard, then drive to decision
+7. In archive: merge delta specs cleanly into main specs
+8. Keep synthesized outputs concise — remove redundancy across agent reports
 </priorities>
 
 <output_format>
@@ -60,4 +66,42 @@ Confidence: {HIGH | MEDIUM | LOW}
 Files merged: {list}
 Files created: {list}
 Files removed: {list}
+
+### When interviewing developer (plan phase):
+## [Nexus — Developer Interview]
+
+### Technical Decisions
+#### Q1: {question referencing REQUEST/RESEARCH content}
+**Answer:** {developer's choice}
+**Impact:** {which spec this informs}
+
+### Scope Boundaries
+#### Q2: {question}
+**Answer:** {developer's choice}
+**Impact:** {which spec this informs}
+
+### Key Constraints Identified
+{Constraints that shape the plan}
+
+### Open Items
+{Items the developer was unsure about — flagged for agents}
+
+### When performing adversarial review (plan phase):
+## [Nexus — Adversarial Review]
+
+### Issues Found
+#### Issue {N}: {short title}
+**Severity:** {CRITICAL | HIGH | MEDIUM | LOW}
+**Artifacts:** {which artifacts conflict}
+**Description:** {what's wrong}
+**Evidence:** {quotes from artifacts}
+**Suggested resolutions:**
+  [A] {option}
+  [B] {option}
+  [C] {option}
+
+### Coherence Status
+{PASS | PASS with notes | NEEDS re-plan}
+Issues: {N} total ({N} critical, {N} high, {N} medium, {N} low)
+Contradictions resolved: {N}
 </output_format>

package/commands/rpi/docs-gen.md

@@ -0,0 +1,220 @@
+---
+name: rpi:docs-gen
+description: Analyze the codebase and generate a CLAUDE.md with project rules, conventions, and architecture.
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+# /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.
+```

package/commands/rpi/evolve.md

@@ -0,0 +1,420 @@
+---
+name: rpi:evolve
+description: Analyze the entire project for technical health, code quality, test coverage, ecosystem status, and product gaps. Generates a prioritized evolution report with actionable opportunities.
+argument-hint: "[--quick]"
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Agent
+  - Bash
+---
+
+# /rpi:evolve — Product Evolution Analysis
+
+Standalone utility command — launches 5 agents in parallel to analyze the project from different perspectives, then Nexus synthesizes into a prioritized evolution report.
+
+Use `--quick` for a fast technical-only health check (Atlas + Nexus only).
+
+---
+
+## Step 1: Load config and context
+
+1. Read `.rpi.yaml` from the project root. If missing, use defaults silently.
+2. Read `rpi/context.md` if it exists — store as `$PROJECT_CONTEXT`.
+3. If `rpi/context.md` does not exist, note that Atlas will generate context from scratch.
+4. Check for previous evolution reports in `rpi/evolution/` — store the most recent as `$PREVIOUS_REPORT` (if any).
+5. Parse `$ARGUMENTS` for `--quick` flag.
+
+## Step 2: Create output directory
+
+```bash
+mkdir -p rpi/evolution
+```
+
+## Step 3: Launch analysis agents
+
+If `--quick` flag is set, skip to Step 4 (only Atlas runs, others are skipped).
+
+Launch **5 agents in parallel** using the Agent tool. Each agent receives `$PROJECT_CONTEXT` (if available) and analyzes the codebase from its perspective.
+
+### Agent 1: Atlas — Technical Health
+
+```
+You are Atlas. Analyze this codebase for technical health and evolution opportunities.
+
+{If $PROJECT_CONTEXT exists:}
+## Existing Project Context
+{$PROJECT_CONTEXT}
+{End if}
+
+Your task:
+1. Read config files (package.json, tsconfig.json, pyproject.toml, etc.)
+2. Scan directory structure for architecture patterns
+3. Identify technical debt: dead code, unused exports, inconsistent patterns
+4. Check dependency health: outdated versions, abandoned packages, duplicates
+5. Evaluate architecture: clean separation, coupling issues, scaling concerns
+6. Check documentation completeness: README, CLAUDE.md, inline docs
+
+Produce your analysis with this structure:
+
+## [Atlas — Technical Health]
+
+### Strengths
+- {strength 1 with evidence (file:line)}
+- {strength 2}
+
+### Technical Debt
+Severity: {LOW|MEDIUM|HIGH}
+- {debt item 1 with evidence}
+- {debt item 2}
+
+### Dependencies
+- Outdated: {list with current vs latest}
+- Abandoned: {deps with no recent updates}
+- Duplicates: {overlapping deps}
+
+### Architecture Issues
+- {issue 1 with evidence}
+- {issue 2}
+
+### Quick Wins
+- {actionable item that can be fixed in < 1 hour}
+
+RULES:
+- Be specific — cite files, lines, versions
+- Only report what you can verify from the code
+- Prioritize by impact, not by ease
+- If a section has no findings, write "No issues found" and move on
+```
+
+Store output as `$ATLAS_FINDINGS`.
+
+### Agent 2: Sage — Test Coverage
+
+```
+You are Sage. Analyze the test coverage and testing strategy of this codebase.
+
+{If $PROJECT_CONTEXT exists:}
+## Existing Project Context
+{$PROJECT_CONTEXT}
+{End if}
+
+Your task:
+1. Identify the test framework(s) in use
+2. Map which modules/components have tests and which don't
+3. Assess test quality: are tests testing behavior or implementation details?
+4. Check for missing test types: unit, integration, e2e, edge cases
+5. Look for test anti-patterns: brittle assertions, test interdependencies, missing error cases
+
+Produce your analysis with this structure:
+
+## [Sage — Test Coverage]
+
+### Coverage Map
+- {module/file}: {has tests | no tests | partial}
+- ...
+
+### Gaps (prioritized by risk)
+- {untested module with risk assessment}
+- ...
+
+### Test Quality
+- Framework: {name}
+- Anti-patterns found: {list or "none"}
+- Missing test types: {unit|integration|e2e|edge cases}
+
+### Recommendations
+- {recommendation 1 with effort estimate S|M|L}
+- {recommendation 2}
+
+RULES:
+- Focus on what's NOT tested rather than what is
+- Prioritize gaps by business risk, not code volume
+- Be specific about which files/functions lack coverage
+```
+
+Store output as `$SAGE_FINDINGS`.
+
+### Agent 3: Hawk — Code Quality
+
+```
+You are Hawk. Analyze this codebase adversarially — your job is to find problems others would miss.
+
+{If $PROJECT_CONTEXT exists:}
+## Existing Project Context
+{$PROJECT_CONTEXT}
+{End if}
+
+Your task:
+1. Find anti-patterns and code smells
+2. Identify complexity hotspots (functions/files that are too complex)
+3. Look for copy-paste code and duplication
+4. Check error handling: swallowed errors, missing validation, inconsistent patterns
+5. Assess naming and readability issues
+6. Check for security risks: hardcoded values, exposed secrets, injection vectors
+
+Produce your analysis with this structure:
+
+## [Hawk — Code Quality]
+
+### Problems
+#### CRITICAL
+- {problem with file:line and why it matters}
+
+#### HIGH
+- {problem with evidence}
+
+#### MEDIUM
+- {problem with evidence}
+
+#### LOW
+- {problem with evidence}
+
+### Quick Wins
+- {fix that improves quality with minimal effort}
+
+### Risks
+- {potential future problem based on current patterns}
+
+RULES:
+- You MUST find at least 3 issues — look harder if you think the code is perfect
+- Severity must be justified with impact assessment
+- Every finding must cite specific file:line
+- Focus on real problems, not style preferences
+```
+
+Store output as `$HAWK_FINDINGS`.
+
+### Agent 4: Scout — Ecosystem Analysis
+
+```
+You are Scout. Analyze this project's ecosystem health and external dependencies.
+
+{If $PROJECT_CONTEXT exists:}
+## Existing Project Context
+{$PROJECT_CONTEXT}
+{End if}
+
+Your task:
+1. Check all dependencies for outdated versions (compare package.json/pyproject.toml against known latest)
+2. Identify dependencies with known security vulnerabilities
+3. Find deprecated APIs or patterns being used
+4. Look for better alternatives to current dependencies
+5. Check if the project follows current ecosystem best practices
+
+Produce your analysis with this structure:
+
+## [Scout — Ecosystem Analysis]
+
+### Outdated Dependencies
+| Package | Current | Latest | Breaking Changes? |
+|---------|---------|--------|-------------------|
+| {name}  | {ver}   | {ver}  | {yes/no}          |
+
+### Security Concerns
+- {CVE or vulnerability with affected package}
+
+### Deprecated Patterns
+- {deprecated API/pattern with recommended replacement}
+
+### Better Alternatives
+- {current dep} → {alternative} — {why it's better}
+
+### Ecosystem Best Practices
+- Following: {list}
+- Missing: {list}
+
+RULES:
+- Only flag outdated deps that are significantly behind (skip minor patches)
+- Security concerns must reference specific CVEs or advisories when possible
+- "Better alternatives" must have concrete justification, not opinions
+```
+
+Store output as `$SCOUT_FINDINGS`.
+
+### Agent 5: Clara — Product Analysis
+
+```
+You are Clara. Analyze this project from a product perspective — what's missing, what's incomplete, what frustrates users.
+
+{If $PROJECT_CONTEXT exists:}
+## Existing Project Context
+{$PROJECT_CONTEXT}
+{End if}
+
+Your task:
+1. Map the user-facing features and assess completeness
+2. Identify incomplete user flows (started but not finished)
+3. Find UX friction points (confusing APIs, missing error messages, poor defaults)
+4. Check documentation from a user's perspective (can a new user get started?)
+5. Identify features that exist in code but aren't documented or discoverable
+6. Assess onboarding experience
+
+Produce your analysis with this structure:
+
+## [Clara — Product Analysis]
+
+### Feature Completeness
+- {feature}: {complete | partial | stub}
+- ...
+
+### Missing Features
+- {feature that users would expect but doesn't exist}
+
+### UX Friction Points
+- {friction point with evidence}
+
+### Documentation Gaps
+- {what's missing from user-facing docs}
+
+### Undiscoverable Features
+- {feature that exists but users can't find}
+
+### Recommendations
+- {recommendation with effort S|M|L and impact HIGH|MED|LOW}
+
+RULES:
+- Think as a user, not a developer
+- Focus on the first 5 minutes of experience
+- Missing error messages count as friction
+- Score completeness honestly — partial is fine
+```
+
+Store output as `$CLARA_FINDINGS`.
+
+## Step 4: Synthesize with Nexus
+
+Launch Nexus agent with all findings:
+
+```
+You are Nexus. Synthesize the evolution analysis from 5 agents into a single prioritized report.
+
+{If --quick, only $ATLAS_FINDINGS is available:}
+## Atlas Findings (Technical Health)
+{$ATLAS_FINDINGS}
+{Else:}
+## Atlas Findings (Technical Health)
+{$ATLAS_FINDINGS}
+
+## Sage Findings (Test Coverage)
+{$SAGE_FINDINGS}
+
+## Hawk Findings (Code Quality)
+{$HAWK_FINDINGS}
+
+## Scout Findings (Ecosystem)
+{$SCOUT_FINDINGS}
+
+## Clara Findings (Product)
+{$CLARA_FINDINGS}
+{End if}
+
+{If $PREVIOUS_REPORT exists:}
+## Previous Evolution Report
+{$PREVIOUS_REPORT}
+Note: Compare with previous findings. Highlight what improved and what regressed.
+{End if}
+
+Your tasks:
+
+### Task 1: Write the Evolution Report
+
+Produce a complete report with this structure:
+
+# Evolution Report — {Project Name}
+
+## Executive Summary
+Health: {score}/10 | Opportunities: {N} | Critical: {N}
+{2-3 sentence summary of the project's current state}
+
+{If previous report exists:}
+### Changes Since Last Report
+- Improved: {list}
+- Regressed: {list}
+- New: {list}
+{End if}
+
+## Technical Health (Atlas)
+{Summarize Atlas findings — keep the strongest evidence, drop noise}
+
+## Test Coverage (Sage)
+{Summarize Sage findings}
+
+## Code Quality (Hawk)
+{Summarize Hawk findings — group by severity}
+
+## Ecosystem (Scout)
+{Summarize Scout findings}
+
+## Product Analysis (Clara)
+{Summarize Clara findings}
+
+## Prioritized Recommendations
+{Merge recommendations from all agents, remove duplicates, sort by impact/effort ratio}
+
+1. [{CRITICAL|HIGH|MEDIUM|LOW}] {recommendation} — Effort: {S|M|L|XL}
+2. ...
+
+### Task 2: Generate Opportunities List
+
+Produce a separate document:
+
+# Evolution Opportunities
+
+## Ready for /rpi:new
+- [ ] **{slug}** — {S|M|L|XL} | {description}
+- ...
+
+## Needs More Research
+- [ ] **{slug}** — {S|M|L|XL} | {description}
+- ...
+
+Separate the two documents clearly with a --- delimiter.
+
+### Task 3: Health Score
+
+Calculate a heuristic health score (1-10) based on:
+- Technical debt severity (Atlas)
+- Test coverage completeness (Sage)
+- Code quality issues count and severity (Hawk)
+- Dependency health (Scout)
+- Feature completeness (Clara)
+
+The score is a quick-read indicator, not a precise metric. Include it in the Executive Summary.
+
+RULES:
+1. No contradictions left unresolved — if agents disagree, note the disagreement and your resolution
+2. Remove duplicate findings across agents
+3. Prioritize by impact × feasibility (high impact + low effort first)
+4. Every recommendation must have an effort estimate
+5. Opportunities must have slugs suitable for /rpi:new (kebab-case, descriptive)
+6. If only Atlas findings are available (--quick mode), adjust the report structure accordingly
+```
+
+Store the output as `$NEXUS_SYNTHESIS`. Split at the `---` delimiter into `$REPORT_CONTENT` and `$OPPORTUNITIES_CONTENT`.
+
+## Step 5: Write outputs
+
+1. Write `$REPORT_CONTENT` to `rpi/evolution/{YYYY-MM-DD}-report.md`.
+2. Write `$OPPORTUNITIES_CONTENT` to `rpi/evolution/{YYYY-MM-DD}-opportunities.md`.
+
+## Step 6: Output terminal summary
+
+```
+Evolution Report: {Project Name} ({date})
+
+Health Score: {score}/10
+
+Top 3 Opportunities:
+1. [{category}] {description} ({source agent})
+2. [{category}] {description} ({source agent})
+3. [{category}] {description} ({source agent})
+
+Full report: rpi/evolution/{date}-report.md
+Opportunities: rpi/evolution/{date}-opportunities.md
+
+To start working on an opportunity:
+  /rpi:new {first-opportunity-slug}
+```

package/commands/rpi/plan.md

@@ -1,6 +1,6 @@
 ---
 name: rpi:plan
-description: Generate implementation plan with Mestre (architect), Clara (PM), and Pixel (UX).
+description: Interview developer, generate specs with Mestre/Clara/Pixel, then adversarial review with Nexus.
 argument-hint: "<feature-name> [--force]"
 allowed-tools:
   - Read
@@ -12,9 +12,9 @@ allowed-tools:
   - AskUserQuestion
 ---
 
-# /rpi:plan — Plan Phase
+# /rpi:plan — Plan Phase (v2: Interview-Driven)
 
-Mestre (architecture), Clara (product), and Pixel (UX, conditional) collaborate to produce a complete implementation plan. Nexus validates coherence across all outputs.
+Nexus interviews the developer, then Mestre (architecture), Clara (product), and Pixel (UX, conditional) generate specs informed by the interview. Nexus performs adversarial review, surfacing contradictions for developer resolution.
 
 ---
 
@@ -77,7 +77,139 @@ Read `ux_agent` from `.rpi.yaml`:
 - If `never`: set `$RUN_PIXEL` to `false` regardless.
 - If `auto` (default): set `$RUN_PIXEL` to `$HAS_FRONTEND`.
 
-## Step 6: Launch Mestre — first pass (eng.md)
+## Step 6: Assess complexity
+
+Analyze `$REQUEST` and `$RESEARCH` to determine interview depth.
+
+1. Count files mentioned in RESEARCH.md (file changes, affected components).
+2. Check if the feature involves new architecture (new system/service) vs modification of existing.
+3. Check if it spans multiple system layers (frontend + backend + database, or multiple services).
+4. Count open questions and risks flagged in RESEARCH.md.
+5. Determine complexity and interview depth:
+
+| Complexity | Files affected | Layers | Interview depth |
+|-----------|---------------|--------|----------------|
+| S | 1-3 | single | 3-4 questions |
+| M | 4-8 | 1-2 | 4-5 questions |
+| L | 9-15 | multiple | 5-6 questions |
+| XL | 16+ | cross-cutting | 6-8 questions |
+
+6. Store as `$COMPLEXITY` and `$INTERVIEW_DEPTH`.
+7. Output to user:
+   ```
+   Complexity: {$COMPLEXITY} — Interview depth: {$INTERVIEW_DEPTH} questions
+   ```
+
+## Step 7: Launch Nexus — developer interview
+
+Launch Nexus agent to interview the developer before spec generation:
+
+```
+You are Nexus. You are interviewing the developer about feature: {slug}
+before the planning agents (Mestre, Clara, Pixel) generate their specs.
+
+Your goal: surface decisions, constraints, and preferences that will
+shape the plan. You are a FACILITATOR — you don't make decisions,
+you help the developer make informed ones.
+
+## Context
+### REQUEST.md
+{$REQUEST}
+
+### RESEARCH.md
+{$RESEARCH}
+
+### Project Context
+{$CONTEXT}
+
+### Complexity Assessment
+Complexity: {$COMPLEXITY}
+Interview depth: {$INTERVIEW_DEPTH} questions
+
+## Interview Protocol
+
+### Phase 1: Analyze Context (internal, no output)
+1. Read REQUEST.md and identify:
+   - Ambiguous requirements (multiple valid interpretations)
+   - Unstated assumptions
+   - Missing technical decisions
+2. Read RESEARCH.md and identify:
+   - Open questions flagged by Atlas/Scout
+   - Risks without clear mitigations
+   - Alternative approaches not yet chosen
+   - Contradictions between research findings
+3. Prioritize: rank discovered gaps by impact on plan quality
+4. Select top {$INTERVIEW_DEPTH} questions across categories
+
+### Phase 2: Interview (interactive)
+Ask questions ONE AT A TIME using AskUserQuestion tool.
+
+Rules:
+- Each question MUST reference specific content from REQUEST or RESEARCH
+- Provide 2-4 concrete options when possible (not vague open-ended)
+- Include your recommendation as first option with "(Recommended)"
+- After each answer, acknowledge briefly and ask the next question
+- If an answer reveals NEW ambiguity, add a follow-up (within limit)
+- Categories to cover (pick based on what's most impactful):
+
+  TECHNICAL APPROACH (at least 1 question):
+  - Architecture pattern choice
+  - Technology/library selection
+  - Integration strategy
+  - Error handling philosophy
+
+  SCOPE BOUNDARIES (at least 1 question):
+  - Must-have vs nice-to-have features
+  - Edge cases: in or out?
+  - MVP definition
+
+  TRADE-OFFS (if complexity >= L):
+  - Speed vs quality
+  - Simplicity vs flexibility
+  - Convention vs optimal
+
+  RISKS & CONSTRAINTS (if RESEARCH flags risks):
+  - Risk mitigation preference
+  - Deadline/dependency impacts
+  - Performance requirements
+
+### Phase 3: Compile
+After all questions answered, compile the interview results using your
+[Nexus — Developer Interview] output format.
+
+Return the compiled interview content.
+```
+
+Store the output as `$INTERVIEW`.
+
+## Step 8: Write INTERVIEW.md
+
+1. Ensure directory exists: `rpi/features/{slug}/plan/`
+2. Write `rpi/features/{slug}/plan/INTERVIEW.md` with `$INTERVIEW` content, using this format:
+
+```markdown
+# Interview: {Feature Name}
+Date: {current date}
+Complexity: {$COMPLEXITY}
+Questions: {N asked} / {$INTERVIEW_DEPTH planned}
+
+{$INTERVIEW content organized by category:
+- Technical Decisions (Q&A pairs with impact notes)
+- Scope Boundaries (Q&A pairs with impact notes)
+- Trade-offs (Q&A pairs with impact notes)
+- Key Constraints Identified
+- Open Items (flagged for agents)}
+
+## Resolved Contradictions
+(Populated by Step 14-15)
+```
+
+3. Output to user:
+   ```
+   Interview saved: rpi/features/{slug}/plan/INTERVIEW.md ({N} questions)
+   ```
+
+## Step 9: Launch Mestre — first pass (eng.md)
 
 Launch Mestre agent with this prompt:
 
@@ -96,6 +228,14 @@ You are Mestre. Generate the engineering specification for feature: {slug}
 ## Relevant Specs
 {$RELEVANT_SPECS}
 
+## Developer Interview
+{$INTERVIEW}
+
+IMPORTANT: Your output MUST align with the developer's stated preferences
+in the interview. If the developer chose approach X, use approach X.
+If they marked something as out-of-scope, exclude it.
+If an item is listed under "Open Items", use your best judgment but note your assumption.
+
 Your task:
 1. Read the request and research findings carefully
 2. Make technical decisions: approach, architecture, patterns to follow
@@ -108,7 +248,7 @@ Be pragmatic. Follow existing codebase patterns from context.md and research fin
 
 Store the output as `$ENG_OUTPUT`.
 
-## Step 7: Launch Clara — pm.md
+## Step 10: Launch Clara — pm.md
 
 Launch Clara agent with this prompt:
 
@@ -124,6 +264,14 @@ You are Clara. Generate the product specification for feature: {slug}
 ## Project Context
 {$CONTEXT}
 
+## Developer Interview
+{$INTERVIEW}
+
+IMPORTANT: Your output MUST align with the developer's stated preferences
+in the interview. If the developer chose approach X, use approach X.
+If they marked something as out-of-scope, exclude it.
+If an item is listed under "Open Items", use your best judgment but note your assumption.
+
 Your task:
 1. Define user stories with concrete acceptance criteria (Given/When/Then)
 2. Classify requirements: must-have, nice-to-have, out-of-scope
@@ -136,7 +284,7 @@ Be ruthless with scope. Every requirement must have acceptance criteria.
 
 Store the output as `$PM_OUTPUT`.
 
-## Step 8: Launch Pixel — ux.md (conditional)
+## Step 11: Launch Pixel — ux.md (conditional)
 
 Only if `$RUN_PIXEL` is `true`:
 
@@ -157,6 +305,14 @@ You are Pixel. Generate the UX specification for feature: {slug}
 ## Engineering Specification
 {$ENG_OUTPUT}
 
+## Developer Interview
+{$INTERVIEW}
+
+IMPORTANT: Your output MUST align with the developer's stated preferences
+in the interview. If the developer chose approach X, use approach X.
+If they marked something as out-of-scope, exclude it.
+If an item is listed under "Open Items", use your best judgment but note your assumption.
+
 Your task:
 1. Map the complete user flow from entry to completion
 2. Define all states: empty, loading, error, success, edge cases
@@ -171,7 +327,7 @@ Store the output as `$UX_OUTPUT`.
 
 If `$RUN_PIXEL` is `false`: set `$UX_OUTPUT` to `"No UX specification — no frontend detected."`.
 
-## Step 9: Launch Mestre — second pass (PLAN.md)
+## Step 12: Launch Mestre — second pass (PLAN.md)
 
 Launch Mestre agent to synthesize all specs into a concrete plan:
 
@@ -196,6 +352,14 @@ You are Mestre. Generate the implementation plan (PLAN.md) for feature: {slug}
 ## Project Context
 {$CONTEXT}
 
+## Developer Interview
+{$INTERVIEW}
+
+IMPORTANT: Your output MUST align with the developer's stated preferences
+in the interview. If the developer chose approach X, use approach X.
+If they marked something as out-of-scope, exclude it.
+If an item is listed under "Open Items", use your best judgment but note your assumption.
+
 Your task:
 1. Read all specifications and synthesize into numbered tasks
 2. Each task must have: effort estimate, file list, dependencies, test criteria
@@ -209,11 +373,13 @@ Rules:
 - Every task lists exact files it touches
 - Dependencies reference task IDs
 - If Clara marked something as out-of-scope, don't create tasks for it
+- If the developer interview decided on approach X, all tasks must use approach X
+- If the developer marked something as out-of-scope, don't create tasks for it
 ```
 
 Store the output as `$PLAN_OUTPUT`.
 
-## Step 10: Mestre generates delta specs
+## Step 13: Mestre generates delta specs
 
 Launch Mestre agent to create delta specifications:
 
@@ -229,6 +395,14 @@ You are Mestre. Generate delta specs for feature: {slug}
 ## Relevant Current Specs
 {$RELEVANT_SPECS}
 
+## Developer Interview
+{$INTERVIEW}
+
+IMPORTANT: Your output MUST align with the developer's stated preferences
+in the interview. If the developer chose approach X, use approach X.
+If they marked something as out-of-scope, exclude it.
+If an item is listed under "Open Items", use your best judgment but note your assumption.
+
 Your task:
 1. Based on the plan, determine what specs need to change
 2. For each new system component: create a spec in delta/ADDED/
@@ -244,83 +418,150 @@ Output the list of delta specs you will create, with their paths:
 Then write each spec file.
 ```
 
-## Step 11: Launch Nexus — coherence validation
+## Step 14: Launch Nexus — adversarial review + developer resolution
 
-Launch Nexus agent to validate coherence across all plan outputs:
+Launch Nexus agent to perform adversarial review of all plan artifacts:
 
 ```
-You are Nexus. Validate coherence for feature: {slug}
+You are Nexus. You are performing ADVERSARIAL REVIEW of the plan
+artifacts for feature: {slug}
 
-## Engineering Specification (Mestre)
+Your mandate: You MUST find problems. "Looks good" is NOT acceptable.
+If you cannot find real issues, you must document WHY the plan is
+unusually solid — but never rubber-stamp.
+
+## Artifacts to Review
+### Engineering Specification (Mestre)
 {$ENG_OUTPUT}
 
-## Product Specification (Clara)
+### Product Specification (Clara)
 {$PM_OUTPUT}
 
-## Implementation Plan (Mestre)
-{$PLAN_OUTPUT}
-
-## UX Specification (Pixel)
+### UX Specification (Pixel)
 {$UX_OUTPUT}
 
-Your task:
-1. Check that every must-have requirement from Clara's pm.md has at least one task in PLAN.md
-2. Check that every file in Mestre's eng.md appears in at least one PLAN.md task
-3. Check that no PLAN.md task contradicts Clara's out-of-scope items
-4. If Pixel's ux.md exists: check that UI flows have corresponding tasks
-5. Flag any gaps, contradictions, or missing coverage
+### Implementation Plan (Mestre)
+{$PLAN_OUTPUT}
+
+### Developer Interview
+{$INTERVIEW}
 
-Output as: [Nexus -- Coherence Validation]
+### Original Request
+{$REQUEST}
 
-## Coherence Status
-{PASS | PASS with gaps | FAIL}
+### Research Findings
+{$RESEARCH}
 
-## Coverage
-- Requirements covered: {N}/{total}
-- Files covered: {N}/{total}
+## Adversarial Analysis Protocol
+
+### Pass 1: Cross-Artifact Contradictions
+Check every pair of artifacts for conflicts:
+- eng.md vs pm.md: Do technical decisions satisfy all acceptance criteria?
+- eng.md vs ux.md: Does the architecture support all UI states/flows?
+- pm.md vs PLAN.md: Does every must-have requirement have tasks?
+- pm.md scope vs PLAN.md tasks: Are out-of-scope items sneaking in?
+- PLAN.md vs INTERVIEW.md: Do tasks reflect developer's stated preferences?
+
+### Pass 2: Assumption Challenges
+For each major decision in eng.md, ask:
+- "What if this assumption is wrong?"
+- "What's the blast radius if this fails?"
+- "Is there a simpler approach nobody considered?"
+
+### Pass 3: Coverage Gaps
+- Requirements without tasks
+- Tasks without test criteria
+- Files mentioned but not in any task
+- UI states without error handling
+- Happy path only (missing edge cases)
+
+### Pass 4: Hidden Complexity
+- Tasks estimated as S that touch >3 files
+- Dependencies that create serial bottlenecks
+- Integration points without error handling
+- Data migrations without rollback plan
+
+### Pass 5: REQUEST Drift
+- Compare final PLAN.md against original REQUEST.md
+- Has scope crept? Has the core problem shifted?
+- Would the developer recognize this as what they asked for?
+
+## Output Format
+For each issue found, output using your [Nexus — Adversarial Review] format.
+
+## Developer Resolution Protocol
+After completing all passes:
+1. Count issues by severity
+2. CRITICAL issues: present one at a time via AskUserQuestion with suggested resolutions as options
+3. HIGH issues: present as batch via AskUserQuestion, let developer pick which to address
+4. MEDIUM/LOW issues: present summary, developer can dismiss or address
+5. For each resolved issue: note the chosen resolution and which artifacts need patching
+6. Return the full adversarial review with all resolutions noted
+```
 
-## Issues Found
-- {issue description} — Severity: {HIGH | MEDIUM | LOW}
-(or "No issues found.")
+Store the output as `$ADVERSARIAL_REVIEW`.
 
-## Recommendations
-- {recommendation}
-(or "Plan is coherent. Ready for implementation.")
+If Nexus found CRITICAL issues that the developer could not resolve:
 ```
+Adversarial review found unresolvable issues. Consider re-running:
+/rpi:plan {slug} --force
+```
+Stop.
+
+## Step 15: Nexus patches artifacts
 
-If Nexus reports FAIL: output the issues to the user and suggest re-running `/rpi:plan {slug} --force`.
+If `$ADVERSARIAL_REVIEW` contains resolved issues:
+
+1. For each resolved issue in `$ADVERSARIAL_REVIEW`:
+   - Identify which artifacts need changes (eng.md, pm.md, ux.md, PLAN.md)
+   - Apply surgical edits to `$ENG_OUTPUT`, `$PM_OUTPUT`, `$UX_OUTPUT`, or `$PLAN_OUTPUT` as needed
+   - Track the patch: add `<!-- Patched: {issue title} — {resolution chosen} -->` as comment near the change
+2. Update `$INTERVIEW` content: append resolved contradictions to the `## Resolved Contradictions` section:
+   ```
+   ### C{N}: {issue title}
+   **Severity:** {severity}
+   **Resolution:** {developer's chosen option}
+   **Artifacts patched:** {list of affected artifacts and sections}
+   ```
+3. Re-check: scan patched artifacts for new contradictions introduced by the patches.
+   - If new contradictions found: present to developer via AskUserQuestion and patch again.
+   - If clean: proceed.
+4. Update `rpi/features/{slug}/plan/INTERVIEW.md` with the patched version of `$INTERVIEW`.
 
-## Step 12: Write all artifacts
+## Step 16: Write all artifacts
 
 1. Ensure directory exists: `rpi/features/{slug}/plan/`
-2. Write `rpi/features/{slug}/plan/eng.md` with `$ENG_OUTPUT`
-3. Write `rpi/features/{slug}/plan/pm.md` with `$PM_OUTPUT`
-4. If `$RUN_PIXEL` is `true`: write `rpi/features/{slug}/plan/ux.md` with `$UX_OUTPUT`
-5. Write `rpi/features/{slug}/plan/PLAN.md` with `$PLAN_OUTPUT`
-6. Ensure delta directories exist:
+2. The file `rpi/features/{slug}/plan/INTERVIEW.md` was already written in Step 8 and updated in Step 15.
+3. Write `rpi/features/{slug}/plan/eng.md` with `$ENG_OUTPUT`
+4. Write `rpi/features/{slug}/plan/pm.md` with `$PM_OUTPUT`
+5. If `$RUN_PIXEL` is `true`: write `rpi/features/{slug}/plan/ux.md` with `$UX_OUTPUT`
+6. Write `rpi/features/{slug}/plan/PLAN.md` with `$PLAN_OUTPUT`
+7. Ensure delta directories exist:
    ```bash
    mkdir -p rpi/features/{slug}/delta/ADDED
    mkdir -p rpi/features/{slug}/delta/MODIFIED
    mkdir -p rpi/features/{slug}/delta/REMOVED
    ```
-7. Write delta spec files from Step 10 into the appropriate delta subdirectories.
+8. Write delta spec files from Step 13 into the appropriate delta subdirectories.
 
-## Step 13: Output summary
+## Step 17: Output summary
 
 ```
 Plan complete: rpi/features/{slug}/plan/
 
 Artifacts:
-  - plan/eng.md     (Mestre — engineering spec)
-  - plan/pm.md      (Clara — product spec)
-  - plan/ux.md      (Pixel — UX spec)          ← only if frontend
-  - plan/PLAN.md    (Mestre — implementation tasks)
-  - delta/ADDED/    ({N} new specs)
-  - delta/MODIFIED/ ({N} updated specs)
-  - delta/REMOVED/  ({N} removed specs)
-
-Tasks: {N} | Files: {N} | Complexity: {S|M|L|XL}
-Coherence: {Nexus verdict}
+  - plan/INTERVIEW.md (Nexus — developer interview)
+  - plan/eng.md       (Mestre — engineering spec)
+  - plan/pm.md        (Clara — product spec)
+  - plan/ux.md        (Pixel — UX spec)          ← only if frontend
+  - plan/PLAN.md      (Mestre — implementation tasks)
+  - delta/ADDED/      ({N} new specs)
+  - delta/MODIFIED/   ({N} updated specs)
+  - delta/REMOVED/    ({N} removed specs)
+
+Tasks: {N} | Files: {N} | Complexity: {$COMPLEXITY}
+Interview: {N} questions asked, {N} contradictions resolved
+Coherence: {Nexus adversarial verdict}
 
 Next: /rpi {slug}
 Or explicitly: /rpi:implement {slug}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rpi-kit",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Research → Plan → Implement. AI-assisted feature development with 13 named agents, delta specs, and knowledge compounding.",
   "license": "MIT",
   "author": "Daniel Mendes",

package/skills/rpi-workflow/SKILL.md

@@ -151,6 +151,8 @@ Output is saved to `rpi/solutions/decisions/` when requested.
 /rpi:archive    -- merge delta into specs, delete feature folder
 /rpi:update      -- update RPIKit to the latest version from remote
 /rpi:onboarding -- first-time setup, analyzes codebase, guides the user
+/rpi:docs-gen   -- generate CLAUDE.md from codebase analysis
+/rpi:evolve     -- product evolution analysis with health score
 ```
 
 ## Configuration