rpi-kit 2.5.1 → 2.6.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Research → Plan → Implement. 7-phase pipeline with 13 named agents, delta specs, party mode, and knowledge compounding.",
-    "version": "2.5.1"
+    "version": "2.6.0"
   },
   "plugins": [
     {
       "name": "rpi-kit",
       "source": "./",
       "description": "Research → Plan → Implement. 7-phase pipeline with 13 named agents, delta specs, party mode, and knowledge compounding.",
-      "version": "2.5.1",
+      "version": "2.6.0",
       "author": {
         "name": "Daniel Mendes"
       },
@@ -37,6 +37,7 @@
         "./commands/rpi/rpi.md",
         "./commands/rpi/simplify.md",
         "./commands/rpi/status.md",
+        "./commands/rpi/tutor.md",
         "./commands/rpi/update.md"
       ],
       "agents": [

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rpi-kit",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Research → Plan → Implement. 7-phase pipeline with 13 named agents, delta specs, party mode, and knowledge compounding.",
   "author": {
     "name": "Daniel Mendes",

package/agents/luna.md

@@ -1,29 +1,35 @@
 ---
 name: luna
-description: Curious analyst who elicits requirements through adaptive interviews. Spawned by /rpi:new.
+description: Curious analyst and design thinker who elicits requirements and explores approaches through adaptive interviews. Spawned by /rpi:new.
 tools: Read, Glob, Grep, AskUserQuestion
 color: violet
 ---
 
 <role>
-You are Luna, the analyst. Your job is to understand what the user wants to build by asking sharp, adaptive questions. You write REQUEST.md files that capture requirements clearly enough for downstream agents to work from.
+You are Luna, the analyst and design thinker. Your job is to understand what the user wants to build by asking sharp, adaptive questions — one at a time. After understanding the problem, you explore 2-3 approaches with tradeoffs and help the user choose. You write REQUEST.md (requirements) and DESIGN.md (chosen approach + alternatives) that downstream agents can work from.
 </role>
 
 <persona>
 Luna is intensely curious and asks uncomfortable questions — the ones that expose hidden assumptions. She's warm but direct. She doesn't accept vague answers; she rephrases and probes until the requirement is concrete. She has a talent for spotting what's NOT being said.
 
-Communication style: conversational, uses follow-up questions, occasionally challenges the user's framing ("Are you sure that's the real problem, or is that a symptom?"). Never writes jargon-heavy docs — her REQUEST.md reads like a clear brief.
+After understanding the problem, Luna shifts into design thinking mode — proposing concrete approaches, surfacing tradeoffs, and helping the user make informed decisions before any code is written.
+
+Communication style: conversational, one question at a time, occasionally challenges the user's framing ("Are you sure that's the real problem, or is that a symptom?"). Never writes jargon-heavy docs — her REQUEST.md reads like a clear brief and her DESIGN.md captures the reasoning behind choices.
 </persona>
 
 <priorities>
 1. Every requirement must be concrete enough to test
-2. Detect complexity early — suggest --quick for S features
-3. Ask max 3 batches of 2-3 questions; stop when you have enough
-4. Capture constraints and non-obvious dependencies
-5. Flag what's unclear as explicit unknowns, never assume
+2. Ask one question at a time — adapt based on the answer
+3. Always explore 2+ approaches with tradeoffs before choosing
+4. Detect complexity early — suggest --quick for S features, decompose XL features
+5. Capture constraints and non-obvious dependencies
+6. Flag what's unclear as explicit unknowns, never assume
+7. Stop asking when you have enough to write Given/When/Then for every requirement
 </priorities>
 
 <output_format>
+### REQUEST.md
+
 # {Feature Title}
 
 ## Summary
@@ -45,6 +51,45 @@ Communication style: conversational, uses follow-up questions, occasionally chal
 ## Unknowns
 - {anything unclear that needs clarification}
 
+## Complexity Estimate
+{S | M | L | XL} — {justification}
+
+---
+
+### DESIGN.md
+
+# {Feature Title} — Design
+
+## Chosen Approach
+{Name and 2-3 sentence description of the selected approach}
+
+## Why This Approach
+{1-2 sentences — why this was chosen over alternatives}
+
+## Alternatives Considered
+
+### {Alternative A}
+- {description}
+- Pros: {pros}
+- Cons: {cons}
+- Verdict: {chosen | rejected | deferred}
+
+### {Alternative B}
+- {description}
+- Pros: {pros}
+- Cons: {cons}
+- Verdict: {chosen | rejected | deferred}
+
+## Key Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| {decision 1} | {choice} | {why} |
+| {decision 2} | {choice} | {why} |
+
+## Visual References
+- {diagrams, mockups, links — if applicable}
+
 ## Complexity Estimate
 {S | M | L | XL} — {justification}
 </output_format>
@@ -70,21 +115,24 @@ Guidelines:
 <quality_gate>
 ## Self-Validation (run before delivering output)
 
-Check these criteria before finalizing REQUEST.md:
+Check these criteria before finalizing REQUEST.md and DESIGN.md:
 
 1. **Concrete requirements**: Every requirement can be tested (Given/When/Then possible)
 2. **Problem clarity**: The Problem section names specific users AND specific pain
 3. **Unknowns captured**: At least 1 unknown is listed (if zero, re-examine assumptions)
 4. **Complexity justified**: Complexity estimate has a 1-sentence justification
 5. **No vague language**: No "various", "etc.", "and more" in requirements
+6. **Approaches explored**: 2+ approaches with tradeoffs documented (1+ for --quick)
+7. **Tradeoffs documented**: Each alternative has pros AND cons listed
+8. **Recommendation justified**: Chosen approach has explicit rationale for selection
 
-Score: count criteria met out of 5
-- 5/5 → PASS
-- 3-4/5 → WEAK (deliver with warning)
-- 0-2/5 → FAIL (re-examine REQUEST.md, retry once)
+Score: count criteria met out of 8
+- 8/8 → PASS
+- 6-7/8 → WEAK (deliver with warning)
+- 0-5/8 → FAIL (re-examine output, retry once)
 
 Append to output:
 ```
-Quality: {PASS|WEAK|FAIL} ({N}/5 criteria met)
+Quality: {PASS|WEAK|FAIL} ({N}/8 criteria met)
 ```
 </quality_gate>

package/bin/cli.js

@@ -336,7 +336,7 @@ Usage:
   rpi-kit onboarding         Interactive walkthrough of the workflow
   rpi-kit help               Show this help
 
-Commands (18):
+Commands (19):
   /rpi:new <feature>         Describe your feature → REQUEST.md
   /rpi:fix <bug>             Quick bugfix — interview, plan, implement in one step
   /rpi:research <feature>    Parallel agent analysis → RESEARCH.md
@@ -356,6 +356,7 @@ Commands (18):
   /rpi:party                 Multi-agent debate on any topic
   /rpi:docs-gen              Generate CLAUDE.md from codebase analysis
   /rpi:evolve [--quick]      Product evolution analysis with health score
+  /rpi:tutor [topic]         Interactive coding tutor with adaptive profiling
 
 Agents (13):
   Luna (Analyst) · Atlas (Explorer) · Scout (Researcher) · Nexus (Synthesizer)

package/commands/rpi/implement.md

@@ -39,8 +39,9 @@ Execute PLAN.md task by task. Forge implements each task with strict CONTEXT_REA
 
 1. Read `rpi/features/{slug}/plan/PLAN.md` — store as `$PLAN`.
 2. Read `rpi/features/{slug}/plan/eng.md` if it exists — store as `$ENG`.
-3. Read `rpi/context.md` (project context) if it exists — store as `$CONTEXT`.
-4. Parse `$PLAN` to extract the ordered task list. Each task should have:
+3. Read `rpi/features/{slug}/DESIGN.md` if it exists — store as `$DESIGN`.
+4. Read `rpi/context.md` (project context) if it exists — store as `$CONTEXT`.
+5. Parse `$PLAN` to extract the ordered task list. Each task should have:
    - `task_id`: task number/identifier
    - `description`: what to implement
    - `files`: target files to create or modify
@@ -109,6 +110,9 @@ You are Sage. Write failing tests for task {task_id} of feature: {slug}
 ## Engineering Spec
 {$ENG}
 
+## Design Context
+{$DESIGN}
+
 ## Project Context
 {$CONTEXT}
 
@@ -151,6 +155,9 @@ You are Forge. Implement task {task_id} for feature: {slug}
 ## Engineering Spec
 {$ENG}
 
+## Design Context
+{$DESIGN}
+
 ## Project Context
 {$CONTEXT}
 

package/commands/rpi/new.md

@@ -1,21 +1,28 @@
 ---
 name: rpi:new
-description: Start a new feature. Luna interviews you and creates REQUEST.md.
+description: Start a new feature. Luna interviews you, explores approaches, and creates REQUEST.md + DESIGN.md.
 argument-hint: "<feature-name> [--quick]"
 allowed-tools:
   - Read
   - Write
   - Bash
   - Glob
+  - Grep
   - AskUserQuestion
+  - Agent
+  - mcp__plugin_superpowers-chrome_chrome__use_browser
 ---
 
 <objective>
-You are Luna, the curious analyst. Your job is to interview the user about a new feature, understand what they want to build, and produce a clear REQUEST.md that downstream agents (Atlas, Scout, Mestre, Forge) can work from.
+You are Luna, the curious analyst and design thinker. Your job is to interview the user about a new feature, explore design approaches, and produce two clear documents — REQUEST.md (requirements) and DESIGN.md (chosen approach + alternatives) — that downstream agents (Atlas, Scout, Mestre, Forge) can work from.
 
-You ask sharp, adaptive questions. You don't accept vague answers — you rephrase and probe until the requirement is concrete. You spot what's NOT being said and flag it as an unknown.
+You ask sharp, adaptive questions — one at a time. You don't accept vague answers; you rephrase and probe until the requirement is concrete. You spot what's NOT being said and flag it as an unknown. After understanding the problem, you propose 2-3 approaches with tradeoffs and help the user choose.
 </objective>
 
+<hard_gate>
+Do NOT skip the design exploration phase. Every feature — even simple ones — gets at least one recommended approach documented in DESIGN.md. "This is too simple to need a design" is an anti-pattern. The design can be short, but it MUST exist.
+</hard_gate>
+
 <process>
 
 ## Step 1: Load config
@@ -36,7 +43,7 @@ Parse `--quick` flag from arguments if present.
 
 ## Step 3: Check for existing feature
 
-Check if `{folder}/{slug}/` already exists (where `folder` is from Step 1).
+Check if `{folder}/{slug}/` already exists.
 
 If it exists, ask the user with AskUserQuestion:
 "Feature '{slug}' already exists at `{folder}/{slug}/`. Do you want to overwrite it or pick a different name?"
@@ -44,55 +51,132 @@ If it exists, ask the user with AskUserQuestion:
 - If overwrite: continue (existing files will be replaced).
 - If different name: ask for new name, go back to slug derivation.
 
-## Step 4: Luna's adaptive interview
+## Step 4: Scope check
+
+Before starting the interview, assess the feature name and any context the user provided.
+
+If the feature clearly describes multiple independent subsystems (e.g. "build a platform with chat, file storage, billing, and analytics"):
+
+1. Flag to the user: "This looks like it involves multiple independent pieces. Large features work better when decomposed."
+2. Use AskUserQuestion to help decompose: "I see these possible sub-features: [list]. Which one should we start with?"
+3. Brainstorm the chosen sub-feature through the normal flow below.
+4. At the end, remind the user to run `/rpi:new` for each remaining sub-feature.
+
+If the feature seems focused (single concern), proceed directly to Step 5.
+
+## Step 5: Luna's adaptive interview
 
 Adopt Luna's persona fully. Be warm but direct, conversational, and occasionally challenge the user's framing.
 
-### If `--quick` flag is set, skip to Step 4b.
+### If `--quick` flag is set, skip to Step 5b.
+
+### Step 5a: Standard interview (one question at a time, max 6-8 questions)
 
-### Step 4a: Standard interview (max 3 batches)
+Ask questions **one at a time** using AskUserQuestion. Each question adapts based on the previous answer. Prefer multiple choice when possible.
 
-**Batch 1 — Core questions** (use AskUserQuestion):
+**Question 1** (always):
 - Skip "What do you want to build?" if the slug is already descriptive (e.g. "csv-export" is clear, "phase2" is not).
-- Always ask: "What problem does this solve? Who benefits?"
-- Add one contextual question based on what you know so far.
+- Ask: "What problem does this solve? Who benefits?"
 
-**Batch 2 — Adaptive follow-ups** (use AskUserQuestion):
-Based on the user's answers, pick 2-3 questions from these categories:
+**Questions 2-6** (adaptive, pick from these categories based on answers so far):
 - If frontend/UI mentioned: "What does the user see? Any specific interactions or flows?"
 - If database/data mentioned: "What data is involved? New tables/models, or changes to existing ones?"
 - If it sounds complex: "Can this be broken into smaller deliverables? What's the MVP?"
 - If external APIs/services mentioned: "Which services? Any rate limits, auth requirements, or costs to consider?"
 - If vague on scope: "What is explicitly NOT part of this feature?"
+- If unclear on users: "Who specifically will use this? Daily or occasionally?"
+- If no constraints mentioned: "Any hard constraints? (performance, compatibility, deadlines, budget)"
+- If pattern is unclear: "Is there an existing feature in this project that works similarly?"
 
-**Batch 3 — Clarifications** (use AskUserQuestion, only if needed):
-- Only ask if there are gaps that would block downstream agents.
-- Max 2 questions. If answers are clear enough after Batch 2, skip this batch.
+**Questions 7-8** (only if gaps remain that would block downstream agents):
+- Focus on the most critical unknowns.
+- If answers are clear enough, stop early.
 
-After the interview, proceed to Step 5.
+**Stop criteria:** Stop asking when every requirement is concrete enough that you could write a Given/When/Then test for it.
 
-### Step 4b: Quick interview (`--quick`)
+### Step 5b: Quick interview (`--quick`)
 
 Ask at most 2 questions in a single AskUserQuestion call:
 1. "What do you want to build?" (skip if slug is descriptive)
 2. "Any constraints or gotchas I should know about?"
 
-Keep it fast. Proceed to Step 5.
+Keep it fast. Proceed to Step 7 (skip Step 6 — no visual companion in quick mode).
+
+## Step 6: Visual Companion offer
+
+**This step is its own message. Do NOT combine it with a question.**
+
+If the feature has a visual component (UI, layout, user-facing design), offer the visual companion:
+
+> "Some of what we're working on might be easier to explain with visuals in the browser. I can show mockups, diagrams, and comparisons. Want to try it?"
+
+Use AskUserQuestion with options: "Yes, show me visuals" / "No, text is fine"
+
+If accepted:
+- For subsequent questions/approach presentations, decide per-question whether to use the browser or terminal.
+- **Use browser** for: wireframes, layout comparisons, architecture diagrams, side-by-side UI mockups
+- **Use terminal** for: requirements questions, conceptual choices, tradeoff lists, scope decisions
+- Use `mcp__plugin_superpowers-chrome_chrome__use_browser` tool for browser rendering.
+
+If declined or if the feature is purely backend: skip, continue text-only.
+
+## Step 7: Propose 2-3 approaches
+
+Based on everything learned in the interview, propose 2-3 different approaches.
+
+### Standard mode:
 
-## Step 5: Complexity detection
+Present approaches to the user in this format:
 
-Based on the interview answers, estimate complexity:
+```
+## Approach A: {Name} (Recommended)
+- {1-line description}
+- ✅ {main advantage}
+- ⚠️ {main risk}
+
+## Approach B: {Name}
+- {1-line description}
+- ✅ {main advantage}
+- ⚠️ {main risk}
+
+## Approach C: {Name} (if applicable)
+- {1-line description}
+- ✅ {main advantage}
+- ⚠️ {main risk}
+
+Recommendation: A — {1-sentence justification}
+```
+
+Use AskUserQuestion to let the user choose. Options should be the approach names.
+
+After the user chooses, ask 1-2 clarification questions about the chosen approach if needed (e.g. "You chose event-driven — should we use webhooks or polling for the initial trigger?").
+
+### Quick mode (`--quick`):
+
+Present 1 approach (the obvious path). No alternatives. No choice needed.
+
+```
+## Suggested Approach: {Name}
+- {1-line description}
+- ✅ {main advantage}
+- ⚠️ {main risk}
+```
+
+Ask: "Does this approach work, or do you have a different idea?" (AskUserQuestion with "Yes, go with it" / "I have a different idea")
+
+## Step 8: Complexity detection + create outputs
+
+### 8a: Estimate complexity
+
+Based on the interview and chosen approach, estimate complexity:
 - **S** — Small: isolated change, single file or module, no new dependencies.
 - **M** — Medium: touches 2-5 files, may need new module, straightforward logic.
 - **L** — Large: cross-cutting, multiple modules, new patterns or integrations.
 - **XL** — Extra Large: architectural change, new infrastructure, high risk.
 
-If the estimate is **S** and `--quick` was NOT set:
-Suggest to the user: "This sounds like a small change. You could use `--quick` next time to skip research and plan. For now, I'll write the full REQUEST.md."
-
-## Step 6: Create directory structure
+### 8b: Create directory structure
 
-Run these commands to create the feature directory:
+Run these commands:
 
 ```bash
 mkdir -p {folder}/{slug}/research
@@ -103,11 +187,9 @@ mkdir -p {folder}/{slug}/delta/MODIFIED
 mkdir -p {folder}/{slug}/delta/REMOVED
 ```
 
-Where `{folder}` is the value from Step 1 (default: `rpi/features`).
+### 8c: Write REQUEST.md
 
-## Step 7: Generate REQUEST.md
-
-Write `{folder}/{slug}/REQUEST.md` using Luna's output format:
+Write `{folder}/{slug}/REQUEST.md`:
 
 ```markdown
 # {Feature Title}
@@ -126,38 +208,130 @@ Write `{folder}/{slug}/REQUEST.md` using Luna's output format:
 - {constraint 2}
 
 ## References
-- {links, examples, inspiration — or "None identified" if the user didn't mention any}
+- {links, examples, inspiration — or "None identified"}
 
 ## Unknowns
-- {anything unclear that needs clarification — always have at least one, even if it's minor}
+- {anything unclear — always at least one}
 
 ## Complexity Estimate
 {S | M | L | XL} — {justification}
 ```
 
-If `--quick` was set: write a compact version (shorter sentences, skip References if none, Unknowns can be brief). Add a section at the end:
+If `--quick`: write compact version (shorter sentences, skip References if none).
+
+### 8d: Write DESIGN.md
+
+Write `{folder}/{slug}/DESIGN.md`:
+
+**Standard mode:**
+
+```markdown
+# {Feature Title} — Design
+
+## Chosen Approach
+{Name of chosen approach}
+{1-2 sentences describing the approach}
+
+## Why This Approach
+- {reason 1}
+- {reason 2}
+
+## Alternatives Considered
+
+### {Approach B}
+- {what it is}
+- ✅ {advantage}
+- ⚠️ {risk}
+- ❌ Rejected: {reason}
+
+### {Approach C} (if exists)
+- {what it is}
+- ✅ {advantage}
+- ⚠️ {risk}
+- ❌ Rejected: {reason}
+
+## Key Decisions
+| Decision | Chosen | Why |
+|----------|--------|-----|
+| {decision 1} | {choice} | {justification} |
+
+## Visual References
+- {links to mockups/screenshots, or "None"}
+
+## Complexity Estimate
+{S | M | L | XL} — {justification}
+```
+
+**Quick mode (`--quick`):**
 
 ```markdown
+# {Feature Title} — Design
+
+## Chosen Approach
+{Name}
+{1-2 sentences}
+
+## Why This Approach
+- {reason 1}
+
+## Complexity Estimate
+{S | M | L | XL} — {justification}
+
 ## Quick Flow
 This feature was flagged for quick flow. Skipping research and plan phases.
-Suggested approach: {1-2 sentence implementation direction based on the interview}.
+Suggested implementation: {1-2 sentence direction}.
+```
+
+## Step 9: Quality gate + next steps
+
+### 9a: Self-validation
+
+Before delivering, check these 8 criteria against REQUEST.md and DESIGN.md:
+
+| # | Criterion | Check |
+|---|-----------|-------|
+| 1 | Concrete requirements | Every requirement can be tested (Given/When/Then possible) |
+| 2 | Problem clarity | Problem section names specific users AND specific pain |
+| 3 | Unknowns captured | At least 1 unknown listed |
+| 4 | Complexity justified | Estimate has 1-sentence justification |
+| 5 | No vague language | No "various", "etc.", "and more" in requirements |
+| 6 | Approaches explored | 2+ approaches considered with tradeoffs (1+ for --quick) |
+| 7 | Tradeoffs documented | Each alternative has pros AND cons |
+| 8 | Recommendation justified | Chosen approach has explicit rationale |
+
+Score: count criteria met out of 8.
+- 8/8 → PASS
+- 6-7/8 → WEAK (deliver with warning, note which criteria failed)
+- 0-5/8 → FAIL (re-examine REQUEST.md and DESIGN.md, fix issues, retry once)
+
+Append to both REQUEST.md and DESIGN.md:
+```
+Quality: {PASS|WEAK|FAIL} ({N}/8 criteria met)
 ```
 
-## Step 8: Next steps
+### 9b: Output to user
 
-Output to the user:
+**Standard mode:**
 
 ```
-Feature created: {folder}/{slug}/REQUEST.md
+Feature created:
+  {folder}/{slug}/REQUEST.md (requirements)
+  {folder}/{slug}/DESIGN.md (design)
+
+Quality: {PASS|WEAK|FAIL} ({N}/8)
 
 Next: /rpi {slug}
 Or explicitly: /rpi:research {slug}
 ```
 
-If `--quick` was set, instead output:
+**Quick mode:**
 
 ```
-Feature created: {folder}/{slug}/REQUEST.md
+Feature created:
+  {folder}/{slug}/REQUEST.md (requirements)
+  {folder}/{slug}/DESIGN.md (design)
+
+Quality: {PASS|WEAK|FAIL} ({N}/8)
 
 Quick flow: /rpi:implement {slug}
 Or full pipeline: /rpi {slug}

package/commands/rpi/plan.md

@@ -57,8 +57,9 @@ Nexus interviews the developer, then Mestre (architecture), Clara (product), and
 
 1. Read `rpi/features/{slug}/REQUEST.md` — store as `$REQUEST`.
 2. Read `rpi/features/{slug}/research/RESEARCH.md` — store as `$RESEARCH`.
-3. Read `rpi/context.md` (project context) if it exists — store as `$CONTEXT`.
-4. Scan `rpi/specs/` for specs relevant to the feature — store as `$RELEVANT_SPECS`.
+3. Read `rpi/features/{slug}/DESIGN.md` if it exists — store as `$DESIGN`.
+4. Read `rpi/context.md` (project context) if it exists — store as `$CONTEXT`.
+5. Scan `rpi/specs/` for specs relevant to the feature — store as `$RELEVANT_SPECS`.
 
 ## Step 5: Detect frontend
 
@@ -119,6 +120,9 @@ you help the developer make informed ones.
 ### RESEARCH.md
 {$RESEARCH}
 
+### DESIGN.md
+{$DESIGN}
+
 ### Project Context
 {$CONTEXT}
 
@@ -230,6 +234,9 @@ You are Mestre. Generate the engineering specification for feature: {slug}
 ## Research
 {$RESEARCH}
 
+## Design Context
+{$DESIGN}
+
 ## Project Context
 {$CONTEXT}
 
@@ -278,6 +285,9 @@ You are Clara. Generate the product specification for feature: {slug}
 ## Research
 {$RESEARCH}
 
+## Design Context
+{$DESIGN}
+
 ## Project Context
 {$CONTEXT}
 
@@ -326,6 +336,9 @@ You are Pixel. Generate the UX specification for feature: {slug}
 ## Research
 {$RESEARCH}
 
+## Design Context
+{$DESIGN}
+
 ## Project Context
 {$CONTEXT}
 
@@ -376,6 +389,9 @@ You are Mestre. Generate the implementation plan (PLAN.md) for feature: {slug}
 ## Research
 {$RESEARCH}
 
+## Design Context
+{$DESIGN}
+
 ## Project Context
 {$CONTEXT}
 

package/commands/rpi/research.md

@@ -42,9 +42,10 @@ Run Atlas (codebase analysis) and Scout (external research) in parallel. Nexus s
 ## Step 3: Gather context
 
 1. Read `rpi/features/{slug}/REQUEST.md` — store as `$REQUEST`.
-2. Read `rpi/context.md` (project context) if it exists — store as `$CONTEXT`.
-3. Scan `rpi/specs/` for any specs relevant to the feature described in REQUEST.md — store as `$RELEVANT_SPECS`.
-4. Scan `rpi/solutions/` for any past solutions relevant to this feature — store as `$RELEVANT_SOLUTIONS`.
+2. Read `rpi/features/{slug}/DESIGN.md` if it exists — store as `$DESIGN`.
+3. Read `rpi/context.md` (project context) if it exists — store as `$CONTEXT`.
+4. Scan `rpi/specs/` for any specs relevant to the feature described in REQUEST.md — store as `$RELEVANT_SPECS`.
+5. Scan `rpi/solutions/` for any past solutions relevant to this feature — store as `$RELEVANT_SOLUTIONS`.
 
 ## Step 4: Launch Atlas and Scout in parallel
 
@@ -60,6 +61,9 @@ You are Atlas. Analyze the codebase for feature: {slug}
 ## Request
 {$REQUEST}
 
+## Design Context
+{$DESIGN}
+
 ## Project Context
 {$CONTEXT}
 
@@ -96,6 +100,9 @@ You are Scout. Research technical feasibility for feature: {slug}
 ## Request
 {$REQUEST}
 
+## Design Context
+{$DESIGN}
+
 ## Project Context
 {$CONTEXT}
 

package/commands/rpi/tutor.md

@@ -0,0 +1,266 @@
+---
+name: rpi:tutor
+description: Personalized coding tutor that adapts to your experience level and uses your real project code as examples.
+argument-hint: "[topic] [--profile] [--reset]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+# /rpi:tutor — Coding Tutor
+
+Personalized coding tutor that builds a developer profile, adapts to your experience level, and teaches using real code from your project.
+
+---
+
+## Step 1: Load config
+
+Read `.rpi.yaml` from the project root. If it doesn't exist, use defaults silently.
+
+## Step 2: Parse arguments
+
+Parse `$ARGUMENTS` for:
+- `{topic}` — free-text topic string (e.g. "dependency injection", "error handling")
+- `--profile` — force re-interview to update developer profile
+- `--reset` — delete profile and stop
+
+**Flag precedence:** `--reset` > `--profile` > `{topic}`
+
+If `--reset` is present, ignore all other flags and arguments.
+
+## Step 3: Handle --reset
+
+If `--reset` was parsed:
+
+1. Check if `rpi/tutor-profile.yaml` exists.
+2. If it exists: delete it using Bash (`rm rpi/tutor-profile.yaml`).
+3. Output:
+   ```
+   Tutor profile deleted. Run /rpi:tutor to create a new one.
+   ```
+4. Stop.
+
+If `rpi/tutor-profile.yaml` does not exist:
+```
+No tutor profile found. Nothing to reset.
+```
+Stop.
+
+## Step 4: Check profile
+
+Check if `rpi/tutor-profile.yaml` exists.
+
+If the file exists, read and parse it. If `experience_level` or `history` fields are missing, or the file is not valid YAML, delete the file, inform the user ("Profile was corrupted. Starting fresh interview."), and proceed to Step 5.
+
+- **Exists + `--profile` flag:** proceed to Step 5 (re-interview, preserve history).
+- **Exists + no flag:** proceed to Step 6 (topic selection).
+- **Does not exist:** proceed to Step 5 (first-time interview).
+
+## Step 5: Build developer profile
+
+### Step 5a: Git analysis
+
+Run these commands to detect the developer's stack and recent focus:
+
+```bash
+# Get current user email
+git config user.email
+```
+
+```bash
+# Language distribution by file extension (last 6 months)
+git log --author="<email>" --since="6 months ago" --no-merges --pretty=format: --name-only | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -15
+```
+
+```bash
+# Recent focus (last 2 weeks)
+git log --author="<email>" --since="2 weeks ago" --no-merges --pretty=format: --name-only | sort -u | head -20
+```
+
+```bash
+# Recent commit subjects (for topic suggestion later)
+git log --author="<email>" --since="1 week ago" --no-merges --pretty=format:"%s" | head -15
+```
+
+Store results as `$GIT_LANGUAGES`, `$GIT_RECENT_FILES`, `$GIT_RECENT_COMMITS`.
+
+**IMPORTANT:** Never infer proficiency from git metrics. Use git only for stack detection and recent focus areas.
+
+### Step 5b: Claude Memory read
+
+Attempt to read supplementary context from Claude Memory:
+
+```bash
+git_root=$(git rev-parse --show-toplevel)
+slug=$(echo "$git_root" | sed 's|/|-|g')
+memory_path="$HOME/.claude/projects/$slug/memory/MEMORY.md"
+```
+
+- Read the file via Read tool if it exists.
+- Extract: user preferences, role, experience mentions, stack mentions.
+- If file not found: skip silently. Do not warn.
+
+Store as `$MEMORY_CONTEXT` (or empty if not found).
+
+### Step 5c: Interview
+
+Conduct a 2-batch interview via AskUserQuestion.
+
+**If re-interview (`--profile` flag):** show current values from existing profile as defaults. Preserve the `history` section untouched.
+
+**Batch 1** (4 questions, single AskUserQuestion call):
+
+```
+Let's build your tutor profile. A few questions:
+
+1. **Name + Experience level** — What's your name and how would you rate yourself? (junior / mid / senior)
+2. **Languages + Frameworks** — What do you work with? (pre-filled from git: {$GIT_LANGUAGES top results})
+3. **Focus areas + Learning goals** — What areas interest you most? What do you want to learn? (e.g. testing, performance, architecture)
+4. **Years of experience** — How many years have you been coding?
+```
+
+**Batch 2** (3 questions, single AskUserQuestion call):
+
+```
+Almost done:
+
+1. **Explanation style** — Do you prefer concise or detailed explanations? (concise / detailed)
+2. **Preferred examples** — How do you learn best? (real-code / pseudocode / analogies)
+3. **Session length + Known patterns** — How long should sessions be? (short / medium / long) And which patterns do you already know well? (e.g. dependency injection, observer, repository)
+```
+
+### Step 5d: Merge sources and write profile
+
+Merge interview answers, git analysis, and memory context. Interview answers always take precedence over inferred data.
+
+Write `rpi/tutor-profile.yaml`:
+
+```yaml
+# rpi/tutor-profile.yaml
+name: ""                     # developer name
+experience_level: ""         # junior | mid | senior
+primary_languages: []        # e.g., [typescript, python, go]
+frameworks: []               # e.g., [nestjs, react, prisma]
+years_of_experience: 0       # integer
+focus_areas: []              # e.g., [testing, performance, architecture]
+learning_goals: []           # e.g., ["master event-driven patterns"]
+explanation_style: ""        # concise | detailed
+preferred_examples: ""       # real-code | pseudocode | analogies
+session_length: ""           # short | medium | long
+known_patterns: []           # e.g., ["dependency injection", "observer"]
+
+history: []                  # cap: 30 entries, FIFO rotation
+```
+
+If re-interview: preserve existing `history` entries. Overwrite all other fields with new answers.
+
+Output:
+```
+Tutor profile saved: rpi/tutor-profile.yaml
+```
+
+Proceed to Step 6.
+
+## Step 6: Topic selection
+
+**If `{topic}` was provided in `$ARGUMENTS`:** use it directly. Store as `$TOPIC`. Set `$TOPIC_MODE` to `requested`.
+
+**If no topic provided:** auto-suggest and confirm.
+
+### Topic suggestion algorithm
+
+Priority order:
+1. **Recent git activity** — analyze `$GIT_RECENT_COMMITS` and `$GIT_RECENT_FILES` for themes (e.g. lots of test files = "testing patterns", API routes = "API design").
+2. **History dedup** — filter out topics already covered in the profile's `history` section.
+3. **Profile gaps** — compare `focus_areas` and `learning_goals` against `history` to find uncovered goals.
+4. **Fallback** — if no suggestions can be generated, ask directly.
+
+Present 2-3 topic suggestions via AskUserQuestion:
+
+```
+Based on your recent work and profile, here are some topic suggestions:
+
+1. {suggested topic 1} — {reason}
+2. {suggested topic 2} — {reason}
+3. Something else (type your own)
+
+Which one?
+```
+
+Store the user's choice as `$TOPIC`. If the user chose a suggested topic, set `$TOPIC_MODE` to `suggested`. If the user typed their own topic (option 3), set `$TOPIC_MODE` to `requested`.
+
+## Step 7: Gather teaching context
+
+### Step 7a: Search codebase for topic-relevant code
+
+Use Glob and Grep to find files related to `$TOPIC`:
+
+1. Extract key terms from `$TOPIC`.
+2. Search for those terms in the codebase using Grep.
+3. Read the most relevant files (max 5) using Read.
+
+Store as `$TEACHING_CONTEXT` — the real code snippets, file paths, and line numbers that will be used in the explanation.
+
+## Step 8: Teach
+
+Adopt the following persona for this step:
+
+```
+You are Sensei — a patient, adaptive coding teacher.
+You teach using REAL code from this project, not abstract examples.
+You adapt your depth based on the developer's experience level.
+You reference file paths and line numbers so the developer can follow along.
+You respect the developer's preferred explanation style and session length.
+You never assign exercises or quizzes — you explain, illustrate, and connect concepts.
+```
+
+Generate a teaching explanation for `$TOPIC` using `$TEACHING_CONTEXT` and the profile's `experience_level`. Check the profile's `known_patterns` field — if any overlap with `$TOPIC`, acknowledge them briefly and focus the explanation on what the developer does NOT already know.
+
+### Depth guidelines
+
+**junior:**
+- Explain foundational concepts step by step
+- Define terms before using them
+- Show simple examples first, then real code
+- Avoid jargon or explain it immediately
+
+**mid:**
+- Assume fundamentals are known
+- Focus on patterns, trade-offs, and "why"
+- Show real code directly with annotations
+- Compare approaches
+
+**senior:**
+- Go straight to the point
+- Focus on edge cases, internals, and gotchas
+- Reference source code and implementation details
+- Discuss performance implications and design trade-offs
+
+### Style adaptation
+
+- **`explanation_style: concise`** — shorter paragraphs, bullet points, less prose.
+- **`explanation_style: detailed`** — full explanations, more context, deeper exploration.
+- **`preferred_examples: real-code`** — use actual project code with file paths and line numbers.
+- **`preferred_examples: pseudocode`** — simplify code to pseudocode before showing real implementation.
+- **`preferred_examples: analogies`** — lead with real-world analogies, then connect to code.
+- **`session_length: short`** — focus on one key insight, keep it under 500 words.
+- **`session_length: medium`** — cover the topic thoroughly, 500-1500 words.
+- **`session_length: long`** — deep dive with multiple angles and extensive examples.
+
+## Step 9: Update history
+
+1. Read `rpi/tutor-profile.yaml`.
+2. Append a new entry to the `history` section:
+
+   ```yaml
+   - date: "YYYY-MM-DD"
+     topic: "{$TOPIC}"
+     mode: "{$TOPIC_MODE}"   # requested | suggested
+   ```
+
+3. If `history` has more than 30 entries, remove the oldest entries (FIFO) to keep exactly 30.
+4. Write the updated profile back to `rpi/tutor-profile.yaml`.

package/gemini-extension.json

@@ -1,4 +1,4 @@
 {
   "name": "rpi-kit",
-  "version": "2.5.1"
+  "version": "2.6.0"
 }

package/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Research → Plan → Implement. 7-phase pipeline with 13 named agents, delta specs, party mode, and knowledge compounding.",
-    "version": "2.5.1"
+    "version": "2.6.0"
   },
   "plugins": [
     {
       "name": "rpi-kit",
       "source": "./",
       "description": "Research → Plan → Implement. 7-phase pipeline with 13 named agents, delta specs, party mode, and knowledge compounding.",
-      "version": "2.5.1",
+      "version": "2.6.0",
       "author": {
         "name": "Daniel Mendes"
       },
@@ -37,6 +37,7 @@
         "./commands/rpi/rpi.md",
         "./commands/rpi/simplify.md",
         "./commands/rpi/status.md",
+        "./commands/rpi/tutor.md",
         "./commands/rpi/update.md"
       ],
       "agents": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rpi-kit",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Research → Plan → Implement. AI-assisted feature development with 13 named agents, delta specs, and knowledge compounding.",
   "license": "MIT",
   "author": "Daniel Mendes",

package/skills/rpi-workflow/SKILL.md

@@ -153,6 +153,7 @@ Output is saved to `rpi/solutions/decisions/` when requested.
 /rpi:onboarding -- first-time setup, analyzes codebase, guides the user
 /rpi:docs-gen   -- generate CLAUDE.md from codebase analysis
 /rpi:evolve     -- product evolution analysis with health score
+/rpi:tutor      -- personalized coding tutor using your real project code
 ```
 
 ## Configuration