rpi-kit 1.4.0 → 2.0.0

package/commands/rpi/plan.md

@@ -1,7 +1,7 @@
 ---
 name: rpi:plan
-description: Generate adaptive plan artifacts from research. Creates PLAN.md with task checklist, eng.md, and optionally pm.md and ux.md.
-argument-hint: "<feature-slug> [--force] [--skip-pm] [--skip-ux]"
+description: Generate implementation plan with Mestre (architect), Clara (PM), and Pixel (UX).
+argument-hint: "<feature-name> [--force]"
 allowed-tools:
   - Read
   - Write
@@ -12,280 +12,316 @@ allowed-tools:
   - AskUserQuestion
 ---
 
-<objective>
-Generate implementation plan artifacts from the research output. Adapts which artifacts to create based on feature type.
-</objective>
+# /rpi:plan — Plan Phase
 
-<process>
+Mestre (architecture), Clara (product), and Pixel (UX, conditional) collaborate to produce a complete implementation plan. Nexus validates coherence across all outputs.
 
-## 1. Load config and parse arguments
+---
 
-Read `.rpi.yaml` for configuration. Also read `profile` and `models` keys.
-Parse `$ARGUMENTS`:
-- First argument: `{feature-slug}` (required)
-- `--force`: proceed even if research verdict was NO-GO
-- `--skip-pm`: don't generate pm.md
-- `--skip-ux`: don't generate ux.md
+## Step 1: Load config and validate
 
-## 1b. Resolve model
+1. Read `.rpi.yaml` for config. Apply defaults if missing:
+   - `folder`: `rpi/features`
+   - `specs_dir`: `rpi/specs`
+   - `context_file`: `rpi/context.md`
+   - `ux_agent`: `auto`
+2. Parse `$ARGUMENTS` to extract `{slug}` and optional `--force` flag.
+3. Validate `rpi/features/{slug}/research/RESEARCH.md` exists. If not:
+   ```
+   RESEARCH.md not found for '{slug}'. Run /rpi:research {slug} first.
+   ```
+   Stop.
 
-Resolve the model for the `plan` 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.
+## Step 2: Check research verdict
 
-## 2. Resolve feature path and validate prerequisites
+1. Read `rpi/features/{slug}/research/RESEARCH.md`.
+2. Look for the `## Verdict` section.
+3. If verdict is `NO-GO` and `--force` was NOT passed:
+   ```
+   Research verdict is NO-GO for '{slug}'.
+   Review RESEARCH.md for details and alternatives.
+   To override: /rpi:plan {slug} --force
+   ```
+   Stop.
+4. If `--force` was passed: proceed despite NO-GO verdict.
 
-Parse `{feature-slug}` from arguments.
+## Step 3: Check existing plan
 
-**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}. Run /rpi:new {feature-slug} first.`
+1. Check if `rpi/features/{slug}/plan/PLAN.md` already exists.
+2. If it exists and `--force` was NOT passed:
+   - Ask the user: "PLAN.md already exists for '{slug}'. Overwrite? (yes/no)"
+   - If no: stop.
+3. If `--force` was passed or user confirms: proceed (will overwrite).
 
-If `type == "change"`:
-- Set `parent_path` to the parent feature directory
-- Read parent artifacts for agent context:
-  - `{parent_path}/REQUEST.md`
-  - `{parent_path}/research/RESEARCH.md` (if exists)
-  - `{parent_path}/plan/PLAN.md` (if exists)
-  - `{parent_path}/plan/eng.md` (if exists)
+## Step 4: Gather context
 
-Read `{path}/research/RESEARCH.md`. If missing:
-```
-Research not found. Run /rpi:research {feature-slug} first.
-```
+1. Read `rpi/features/{slug}/REQUEST.md` — store as `$REQUEST`.
+2. Read `rpi/features/{slug}/research/RESEARCH.md` — store as `$RESEARCH`.
+3. Read `rpi/context.md` (project context) if it exists — store as `$CONTEXT`.
+4. Scan `rpi/specs/` for specs relevant to the feature — store as `$RELEVANT_SPECS`.
 
-Check verdict. If NO-GO and no `--force`:
-```
-Research verdict is NO-GO. Review alternatives in RESEARCH.md.
-To proceed anyway: /rpi:plan {feature-slug} --force
-```
+## Step 5: Detect frontend
 
-If plan artifacts already exist, ask: "Plan already exists. Overwrite?"
+Check the project root for frontend framework config files:
+- `next.config.*` or `next.config.ts` → Next.js
+- `vite.config.*` → Vite (React/Vue/Svelte)
+- `angular.json` → Angular
+- `svelte.config.*` → Svelte/SvelteKit
+- `nuxt.config.*` → Nuxt
+- `package.json` containing `react`, `vue`, `angular`, or `svelte` in dependencies
 
-## 3. Detect feature type and confirm artifacts
+Set `$HAS_FRONTEND` to `true` if any of these are detected.
 
-Analyze RESEARCH.md to detect feature type:
-- Has UI components, user flows, or frontend files → suggest pm.md + ux.md
-- Backend only, API, or infrastructure → suggest skipping ux.md
-- Simple utility or refactor → suggest skipping pm.md + ux.md
+Read `ux_agent` from `.rpi.yaml`:
+- If `always`: set `$RUN_PIXEL` to `true` regardless of frontend detection.
+- If `never`: set `$RUN_PIXEL` to `false` regardless.
+- If `auto` (default): set `$RUN_PIXEL` to `$HAS_FRONTEND`.
 
-Present detection to user with AskUserQuestion:
-"Based on the research, this looks like a {type} feature. I'll generate:"
-- Options showing which artifacts will be created
-- Let user confirm or adjust
+## Step 6: Launch Mestre — first pass (eng.md)
 
-Apply any `--skip-pm` or `--skip-ux` flags as overrides.
+Launch Mestre agent with this prompt:
 
-## 3b. Interview user for alignment
+```
+You are Mestre. Generate the engineering specification for feature: {slug}
 
-Read all research artifacts:
-- `{folder}/{feature-slug}/REQUEST.md`
-- `{folder}/{feature-slug}/research/RESEARCH.md`
+## Request
+{$REQUEST}
 
-Based on the content, interview the user using AskUserQuestion to clarify anything that could affect the plan. Ask about **all relevant dimensions** — not just one:
+## Research
+{$RESEARCH}
 
-- **Technical implementation**: preferred patterns, constraints, performance requirements, existing code to build on
-- **UI & UX** (if applicable): expected flows, interaction patterns, states (loading, empty, error), design preferences
-- **Concerns**: risks identified in research, areas of uncertainty, things the user is worried about
-- **Tradeoffs**: decisions surfaced in research that have multiple valid approaches — present options and ask for preference
-- **Scope boundaries**: what explicitly should NOT be in this plan, MVP vs. future
+## Project Context
+{$CONTEXT}
 
-Rules:
-- Ask focused, specific questions based on what you read — not generic ones
-- Reference concrete findings from the research (e.g., "Research found two patterns for X: {A} and {B}. Which do you prefer?")
-- If the research surfaced CONCERN or BLOCK verdicts, ask about those specifically
-- Group related questions together — don't ask one at a time unless a follow-up depends on a previous answer
-- Document the user's answers — they will be passed as additional context to the agents in subsequent steps
+## Relevant Specs
+{$RELEVANT_SPECS}
 
-After the interview, create a brief alignment summary that will be included in agent prompts:
-```
-## User Alignment Notes
-{Summary of key decisions, preferences, and constraints from the interview}
+Your task:
+1. Read the request and research findings carefully
+2. Make technical decisions: approach, architecture, patterns to follow
+3. Identify files to create, modify, and remove
+4. List architectural risks with mitigations
+5. Output using your eng.md format: [Mestre -- Engineering Specification]
+
+Be pragmatic. Follow existing codebase patterns from context.md and research findings. No over-engineering.
 ```
 
-## 4. Generate eng.md (always)
+Store the output as `$ENG_OUTPUT`.
+
+## Step 7: Launch Clara — pm.md
+
+Launch Clara agent with this prompt:
 
-Launch senior-engineer agent. If a model was resolved in Step 1b, include `model: "{resolved_model}"` in the Agent tool call.
 ```
-You are planning the technical implementation for a feature.
+You are Clara. Generate the product specification for feature: {slug}
 
-Read these files:
-- {folder}/{feature-slug}/REQUEST.md
-- {folder}/{feature-slug}/research/RESEARCH.md
+## Request
+{$REQUEST}
 
-User Alignment Notes (from interview):
-{alignment_summary}
+## Research
+{$RESEARCH}
 
-Produce eng.md — a technical specification covering:
-1. Architecture overview (how it fits into existing codebase)
-2. Dependencies (new packages, existing modules to extend)
-3. Data models (schema changes, new types)
-4. API design (endpoints, contracts, error handling)
-5. File structure (new files to create, existing files to modify)
-6. Testing strategy (what to test, how)
+## Project Context
+{$CONTEXT}
 
-Be concrete. Cite existing codebase files and patterns from the research.
-Follow senior-engineer rules from RPI agent guidelines.
+Your task:
+1. Define user stories with concrete acceptance criteria (Given/When/Then)
+2. Classify requirements: must-have, nice-to-have, out-of-scope
+3. Cut anything that doesn't map to the core problem in REQUEST.md
+4. Define success metrics
+5. Output using your pm.md format: [Clara -- Product Specification]
+
+Be ruthless with scope. Every requirement must have acceptance criteria.
 ```
 
-If `type == "change"`, append to the agent prompt:
+Store the output as `$PM_OUTPUT`.
 
-```
-## Parent Feature Context
-{contents of parent artifacts read in step 2}
+## Step 8: Launch Pixel — ux.md (conditional)
+
+Only if `$RUN_PIXEL` is `true`:
+
+Launch Pixel agent with this prompt:
 
-This is a CHANGE to an existing feature. Focus on:
-- What's different from the parent implementation
-- Compatibility with existing code
-- Breaking changes to watch for
 ```
+You are Pixel. Generate the UX specification for feature: {slug}
+
+## Request
+{$REQUEST}
+
+## Research
+{$RESEARCH}
 
-> **Note:** Also append this same parent context block to the pm.md (step 5), ux.md (step 6), and PLAN.md (step 7) agent prompts when `type == "change"`.
+## Project Context
+{$CONTEXT}
 
-## 5. Generate pm.md (if not skipped)
+## Engineering Specification
+{$ENG_OUTPUT}
 
-Launch product-manager agent. If a model was resolved, include `model: "{resolved_model}"` in the Agent tool call.
+Your task:
+1. Map the complete user flow from entry to completion
+2. Define all states: empty, loading, error, success, edge cases
+3. Identify accessibility requirements
+4. Consider responsive behavior
+5. Output using your ux.md format: [Pixel -- UX Specification]
+
+Think from the user's perspective. If a flow needs a tooltip, the design failed.
 ```
-You are creating product requirements for a feature.
 
-Read these files:
-- {folder}/{feature-slug}/REQUEST.md
-- {folder}/{feature-slug}/research/RESEARCH.md
+Store the output as `$UX_OUTPUT`.
+
+If `$RUN_PIXEL` is `false`: set `$UX_OUTPUT` to `"No UX specification — no frontend detected."`.
 
-User Alignment Notes (from interview):
-{alignment_summary}
+## Step 9: Launch Mestre — second pass (PLAN.md)
 
-Produce pm.md — product requirements covering:
-1. User stories with acceptance criteria
-2. Scope definition with effort estimates (S/M/L/XL per item)
-3. Out of scope (what this feature does NOT do)
-4. Success metrics (how to measure if the feature works)
-5. Edge cases and error scenarios
+Launch Mestre agent to synthesize all specs into a concrete plan:
 
-Follow product-manager rules from RPI agent guidelines.
 ```
+You are Mestre. Generate the implementation plan (PLAN.md) for feature: {slug}
 
-## 6. Generate ux.md (if not skipped)
+## Engineering Specification
+{$ENG_OUTPUT}
 
-Launch ux-designer agent. If a model was resolved, include `model: "{resolved_model}"` in the Agent tool call.
-```
-You are designing the user experience for a feature.
+## Product Specification
+{$PM_OUTPUT}
+
+## UX Specification
+{$UX_OUTPUT}
+
+## Request
+{$REQUEST}
 
-Read these files:
-- {folder}/{feature-slug}/REQUEST.md
-- {folder}/{feature-slug}/research/RESEARCH.md
+## Research
+{$RESEARCH}
 
-User Alignment Notes (from interview):
-{alignment_summary}
+## Project Context
+{$CONTEXT}
 
-Produce ux.md — UX design covering:
-1. User journey (step-by-step flow from entry to completion)
-2. Interaction patterns (what the user sees and does at each step)
-3. Edge cases (errors, empty states, loading, permissions)
-4. Existing components to reuse (cite from codebase research)
-5. Accessibility considerations
+Your task:
+1. Read all specifications and synthesize into numbered tasks
+2. Each task must have: effort estimate, file list, dependencies, test criteria
+3. Tasks must be small enough for one commit each
+4. Group tasks into phases where logical
+5. Include metadata: total tasks, total files, overall complexity
+6. Output using your PLAN.md format: [Mestre -- Implementation Plan]
 
-Follow ux-designer rules from RPI agent guidelines.
+Rules:
+- Tasks are numbered (1.1, 1.2, 2.1, etc.)
+- 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
 ```
 
-## 7. Generate PLAN.md
+Store the output as `$PLAN_OUTPUT`.
+
+## Step 10: Mestre generates delta specs
 
-After all agents complete (eng.md is required, pm.md and ux.md may be parallel), launch senior-engineer agent again to create the task breakdown. If a model was resolved, include `model: "{resolved_model}"` in the Agent tool call.
+Launch Mestre agent to create delta specifications:
 
 ```
-You are creating an implementation plan from the technical spec.
+You are Mestre. Generate delta specs for feature: {slug}
 
-Read these files:
-- {folder}/{feature-slug}/REQUEST.md
-- {folder}/{feature-slug}/research/RESEARCH.md
-- {folder}/{feature-slug}/plan/eng.md
-- {folder}/{feature-slug}/plan/pm.md (if exists)
-- {folder}/{feature-slug}/plan/ux.md (if exists)
+## Implementation Plan
+{$PLAN_OUTPUT}
 
-User Alignment Notes (from interview):
-{alignment_summary}
+## Engineering Specification
+{$ENG_OUTPUT}
 
-Produce PLAN.md — an ordered task checklist organized by phases.
+## Relevant Current Specs
+{$RELEVANT_SPECS}
 
-Format for each task:
-- [ ] **{phase}.{task}** {Task description}
-  Effort: S | M | L | XL | Deps: {task IDs or "none"}
-  Files: {files to create or modify}
-  Test: {what to test — behavior assertion in plain language}
+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/
+3. For each existing spec that changes: create the updated version in delta/MODIFIED/
+4. For any spec that becomes obsolete: create a marker in delta/REMOVED/
+5. Delta specs capture ONLY what changes — not the entire system
 
-Group tasks into logical phases (e.g., Phase 1: Data Layer, Phase 2: Business Logic, Phase 3: UI, Phase 4: Integration).
+Output the list of delta specs you will create, with their paths:
+- delta/ADDED/{name}.md — {description}
+- delta/MODIFIED/{name}.md — {description}
+- delta/REMOVED/{name}.md — {description}
 
-Rules:
-- Every task should be completable in one focused session
-- L or XL tasks should be broken into smaller subtasks
-- Dependencies must be explicit — no circular deps
-- Files listed must be specific paths, not directories
-- Every task must have a Test field describing what behavior to verify
-- Test descriptions should be assertions, not vague: "returns 404 for missing user" not "test error handling"
-- After generating all tasks, count total tasks, unique files, and max dependency depth
-- These metrics will be used for session isolation tier detection
+Then write each spec file.
 ```
 
-## 7b. Compute plan metadata
+## Step 11: Launch Nexus — coherence validation
 
-After PLAN.md is generated, compute session isolation metrics:
+Launch Nexus agent to validate coherence across all plan outputs:
 
-1. Count total tasks in PLAN.md
-2. Count unique files across all task `Files:` fields
-3. Calculate max dependency depth:
-   - For each task, follow its `Deps:` chain to find the longest path
-   - Depth = longest chain length (task with no deps = depth 0)
-4. Compute context weight:
-   ```
-   context_weight = task_count + (total_files * 0.5) + (max_depth * 2)
-   ```
-5. Determine suggested tier:
-   - context_weight <= 8: tier 1
-   - context_weight 9-18: tier 2
-   - context_weight > 18: tier 3
-6. Compute plan hash:
-   - Collect all files listed in task `Files:` fields
-   - For files that exist: read content, sort by path, concatenate
-   - For files to be created: skip (they don't exist yet)
-   - Hash the concatenated content with sha256
-   ```bash
-   cat {sorted existing files} | shasum -a 256 | cut -d' ' -f1
-   ```
+```
+You are Nexus. Validate coherence for feature: {slug}
+
+## Engineering Specification (Mestre)
+{$ENG_OUTPUT}
 
-Append to the top of PLAN.md (after the title, before Phase 1):
+## Product Specification (Clara)
+{$PM_OUTPUT}
 
-```markdown
-## Metadata
-tasks: {count} | files: {count} | max_depth: {depth}
-context_weight: {weight}
-suggested_tier: {1|2|3}
-plan_hash: {sha256_hash}
+## Implementation Plan (Mestre)
+{$PLAN_OUTPUT}
+
+## 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
+
+Output as: [Nexus -- Coherence Validation]
+
+## Coherence Status
+{PASS | PASS with gaps | FAIL}
+
+## Coverage
+- Requirements covered: {N}/{total}
+- Files covered: {N}/{total}
+
+## Issues Found
+- {issue description} — Severity: {HIGH | MEDIUM | LOW}
+(or "No issues found.")
+
+## Recommendations
+- {recommendation}
+(or "Plan is coherent. Ready for implementation.")
 ```
 
-## 8. Write all artifacts
+If Nexus reports FAIL: output the issues to the user and suggest re-running `/rpi:plan {slug} --force`.
 
-Write all generated files to `{folder}/{feature-slug}/plan/`:
-- `PLAN.md` (always)
-- `eng.md` (always)
-- `pm.md` (if generated)
-- `ux.md` (if generated)
+## Step 12: Write all artifacts
 
-## 9. Present plan summary
+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:
+   ```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.
+
+## Step 13: Output summary
 
-Output:
 ```
-Plan created for {feature-slug}:
-- PLAN.md: {N} tasks across {M} phases
-- eng.md: Technical specification
-{- pm.md: Product requirements (if generated)}
-{- ux.md: UX design (if generated)}
-
-Session isolation: Tier {1|2|3} (context weight: {weight})
-{If tier 1: "Small feature — single session recommended"}
-{If tier 2: "Medium feature — session warning after {max_tasks_per_session} tasks"}
-{If tier 3: "Large feature — session checkpoints will be enforced"}
-
-Next: /rpi:implement {feature-slug}
+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}
+
+Next: /rpi {slug}
+Or explicitly: /rpi:implement {slug}
 ```
-
-</process>