rpi-kit 1.0.0

package/commands/rpi/docs.md

@@ -0,0 +1,193 @@
+---
+name: rpi:docs
+description: Generate code documentation from implementation artifacts. Adds inline docs, updates README, generates API docs, and creates changelog entry. Final step in the RPI pipeline.
+argument-hint: "<feature-slug> [--skip-inline] [--skip-readme] [--skip-changelog]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<objective>
+Generate documentation for a completed feature using all RPI artifacts as source. Adds inline code documentation, updates project README if needed, generates API docs for new endpoints, and creates a changelog entry.
+</objective>
+
+<process>
+
+## 1. Load config and parse arguments
+
+Read `.rpi.yaml` for folder path.
+Parse `$ARGUMENTS`:
+- First argument: `{feature-slug}` (required)
+- `--skip-inline`: skip adding inline code documentation
+- `--skip-readme`: skip README updates
+- `--skip-changelog`: skip changelog entry
+
+## 2. Validate prerequisites
+
+Verify the feature has passed review. Read `{folder}/{feature-slug}/implement/IMPLEMENT.md`.
+
+Check for review verdict:
+- If verdict is PASS → proceed
+- If verdict is FAIL → error:
+  ```
+  Feature has not passed review. Run /rpi:review {feature-slug} first.
+  ```
+- If IMPLEMENT.md doesn't exist → error:
+  ```
+  Implementation not found. Run /rpi:implement {feature-slug} first.
+  ```
+
+## 3. Gather all artifacts
+
+Read all feature artifacts for context:
+- `{folder}/{feature-slug}/REQUEST.md` — what was requested
+- `{folder}/{feature-slug}/research/RESEARCH.md` — decisions and trade-offs
+- `{folder}/{feature-slug}/plan/eng.md` — technical spec (APIs, models, architecture)
+- `{folder}/{feature-slug}/plan/pm.md` — acceptance criteria (if exists)
+- `{folder}/{feature-slug}/plan/PLAN.md` — task list with files
+- `{folder}/{feature-slug}/implement/IMPLEMENT.md` — what was actually built, deviations
+
+## 4. Identify documentation targets
+
+From IMPLEMENT.md and PLAN.md, collect:
+- All files created or modified
+- New public functions, classes, types, and exports
+- New API endpoints or routes
+- New configuration options or environment variables
+- Deviations from the plan (may need extra documentation)
+
+Use Glob and Grep to read the actual implemented files and identify what needs documentation.
+
+## 5. Launch parallel documentation agents
+
+Use the Agent tool to launch applicable agents concurrently.
+
+### Agent 1: Inline Documentation (unless --skip-inline)
+
+```
+You are documenting code for a completed feature.
+
+Read these artifacts for context:
+- {folder}/{feature-slug}/plan/eng.md
+- {folder}/{feature-slug}/implement/IMPLEMENT.md
+
+Then read each implemented file listed in IMPLEMENT.md.
+
+Add inline documentation ONLY where it adds value:
+1. Public functions/methods: brief JSDoc/docstring with params and return type
+2. Complex logic: short comment explaining WHY, not WHAT
+3. Non-obvious design decisions: reference the trade-off from eng.md
+4. New types/interfaces: brief description of purpose
+
+Rules:
+- Do NOT add obvious comments ("// returns the user" on a getUser function)
+- Do NOT document private/internal helpers unless logic is non-trivial
+- Match the project's existing documentation style and conventions
+- If the project has no inline docs convention, use minimal JSDoc/docstrings only on public APIs
+- Do NOT modify any behavior — documentation only
+```
+
+### Agent 2: API Documentation (if new endpoints exist)
+
+```
+You are generating API documentation for new endpoints.
+
+Read these artifacts:
+- {folder}/{feature-slug}/plan/eng.md (API design section)
+- {folder}/{feature-slug}/implement/IMPLEMENT.md
+
+Find all new API endpoints/routes in the implemented files using Grep.
+
+For each endpoint, document:
+- Method and path
+- Request parameters/body with types
+- Response format with types
+- Error responses
+- Authentication requirements
+- Example request/response
+
+Check if the project has an existing API docs file or pattern (e.g., docs/api.md, swagger/openapi spec, README API section). If yes, extend it. If no, create `{folder}/{feature-slug}/implement/API.md`.
+
+Use the format that matches existing project conventions.
+```
+
+### Agent 3: README & Changelog (unless both skipped)
+
+```
+You are updating project documentation for a completed feature.
+
+Read these artifacts:
+- {folder}/{feature-slug}/REQUEST.md (feature summary)
+- {folder}/{feature-slug}/implement/IMPLEMENT.md (what was built, deviations)
+- {folder}/{feature-slug}/plan/eng.md (new dependencies, config)
+
+Tasks:
+
+1. README update (unless --skip-readme):
+   - Read the project's existing README.md
+   - Determine if the feature needs to be mentioned (new user-facing capability, new config, new dependency)
+   - If yes, add a concise entry in the appropriate section
+   - If the feature is purely internal/refactor, skip README update
+   - Do NOT rewrite the README — only add what's necessary
+
+2. Changelog entry (unless --skip-changelog):
+   - Check if CHANGELOG.md exists. If not, create it with Keep a Changelog format
+   - Add an entry under [Unreleased]:
+     - Added: new features
+     - Changed: modifications to existing features
+     - Fixed: bug fixes
+   - Keep entries concise — one line per change
+   - Reference the feature slug for traceability
+```
+
+## 6. Write DOCS.md summary
+
+After all agents complete, write `{folder}/{feature-slug}/implement/DOCS.md`:
+
+```markdown
+# Documentation: {Feature Title}
+
+Generated: {timestamp}
+
+## Inline Documentation
+- Files documented: {N}
+- Public APIs documented: {list}
+{Or: "Skipped (--skip-inline)"}
+
+## API Documentation
+- New endpoints: {N}
+- Docs location: {path}
+{Or: "No new endpoints"}
+
+## README
+- Updated: yes/no
+- Changes: {brief description}
+{Or: "Skipped (--skip-readme)"}
+
+## Changelog
+- Entry added: yes/no
+- Section: Added/Changed/Fixed
+{Or: "Skipped (--skip-changelog)"}
+```
+
+## 7. Present result
+
+Output:
+```
+Documentation complete for {feature-slug}:
+- Inline docs: {N} files documented
+- API docs: {endpoint count or "none"}
+- README: {updated or skipped}
+- Changelog: {entry added or skipped}
+
+Feature {feature-slug} is fully complete.
+All artifacts: {folder}/{feature-slug}/
+```
+
+</process>

package/commands/rpi/implement.md

@@ -0,0 +1,275 @@
+---
+name: rpi:implement
+description: Execute the implementation plan with task-level tracking, smart parallelism, automatic simplification, and mandatory code review.
+argument-hint: "<feature-slug> [--sequential|--parallel] [--skip-simplify] [--skip-review] [--resume]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<objective>
+Execute tasks from PLAN.md with per-task commits, automatic code simplification, and mandatory code review. Track everything in IMPLEMENT.md.
+</objective>
+
+<process>
+
+## 1. Load config and parse arguments
+
+Read `.rpi.yaml` for configuration.
+Parse `$ARGUMENTS`:
+- First argument: `{feature-slug}` (required)
+- `--sequential`: force single agent mode
+- `--parallel`: force parallel wave mode
+- `--skip-simplify`: skip the simplify step (overrides config)
+- `--skip-review`: skip the review step (overrides config)
+- `--resume`: resume from last completed task in existing IMPLEMENT.md
+
+## 2. Validate prerequisites
+
+Read `{folder}/{feature-slug}/plan/PLAN.md`. If missing:
+```
+Plan not found. Run /rpi:plan {feature-slug} first.
+```
+
+Also read eng.md (and pm.md, ux.md if they exist) for full context.
+
+## 3. Handle resume
+
+If `--resume` or IMPLEMENT.md already exists:
+- Read IMPLEMENT.md
+- Parse completed tasks (lines with `[x]`)
+- Identify next uncompleted task
+- Inform user: "Resuming from task {id}: {name}"
+
+If IMPLEMENT.md exists and no `--resume`:
+- Ask user: "Implementation in progress ({N}/{total} tasks). Resume or restart?"
+
+## 4. Initialize IMPLEMENT.md
+
+If starting fresh, create `{folder}/{feature-slug}/implement/IMPLEMENT.md`:
+
+```markdown
+# Implementation: {Feature Title}
+
+Started: {timestamp}
+
+## Tasks
+
+{Copy task checklist from PLAN.md with all boxes unchecked}
+
+## Deviations
+
+_None yet._
+
+## Simplify Findings
+
+_Pending._
+
+## Review
+
+_Pending._
+```
+
+## 5. Determine execution mode
+
+Count total uncompleted tasks.
+
+If `--sequential` flag: single agent mode.
+If `--parallel` flag: wave mode.
+Otherwise, use smart default:
+- < {parallel_threshold from config, default 8} tasks → single agent
+- >= threshold → parallel waves
+
+## 6. Execute tasks
+
+### Single agent mode:
+
+For each task in order (respecting dependencies):
+
+1. Read PLAN.md task details (files, deps, test spec if present)
+2. Read eng.md for technical context
+
+#### If TDD is enabled (`tdd: true` in config):
+
+Follow strict RED → GREEN → REFACTOR per task:
+
+**RED — Write failing test:**
+3a. Launch test-engineer agent:
+   ```
+   You are the test-engineer agent for the RPI workflow.
+
+   Read these files for context:
+   - {folder}/{feature-slug}/plan/PLAN.md
+   - {folder}/{feature-slug}/plan/eng.md
+
+   Current task:
+   **{task_id}** {task_description}
+   Files: {files}
+   Test: {test_spec from PLAN.md, if present}
+
+   Write ONE failing test for this task.
+   - Exercise real code through public interfaces
+   - Clear, behavior-describing test name
+   - Minimal assertions — one logical check
+   - Follow project test conventions
+   - Do NOT write implementation code
+   ```
+
+**VERIFY RED — Confirm correct failure:**
+3b. Run the test:
+   ```bash
+   {test_runner} {test_file}
+   ```
+   - Test fails for expected reason → proceed
+   - Test errors (syntax/import) → fix test, re-run
+   - Test passes → behavior exists already, skip or ask user
+
+**GREEN — Minimal implementation:**
+3c. Launch plan-executor agent:
+   ```
+   You are implementing a single task using TDD.
+
+   The following test is currently FAILING:
+   {test_file}:{test_name}
+   Failure: {failure_reason}
+
+   Write the MINIMAL code to make this test pass.
+   - Only touch files listed for this task
+   - Do NOT add features beyond what the test requires
+   - Match existing code style
+   - If blocked, report the blocker — don't improvise
+   ```
+
+**VERIFY GREEN — Confirm pass:**
+3d. Run the test again:
+   ```bash
+   {test_runner} {test_file}
+   ```
+   Run full suite to check regressions:
+   ```bash
+   {test_runner}
+   ```
+   - All pass → proceed to REFACTOR
+   - Target fails → fix implementation (not the test), re-run
+   - Other tests break → fix regressions first
+
+**REFACTOR — Clean up:**
+3e. Review implementation: remove duplication, improve names, extract helpers if 3+ uses.
+   Re-run tests to confirm still green.
+
+**Additional test cycles:**
+3f. If the task has multiple test scenarios (from test spec or eng.md edge cases), repeat RED → GREEN → REFACTOR for each additional test before moving to next task.
+
+#### If TDD is disabled (default):
+
+3. Launch plan-executor agent:
+   ```
+   You are implementing a single task from the RPI plan.
+
+   Read these files for context:
+   - {folder}/{feature-slug}/plan/PLAN.md
+   - {folder}/{feature-slug}/plan/eng.md
+   - {additional plan files if they exist}
+
+   Current task:
+   **{task_id}** {task_description}
+   Effort: {effort} | Files: {files}
+
+   Rules:
+   - Only touch files listed for this task
+   - Match existing code style
+   - If blocked, report the blocker — don't improvise
+   - When done, report: files changed, any deviations
+   ```
+
+#### After task completion (both modes):
+
+4. Update IMPLEMENT.md:
+   - Mark task as `[x]` with timestamp
+   - Record files changed
+   - Record any deviations
+   - If TDD: record tests written and pass/fail status
+5. If config `commit_style` is `conventional`:
+   - Stage changed files
+   - Commit: `{type}({task_id}): {task_description}`
+
+### Parallel wave mode:
+
+1. Group tasks by phase from PLAN.md
+2. Within each phase, identify dependency waves:
+   - Wave 1: tasks with no deps (or deps already completed)
+   - Wave 2: tasks depending only on wave 1
+   - Wave 3: tasks depending on waves 1-2
+3. For each wave, launch all tasks as parallel agents
+4. Wait for all wave agents to complete
+5. Update IMPLEMENT.md with all completed tasks
+6. Proceed to next wave
+
+## 7. Phase checkpoint
+
+After all tasks in a phase complete:
+
+Output:
+```
+Phase {N}: {Phase Name}
+Tasks: {completed}/{total}
+Commits: {list}
+```
+
+If any tasks failed or were blocked, ask user how to proceed.
+
+## 8. Run simplify (unless --skip-simplify)
+
+If `auto_simplify` is true in config (and no `--skip-simplify`):
+
+Run the simplify process as defined in `/rpi:simplify {feature-slug}`.
+Record findings in IMPLEMENT.md under "## Simplify Findings".
+
+## 9. Run review (unless --skip-review)
+
+If `review_after_implement` is true in config (and no `--skip-review`):
+
+Run the review process as defined in `/rpi:review {feature-slug}`.
+Record verdict in IMPLEMENT.md under "## Review".
+
+## 10. Finalize IMPLEMENT.md
+
+Update IMPLEMENT.md with:
+```markdown
+## Summary
+
+Completed: {timestamp}
+Total tasks: {N}
+Commits: {list with hashes}
+Phases: {M}
+
+## Review Verdict: {PASS|FAIL}
+{details}
+```
+
+## 11. Present result
+
+If PASS:
+```
+Feature {feature-slug} implemented.
+{N} tasks completed across {M} phases.
+Review: PASS
+
+All artifacts: {folder}/{feature-slug}/
+```
+
+If FAIL:
+```
+Feature {feature-slug} implementation complete but review found issues:
+{list issues}
+
+Fix and re-run: /rpi:review {feature-slug}
+```
+
+</process>

package/commands/rpi/init.md

@@ -0,0 +1,82 @@
+---
+name: rpi:init
+description: Initialize RPI workflow configuration for this project. Sets up feature folder location, default research tier, and preferences.
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - AskUserQuestion
+---
+
+<objective>
+Create a `.rpi.yaml` configuration file at the project root with user preferences for the RPI workflow.
+</objective>
+
+<process>
+
+## 1. Check for existing config
+
+Use Glob to search for `.rpi.yaml` at the project root. If it exists, read it and ask the user if they want to reconfigure or keep existing settings.
+
+## 2. Interview the user
+
+Use AskUserQuestion to gather preferences. Ask up to 4 questions at a time:
+
+**Batch 1:**
+- "Where should feature folders live?" — Options: `rpi/` (Recommended), `.rpi/`, `docs/features/`, custom path
+- "What's your default research tier?" — Options: `standard` (Recommended), `quick`, `deep`
+
+**Batch 2:**
+- "Should code simplification run automatically before review?" — Options: Yes (Recommended), No
+- "What commit message style do you prefer?" — Options: `conventional` (Recommended, e.g., feat(1.1): task name), `descriptive` (plain English)
+
+**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
+
+**Batch 4 (TDD):**
+- "Enable Test-Driven Development during implementation?" — Options: No (default), Yes
+- If yes: "What command runs your tests?" — Options: auto-detect (Recommended), `npm test`, `npx vitest`, `pytest`, custom
+
+## 3. Create .rpi.yaml
+
+Write the config file at the project root:
+
+```yaml
+# RPI Workflow Configuration
+# Docs: https://github.com/mndz/rpi-kit
+
+folder: {user_choice}
+tier: {user_choice}
+auto_simplify: {true|false}
+commit_style: {conventional|descriptive}
+parallel_threshold: {number}
+skip_artifacts: []
+review_after_implement: true
+branch_per_feature: {true|false}
+tdd: {true|false}
+test_runner: {auto|command}
+```
+
+## 4. Create feature folder
+
+Create the configured folder directory if it doesn't exist:
+```bash
+mkdir -p {folder}
+```
+
+## 5. Confirm
+
+Output a brief confirmation:
+```
+RPI initialized.
+Config: .rpi.yaml
+Features: {folder}/
+Tier: {tier}
+
+Next: /rpi:new to start your first feature.
+```
+
+</process>

package/commands/rpi/new.md

@@ -0,0 +1,100 @@
+---
+name: rpi:new
+description: Start a new feature with an adaptive interview. Generates a structured REQUEST.md in the feature folder.
+argument-hint: "[feature-name]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - AskUserQuestion
+---
+
+<objective>
+Interview the user about a new feature and generate a structured REQUEST.md in `{folder}/{feature-slug}/`.
+</objective>
+
+<process>
+
+## 1. Load config
+
+Read `.rpi.yaml` from the project root. If it doesn't exist, use defaults:
+- folder: `rpi`
+- tier: `standard`
+
+## 2. Determine feature slug
+
+If `$ARGUMENTS` contains a feature name, convert to kebab-case slug.
+If no argument, ask: "What feature do you want to build?" and derive the slug from the answer.
+
+## 3. Check for existing feature
+
+Check if `{folder}/{feature-slug}/` already exists. If yes, warn the user and ask if they want to continue (overwrite REQUEST.md) or pick a different name.
+
+## 4. Adaptive interview
+
+Start with core questions, then ask follow-ups based on answers.
+
+**Core (always ask):**
+- "What feature do you want to build?" (skip if already answered from slug)
+- "What problem does this solve? Who benefits?"
+
+**Adaptive follow-ups (based on answers):**
+- If feature involves UI: "Any specific UX requirements or references?"
+- If feature involves data: "What data models or schemas are affected?"
+- If feature sounds complex: "What's the rough complexity you expect? (S/M/L/XL)"
+- If mentions external services: "Any API constraints or rate limits to consider?"
+- Always offer: "Any other constraints, references, or inspiration? (links, screenshots, examples)"
+
+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
+
+Create the feature folder and write REQUEST.md:
+
+```bash
+mkdir -p {folder}/{feature-slug}/research
+mkdir -p {folder}/{feature-slug}/plan
+mkdir -p {folder}/{feature-slug}/implement
+```
+
+Write `{folder}/{feature-slug}/REQUEST.md` with this structure:
+
+```markdown
+# {Feature Title}
+
+## Summary
+{1-3 sentence description of the feature}
+
+## Problem
+{What problem does this solve? Who is affected?}
+
+## Target Users
+{Who will use this feature?}
+
+## Constraints
+- {Technical constraints}
+- {Business constraints}
+- {Dependencies}
+
+## References
+- {Links, screenshots, examples, inspiration}
+
+## Complexity Estimate
+{S | M | L | XL} — {brief justification}
+```
+
+## 6. Next step
+
+Output:
+```
+Feature created: {folder}/{feature-slug}/REQUEST.md
+
+Next: /rpi:research {feature-slug}
+Options:
+  --quick     Feasibility check only (fast)
+  --standard  Scope + technical approach (default)
+  --deep      Full analysis with strategic review
+```
+
+</process>