rpi-kit 1.1.0 → 1.2.0

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

@@ -38,6 +38,8 @@ You follow the RPI (Research → Plan → Implement) workflow for feature develo
 - `/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
 
@@ -60,6 +62,7 @@ You follow the RPI (Research → Plan → Implement) workflow for feature develo
 | 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
 

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>

package/commands/rpi/implement.md

@@ -1,7 +1,7 @@
 ---
 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]"
+argument-hint: "<feature-slug> [--sequential|--parallel] [--skip-simplify] [--skip-review] [--resume] [--from-task <id>]"
 allowed-tools:
   - Read
   - Write
@@ -29,6 +29,7 @@ Parse `$ARGUMENTS`:
 - `--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
+- `--from-task {id}`: resume from a specific task ID (used with --resume)
 
 ## 2. Validate prerequisites
 
@@ -39,20 +40,70 @@ Plan not found. Run /rpi:plan {feature-slug} first.
 
 Also read eng.md (and pm.md, ux.md if they exist) for full context.
 
+## 2b. Detect session isolation tier
+
+Read `session_isolation` from `.rpi.yaml` (default: `auto`).
+
+If `session_isolation: off`, skip all isolation logic. Use current behavior.
+
+If `session_isolation: aggressive`, set tier = 3 and max_tasks = 3.
+
+If `session_isolation: auto`:
+1. Read `## Metadata` section from PLAN.md
+2. Extract `suggested_tier` and `context_weight`
+3. If metadata section missing (old plans), compute from tasks:
+   - Count tasks, unique files, max dependency depth
+   - Calculate context_weight
+4. Recalculate plan_hash from current file contents:
+   ```bash
+   cat {sorted existing files from PLAN.md tasks} | shasum -a 256 | cut -d' ' -f1
+   ```
+5. Compare with `plan_hash` from metadata. If different:
+   ```
+   Codebase has changed since planning.
+   Changed files: {list files where content differs}
+   Options:
+   - Continue anyway (changes may be compatible)
+   - Re-plan: /rpi:plan {feature-slug} --force
+   - Review changes manually
+   ```
+   Use AskUserQuestion to let user decide.
+6. Set tier and max_tasks_per_session based on context_weight:
+   - Tier 1 (weight <= 8): max_tasks = unlimited
+   - Tier 2 (weight 9-18): max_tasks = config value or 5
+   - Tier 3 (weight > 18): max_tasks = config value or 4
+
+Inform user:
+```
+Session isolation: Tier {N} (context weight: {weight})
+{Tier 1: "Single session — no checkpoints needed"}
+{Tier 2: "Session warning after {max_tasks} tasks"}
+{Tier 3: "Forced checkpoints after each wave"}
+```
+
 ## 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}"
+1. Read all files in `{folder}/{feature-slug}/implement/checkpoints/`
+2. Parse each checkpoint: extract task_id and status
+3. Build completed set from checkpoints where status == "done"
+4. If `--from-task {id}` specified, resume from that task
+5. Otherwise, find first uncompleted task in PLAN.md order
+6. Count completed tasks to determine session task counter start
+7. Inform user: "Resuming from task {id}: {name} ({completed}/{total} done)"
 
 If IMPLEMENT.md exists and no `--resume`:
 - Ask user: "Implementation in progress ({N}/{total} tasks). Resume or restart?"
 
-## 4. Initialize IMPLEMENT.md
+## 4. Initialize implementation directory
 
-If starting fresh, create `{folder}/{feature-slug}/implement/IMPLEMENT.md`:
+If starting fresh:
+```bash
+mkdir -p {folder}/{feature-slug}/implement/checkpoints
+mkdir -p {folder}/{feature-slug}/implement/sessions
+```
+
+Create `{folder}/{feature-slug}/implement/IMPLEMENT.md`:
 
 ```markdown
 # Implementation: {Feature Title}
@@ -88,141 +139,240 @@ Otherwise, use smart default:
 
 ## 6. Execute tasks
 
-### Single agent mode:
+Initialize session task counter: `tasks_this_session = 0`
 
-For each task in order (respecting dependencies):
+### 6a. Agent prompt template (all tiers)
 
-1. Read PLAN.md task details (files, deps, test spec if present)
-2. Read eng.md for technical context
+For each task, construct the agent prompt:
+
+```
+You are the plan-executor agent for the RPI workflow.
+
+## Pre-Implementation (MANDATORY)
+Before writing ANY code, read ALL target files and output:
+CONTEXT_READ: [list of files examined]
+EXISTING_PATTERNS: [key patterns observed -- naming, error handling, imports]
+
+## Your Task
+**{task_id}** {task_description}
+Effort: {effort}
+Files: {files}
+Test: {test_spec from PLAN.md, if present}
+
+## Technical Context
+{contents of eng.md}
+
+## Rules
+- Only touch files listed for this task
+- Match patterns from CONTEXT_READ -- do not invent new patterns
+- If blocked, report the blocker -- don't improvise
+- Classify any deviations: cosmetic | interface | scope
+
+## Output Protocol
+Write checkpoint to `{folder}/{feature-slug}/implement/checkpoints/{task_id}.md`:
+
+## Status: {task_id}
+status: done | blocked | deviated
+files_read: ["files examined"]
+files_changed: ["files modified"]
+commit: {hash}
+deviations: none | {severity}: {description}
+duration: {seconds}s
+context_read: ["files from CONTEXT_READ"]
+patterns_followed: ["observed patterns"]
+
+Return single line: `DONE: {task_id} | files: N | deviations: none`
+```
 
 #### If TDD is enabled (`tdd: true` in config):
 
-Follow strict RED → GREEN → REFACTOR per task:
+Before launching plan-executor, run TDD cycle 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
-   ```
+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 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
+**VERIFY RED:** Run test → must fail for expected reason.
+**GREEN:** Launch plan-executor with the prompt template above, adding: "The following test is FAILING: {test_file}:{test_name}. Write MINIMAL code to pass it."
+**VERIFY GREEN:** Run test + full suite → all pass.
+**REFACTOR:** Clean up, re-run tests.
+**Additional cycles:** Repeat RED → GREEN → REFACTOR for each test scenario.
 
-**REFACTOR — Clean up:**
-3e. Review implementation: remove duplication, improve names, extract helpers if 3+ uses.
-   Re-run tests to confirm still green.
+### Tier 1 execution (Inline — weight <= 8):
 
-**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.
+For each task in order (respecting dependencies):
+1. Launch plan-executor agent (foreground) with the prompt template
+2. Agent returns full result
+3. Extract status line from result. Discard rest.
+4. Increment `tasks_this_session`
+5. If config `commit_style` is `conventional`: verify agent committed, or stage and commit
+6. Proceed to next task
 
-#### If TDD is disabled (default):
+### Tier 2 execution (File-mediated — weight 9-18):
 
-3. Launch plan-executor agent:
+For each task in order (respecting dependencies):
+1. Launch plan-executor agent (foreground) with the prompt template
+2. Agent writes checkpoint file and returns 1-line status
+3. Parse status line only. Do NOT read the full agent response for context.
+4. Increment `tasks_this_session`
+5. If config `commit_style` is `conventional`: verify agent committed
+6. **Session warning check**: if `tasks_this_session >= max_tasks_per_session`:
    ```
-   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
+   Session getting long ({tasks_this_session} tasks completed).
+   Consider starting a new session for better accuracy:
+   /rpi:implement {feature-slug} --resume
    ```
+   Continue if user wants to proceed.
+7. Proceed to next task
 
-#### 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:
+### Tier 3 execution (Wave-isolated — weight > 18):
 
 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
+3. For each wave:
+   a. Launch ALL wave tasks as parallel foreground agents (one message, multiple Agent calls)
+   b. Each agent uses the prompt template
+   c. Wait for all agents in wave to complete
+   d. For each completed agent, parse status line only
+   e. Increment `tasks_this_session` by wave size
+   f. **Deviation check** (see section 6b)
+   g. **Rollback check** (see section 6c)
+4. After each wave, **forced session checkpoint** (see section 6d)
+
+## 6b. Handle deviations
+
+After each task (all tiers) or after each wave (Tier 3):
+
+1. Parse the status line for deviations
+2. If `deviations: none` — continue
+3. If deviation reported, read the checkpoint file to get severity:
+   - `cosmetic`: log in IMPLEMENT.md, continue automatically
+   - `interface`:
+     a. Read PLAN.md to find tasks that depend on the current task
+     b. Check if any dependent task's `Files:` field overlaps with the deviated files
+     c. If overlap: pause execution, ask user:
+        ```
+        Task {task_id} changed an interface ({description}).
+        Downstream tasks that may be affected: {list}
+        Options:
+        - Continue (downstream agents will read the actual code)
+        - Pause and review the change
+        - Revert task {task_id} and re-plan
+        ```
+     d. If no overlap: log, continue
+   - `scope`:
+     a. Pause execution immediately
+     b. Read full checkpoint file for details
+     c. Ask user:
+        ```
+        Task {task_id} deviated in scope: {description}
+        Options:
+        - Accept the deviation and continue
+        - Revert task {task_id}: git revert {commit_hash}
+        - Stop implementation for manual review
+        ```
+
+## 6c. Rollback protocol (Tier 3 parallel waves only)
+
+If any task in a wave reports `status: blocked`:
+
+1. Identify the blocked task and its reason
+2. Read PLAN.md dependency graph
+3. Find completed tasks in the SAME wave that depend on the blocked task:
+   ```
+   invalidated = [t for t in wave_completed if blocked_task_id in t.deps]
+   ```
+4. For each invalidated task:
+   a. Read its checkpoint file to get commit hash
+   b. Run: `git revert {commit_hash} --no-commit`
+   c. Update checkpoint file: `status: rolled_back`
+5. If any reverts were staged:
+   ```bash
+   git commit -m "revert: rollback tasks {list} due to {blocked_task_id} failure"
+   ```
+6. Inform user:
+   ```
+   Task {blocked_task_id} blocked: {reason}
+   Rolled back dependent tasks: {list}
+   Kept independent tasks: {list}
 
-## 7. Phase checkpoint
+   Fix the blocker and resume:
+   /rpi:implement {feature-slug} --resume --from-task {blocked_task_id}
+   ```
+7. Stop execution (do not proceed to next wave)
+
+## 6d. Session checkpoint
+
+Triggered by:
+- Tier 2: user agrees to take a break after session warning
+- Tier 3: after every wave completes
+
+### Checkpoint process:
+
+1. **Aggregate IMPLEMENT.md** from checkpoint files:
+   - Read all files in `{folder}/{feature-slug}/implement/checkpoints/`
+   - Sort by task ID
+   - Build IMPLEMENT.md with all task statuses, files changed, deviations
+   - Preserve existing sections (Simplify Findings, Review) if present
+
+2. **Write session record** to `{folder}/{feature-slug}/implement/sessions/session-{N}.md`:
+   ```markdown
+   # Session {N}
+   Started: {timestamp}
+   Ended: {timestamp}
+   Tier: {tier}
+   Tasks completed: {list of task IDs completed this session}
+   Total progress: {completed}/{total}
+   Next task: {next_task_id}
+   Deviations: {summary or "none"}
+   ```
 
-After all tasks in a phase complete:
+3. **Print resume command**:
+   ```
+   Session checkpoint saved.
+   Completed: {completed}/{total} tasks
+   To continue in a new session:
+   /rpi:implement {feature-slug} --resume
+   ```
 
-Output:
-```
-Phase {N}: {Phase Name}
-Tasks: {completed}/{total}
-Commits: {list}
-```
+4. **For Tier 3: stop execution**. The user must start a new session.
+   For Tier 2: continue if user wants to, or stop.
 
-If any tasks failed or were blocked, ask user how to proceed.
+## 7. Phase checkpoint
+
+After all tasks in a PLAN.md phase complete:
+
+1. Read checkpoint files for all tasks in the phase
+2. Count completed vs blocked vs deviated
+3. Output:
+   ```
+   Phase {N}: {Phase Name}
+   Tasks: {completed}/{total}
+   Commits: {list from checkpoint files}
+   Deviations: {count by severity}
+   ```
+4. If any tasks blocked, ask user how to proceed before next phase
 
 ## 8. Run simplify (unless --skip-simplify)
 
@@ -240,14 +390,19 @@ Record verdict in IMPLEMENT.md under "## Review".
 
 ## 10. Finalize IMPLEMENT.md
 
-Update IMPLEMENT.md with:
+Rebuild IMPLEMENT.md from all checkpoint files:
+1. Read all files in `checkpoints/`
+2. Build task list with statuses, commits, deviations
+3. Append summary:
+
 ```markdown
 ## Summary
 
 Completed: {timestamp}
 Total tasks: {N}
-Commits: {list with hashes}
-Phases: {M}
+Sessions: {count from sessions/ directory}
+Commits: {list with hashes from checkpoints}
+Deviations: {count by severity}
 
 ## Review Verdict: {PASS|FAIL}
 {details}
@@ -272,6 +427,18 @@ Feature {feature-slug} implementation complete but review found issues:
 Fix and re-run: /rpi:review {feature-slug}
 ```
 
+## 11b. Cross-phase session boundary (Tier 3 only)
+
+If tier == 3, after presenting the final result, add:
+
+```
+This was a large feature (Tier 3). For future features of this complexity,
+consider running each RPI phase in a separate session:
+1. Session 1: /rpi:new + /rpi:research
+2. Session 2: /rpi:plan
+3. Session 3+: /rpi:implement --resume (one session per wave)
+```
+
 ## 12. Handle isolation cleanup
 
 Read `isolation` from `.rpi.yaml`.