rpi-kit 1.0.0 → 1.0.1

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/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.0.1",
   "description": "Research → Plan → Implement. A systematic feature development workflow for Claude Code.",
   "license": "MIT",
   "author": "Daniel Mendes",
@@ -30,6 +30,7 @@
     "LICENSE"
   ],
   "scripts": {
+    "test": "node --test test/cli.test.js test/commands.test.js",
     "postinstall": "node bin/cli.js install --silent"
   }
 }