@juicesharp/rpiv-pi 1.2.1 → 1.3.0

package/README.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/@juicesharp/rpiv-pi.svg)](https://www.npmjs.com/package/@juicesharp/rpiv-pi)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **Pi compatibility** - `rpiv-pi` `0.14.x` tracks `@mariozechner/pi-coding-agent` `0.70.x` and `@tintinweb/pi-subagents` `0.6.x`. If you see peer-dep resolution issues after a Pi upgrade, open an issue.
+> **Pi compatibility** - `rpiv-pi` `0.14.x` tracks `@earendil-works/pi-coding-agent` `0.70.x` and `@tintinweb/pi-subagents` `0.6.x`. If you see peer-dep resolution issues after a Pi upgrade, open an issue.
 
 > **⚠️ Upgrading from `0.13.x`** - `1.0.0` swaps the subagent provider from `npm:pi-subagents` (nicobailon fork) back to `npm:@tintinweb/pi-subagents` (resumed maintenance). On first launch after upgrade you'll see *"rpiv-pi requires 1 sibling extension(s): @tintinweb/pi-subagents"* - **run `/rpiv-setup` once and restart Pi**. The setup dialog previews both changes (install `@tintinweb/pi-subagents`, remove `npm:pi-subagents` from `~/.pi/agent/settings.json`) and applies them only after you confirm. After restart, run `/rpiv-update-agents` to refresh the 12 bundled specialist frontmatters. Customised `<cwd>/.pi/agents/*.md` files are not touched. The tool name reverts from `subagent` → `Agent` (param `subagent_type`/`description`/`prompt`) - only your own custom skills/agents need editing; the bundled rpiv-pi specialists are migrated in this release.
 
@@ -29,7 +29,7 @@ Skill-based development workflow for [Pi Agent](https://github.com/badlogic/pi-m
 - **[Pi Agent](https://github.com/badlogic/pi-mono)** - install globally so the `pi` command is available:
 
   ```bash
-  npm install -g @mariozechner/pi-coding-agent
+  npm install -g @earendil-works/pi-coding-agent
   ```
 
 - **Model provider** *(first-time Pi Agent users only - skip if `/login` already works or `~/.pi/agent/models.json` is configured)*. Pick one:
@@ -182,7 +182,7 @@ Invoke via `/skill:<name>` from inside a Pi Agent session.
 | `/rpiv-setup` | Install all sibling plugins in one go |
 | `/rpiv-update-agents` | Sync rpiv agent profiles: add new, update changed, remove stale |
 | `/advisor` | Configure advisor model and reasoning effort |
-| `/btw` | Ask a side question without polluting the main conversation |
+| `/btw` | Ask a side question without polluting the main conversation _(requires `@juicesharp/rpiv-btw`, opt-in)_ |
 | `/languages` | Pick the UI language for rpiv-* TUI strings (Deutsch / English / Español / Français / Português / Português (Brasil) / Русский / Українська) |
 | `/todos` | Show current todo list |
 | `/web-search-config` | Set Brave Search API key |
@@ -222,7 +222,7 @@ Pi Agent discovers extensions via `"extensions": ["./extensions"]` and skills vi
 
 - **Web search** - run `/web-search-config` to set the Brave Search API key, or set the `BRAVE_SEARCH_API_KEY` environment variable
 - **Advisor** - run `/advisor` to select a reviewer model and reasoning effort
-- **Side questions** - type `/btw <question>` anytime (even mid-stream) to ask the primary model a one-off question; answer appears in a borderless bottom overlay and never enters the main conversation
+- **Side questions** _(opt-in: `pi install npm:@juicesharp/rpiv-btw`)_ - type `/btw <question>` anytime (even mid-stream) to ask the primary model a one-off question; answer appears in a borderless bottom overlay and never enters the main conversation
 - **UI language** - run `/languages` to pick the locale for rpiv-* TUI strings, or pass `pi --locale <code>` at startup. Detection priority: flag → `~/.config/rpiv-i18n/locale.json` → `LANG` / `LC_ALL` → English. LLM-facing copy stays English by design
 - **Agent concurrency** - open the `/agents` overlay and tune `Settings → Max concurrency` to match your provider's rate limits. `@tintinweb/pi-subagents` owns this setting; rpiv-pi does not seed it.
 - **Agent profiles** - editable at `<cwd>/.pi/agents/`; sync from bundled defaults with `/rpiv-update-agents` (overwrites rpiv-managed files, preserves your custom agents)

package/extensions/rpiv-core/git-context.ts

@@ -8,7 +8,7 @@
  * redirection, so either form is worktree-safe.
  */
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 type GitContext = { branch: string; commit: string; user: string };
 

package/extensions/rpiv-core/guidance.ts

@@ -21,7 +21,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, sep } from "node:path";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { FLAG_DEBUG, MSG_TYPE_GUIDANCE } from "./constants.js";
 
 // ---------------------------------------------------------------------------

package/extensions/rpiv-core/index.ts

@@ -7,7 +7,7 @@
  * Tool-owning plugins are siblings (see siblings.ts); install via /rpiv-setup.
  */
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { FLAG_DEBUG } from "./constants.js";
 import { registerSessionHooks } from "./session-hooks.js";
 import { registerSetupCommand } from "./setup-command.js";

package/extensions/rpiv-core/session-hooks.ts

@@ -7,7 +7,7 @@
 
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
-import { type ExtensionAPI, isToolCallEventType } from "@mariozechner/pi-coding-agent";
+import { type ExtensionAPI, isToolCallEventType } from "@earendil-works/pi-coding-agent";
 import { type SyncResult, syncBundledAgents } from "./agents.js";
 import { FLAG_DEBUG, MSG_TYPE_GIT_CONTEXT } from "./constants.js";
 import {

package/extensions/rpiv-core/setup-command.ts

@@ -8,7 +8,7 @@
  * Reports succeeded/failed split; prompts the user to restart Pi on success.
  */
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { findMissingSiblings } from "./package-checks.js";
 import { spawnPiInstall } from "./pi-installer.js";
 import { findLegacySiblings, pruneLegacySiblings } from "./prune-legacy-siblings.js";

package/extensions/rpiv-core/siblings.test.ts

@@ -2,8 +2,8 @@ import { describe, expect, it } from "vitest";
 import { LEGACY_SIBLINGS, SIBLINGS } from "./siblings.js";
 
 describe("SIBLINGS registry", () => {
-	it("contains 8 entries (pi-subagents at SIBLINGS[0] — tintinweb fork is the dispatch runtime)", () => {
-		expect(SIBLINGS).toHaveLength(8);
+	it("contains 7 entries (pi-subagents at SIBLINGS[0] — tintinweb fork is the dispatch runtime)", () => {
+		expect(SIBLINGS).toHaveLength(7);
 	});
 
 	it("lists @tintinweb/pi-subagents at SIBLINGS[0]", () => {
@@ -14,6 +14,10 @@ describe("SIBLINGS registry", () => {
 		expect(SIBLINGS.find((s) => s.pkg === "npm:pi-subagents")).toBeUndefined();
 	});
 
+	it("does NOT list rpiv-btw (standalone-only — rpiv-pi has no runtime dependency on it)", () => {
+		expect(SIBLINGS.find((s) => s.pkg === "npm:@juicesharp/rpiv-btw")).toBeUndefined();
+	});
+
 	for (const s of SIBLINGS) {
 		it(`${s.pkg} — self-match against settings.json line shape`, () => {
 			expect(s.matches.test(s.pkg.replace(/^npm:/, ""))).toBe(true);

package/extensions/rpiv-core/siblings.ts

@@ -40,11 +40,6 @@ export const SIBLINGS: readonly SiblingPlugin[] = [
 		matches: /rpiv-advisor/i,
 		provides: "advisor tool + /advisor command",
 	},
-	{
-		pkg: "npm:@juicesharp/rpiv-btw",
-		matches: /rpiv-btw/i,
-		provides: "/btw side-question command",
-	},
 	{
 		pkg: "npm:@juicesharp/rpiv-i18n",
 		matches: /rpiv-i18n(?![-\w])/i,

package/extensions/rpiv-core/update-agents-command.ts

@@ -3,7 +3,7 @@
  * Adds new, overwrites changed managed files, removes stale managed files.
  */
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type SyncResult, syncBundledAgents } from "./agents.js";
 
 const MSG_UP_TO_DATE = "All agents already up-to-date.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "A skill-based development workflow for Pi Agent. Five skills (research, design, plan, implement, validate) and the shared subagents that compose its ship-loop.",
   "keywords": [
     "pi-package",
@@ -44,12 +44,11 @@
     ]
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": "*",
     "@tintinweb/pi-subagents": "*",
     "@juicesharp/rpiv-ask-user-question": "*",
     "@juicesharp/rpiv-todo": "*",
     "@juicesharp/rpiv-advisor": "*",
-    "@juicesharp/rpiv-btw": "*",
     "@juicesharp/rpiv-i18n": "*",
     "@juicesharp/rpiv-web-tools": "*",
     "@juicesharp/rpiv-args": "*",

package/skills/frontend-design/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: frontend-design
+description: "Create distinctive, production-grade frontend interfaces with high design quality. Use when the user asks to build web components, pages, or applications, or wants design guidance. Also use during frontend UI work — pass `--headless` for projects with established styles to inject guidelines without the interview checkpoint."
+argument-hint: "[--headless]"
+---
+
+# Frontend Design
+
+You are tasked with injecting tailored visual design guidance into the agent's context, preventing generic "AI slop" aesthetics in frontend output. The workflow has three steps: (1) scan the project for existing style context, (2) run an adaptive aesthetic checkpoint across 7 dimensions (skipping settled ones), (3) synthesize tailored guidelines + anti-slop guardrails.
+
+Two invocation modes:
+- **Full checkpoint** (default): scan → 7-dimension interview → inject guidelines
+- **Headless** (`--headless`): scan → inject findings as guidelines → stop (no interview)
+
+**How it works**:
+- Parse input and detect invocation mode (Step 1)
+- Scan for existing style context via codebase-locator agent (Step 2)
+- Run adaptive aesthetic checkpoint via ask_user_question (Step 3)
+- Synthesize and inject tailored guidelines + anti-slop list (Step 4)
+
+## Input: `$ARGUMENTS`
+
+## Step 1: Input Handling
+
+1. **No argument provided** — full checkpoint mode:
+   ```
+   I'll guide your frontend design direction. Provide one of:
+
+   `/skill:frontend-design`                — full aesthetic checkpoint (scan + interview + guidelines)
+   `/skill:frontend-design --headless`     — scan-only: inject style findings without interview
+   ```
+   Then wait for input.
+
+2. **`$ARGUMENTS` contains `--headless`** — headless mode:
+   - Set mode to `headless`. Proceed to Step 2. After Step 2, skip Step 3 and go directly to Step 4.
+
+3. **Otherwise** — full checkpoint mode:
+   - Set mode to `full`. Proceed to Step 2.
+
+4. **Read any context files mentioned** in the prompt (DESIGN.md, style guides, tickets) FULLY before proceeding.
+
+**No agent dispatch in Step 1.** Only `Read` on user-named paths.
+
+## Step 2: Style Discovery (parallel agents)
+
+Dispatch a single codebase-locator agent to scan for existing style context.
+
+**Agent — Style system scan:**
+- subagent_type: `codebase-locator`
+- description: "Scan for style systems"
+- prompt: "Scan the project for existing style context. Look for: (1) DESIGN.md files (Google's design spec), (2) design token files (tokens.css, tokens.json, design-tokens.*), (3) Tailwind/CSS framework configs (tailwind.config.*, postcss.config.*), (4) style guide or brand guideline files, (5) CSS custom property definitions (--color-*, --font-*, --spacing-*), (6) component library setups (Storybook, component indexes). Return file paths grouped by category with line offsets."
+
+Wait for the agent to complete before proceeding.
+
+### Scan Findings Summary
+
+Present findings grouped by dimension:
+- **DESIGN.md**: found at `path/to/DESIGN.md` (or "none found")
+- **Tokens/Variables**: found at `path/to/tokens.css` with N custom properties (or "none found")
+- **Framework config**: found at `path/to/tailwind.config.ts` (or "none found")
+- **Style guides**: found at `path/to/style-guide.md` (or "none found")
+- **Component library**: found at `path/to/components/` with N files (or "none found")
+
+### If DESIGN.md found
+
+Read it FULLY using the Read tool. This is the primary style source — its decisions take precedence over scan findings for the checkpoint.
+
+### Headless exit
+
+**If mode is `headless`:**
+1. Synthesize scan findings into concise style guidelines (respect what exists, note what's missing)
+2. Inject as assistant message (see Step 4 output format)
+3. **Stop — do not proceed to Step 3.**
+
+### Full checkpoint continuation
+
+**If mode is `full`:** Proceed to Step 3. Carry scan findings forward — they inform skip logic and pre-fill recommendations.
+
+## Step 3: Aesthetic Checkpoint
+
+Ask the developer about aesthetic direction across 7 dimensions. Use `ask_user_question` — one question at a time, wait for the answer before asking the next. Lead each question with the recommended option labeled `(Recommended)`.
+
+### Skip Logic
+
+Before asking each dimension, check if the scan (Step 2) found a **complete system** for that dimension. If yes, note the finding and skip the question. If the system is partial, still ask but pre-fill the recommendation from the scan.
+
+**Skip thresholds by dimension** (agent judgment — these are examples, not rigid checklists):
+- **Typography**: skip if font imports + type scale + CSS variables for font families all exist
+- **Color**: skip if color palette tokens + theme variables + accent colors all exist
+- **Motion**: skip if transition/animation tokens or a motion library is configured
+- **Spatial**: skip if spacing scale tokens + layout system (grid/flex patterns) both exist
+- **Backgrounds**: skip if texture/gradient/pattern definitions exist in the style system
+- **Tone/Mood**: never skip — conceptual, not detectable from code
+- **Differentiation**: never skip — conceptual, requires developer input
+
+When skipping, record: "Dimension X: [finding from scan] — respecting existing system."
+
+### Dimension 1: Tone & Mood
+
+Ask via `ask_user_question`:
+- Question: "What aesthetic tone should this interface convey?"
+- Header: "Tone"
+- Options (pick 3-4 that fit the project context, always include the first):
+  - "Editorial / magazine (Recommended)" (if no prior context) — refined typography, generous whitespace, content-first
+  - "Brutally minimal" — stripped to essentials, monochrome, no decoration
+  - "Playful / toy-like" — rounded shapes, bright colors, bouncy interactions
+  - "Retro-futuristic" — CRT textures, neon accents, terminal aesthetics
+  - "Luxury / refined" — dark palettes, serif fonts, gold accents, subtle motion
+  - "Brutalist / raw" — exposed structure, harsh contrasts, system fonts used intentionally
+  - "Art deco / geometric" — ornamental patterns, metallic accents, symmetrical layouts
+  - "Soft / pastel" — light tones, rounded corners, gentle gradients
+- If the DESIGN.md or scan findings suggest a tone, make that the `(Recommended)` option.
+
+### Dimension 2: Color Direction
+
+Ask via `ask_user_question`:
+- Question: "What color direction fits this interface?"
+- Header: "Color"
+- Options:
+  - "Dark mode, warm accents" — dark backgrounds, amber/gold/orange highlights
+  - "Dark mode, cool accents" — dark backgrounds, blue/teal/purple highlights
+  - "Light mode, muted palette" — off-white backgrounds, desaturated earth tones
+  - "Light mode, vibrant" — white/light backgrounds, bold primary colors
+  - "High contrast" — stark black/white with one accent color
+- If scan found color tokens/theme, make the closest match the `(Recommended)` option.
+
+### Dimension 3: Typography
+
+Ask via `ask_user_question`:
+- Question: "What typography direction for this interface?"
+- Header: "Typography"
+- Options:
+  - "Serif display + sans body" — editorial feel, character in headings
+  - "All sans-serif, distinctive pairing" — modern, clean, pair unexpected fonts
+  - "Monospace-forward" — terminal/code aesthetic, developer tools
+  - "Mixed: display serif + monospace accents" — editorial meets technical
+- If scan found font imports/type scale, pre-fill the `(Recommended)` option from what exists.
+
+### Dimension 4: Motion
+
+Ask via `ask_user_question`:
+- Question: "How much motion and animation?"
+- Header: "Motion"
+- Options:
+  - "Subtle micro-interactions" — hover effects, smooth transitions, gentle reveals
+  - "Bold page-load choreography" — staggered reveals, dramatic entrances, scroll-triggered
+  - "CSS-only, no JS" — pure CSS transitions and animations, lightweight
+  - "Static / minimal" — no animation, focus on typography and layout
+- If scan found animation tokens/motion library, pre-fill the `(Recommended)` option.
+
+### Dimension 5: Spatial Composition
+
+Ask via `ask_user_question`:
+- Question: "What spatial composition approach?"
+- Header: "Spatial"
+- Options:
+  - "Generous whitespace, asymmetric" — editorial layout, breathing room, offset elements
+  - "Dense, information-rich" — dashboard-style, maximum content per viewport
+  - "Grid-breaking, overlapping" — elements that break the grid, layered composition
+  - "Structured grid, symmetric" — traditional layout, predictable alignment
+- If scan found spacing tokens/grid system, pre-fill the `(Recommended)` option.
+
+### Dimension 6: Backgrounds & Texture
+
+Ask via `ask_user_question`:
+- Question: "What background treatment?"
+- Header: "Backgrounds"
+- Options:
+  - "Solid with subtle noise/grain" — flat color with texture overlay for depth
+  - "Gradient mesh" — multi-color gradients, blurred shapes, atmospheric
+  - "Geometric patterns" — repeating shapes, lines, or decorative elements
+  - "Clean solid, no texture" — pure flat color, let content be the visual
+- If scan found background/texture definitions, pre-fill the `(Recommended)` option.
+
+### Dimension 7: Differentiation
+
+Ask via `ask_user_question`:
+- Question: "What makes this interface UNFORGETTABLE? What's the one thing someone will remember?"
+- Header: "Differentiation"
+- Options (pick 2-3 that fit, always include an open-ended):
+  - "Typography as art" — oversized, expressive type as the primary visual element
+  - "Unexpected interaction" — a signature interaction pattern that surprises
+  - "Atmosphere" — immersive background/texture that sets a mood
+  - "Layout rebellion" — breaks every grid convention intentionally
+- This dimension is always asked — it cannot be derived from scan findings.
+
+### Record Checkpoint Answers
+
+After all 7 dimensions (or all unsettled dimensions if some were skipped), compile the answers into a structured record:
+- Each settled dimension: "Dimension: chosen option"
+- Each skipped dimension: "Dimension: [existing finding] — respecting existing system"
+
+Carry this record to Step 4 for guideline synthesis.
+
+## Step 4: Guideline Synthesis
+
+Combine scan findings (Step 2) and checkpoint answers (Step 3, or scan-only findings in headless mode) into tailored aesthetic guidelines. Emit as your own assistant message — this primes your context for all subsequent frontend code generation.
+
+### Output Format
+
+Structure the guidelines as a concise, actionable brief:
+
+```markdown
+## Frontend Design Guidelines
+
+**Tone**: {chosen tone} — {1-sentence description of how it manifests}
+**Color**: {chosen direction} — {specific palette suggestion: primary, accent, background}
+**Typography**: {chosen direction} — {specific font suggestions: display + body}
+**Motion**: {chosen level} — {specific approach: CSS transitions, scroll triggers, etc.}
+**Spatial**: {chosen composition} — {layout approach: grid, whitespace, asymmetry}
+**Backgrounds**: {chosen treatment} — {specific texture/gradient/solid approach}
+**Differentiation**: {chosen differentiator} — {how to make it unforgettable}
+
+{For each skipped dimension:}
+**{Dimension}**: Respecting existing system — {brief description of what was found at `file:line`}
+
+### NEVER Generate
+
+- Overused display fonts: Inter, Roboto, Arial, system-ui as hero/display type
+- Clichéd color schemes: purple-to-blue gradients on white backgrounds, generic "SaaS blue"
+- Predictable layouts: centered card stacks, hero-image-then-three-columns, cookie-cutter navbars
+- Cookie-cutter component patterns: identical rounded cards with shadow-md, every section with max-w-7xl mx-auto
+- Generic motion: fade-in on every scroll, identical bounce animations, no intentional choreography
+
+{If DESIGN.md was NOT found in Step 2:}
+
+**Note**: No DESIGN.md found in this project. Consider creating one to codify these design decisions for future reference. See Google's DESIGN.md spec for format guidance.
+```
+
+### Injection
+
+Emit the complete guidelines as your own assistant message. Do NOT write to a file. Do NOT use `pi.sendMessage`. The guidelines become part of the conversation transcript — they survive compaction and inform all subsequent turns.
+
+If in headless mode, the guidelines should be briefer — focus on what the scan found and how to respect it, skip the full checkpoint synthesis.
+
+## Important Notes
+
+- **Frontmatter**: `allowed-tools` is intentionally omitted — the skill inherits `Agent`, `ask_user_question`, `Read`, `Write`, `Bash`, `Glob`, `Grep`. Do NOT re-add the line.
+- **Always scan before asking**: Step 2 (style discovery) always runs before Step 3 (checkpoint). Never ask aesthetic questions without first checking what exists.
+- **One question at a time**: Use `ask_user_question` for each dimension individually. Never batch multiple dimensions into one call.
+- **Never ask confirmatory questions**: Do not ask "does this look good?" or "want to adjust?" at the end. The guidelines ARE the output — emit them and stop.
+- **Skip logic is judgment, not rules**: The skip thresholds are examples. If a project has a partial system that's clearly intentional (e.g., 3 custom font variables but no full scale), skip and note it.
+- **Headless mode exits after Step 2**: When `--headless` is passed, scan → inject findings → stop. Do not proceed to Step 3.
+- **Anti-slop list is always included**: Every invocation (full or headless) includes the NEVER Generate list. This is not optional.
+- **DESIGN.md takes precedence**: If a DESIGN.md file is found, its decisions override scan findings for the checkpoint. Read it fully before asking questions.
+- **Guidelines are inline, not persisted**: The output is an assistant message, not a file. If the developer wants to persist the guidelines, they should create a DESIGN.md manually.
+- **No template files**: This skill is a single SKILL.md. Do not create `templates/` or `examples/` subdirectories.

package/skills/implement/SKILL.md

@@ -74,26 +74,47 @@ If the plan has existing checkmarks:
 
 Remember: You're implementing a solution, not just checking boxes. Keep the end goal in mind and maintain forward momentum.
 
-## Closing Out
+## Present and Chain
 
-When the last in-scope phase is complete (or the user pauses execution), print a closing block in this exact shape:
+When the last in-scope phase is complete, print the **completion** closing block:
 
 ```
-Implementation {complete | paused at Phase {N}}: `thoughts/shared/plans/{filename}.md`
+Implementation complete:
+`thoughts/shared/plans/{filename}.md`
 
 {P} phases completed, {M} files changed, {T} tests passing.
-Outstanding: {list of unchecked items, blockers, or "none"}.
+Outstanding: none.
+
+Please review the diff and let me know if anything should reopen a phase.
 
 ---
 
-💬 Follow-up: implement edits source files, not artifacts. For plan-level changes run `/skill:revise <plan-path>` first; for session pauses run `/skill:create-handoff`.
+💬 Follow-up: surface code/plan mismatches inline via the `ask_user_question` flow ("Follow the plan / Skip this change / Update the plan") — that is implement's only in-skill follow-up surface. For plan-level changes run `/skill:revise <plan-path>`; for session pauses run `/skill:create-handoff`.
 
 **Next step:** `/skill:validate thoughts/shared/plans/{filename}.md` — verify the implementation against the plan's success criteria before committing.
 
 > 🆕 Tip: start a fresh session with `/new` first — chained skills work best with a clean context window.
 ```
 
-If the run was paused mid-plan rather than completed, swap the next-step line for `/skill:create-handoff` so context can be resumed cleanly in a new session — the same `/new` tip still applies.
+If the run was paused mid-plan rather than completed, print the **paused** variant instead:
+
+```
+Implementation paused at Phase {N}:
+`thoughts/shared/plans/{filename}.md`
+
+{P} phases completed, {M} files changed, {T} tests passing.
+Outstanding: {list of unchecked items, blockers}.
+
+Please review what landed and let me know if anything needs to change before resuming.
+
+---
+
+💬 Follow-up: surface code/plan mismatches inline via the `ask_user_question` flow ("Follow the plan / Skip this change / Update the plan") — that is implement's only in-skill follow-up surface. For plan-level changes run `/skill:revise <plan-path>` first.
+
+**Next step:** `/skill:create-handoff` — capture in-flight state so the next session can resume cleanly via `/skill:resume-handoff`.
+
+> 🆕 Tip: start a fresh session with `/new` first — chained skills work best with a clean context window.
+```
 
 ## Handle Follow-ups