rpi-kit 1.0.0 → 1.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "rpi-kit",
+  "version": "1.1.0",
+  "description": "Research → Plan → Implement. A systematic feature development workflow with validation gates, multi-role agent teams, and adaptive depth.",
+  "owner": {
+    "name": "Daniel Mendes"
+  },
+  "plugins": [
+    {
+      "name": "rpi-kit",
+      "source": "./",
+      "description": "Research → Plan → Implement. A systematic feature development workflow for Claude Code and Codex.",
+      "version": "1.1.0",
+      "author": {
+        "name": "Daniel Mendes"
+      },
+      "license": "MIT",
+      "keywords": ["workflow", "research", "planning", "implementation", "feature-development", "agents"],
+      "category": "productivity"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "rpi-kit",
+  "version": "1.1.0",
+  "description": "Research → Plan → Implement. A systematic feature development workflow with validation gates, multi-role agent teams, and adaptive depth.",
+  "author": {
+    "name": "Daniel Mendes",
+    "url": "https://github.com/dmend3z"
+  },
+  "repository": "https://github.com/dmend3z/rpi-kit",
+  "license": "MIT",
+  "keywords": [
+    "workflow",
+    "research",
+    "planning",
+    "implementation",
+    "feature-development",
+    "agents",
+    "codex"
+  ]
+}

package/README.md

@@ -6,13 +6,29 @@ RPIKit guides AI-first developers through a structured 3-phase pipeline with val
 
 ## Install
 
-### Claude Code (plugin)
+### Claude Code
+
+**From the marketplace (recommended):**
 
 ```bash
 claude plugin install rpi-kit
 ```
 
-Or clone and install locally:
+**From npm:**
+
+```bash
+npm install -g rpi-kit
+```
+
+The postinstall script registers the plugin automatically. If it fails, register manually:
+
+```bash
+claude plugin install /path/to/rpi-kit
+```
+
+> **Tip:** `npm root -g` shows where global packages are installed. The path is usually something like `~/.nvm/versions/node/vX.X.X/lib/node_modules/rpi-kit`.
+
+**From source:**
 
 ```bash
 git clone https://github.com/dmend3z/rpi-kit.git
@@ -147,7 +163,7 @@ commit_style: conventional     # Commit message format
 parallel_threshold: 8          # Task count for parallel mode
 skip_artifacts: []             # Artifacts to never generate
 review_after_implement: true   # Mandatory review gate
-branch_per_feature: false      # Git branch per feature
+isolation: none                # none | branch | worktree
 tdd: false                     # Enable Test-Driven Development
 test_runner: auto              # Test command (auto-detect or explicit)
 ```

package/agents/test-engineer.md

@@ -1,3 +1,10 @@
+---
+name: test-engineer
+description: Writes focused, minimal failing tests before implementation code exists. Follows strict TDD — one test at a time, verify it fails, then hand off to the implementer. Spawned by /rpi:test and /rpi:implement (when TDD enabled).
+tools: Read, Write, Edit, Bash, Glob, Grep
+color: red
+---
+
 # Test Engineer
 
 You write focused, minimal failing tests before implementation code exists. You follow strict TDD: one test at a time, verify it fails, then hand off to the implementer.

package/bin/cli.js

@@ -28,14 +28,14 @@ function hasCodex() {
 function installClaude() {
   log("Installing RPIKit for Claude Code...");
   try {
-    execFileSync("claude", ["plugin", "add", PLUGIN_DIR], {
+    execFileSync("claude", ["plugin", "install", PLUGIN_DIR], {
       stdio: silent ? "pipe" : "inherit",
     });
     log("Claude Code: installed.");
     return true;
   } catch {
     log("Claude Code: could not register plugin automatically.");
-    log("  Manual install: claude plugin add " + PLUGIN_DIR);
+    log("  Manual install: claude plugin install " + PLUGIN_DIR);
     return false;
   }
 }
@@ -85,6 +85,7 @@ Usage:
   rpi-kit install --claude   Install for Claude Code only
   rpi-kit install --codex    Install for Codex only (copies AGENTS.md to cwd)
   rpi-kit uninstall          Remove from Claude Code
+  rpi-kit onboarding         Interactive walkthrough of the workflow
   rpi-kit help               Show this help
 
 After install, use in Claude Code:
@@ -127,10 +128,21 @@ switch (command) {
           log("  rpi-kit install --codex");
         }
       }
+
+      if (installed && !silent) {
+        log("");
+        log("New to RPIKit? Run: rpi-kit onboarding");
+      }
     }
     break;
   }
 
+  case "onboarding": {
+    const { run } = require("./onboarding");
+    run();
+    break;
+  }
+
   case "uninstall":
     uninstallClaude();
     break;

package/bin/onboarding.js

@@ -0,0 +1,145 @@
+const readline = require("readline");
+
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const RESET = "\x1b[0m";
+
+const steps = [
+  {
+    title: "Welcome to RPIKit",
+    body: `
+${BOLD}Research → Plan → Implement${RESET}
+
+RPIKit is a structured feature development workflow for Claude Code and Codex.
+It guides you through 3 phases with validation gates, so you research before
+you plan, and plan before you code.
+
+${DIM}11 specialized agents simulate a product team:
+engineers, PMs, designers, reviewers — all working in parallel.${RESET}`,
+  },
+  {
+    title: "The Pipeline",
+    body: `
+${DIM}Your feature flows through these phases:${RESET}
+
+  ${CYAN}/rpi:new${RESET}        Describe your feature → ${BOLD}REQUEST.md${RESET}
+       │
+  ${CYAN}/rpi:research${RESET}   Parallel agent analysis → ${BOLD}RESEARCH.md${RESET} + GO/NO-GO
+       │
+  ${CYAN}/rpi:plan${RESET}       Generate specs + tasks → ${BOLD}PLAN.md${RESET} + eng/pm/ux.md
+       │
+  ${CYAN}/rpi:implement${RESET}  Execute tasks with tracking → ${BOLD}IMPLEMENT.md${RESET}
+       │
+  ${CYAN}/rpi:simplify${RESET}   Code quality checks → auto-fix issues
+       │
+  ${CYAN}/rpi:review${RESET}     Review against plan → PASS / FAIL
+       │
+  ${CYAN}/rpi:docs${RESET}       Document the code → inline docs + changelog`,
+  },
+  {
+    title: "Research Tiers",
+    body: `
+${DIM}Control depth and cost with tier flags:${RESET}
+
+  ${GREEN}--quick${RESET}      2 agents    Fast feasibility check
+  ${YELLOW}--standard${RESET}   4 agents    Scope + technical approach ${DIM}(default)${RESET}
+  ${CYAN}--deep${RESET}       6 agents    Full strategic analysis
+
+${DIM}Agents run in parallel — deep research doesn't mean slow research.${RESET}`,
+  },
+  {
+    title: "Feature Folder Structure",
+    body: `
+${DIM}Each feature gets its own folder with all artifacts:${RESET}
+
+  rpi/
+  └── ${BOLD}your-feature/${RESET}
+      ├── REQUEST.md              ${DIM}What and why${RESET}
+      ├── research/
+      │   └── RESEARCH.md         ${DIM}GO/NO-GO analysis${RESET}
+      ├── plan/
+      │   ├── PLAN.md             ${DIM}Task checklist${RESET}
+      │   ├── eng.md              ${DIM}Technical spec${RESET}
+      │   ├── pm.md               ${DIM}Product requirements${RESET}
+      │   └── ux.md               ${DIM}UX design${RESET}
+      └── implement/
+          ├── IMPLEMENT.md        ${DIM}Execution audit trail${RESET}
+          └── DOCS.md             ${DIM}Documentation summary${RESET}`,
+  },
+  {
+    title: "TDD Support",
+    body: `
+${DIM}RPIKit supports strict Test-Driven Development per task:${RESET}
+
+  ${CYAN}RED${RESET}      → Write one failing test
+  ${GREEN}GREEN${RESET}    → Write minimal code to pass
+  ${YELLOW}REFACTOR${RESET} → Clean up, re-run tests
+
+${DIM}Enable in .rpi.yaml:${RESET}
+  tdd: true
+  test_runner: auto
+
+${DIM}Or run standalone:${RESET}  /rpi:test your-feature --task 1.2`,
+  },
+  {
+    title: "Get Started",
+    body: `
+${BOLD}Step 1:${RESET} Open Claude Code in your project
+
+${BOLD}Step 2:${RESET} Initialize RPIKit
+  ${CYAN}/rpi:init${RESET}
+
+${BOLD}Step 3:${RESET} Create your first feature
+  ${CYAN}/rpi:new my-feature${RESET}
+
+${BOLD}Step 4:${RESET} Follow the pipeline
+  ${CYAN}/rpi:research my-feature${RESET}
+  ${CYAN}/rpi:plan my-feature${RESET}
+  ${CYAN}/rpi:implement my-feature${RESET}
+
+${DIM}Use /rpi:status anytime to see where you are.${RESET}
+
+${GREEN}Happy building!${RESET}`,
+  },
+];
+
+function run() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  let current = 0;
+
+  function show(index) {
+    const step = steps[index];
+    const progress = `${DIM}[${index + 1}/${steps.length}]${RESET}`;
+
+    console.clear();
+    console.log();
+    console.log(`  ${progress} ${BOLD}${step.title}${RESET}`);
+    console.log(`  ${"─".repeat(50)}`);
+    console.log(step.body);
+    console.log();
+
+    if (index < steps.length - 1) {
+      rl.question(`  ${DIM}Press Enter to continue (q to quit)${RESET} `, (answer) => {
+        if (answer.toLowerCase() === "q") {
+          rl.close();
+          return;
+        }
+        current++;
+        show(current);
+      });
+    } else {
+      rl.close();
+    }
+  }
+
+  show(0);
+}
+
+module.exports = { run };

package/codex.md

@@ -0,0 +1,69 @@
+# RPI Workflow Rules
+
+You follow the RPI (Research → Plan → Implement) workflow for feature development.
+
+## Core Principles
+
+1. **Never implement without research.** Every feature starts with a REQUEST.md and goes through a GO/NO-GO research gate.
+2. **Never code without a plan.** The plan phase produces structured artifacts (PLAN.md, eng.md, and optionally pm.md/ux.md) before any code is written.
+3. **Track every task.** Implementation uses task-level tracking with commits per task and phase checkpoints.
+4. **Simplify before review.** After implementation, run code simplification (reuse, quality, efficiency) before code review.
+5. **Review against the plan.** Code review checks implementation against plan requirements, not just code quality.
+6. **Test before you code (when TDD enabled).** Write one failing test, verify it fails, write minimal code to pass, verify it passes, refactor. No implementation without a failing test first.
+
+## File Conventions
+
+```
+{folder}/{feature-slug}/
+├── REQUEST.md              # Feature description (structured sections)
+├── research/
+│   └── RESEARCH.md         # GO/NO-GO analysis with agent perspectives
+├── plan/
+│   ├── PLAN.md             # Task checklist with effort, deps, files
+│   ├── pm.md               # (adaptive) User stories + acceptance criteria
+│   ├── ux.md               # (adaptive) User flows + interaction patterns
+│   └── eng.md              # Technical architecture + dependencies
+└── implement/
+    └── IMPLEMENT.md        # Full audit trail: tasks, commits, deviations
+```
+
+## Workflow Commands
+
+- `/rpi:init` — Set up RPI config for this project
+- `/rpi:new` — Interactive interview to create a feature REQUEST.md
+- `/rpi:research <feature>` — Research phase with GO/NO-GO verdict
+- `/rpi:plan <feature>` — Generate plan artifacts from research
+- `/rpi:implement <feature>` — Execute plan with task tracking
+- `/rpi:simplify <feature>` — Code simplification (reuse, quality, efficiency)
+- `/rpi:test <feature>` — Run TDD cycles (RED → GREEN → REFACTOR) per task
+- `/rpi:status` — Show all features and their current phase
+- `/rpi:review <feature>` — Code review against plan
+
+## Research Tiers
+
+- `--quick` — Feasibility check only (2 agents: requirements + codebase)
+- `--standard` — Scope + technical approach (4 agents: + PM + engineer)
+- `--deep` — Full analysis with strategic assessment (5-6 agents: + CTO + UX if UI)
+
+## Agent Team
+
+| Role | Perspective |
+|------|-------------|
+| Requirement Parser | Extracts structured requirements, lists unknowns |
+| Product Manager | Scope, user stories, effort, acceptance criteria |
+| UX Designer | User flows, interaction patterns, existing components |
+| Senior Engineer | Technical approach, architecture, dependencies |
+| CTO Advisor | Risk, feasibility, strategic alignment, alternatives |
+| Doc Synthesizer | Merges research into executive summary + verdict |
+| Plan Executor | Implements tasks surgically, one at a time |
+| Code Simplifier | Reuse, quality, efficiency checks with fixes |
+| Code Reviewer | Reviews against plan requirements |
+| Codebase Explorer | Scans existing code for patterns and context |
+| Test Engineer | Writes failing tests before implementation (TDD) |
+
+## GO/NO-GO Verdicts
+
+- **GO** — Feature is feasible, proceed to planning
+- **GO with concerns** — Feasible but has risks that need mitigation
+- **NO-GO** — Not feasible as described; alternatives suggested
+- Override a NO-GO verdict: `/rpi:plan {feature-slug} --force`

package/commands/rpi/add-todo.md

@@ -0,0 +1,83 @@
+---
+name: rpi:add-todo
+description: Add a quick todo so you don't forget what to implement next.
+argument-hint: "[todo title]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - AskUserQuestion
+---
+
+<objective>
+Create a todo file in `{folder}/todos/` to capture an implementation idea before it's forgotten.
+</objective>
+
+<process>
+
+## 1. Load config
+
+Read `.rpi.yaml` for folder path. Default to `rpi/` if not found.
+
+## 2. Ensure todos folder exists
+
+```bash
+mkdir -p {folder}/todos
+```
+
+## 3. Determine todo title
+
+If `$ARGUMENTS` contains a title, use it. Otherwise ask:
+"What do you want to remember to implement?"
+
+Convert the title to a kebab-case slug for the filename.
+
+## 4. Check for duplicates
+
+Use Glob to check if `{folder}/todos/{slug}.md` already exists. If yes, warn the user and ask if they want to update the existing one or pick a different name.
+
+## 5. Quick interview
+
+Ask 1-2 focused questions using AskUserQuestion:
+
+- "Brief description — what should this do?" (skip if the title is already descriptive enough)
+- "Priority?" — Options: `high`, `medium` (default), `low`
+
+Keep it fast. The point is to capture the idea before it's lost, not to write a full spec.
+
+## 6. Create the todo file
+
+Write `{folder}/todos/{slug}.md`:
+
+```markdown
+# {Todo Title}
+
+## What
+{Brief description of what to implement}
+
+## Priority
+{high | medium | low}
+
+## Notes
+- {Any extra context the user mentioned, or leave empty}
+
+---
+Added: {YYYY-MM-DD}
+Status: pending
+```
+
+## 7. Confirm
+
+Output:
+
+```
+Todo added: {folder}/todos/{slug}.md
+Priority: {priority}
+
+Quick actions:
+  /rpi:new {slug}    Promote to a full RPI feature
+  /rpi:todos         List all pending todos
+```
+
+</process>

package/commands/rpi/implement.md

@@ -272,4 +272,45 @@ Feature {feature-slug} implementation complete but review found issues:
 Fix and re-run: /rpi:review {feature-slug}
 ```
 
+## 12. Handle isolation cleanup
+
+Read `isolation` from `.rpi.yaml`.
+
+**If `isolation: none`** — do nothing.
+
+**If `isolation: branch`:**
+Ask the user:
+```
+Feature branch: feature/{feature-slug}
+Want to merge into {main-branch} now? (yes/no)
+```
+If yes:
+```bash
+git checkout {main-branch}
+git merge feature/{feature-slug}
+```
+
+**If `isolation: worktree`:**
+Ask the user:
+```
+Worktree: .worktrees/{feature-slug}
+Branch: feature/{feature-slug}
+Want to merge into {main-branch} and remove the worktree? (yes/no)
+```
+If yes:
+```bash
+cd {project-root}
+git checkout {main-branch}
+git merge feature/{feature-slug}
+git worktree remove .worktrees/{feature-slug}
+```
+If no:
+```
+Worktree preserved at .worktrees/{feature-slug}
+To merge later:
+  git checkout {main-branch} && git merge feature/{feature-slug}
+To remove:
+  git worktree remove .worktrees/{feature-slug}
+```
+
 </process>

package/commands/rpi/init.md

@@ -34,7 +34,7 @@ Use AskUserQuestion to gather preferences. Ask up to 4 questions at a time:
 
 **Batch 3:**
 - "Task count threshold for parallel execution?" — Options: 8 (Recommended), 5, 12, always sequential
-- "Create a git branch per feature?" — Options: No (Recommended), Yes
+- "How do you want to isolate features?" — Options: `none` (Recommended — work on current branch), `branch` (create a git branch per feature), `worktree` (create a git worktree + branch in `.worktrees/`)
 
 **Batch 4 (TDD):**
 - "Enable Test-Driven Development during implementation?" — Options: No (default), Yes
@@ -55,7 +55,7 @@ commit_style: {conventional|descriptive}
 parallel_threshold: {number}
 skip_artifacts: []
 review_after_implement: true
-branch_per_feature: {true|false}
+isolation: {none|branch|worktree}
 tdd: {true|false}
 test_runner: {auto|command}
 ```

package/commands/rpi/new.md

@@ -48,10 +48,54 @@ Start with core questions, then ask follow-ups based on answers.
 
 Use AskUserQuestion for structured questions. Keep it conversational — 2-3 questions per batch, max 3 batches. Stop when you have enough to write a clear REQUEST.md.
 
-## 5. Generate REQUEST.md
+## 5. Set up isolation
 
-Create the feature folder and write REQUEST.md:
+Read `isolation` from `.rpi.yaml` (default: `none`).
 
+**If `isolation: none`** — do nothing, continue on current branch.
+
+**If `isolation: branch`:**
+```bash
+git checkout -b feature/{feature-slug}
+```
+
+**If `isolation: worktree`:**
+1. Verify `.worktrees/` is in `.gitignore`:
+   ```bash
+   git check-ignore -q .worktrees 2>/dev/null
+   ```
+   If NOT ignored, add `.worktrees/` to `.gitignore` and commit:
+   ```bash
+   echo ".worktrees/" >> .gitignore
+   git add .gitignore && git commit -m "chore: add .worktrees/ to .gitignore"
+   ```
+2. Create the worktree:
+   ```bash
+   git worktree add .worktrees/{feature-slug} -b feature/{feature-slug}
+   ```
+3. Run project setup in the worktree (auto-detect from project files: `npm install`, `pip install`, etc.)
+4. Inform the user:
+   ```
+   Worktree created at .worktrees/{feature-slug}
+   Branch: feature/{feature-slug}
+
+   To work in the worktree, open a new terminal:
+     cd .worktrees/{feature-slug}
+   ```
+
+## 6. Generate REQUEST.md
+
+Create the feature folder and write REQUEST.md.
+
+**If `isolation: worktree`**, the feature folder is created inside the worktree:
+```bash
+cd .worktrees/{feature-slug}
+mkdir -p {folder}/{feature-slug}/research
+mkdir -p {folder}/{feature-slug}/plan
+mkdir -p {folder}/{feature-slug}/implement
+```
+
+**Otherwise:**
 ```bash
 mkdir -p {folder}/{feature-slug}/research
 mkdir -p {folder}/{feature-slug}/plan
@@ -84,7 +128,7 @@ Write `{folder}/{feature-slug}/REQUEST.md` with this structure:
 {S | M | L | XL} — {brief justification}
 ```
 
-## 6. Next step
+## 7. Next step
 
 Output:
 ```

package/commands/rpi/onboarding.md

@@ -0,0 +1,241 @@
+---
+name: rpi:onboarding
+description: Interactive guided tour of the RPI workflow. Walks through each phase with a real demo feature, explaining what happens at each step.
+argument-hint: "[--demo]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - AskUserQuestion
+---
+
+<objective>
+Guide a new user through the RPIKit workflow with clear explanations of each phase. Optionally create a demo feature to show the pipeline in action.
+</objective>
+
+<process>
+
+## 1. Welcome
+
+Output:
+```
+Welcome to RPIKit — Research, Plan, Implement.
+
+RPIKit is a structured workflow that guides you through 3 phases before writing
+any code. Each phase produces artifacts that feed the next, with validation
+gates that prevent premature implementation.
+
+Let me walk you through the pipeline.
+```
+
+## 2. Explain the pipeline
+
+Present the full pipeline with brief descriptions:
+
+```
+The RPIKit Pipeline
+───────────────────
+
+  /rpi:init         One-time project setup (.rpi.yaml)
+
+  /rpi:new          Describe your feature → REQUEST.md
+       │            You answer a few questions about what you want to build.
+       │            RPIKit captures requirements in a structured format.
+       ▼
+  /rpi:research     Analyze feasibility → RESEARCH.md
+       │            2-6 agents run in parallel: parsing requirements,
+       │            exploring your codebase, assessing scope and risk.
+       │            Produces a GO / NO-GO verdict.
+       ▼
+  /rpi:plan         Generate specs + tasks → PLAN.md
+       │            Creates technical spec (eng.md), product requirements
+       │            (pm.md), UX design (ux.md), and a task checklist.
+       │            Adapts which artifacts to create based on feature type.
+       ▼
+  /rpi:implement    Execute tasks → IMPLEMENT.md
+       │            Builds the feature task-by-task with per-task commits.
+       │            Supports TDD (Red-Green-Refactor) and parallel execution.
+       ▼
+  /rpi:simplify     Code quality → auto-fix
+       │            3 agents check: code reuse, quality patterns, efficiency.
+       │            Fixes issues directly.
+       ▼
+  /rpi:review       Verify against plan → PASS / FAIL
+       │            Reviews completeness, correctness, deviations, test
+       │            coverage. Every finding cites a plan requirement.
+       ▼
+  /rpi:docs         Document the code → inline docs + changelog
+                    Adds JSDoc/docstrings, API docs, README and changelog
+                    updates. Only runs after review PASS.
+
+  /rpi:status       Dashboard — see all features and their current phase.
+```
+
+## 3. Explain the agents
+
+```
+RPIKit simulates a product team with 12 specialized agents:
+
+  Research agents (run in parallel):
+  ┌─────────────────────┬──────────────────────────────────────┐
+  │ Requirement Parser  │ Extracts testable requirements       │
+  │ Codebase Explorer   │ Scans your code for patterns         │
+  │ Product Manager     │ Scope, user stories, effort          │
+  │ Senior Engineer     │ Architecture, dependencies           │
+  │ CTO Advisor         │ Risk, strategy (deep tier only)      │
+  │ UX Designer         │ User flows, interactions (if UI)     │
+  │ Doc Synthesizer     │ Merges all outputs into RESEARCH.md  │
+  └─────────────────────┴──────────────────────────────────────┘
+
+  Execution agents:
+  ┌─────────────────────┬──────────────────────────────────────┐
+  │ Plan Executor       │ Implements one task at a time        │
+  │ Test Engineer       │ Writes failing tests (TDD)           │
+  │ Code Simplifier     │ Reuse, quality, efficiency checks    │
+  │ Code Reviewer       │ Reviews against plan requirements    │
+  │ Doc Writer          │ Generates code documentation         │
+  └─────────────────────┴──────────────────────────────────────┘
+```
+
+## 4. Explain research tiers
+
+```
+Research Tiers — control depth and cost:
+
+  --quick      2 agents    "Can we do this?"
+                           Requirements + codebase scan.
+                           Use for small features or feasibility checks.
+
+  --standard   4 agents    "How should we do this?"  (default)
+                           Adds product scope and technical approach.
+                           Use for most features.
+
+  --deep       6 agents    "Should we do this?"
+                           Adds strategic risk and UX analysis.
+                           Use for large features or risky changes.
+```
+
+## 5. Show folder structure
+
+```
+Feature Folder Structure:
+
+  rpi/
+  └── your-feature/
+      ├── REQUEST.md              ← What you want to build
+      ├── research/
+      │   └── RESEARCH.md         ← GO/NO-GO analysis
+      ├── plan/
+      │   ├── PLAN.md             ← Task checklist by phases
+      │   ├── eng.md              ← Technical specification
+      │   ├── pm.md               ← Product requirements (adaptive)
+      │   └── ux.md               ← UX design (adaptive)
+      └── implement/
+          ├── IMPLEMENT.md        ← Execution audit trail
+          └── DOCS.md             ← Documentation summary
+
+Each file is a gate — you can't plan without research, can't implement
+without a plan, can't document without a passing review.
+```
+
+## 6. Ask about demo
+
+Use AskUserQuestion:
+"Want me to create a demo feature so you can see the pipeline in action? I'll create a small example feature and walk you through each step."
+
+Options:
+- "Yes, show me a demo" → proceed to step 7
+- "No, I'll start on my own" → skip to step 8
+
+## 7. Demo walkthrough (if user wants demo)
+
+Create a minimal demo feature to show what each artifact looks like:
+
+### 7.1 Create demo config
+
+If `.rpi.yaml` doesn't exist, create a minimal one:
+```yaml
+folder: rpi
+tier: quick
+auto_simplify: true
+commit_style: conventional
+parallel_threshold: 8
+review_after_implement: true
+isolation: none
+tdd: false
+test_runner: auto
+```
+
+### 7.2 Create demo REQUEST.md
+
+```bash
+mkdir -p rpi/demo-greeting/research
+mkdir -p rpi/demo-greeting/plan
+mkdir -p rpi/demo-greeting/implement
+```
+
+Write `rpi/demo-greeting/REQUEST.md`:
+```markdown
+# Greeting Message
+
+## Summary
+Add a simple greeting function that returns a personalized welcome message.
+
+## Problem
+The application has no way to greet users by name. This is needed for the onboarding flow.
+
+## Target Users
+All new users during their first session.
+
+## Constraints
+- Must be a pure function (no side effects)
+- Must handle missing or empty names gracefully
+
+## References
+- None
+
+## Complexity Estimate
+S — Single function with basic input validation
+```
+
+### 7.3 Explain what just happened
+
+Output:
+```
+I created a demo feature: rpi/demo-greeting/
+
+This is what /rpi:new does — it interviews you about your feature and creates
+REQUEST.md with structured requirements.
+
+In a real workflow, the next steps would be:
+  /rpi:research demo-greeting    → agents analyze feasibility
+  /rpi:plan demo-greeting        → generate specs and task checklist
+  /rpi:implement demo-greeting   → build it task by task
+
+You can run these commands now to see the full pipeline, or delete the demo:
+  rm -rf rpi/demo-greeting
+```
+
+## 8. Next steps
+
+Output:
+```
+You're ready to go! Here's your first workflow:
+
+  1. /rpi:init                    Set up your preferences
+  2. /rpi:new my-feature          Describe what you want to build
+  3. /rpi:research my-feature     Let the agents analyze it
+  4. /rpi:plan my-feature         Generate the implementation plan
+  5. /rpi:implement my-feature    Build it
+
+Use /rpi:status anytime to see where your features stand.
+
+Tips:
+  - Start with --quick tier for small features
+  - Use --deep tier when adding new architecture or risky dependencies
+  - Enable tdd: true in .rpi.yaml if you want test-first development
+  - Run /rpi:simplify anytime to check code quality on recent changes
+```
+
+</process>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rpi-kit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Research → Plan → Implement. A systematic feature development workflow for Claude Code.",
   "license": "MIT",
   "author": "Daniel Mendes",
@@ -22,14 +22,18 @@
     "rpi-kit": "./bin/cli.js"
   },
   "files": [
+    ".claude-plugin/",
     "bin/",
     "commands/",
     "agents/",
+    "skills/",
     "AGENTS.md",
+    "codex.md",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
+    "test": "node --test test/cli.test.js test/commands.test.js",
     "postinstall": "node bin/cli.js install --silent"
   }
 }

package/skills/rpi-agents/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: rpi-agents
+description: This skill should be used when the user asks about RPI agent behavior, rules, or roles, asks "what agents are involved", "how does the code reviewer work", "what are the agent rules", "customize agent behavior", or mentions agent names like requirement-parser, product-manager, ux-designer, senior-engineer, cto-advisor, doc-synthesizer, plan-executor, code-simplifier, code-reviewer, explore-codebase, or test-engineer.
+version: 1.0.1
+license: MIT
+---
+
+# RPI Agent Guidelines
+
+Behavioral constraints for RPI agents. Every agent follows the general rules below PLUS their role-specific rules.
+
+## General Rules (All Agents)
+
+1. **Cite evidence.** Every claim must reference a specific file, dependency, or codebase pattern. No unsupported statements.
+2. **Name unknowns.** If you're uncertain, say what you don't know. Never fill gaps with assumptions.
+3. **Be concrete.** Anti-pattern: "This could improve performance." Instead: "Batching the 3 API calls reduces round-trips from 3 to 1."
+4. **Stay in scope.** Only analyze what's relevant to the feature. Don't audit the entire codebase.
+5. **Structured output.** Use the section format specified for your role. Include your verdict per section.
+
+## Output Format (Research Agents)
+
+Each research agent outputs markdown sections with verdicts:
+
+```markdown
+## [Section Name]
+Verdict: GO | CONCERN | BLOCK
+
+[Findings with evidence]
+
+### [Sub-section if needed]
+[Details]
+```
+
+End with: `Estimated Complexity: S | M | L | XL`
+
+## Agent Roles
+
+The RPI workflow uses 10 specialized agents. Each has detailed behavioral rules, anti-patterns, and output formats defined in its own file under `agents/`:
+
+| Agent | Role | Phase |
+|-------|------|-------|
+| requirement-parser | Extract structured, testable requirements | Research |
+| product-manager | Scope, user stories, effort, acceptance criteria | Research, Plan |
+| ux-designer | User flows, interaction patterns, UI decisions | Research (deep), Plan |
+| senior-engineer | Technical approach, architecture, dependencies | Research, Plan |
+| cto-advisor | Risk, feasibility, strategic alignment | Research (deep) |
+| doc-synthesizer | Merge research outputs into RESEARCH.md | Research |
+| explore-codebase | Scan codebase for patterns and context | Research |
+| test-engineer | Write failing tests before implementation (TDD) | Implement (TDD), Test |
+| plan-executor | Implement tasks from PLAN.md surgically | Implement |
+| code-simplifier | Check reuse, quality, efficiency and fix | Implement |
+| code-reviewer | Review implementation against plan | Implement, Review |
+
+For full role-specific rules, anti-patterns, and output formats, see the individual agent definitions in `agents/*.md`.
+
+## Related
+
+For the workflow process (phases, commands, configuration), see the **rpi-workflow** skill.

package/skills/rpi-workflow/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: rpi-workflow
+description: This skill should be used when the user wants to develop a feature systematically, asks "how do I start a new feature", "walk me through the workflow", "help me build this step by step", says "research plan implement", mentions TDD or test-driven development, or mentions any RPI command (/rpi:init, /rpi:new, /rpi:research, /rpi:plan, /rpi:implement, /rpi:test, /rpi:simplify, /rpi:status, /rpi:review).
+version: 0.2.0
+license: MIT
+---
+
+# RPI Workflow
+
+RPI (Research → Plan → Implement) is a systematic feature development workflow with validation gates at each phase.
+
+## Workflow Phases
+
+### Phase 0: Init
+Run `/rpi:init` once per project to configure:
+- Feature folder location (default: `rpi/`)
+- Default research tier
+- Parallel threshold, commit style, and other preferences
+- Creates `.rpi.yaml` at project root
+
+### Phase 1: New Feature
+Run `/rpi:new` to start. Adaptive interview:
+- Start with core questions: what feature, what problem it solves
+- Ask follow-ups based on answers (who uses it, complexity, constraints, references)
+- Set up isolation based on `isolation` config:
+  - `none`: work on current branch
+  - `branch`: `git checkout -b feature/{slug}`
+  - `worktree`: create `.worktrees/{slug}` with `git worktree add`
+- Generate `{folder}/{feature-slug}/REQUEST.md` with structured sections
+
+REQUEST.md sections: Summary, Problem, Target Users, Constraints, References, Complexity Estimate.
+
+### Phase 2: Research
+Run `/rpi:research {feature-slug}` with optional tier flag.
+
+Research tiers control agent composition:
+- `--quick`: requirement-parser + explore-codebase (feasibility only)
+- `--standard` (default): + product-manager + senior-engineer (scope + approach)
+- `--deep`: + cto-advisor + ux-designer if UI (full analysis + alternatives)
+
+All selected agents run in **parallel fan-out**. Doc-synthesizer merges outputs into RESEARCH.md.
+
+RESEARCH.md format:
+1. Executive Summary (5 lines: verdict, complexity, risk, recommendation, key finding)
+2. Requirements Analysis
+3. Product Scope
+4. Codebase Context
+5. Technical Analysis
+6. Strategic Assessment (deep tier only)
+7. Alternatives (mandatory if NO-GO)
+
+Verdicts: **GO**, **GO with concerns**, **NO-GO**
+- NO-GO includes alternative approaches and scope reduction suggestions
+- Override with `--force` flag
+
+### Phase 3: Plan
+Run `/rpi:plan {feature-slug}`.
+
+Adaptive artifact generation:
+- Always: PLAN.md (task checklist) + eng.md (technical spec)
+- Adaptive: pm.md (user stories) and ux.md (user flows) — generated based on feature type
+- After research, asks user to confirm which artifacts to generate
+
+PLAN.md task format:
+```markdown
+## Phase 1: Phase Name
+
+- [ ] **1.1** Task description
+  Effort: S | Deps: none
+  Files: src/path/to/file.ts
+  Test: returns 200 for valid request with auth token
+
+- [ ] **1.2** Another task
+  Effort: M | Deps: 1.1
+  Files: src/other/file.ts
+  Test: rejects duplicate entries with 409 conflict
+```
+
+### Standalone: TDD
+Run `/rpi:test {feature-slug}` to run TDD cycles on individual tasks.
+
+- Works independently of `/rpi:implement` — use when you want TDD on specific tasks
+- Strict RED → GREEN → REFACTOR per task, one test at a time
+- Auto-detects test framework and conventions from the project
+- Flags: `--task <id>` for single task, `--all` for all uncompleted tasks
+
+### Phase 4: Implement
+Run `/rpi:implement {feature-slug}`.
+
+Smart execution mode:
+- < 8 tasks: single plan-executor agent, sequential
+- 8+ tasks: group into waves by dependency, execute in parallel
+- Override: `--sequential` or `--parallel` flags
+
+Pipeline per phase:
+1. Execute tasks → commit per task
+   - If TDD enabled: RED (write failing test) → VERIFY RED → GREEN (minimal code) → VERIFY GREEN → REFACTOR → commit
+   - If TDD disabled: execute task → commit (original behavior)
+2. Simplify (3 parallel sub-agents: reuse, quality, efficiency)
+3. Review (code-reviewer checks against plan + test coverage)
+4. Phase verdict: PASS or FAIL
+
+IMPLEMENT.md tracks: task completion with commits, start/end times, files changed, deviations, simplify findings, review verdict.
+
+After implementation, isolation cleanup runs based on config:
+- `none`: nothing
+- `branch`: asks to merge into main branch
+- `worktree`: asks to merge + remove the worktree
+
+## Configuration (.rpi.yaml)
+
+```yaml
+folder: rpi                    # Feature folder location
+tier: standard                 # Default research tier
+auto_simplify: true            # Run simplify before review
+commit_style: conventional     # Commit message format
+parallel_threshold: 8          # Task count for parallel mode
+skip_artifacts: []             # Artifacts to never generate
+review_after_implement: true   # Mandatory review gate
+isolation: none                # none | branch | worktree
+tdd: false                     # Enable Test-Driven Development
+test_runner: auto              # Test command (auto-detect or explicit)
+```
+
+## Feature Folder Structure
+
+```
+{folder}/{feature-slug}/
+├── REQUEST.md
+├── research/
+│   └── RESEARCH.md
+├── plan/
+│   ├── PLAN.md
+│   ├── pm.md          (adaptive)
+│   ├── ux.md          (adaptive)
+│   └── eng.md
+└── implement/
+    └── IMPLEMENT.md
+```
+
+## Cross-Session Continuity
+
+All state lives in markdown files. When resuming:
+- `/rpi:status` shows all features with current phase and progress
+- `/rpi:implement` reads IMPLEMENT.md and resumes from last completed task
+- Multiple features can be in progress simultaneously
+
+## Related
+
+For agent behavioral guidelines, see the **rpi-agents** skill or individual agent files in `agents/`.