rpi-kit 1.0.1 → 1.2.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/AGENTS.md

@@ -81,6 +81,10 @@ You implement tasks from PLAN.md one at a time with surgical precision.
 3. Match existing code style exactly — even if you'd do it differently
 4. If a task is blocked, skip it and note the blocker — don't improvise
 5. Every commit message references the task ID: "feat(1.3): route handlers"
+6. Before writing code, read ALL target files and output CONTEXT_READ and EXISTING_PATTERNS
+7. After completion, write a checkpoint file to `implement/checkpoints/{task_id}.md` with structured status
+8. Return a single status line to the orchestrator — do not return verbose output
+9. Classify deviations as cosmetic (auto-accept), interface (flag downstream), or scope (block for human)
 
 ## Code Simplifier
 

package/README.md

@@ -71,6 +71,8 @@ Copy `AGENTS.md` and `codex.md` to your project root. The workflow rules and age
 | `/rpi:simplify` | Code simplification (reuse, quality, efficiency) |
 | `/rpi:status` | Show all features and their current phase |
 | `/rpi:review` | Code review against plan requirements + test coverage |
+| `/rpi:docs` | Generate documentation from implementation artifacts |
+| `/rpi:add-todo` | Capture quick implementation ideas in `{folder}/todos/` |
 
 ## Research Tiers
 
@@ -84,7 +86,7 @@ Control depth and cost with tier flags:
 
 ## Agent Team
 
-RPIKit simulates a product team with 11 specialized agents:
+RPIKit simulates a product team with 12 specialized agents:
 
 | Agent | Perspective |
 |-------|-------------|
@@ -99,6 +101,7 @@ RPIKit simulates a product team with 11 specialized agents:
 | Test Engineer | Writes failing tests before implementation (TDD) |
 | Code Simplifier | Reuse, quality, efficiency checks with direct fixes |
 | Code Reviewer | Reviews against plan requirements + test coverage |
+| Doc Writer | Generates documentation from artifacts for completed features |
 
 All agents follow behavioral constraints inspired by [Karpathy's coding guidelines](https://x.com/karpathy/status/2015883857489522876): cite evidence, name unknowns, be concrete, stay in scope.
 
@@ -174,7 +177,7 @@ test_runner: auto              # Test command (auto-detect or explicit)
 |---|---|---|---|
 | Focus | Spec-driven artifacts | Feature lifecycle with gates | Full project management |
 | Phases | Fluid (propose/apply) | 3 phases (R→P→I) | Roadmap → phases → tasks |
-| Agents | None | 11 specialized roles | 15+ orchestrated agents |
+| Agents | None | 12 specialized roles | 15+ orchestrated agents |
 | TDD | None | Integrated RED→GREEN→REFACTOR | None |
 | Validation | None | GO/NO-GO research gate | Goal-backward verification |
 | Scope | Single change | Single feature | Entire project |

package/agents/plan-executor.md

@@ -17,6 +17,11 @@ You implement tasks from the RPI plan. You work surgically — one task at a tim
 5. Commit messages reference the task ID: `feat(1.3): route handlers` or `test(2.1): auth middleware tests`
 6. Read the eng.md technical spec before implementing — follow the architecture decisions
 7. After each task, report: files changed, lines added/removed, any deviations from plan
+8. Classify deviations by severity:
+   - `cosmetic`: naming, formatting changes (auto-accepted, log only)
+   - `interface`: changed function signatures, added/removed parameters (flags downstream tasks)
+   - `scope`: did more or less than specified (blocks execution, requires human decision)
+9. Write a per-task checkpoint file after completion (see Output Protocol in section 5)
 </rules>
 
 <anti_patterns>
@@ -34,11 +39,17 @@ You implement tasks from the RPI plan. You work surgically — one task at a tim
 
 ## For each assigned task:
 
-### 1. Read context
-- Read the task description from PLAN.md (effort, deps, files)
+### 1. Pre-Implementation Context Read (MANDATORY)
+- Read ALL target files listed in the task's `Files:` field
 - Read eng.md for technical approach
 - Read pm.md for acceptance criteria (if exists)
 - Read ux.md for UX requirements (if exists and task is UI-related)
+- Output before ANY code changes:
+  ```
+  CONTEXT_READ: [list of files examined]
+  EXISTING_PATTERNS: [key patterns observed -- naming, error handling, imports]
+  ```
+- Match these patterns in your implementation — do not invent new patterns
 
 ### 2. Verify dependencies
 - Check that all dependency tasks are completed
@@ -55,20 +66,30 @@ You implement tasks from the RPI plan. You work surgically — one task at a tim
 - If the task has acceptance criteria (from pm.md), verify each one
 - Check that the implementation matches the task description
 
-### 5. Report
-Output for each completed task:
+### 5. Write checkpoint and report
+
+Write checkpoint file to `{folder}/{feature-slug}/implement/checkpoints/{task_id}.md`:
+
+```markdown
+## Status: {task_id}
+status: done | blocked | deviated
+files_read: ["list of files read in pre-implementation"]
+files_changed: ["list of files created or modified"]
+commit: {commit_hash}
+deviations: none | {severity}: {description}
+duration: {estimated_seconds}s
+context_read: ["files from CONTEXT_READ step"]
+patterns_followed: ["patterns from EXISTING_PATTERNS step"]
+```
+
+Return to orchestrator (single line only):
 ```
-Task {id}: {name} — DONE
-Files: {list of files changed}
-Lines: +{added} -{removed}
-Deviations: {none | list deviations with rationale}
+DONE: {task_id} | files: {N} changed | deviations: none
 ```
 
-If blocked:
+Or if blocked:
 ```
-Task {id}: {name} — BLOCKED
-Reason: {why}
-Suggestion: {what to do}
+BLOCKED: {task_id} | reason: {short description}
 ```
 
 </execution_flow>

package/bin/onboarding.js

@@ -17,7 +17,7 @@ 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:
+${DIM}12 specialized agents simulate a product team:
 engineers, PMs, designers, reviewers — all working in parallel.${RESET}`,
   },
   {
@@ -89,18 +89,15 @@ ${DIM}Or run standalone:${RESET}  /rpi:test your-feature --task 1.2`,
     body: `
 ${BOLD}Step 1:${RESET} Open Claude Code in your project
 
-${BOLD}Step 2:${RESET} Initialize RPIKit
-  ${CYAN}/rpi:init${RESET}
+${BOLD}Step 2:${RESET} Run the interactive onboarding
+  ${CYAN}/rpi:onboarding${RESET}
 
-${BOLD}Step 3:${RESET} Create your first feature
-  ${CYAN}/rpi:new my-feature${RESET}
+${DIM}This will analyze your codebase, generate a project profile,
+suggest features to build, and guide you through your first 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}
+${DIM}Or jump straight in:${RESET}
+  ${CYAN}/rpi:init${RESET}              Configure RPIKit
+  ${CYAN}/rpi:new my-feature${RESET}    Start a feature
 
 ${GREEN}Happy building!${RESET}`,
   },

package/codex.md

@@ -0,0 +1,72 @@
+# 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
+- `/rpi:docs <feature>` — Generate documentation from artifacts
+- `/rpi:add-todo` — Capture quick implementation ideas
+
+## 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) |
+| Doc Writer | Generates documentation from artifacts |
+
+## 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

@@ -77,7 +77,7 @@ Priority: {priority}
 
 Quick actions:
   /rpi:new {slug}    Promote to a full RPI feature
-  /rpi:todos         List all pending todos
+  /rpi:status        Show all features and their current phase
 ```
 
 </process>