rpi-kit 2.1.1 → 2.1.3

package/.claude-plugin/marketplace.json

@@ -1,26 +1,61 @@
 {
-  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "rpi-kit",
-  "version": "2.1.0",
-  "description": "Research → Plan → Implement. 7-phase pipeline with 13 named agents, delta specs, party mode, and knowledge compounding.",
   "owner": {
     "name": "Daniel Mendes"
   },
+  "metadata": {
+    "description": "Research → Plan → Implement. 7-phase pipeline with 13 named agents, delta specs, party mode, and knowledge compounding.",
+    "version": "2.1.1"
+  },
   "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.0",
+      "version": "2.1.1",
       "author": {
         "name": "Daniel Mendes"
       },
       "license": "MIT",
       "keywords": ["workflow", "research", "planning", "implementation", "agents", "delta-specs", "knowledge-compounding"],
       "category": "productivity",
-      "agents": 13,
-      "commands": 15,
-      "skills": 2
+      "commands": [
+        "./commands/rpi/archive.md",
+        "./commands/rpi/docs.md",
+        "./commands/rpi/docs-gen.md",
+        "./commands/rpi/implement.md",
+        "./commands/rpi/init.md",
+        "./commands/rpi/learn.md",
+        "./commands/rpi/new.md",
+        "./commands/rpi/onboarding.md",
+        "./commands/rpi/party.md",
+        "./commands/rpi/plan.md",
+        "./commands/rpi/research.md",
+        "./commands/rpi/review.md",
+        "./commands/rpi/rpi.md",
+        "./commands/rpi/simplify.md",
+        "./commands/rpi/status.md",
+        "./commands/rpi/update.md"
+      ],
+      "agents": [
+        "./agents/atlas.md",
+        "./agents/clara.md",
+        "./agents/forge.md",
+        "./agents/hawk.md",
+        "./agents/luna.md",
+        "./agents/mestre.md",
+        "./agents/nexus.md",
+        "./agents/pixel.md",
+        "./agents/quill.md",
+        "./agents/razor.md",
+        "./agents/sage.md",
+        "./agents/scout.md",
+        "./agents/shield.md"
+      ],
+      "skills": [
+        "./skills/rpi-agents/SKILL.md",
+        "./skills/rpi-workflow/SKILL.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/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/marketplace.json

@@ -0,0 +1,60 @@
+{
+  "name": "rpi-kit",
+  "owner": {
+    "name": "Daniel Mendes"
+  },
+  "metadata": {
+    "description": "Research → Plan → Implement. 7-phase pipeline with 13 named agents, delta specs, party mode, and knowledge compounding.",
+    "version": "2.1.1"
+  },
+  "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",
+      "author": {
+        "name": "Daniel Mendes"
+      },
+      "license": "MIT",
+      "keywords": ["workflow", "research", "planning", "implementation", "agents", "delta-specs", "knowledge-compounding"],
+      "category": "productivity",
+      "commands": [
+        "./commands/rpi/archive.md",
+        "./commands/rpi/docs.md",
+        "./commands/rpi/implement.md",
+        "./commands/rpi/init.md",
+        "./commands/rpi/learn.md",
+        "./commands/rpi/new.md",
+        "./commands/rpi/onboarding.md",
+        "./commands/rpi/party.md",
+        "./commands/rpi/plan.md",
+        "./commands/rpi/research.md",
+        "./commands/rpi/review.md",
+        "./commands/rpi/rpi.md",
+        "./commands/rpi/simplify.md",
+        "./commands/rpi/status.md",
+        "./commands/rpi/update.md"
+      ],
+      "agents": [
+        "./agents/atlas.md",
+        "./agents/clara.md",
+        "./agents/forge.md",
+        "./agents/hawk.md",
+        "./agents/luna.md",
+        "./agents/mestre.md",
+        "./agents/nexus.md",
+        "./agents/pixel.md",
+        "./agents/quill.md",
+        "./agents/razor.md",
+        "./agents/sage.md",
+        "./agents/scout.md",
+        "./agents/shield.md"
+      ],
+      "skills": [
+        "./skills/rpi-agents/SKILL.md",
+        "./skills/rpi-workflow/SKILL.md"
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rpi-kit",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "Research → Plan → Implement. AI-assisted feature development with 13 named agents, delta specs, and knowledge compounding.",
   "license": "MIT",
   "author": "Daniel Mendes",
@@ -30,7 +30,8 @@
     "AGENTS.md",
     "CHANGELOG.md",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "marketplace.json"
   ],
   "scripts": {
     "test": "node --test test/cli.test.js test/commands.test.js",

package/skills/rpi-workflow/SKILL.md

@@ -151,6 +151,7 @@ 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
 ```
 
 ## Configuration