rpi-kit 1.4.0 → 2.0.0

package/commands/rpi/onboarding.md

@@ -1,6 +1,6 @@
 ---
 name: rpi:onboarding
-description: Analyze your codebase, generate a project profile, suggest features to build, and guide you through your first RPI feature.
+description: First-time setup — analyzes your codebase, generates context, and guides you through your first feature.
 argument-hint: "[--refresh]"
 allowed-tools:
   - Read
@@ -12,414 +12,235 @@ allowed-tools:
   - AskUserQuestion
 ---
 
-<objective>
-Auto-analyze the user's codebase with parallel agents, generate a persistent .rpi-profile.md, suggest features to build, and interactively guide the user through their first feature.
-</objective>
+# /rpi:onboarding — Guided First-Time Setup
 
-<process>
+Walks the user through RPIKit setup: explains the workflow, configures the project, analyzes the codebase, and guides them into their first feature.
 
-## 1. Welcome
+---
 
-Output:
-```
-Welcome to RPIKit — Research, Plan, Implement.
+## Step 1: Welcome message
 
-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.
+Output to the user:
 
-I'm going to analyze your project first, then suggest features you
-could build with RPIKit.
 ```
+Welcome to RPIKit v2 — Research, Plan, Implement.
 
-Check if `.rpi-profile.md` already exists and `--refresh` flag is NOT set:
-- If exists: ask "Project profile already exists. Refresh it or skip to feature selection?"
-- If `--refresh`: proceed with fresh analysis regardless
+RPIKit is a 7-phase development workflow with 13 specialized AI agents.
+Each phase produces artifacts that feed the next, with validation gates
+that prevent premature implementation.
 
-## 2. Codebase Analysis
-
-Output:
-```
-Analyzing your project...
+I'll analyze your project, set up configuration, and guide you through
+your first feature.
 ```
 
-Launch 3 agents in parallel using the Agent tool in a single message:
+## Step 2: Parse arguments and check existing setup
 
-### Agent A: Stack & Conventions Scanner
+1. Parse `$ARGUMENTS` for `--refresh` flag.
+2. Check if `rpi/context.md` exists.
 
-```
-You are analyzing a project's technology stack and coding conventions. This is a READ-ONLY task — do not write any files.
-
-1. Use Glob to find project config files:
-   - package.json, tsconfig.json, tsconfig*.json
-   - Cargo.toml, pyproject.toml, setup.py, setup.cfg
-   - go.mod, Gemfile, composer.json, pom.xml, build.gradle
-   - .eslintrc*, .prettierrc*, biome.json
-   - vite.config.*, next.config.*, webpack.config.*
-   - jest.config.*, vitest.config.*, pytest.ini
-   - docker-compose.yml, Dockerfile
-   - prisma/schema.prisma, drizzle.config.*
-
-2. Read the config files found to identify:
-   - Primary language and version
-   - Framework and version
-   - Database and ORM
-   - Test framework and runner
-   - Linter and formatter
-   - Bundler and build tool
-   - Styling approach (CSS modules, Tailwind, styled-components, etc.)
-
-3. Use Glob to find 5-10 representative source files (pick from different directories):
-   - Read them to detect:
-     - File naming convention (kebab-case, camelCase, PascalCase, snake_case)
-     - Component/module pattern (functional components, classes, modules)
-     - Import style (relative paths, path aliases, barrel exports)
-     - Error handling pattern (try/catch, Result types, custom errors)
-     - API pattern (REST routes, GraphQL resolvers, tRPC procedures)
-
-4. Identify architecture:
-   - Directory structure pattern (src/, app/, lib/, etc.)
-   - Layering (routes → services → repositories, etc.)
-   - Key entry points (main files, layout files, middleware)
-
-Output your findings in this exact format:
+- If `rpi/context.md` exists and `--refresh` was NOT passed:
+  Ask with AskUserQuestion: "Project already configured. Do you want to refresh the analysis or skip to feature selection?"
+  - If refresh: proceed to Step 3 (full init flow).
+  - If skip: jump to Step 5 (read existing `rpi/context.md` and present summary).
+- If `--refresh` was passed: proceed to Step 3 (full init flow).
+- If `rpi/context.md` does not exist: proceed to Step 3 (full init flow).
 
-## Stack
-- Language: {language} {version}
-- Framework: {framework} {version}
-- Database: {db} via {orm}
-- Testing: {test_framework}
-- Styling: {approach}
-- Linter: {tool}
-- Bundler: {tool}
+## Step 3: Run /rpi:init flow inline — configuration interview
 
-## Conventions
-- File naming: {pattern}
-- Component pattern: {pattern}
-- Import style: {pattern}
-- Error handling: {pattern}
-- API pattern: {pattern}
+### Step 3a: Check existing config
 
-## Architecture
-- Pattern: {description}
-- Key directories: {list}
-- Entry points: {list}
-```
+Check if `.rpi.yaml` exists.
+- If it exists and `--refresh` was NOT passed: ask with AskUserQuestion: ".rpi.yaml already exists. Overwrite with fresh config or keep current settings?"
+  - If keep: skip to Step 3c.
+  - If overwrite: proceed to Step 3b.
+- If it exists and `--refresh` was passed: proceed to Step 3b.
+- If it does not exist: proceed to Step 3b.
 
-### Agent B: Code Health Scanner
+### Step 3b: Interview (2 batches)
 
-```
-You are analyzing a project's code health. This is a READ-ONLY task — do not write any files.
-
-1. Use Grep to search for task markers:
-   - Pattern: TODO|FIXME|HACK|XXX|WORKAROUND|BUG
-   - Record: file, line number, and the marker text
-   - Categorize by priority: FIXME/BUG = high, TODO = medium, HACK/XXX/WORKAROUND = low
-
-2. Analyze test coverage gaps:
-   - Use Glob to find all source files (*.ts, *.tsx, *.js, *.jsx, *.py, *.rs, *.go, etc.)
-   - Use Glob to find all test files (*.test.*, *.spec.*, *_test.*, test_*.*)
-   - Compare: which source modules have no corresponding test file?
-   - List the untested modules
-
-3. Check for dead code signals:
-   - Use Grep to find exported functions/classes
-   - Use Grep to find imports of those exports
-   - Flag exports with zero imports (potential dead code)
-   - Limit to 5 findings max
-
-4. Check dependency health:
-   - If package.json exists, note how many dependencies and devDependencies
-   - Look for lock file (package-lock.json, yarn.lock, pnpm-lock.yaml)
-   - Note if any dependency versions use '*' or 'latest'
-
-5. Find uncovered error paths:
-   - Use Grep to find try/catch blocks, .catch(), or error handlers
-   - Look for empty catch blocks or catch blocks that only log
-   - Limit to 5 findings max
-
-Output your findings in this exact format:
-
-## Health
-- Task markers: {N} found ({high} high, {med} medium, {low} low priority)
-- Test coverage: {tested}/{total} modules have tests ({percentage}%)
-- Dead code signals: {N} potentially unused exports
-- Dependencies: {N} deps, {M} devDeps, lock file: {yes/no}
-- Uncovered error paths: {N} found
-
-### High Priority Markers
-- {file}:{line} — {marker text}
-
-### Untested Modules
-- {file} — no test file found
-
-### Uncovered Error Paths
-- {file}:{line} — {description}
-
-## Suggested Features (from code health)
-1. [{priority}] {slug} — {description based on findings}
-2. [{priority}] {slug} — {description}
-(Generate 1-3 suggestions based on the most impactful findings)
-```
+**Batch 1** (use AskUserQuestion — ask all at once):
+- "Do you use TDD? (yes/no, default: no)"
+- "Commit style? (conventional/freeform, default: conventional)"
+- "When should the UX agent (Pixel) run? (auto/always/never, default: auto — runs when frontend detected)"
 
-### Agent C: Git & History Analyzer
+**Batch 2** (use AskUserQuestion — ask all at once):
+- "Auto-learn from implementations? When Forge finishes a task, should RPIKit capture the solution in rpi/solutions/? (yes/no, default: no)"
+- "Party mode default panel size? (3/5/7, default: 5)"
 
-```
-You are analyzing a project's git history and risk profile. This is a READ-ONLY task — do not write any files.
+### Step 3c: Write .rpi.yaml
 
-1. Run git commands to gather history (last 30 days):
-   ```bash
-   git log --oneline --since="30 days ago" | head -30
-   ```
-   ```bash
-   git shortlog -sn --since="30 days ago"
-   ```
-   ```bash
-   git log --since="30 days ago" --pretty=format: --name-only | sort | uniq -c | sort -rn | head -10
-   ```
-
-2. Identify hotspot files (most frequently changed in 30 days)
+Write `.rpi.yaml` to the project root with the user's responses (use defaults for unanswered questions):
 
-3. Identify recent focus areas from commit messages:
-   - What themes appear? (auth, payments, UI, refactor, bugfix, etc.)
+```yaml
+version: 2
 
-4. Check for GitHub remote and issues:
-   ```bash
-   git remote get-url origin 2>/dev/null
-   ```
-   If GitHub remote exists, try:
-   ```bash
-   gh issue list --limit 5 --state open 2>/dev/null
-   ```
-   If gh is not available or fails, skip gracefully.
+# Directories
+folder: rpi/features
+specs_dir: rpi/specs
+solutions_dir: rpi/solutions
+context_file: rpi/context.md
 
-5. Assess risks:
-   - Files changed very frequently (>10 times in 30 days) = churn risk
-   - Single contributor to critical files = bus factor risk
-   - No recent commits in important directories = stale code risk
+# Execution
+parallel_threshold: 8
+commit_style: {user_response | conventional}
+tdd: {user_response | false}
 
-Output your findings in this exact format:
+# Agents
+ux_agent: {user_response | auto}
 
-## Git Insights
-- Commits (30d): {N}
-- Contributors (30d): {N}
-- Most changed files: {file1} ({count}), {file2} ({count}), {file3} ({count})
-- Recent focus: {themes}
-- Open issues: {N} (or "GitHub CLI not available")
+# Quick flow
+quick_complexity: S
 
-## Risks
-- {risk_type}: {description} — {evidence}
-(List 1-5 risks based on findings. If no significant risks, say "No significant risks detected.")
+# Knowledge compounding
+auto_learn: {user_response | true}
 
-## Suggested Features (from git analysis)
-1. [{priority}] {slug} — {description based on findings}
-(Generate 0-2 suggestions. Only suggest if findings warrant it.)
+# Party mode
+party_default_agents: {user_response | 5}
 ```
 
-## 3. Generate Project Profile
+### Step 3d: Create directory structure
 
-After all 3 agents complete, merge their outputs into `.rpi-profile.md`.
-
-### 3.1 Merge agent outputs
-
-Combine the structured sections from all 3 agents:
-- From Agent A: Stack, Conventions, Architecture
-- From Agent B: Health, Suggested Features
-- From Agent C: Git Insights, Risks, Suggested Features
+```bash
+mkdir -p rpi/specs
+mkdir -p rpi/solutions
+mkdir -p rpi/features
+```
 
-### 3.2 Deduplicate and rank suggestions
+## Step 4: Launch Atlas — codebase analysis
 
-Merge suggested features from Agent B and Agent C:
-- Remove duplicates (same area of code)
-- Rank by priority: HIGH > MEDIUM > LOW
-- Keep top 5 suggestions max
+Launch Atlas agent to analyze the codebase and generate `rpi/context.md`:
 
-### 3.3 Write .rpi-profile.md
+```
+You are Atlas. Analyze this entire codebase and produce a comprehensive project context document.
 
-Write the merged profile to `.rpi-profile.md` at the project root:
+Your task:
+1. Read config files first (package.json, tsconfig, Cargo.toml, pyproject.toml, go.mod, etc.)
+2. Explore the directory structure — map all key directories and their purposes
+3. Find 5-10 representative source files across different parts of the codebase
+4. Detect naming conventions, component patterns, import style, error handling
+5. Identify the testing setup and coverage patterns
+6. Note any TODOs, FIXMEs, or incomplete areas in the code
+7. Identify untested modules or areas with weak coverage
+8. Spot architectural risks or technical debt
 
-```markdown
-# Project Profile
+Output format — write this directly to rpi/context.md:
 
-Generated: {YYYY-MM-DD HH:mm}
+# Project Context
 
-{Stack section from Agent A}
+## Stack
+- Language: {language} {version}
+- Framework: {framework} {version}
+- Database: {db} (if any)
+- Testing: {test_framework}
+- Build: {build_tool}
+- Package Manager: {package_manager}
 
-{Conventions section from Agent A}
+## Architecture
+- Pattern: {description}
+- Key directories: {list with purposes}
+- Entry points: {list}
 
-{Architecture section from Agent A}
+## Conventions
+- File naming: {pattern}
+- Component pattern: {pattern}
+- Import style: {pattern}
+- Error handling: {pattern}
+- API pattern: {pattern}
 
-{Health section from Agent B}
+## Key Files
+{List of important files with brief descriptions}
 
-{Risks section from Agent C}
+## Existing Tests
+{Summary of test coverage and testing patterns}
 
-## Suggested Features
-{Merged and ranked list from Agents B and C}
-1. [{priority}] {slug} — {description}
-   Source: {what finding led to this suggestion}
-2. ...
+## Risks and Technical Debt
+{Identified risks, TODOs, FIXMEs, weak areas}
 
-{Git Insights section from Agent C}
+## Opportunities
+{3-5 concrete feature ideas based on: TODOs found, untested modules, missing error handling, potential improvements}
 ```
 
-### 3.4 Run /rpi:init if needed
+Wait for Atlas to complete. Store the output as `$ATLAS_OUTPUT`.
 
-Check if `.rpi.yaml` exists:
-- If yes: read it and confirm with user ("Found existing config. Using it.")
-- If no: run the init flow — ask the 4 batches of questions from `/rpi:init` and create `.rpi.yaml`
+## Step 5: Present codebase analysis summary
 
-### 3.5 Present profile summary
+1. Read `rpi/context.md` (freshly generated or existing).
+2. Output a condensed summary to the user:
 
-Output a condensed version of the profile:
 ```
-Project Profile — saved to .rpi-profile.md
+Project Analysis Complete
 
-  Stack:    {language} / {framework} / {db}
-  Tests:    {tested}/{total} modules covered ({percentage}%)
-  Health:   {N} TODOs, {M} uncovered error paths
-  Risks:    {risk_count} identified
-  Hotspots: {top_file} ({changes} changes in 30d)
+Stack: {language} + {framework}
+Architecture: {pattern}
+Files: {approximate count}
+Tests: {coverage summary}
 
-  {N} feature suggestions generated.
+Key findings:
+- {finding 1}
+- {finding 2}
+- {finding 3}
 ```
 
-## 4. Feature Selection
+## Step 6: Suggest features
 
-Present the suggested features from the profile and ask the user what they want to do.
-
-Use AskUserQuestion:
+Based on the `## Opportunities` section in `rpi/context.md` (or from `$ATLAS_OUTPUT`), present 3-5 concrete feature suggestions:
 
-"Based on your project analysis, here are the top suggestions:
+```
+Based on the analysis, here are some things you could work on:
 
-{numbered list of suggestions with priority and description}
+1. {feature idea} — {brief justification from codebase analysis}
+2. {feature idea} — {brief justification}
+3. {feature idea} — {brief justification}
+```
 
-What would you like to do?"
+Each suggestion should be grounded in something Atlas actually found (a TODO, an untested module, a missing pattern, a risk to address).
 
-Options:
-- "Build one of these features" → ask which one, proceed to Phase 5 option A
-- "Describe my own feature" → proceed to Phase 5 option B
-- "See a demo first" → proceed to Phase 5 option C
-- "I'm done — I'll explore on my own" → proceed to Phase 5 option D
+## Step 7: Ask what the user wants to do
 
-If user picks "Build one of these features", follow up with AskUserQuestion listing the suggestions as selectable options.
+Use AskUserQuestion:
 
-## 5. Guided First Feature
+"What would you like to do?
+A) Build one of these features (pick a number)
+B) Describe my own feature
+C) I'll explore on my own"
 
-### Option A: Build a suggested feature
+### If A (build a suggested feature):
 
-1. Read the selected suggestion from the profile
-2. Read `.rpi.yaml` for the configured folder
-3. Create the feature folder structure:
-   ```bash
-   mkdir -p {folder}/{slug}/research
-   mkdir -p {folder}/{slug}/plan
-   mkdir -p {folder}/{slug}/implement
-   ```
-4. Pre-fill REQUEST.md using context from the profile and the suggestion:
-   - Summary: from the suggestion description
-   - Problem: from the source finding (TODO, test gap, risk)
-   - Target Users: infer from the codebase context
-   - Constraints: from conventions and architecture in the profile
-   - Complexity Estimate: infer from the suggestion scope
-5. Show the generated REQUEST.md to the user
-6. Output:
+1. Convert the selected feature idea into a slug.
+2. Read `commands/rpi/new.md` and follow its process from Step 4 onward (Luna's interview), using the suggested feature as context.
+3. After REQUEST.md is created, output:
    ```
-   Feature created: {folder}/{slug}/REQUEST.md
+   Feature created: rpi/features/{slug}/REQUEST.md
 
-   This is what /rpi:new produces — a structured feature description.
-
-   Next steps:
-     /rpi:research {slug}    Agents analyze feasibility → GO/NO-GO
-     /rpi:plan {slug}        Generate specs + task checklist
-     /rpi:implement {slug}   Build it task by task
-
-   Want me to run /rpi:research {slug} now?
+   Next: /rpi {slug}
    ```
-7. If user says yes, explain what's about to happen ("Research phase: agents will analyze your codebase and requirements in parallel..."), then suggest they run the command.
-
-### Option B: Describe your own feature
-
-1. Explain: "Let's create your first feature. I'll ask a few questions to understand what you want to build."
-2. Run the same interview flow as `/rpi:new`:
-   - Ask: "What feature do you want to build?"
-   - Derive slug from answer
-   - Ask: "What problem does this solve? Who benefits?"
-   - Ask adaptive follow-ups based on answers
-3. Create REQUEST.md in the feature folder
-4. Present next steps as in Option A
-
-### Option C: See a demo
-
-1. If `.rpi.yaml` doesn't exist, create a minimal one with defaults
-2. Create demo folder and REQUEST.md:
-   ```bash
-   mkdir -p {folder}/demo-greeting/research
-   mkdir -p {folder}/demo-greeting/plan
-   mkdir -p {folder}/demo-greeting/implement
-   ```
-3. Write `{folder}/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.
+### If B (describe own feature):
 
-   ## 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
-   ```
-4. Explain each section:
+1. Ask with AskUserQuestion: "What's the name for this feature? (short, e.g. 'oauth', 'dark-mode', 'csv-export')"
+2. Read `commands/rpi/new.md` and follow its process from Step 4 onward (Luna's interview).
+3. After REQUEST.md is created, output:
    ```
-   I created a demo feature: {folder}/demo-greeting/
+   Feature created: rpi/features/{slug}/REQUEST.md
 
-   This is what /rpi:new produces. Let me walk through the sections:
+   Next: /rpi {slug}
+   ```
 
-     Summary      → One-line description of the feature
-     Problem      → Why this is needed, who's affected
-     Target Users → Who will use it
-     Constraints  → Technical and business boundaries
-     Complexity   → Rough size estimate (S/M/L/XL)
+### If C (explore on their own):
 
-   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
+Proceed to Step 8.
 
-   You can run these commands now, or clean up the demo:
-     rm -rf {folder}/demo-greeting
-   ```
+## Step 8: Quick reference card
 
-### Option D: Exit
+Output to the user:
 
-Output:
 ```
-Your project profile is saved at .rpi-profile.md
-RPIKit agents will use it for better context in all future commands.
-
-Quick reference:
-  /rpi:new my-feature          Start a new feature
-  /rpi:research my-feature     Analyze feasibility
-  /rpi:plan my-feature         Generate implementation plan
-  /rpi:implement my-feature    Build it
-  /rpi:status                  See all features
-
-Tips:
-  - Start with --quick tier for small features
-  - Use --deep tier for risky or large changes
-  - Enable tdd: true in .rpi.yaml for test-first development
-  - Run /rpi:onboarding --refresh to re-analyze your project anytime
+Quick Reference:
+  /rpi:new my-feature    Start a new feature
+  /rpi my-feature        Auto-progress to next phase
+  /rpi:party "topic"     Multi-agent debate
+  /rpi:learn             Capture a solution
+  /rpi:status            See all features
+
+Setup complete. Happy building!
 ```
-
-</process>