@juicesharp/rpiv-pi 1.1.3 → 1.1.5

package/README.md

@@ -11,31 +11,31 @@
 [![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 `@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.
 
-> **⚠️ 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.
+> **⚠️ 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.
 
-Skill-based development workflow for [Pi Agent](https://github.com/badlogic/pi-mono) — discover, research, design, plan, implement, and validate. rpiv-pi extends Pi Agent with a pipeline of chained AI skills, named subagents for parallel analysis, and session lifecycle hooks for automatic context injection.
+Skill-based development workflow for [Pi Agent](https://github.com/badlogic/pi-mono) - discover, research, design, plan, implement, and validate. rpiv-pi extends Pi Agent with a pipeline of chained AI skills, named subagents for parallel analysis, and session lifecycle hooks for automatic context injection.
 
 ## What you get
 
-- **A pipeline of chained AI skills** — discover → research → design → plan → implement → validate, each producing a reviewable artifact under `thoughts/shared/`.
-- **Named subagents for parallel analysis** — `codebase-analyzer`, `codebase-locator`, `codebase-pattern-finder`, `claim-verifier`, and 8 more, dispatched automatically by skills.
-- **Session lifecycle hooks** — agent profiles, guidance files, and pipeline directories scaffold themselves on first launch.
+- **A pipeline of chained AI skills** - discover → research → design → plan → implement → validate, each producing a reviewable artifact under `thoughts/shared/`.
+- **Named subagents for parallel analysis** - `codebase-analyzer`, `codebase-locator`, `codebase-pattern-finder`, `claim-verifier`, and 8 more, dispatched automatically by skills.
+- **Session lifecycle hooks** - agent profiles, guidance files, and pipeline directories scaffold themselves on first launch.
 
 ## Prerequisites
 
-- **Node.js** — required by Pi Agent
-- **[Pi Agent](https://github.com/badlogic/pi-mono)** — install globally so the `pi` command is available:
+- **Node.js** - required by Pi Agent
+- **[Pi Agent](https://github.com/badlogic/pi-mono)** - install globally so the `pi` command is available:
 
   ```bash
   npm install -g @mariozechner/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:
+- **Model provider** *(first-time Pi Agent users only - skip if `/login` already works or `~/.pi/agent/models.json` is configured)*. Pick one:
 
-  - **Subscription login** — start Pi Agent and run `/login` to authenticate with Anthropic Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot, or Gemini.
-  - **BYOK (API key)** — edit `~/.pi/agent/models.json` and add a provider entry with `baseUrl`, `api`, `apiKey`, and `models[]`. Example (z.ai GLM coding plan):
+  - **Subscription login** - start Pi Agent and run `/login` to authenticate with Anthropic Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot, or Gemini.
+  - **BYOK (API key)** - edit `~/.pi/agent/models.json` and add a provider entry with `baseUrl`, `api`, `apiKey`, and `models[]`. Example (z.ai GLM coding plan):
 
     ```json
     {
@@ -64,7 +64,7 @@ Skill-based development workflow for [Pi Agent](https://github.com/badlogic/pi-m
     }
     ```
 
-- **git** *(recommended)* — rpiv-pi works without it, but branch and commit context won't be available to skills.
+- **git** *(recommended)* - rpiv-pi works without it, but branch and commit context won't be available to skills.
 
 ## Quick Start
 
@@ -114,18 +114,18 @@ Each skill produces an artifact consumed by the next. Run them in order, or jump
 
 Skills compose. Pick the entry point that matches your intent:
 
-- **Form context before a task** — `/skill:discover "[topic]"` → `/skill:research <questions artifact>`. Produces a high-signal subspace of the codebase relevant to your topic, ready to feed directly into the next prompt.
-- **Compare approaches before designing** — `/skill:explore "[problem]"` → `/skill:design <solutions artifact>`. Use when multiple valid solutions exist; the solutions artifact is a first-class input to `design` alongside a `research` artifact.
-- **One-shot plan from research** — `/skill:research <questions>` → `/skill:blueprint <research artifact>` → `/skill:implement`. Fuses `design` + `plan` into a single pass with the same slice-by-slice rigor, but spawns only `codebase-pattern-finder` upfront (vs `design`'s 4-agent fan-out) by trusting the research artifact's integration/precedent sections. Use for solo work or when no one else needs to review the design before implementation; pick `design` → `plan` when the design is itself a deliverable or when research is thin and you want the fuller verification sweep.
-- **Full feature build** — `/skill:discover` → `research` → `design` → `plan` → `implement` → `validate` → (`code-review` ↔ `commit`). The default pipeline; jump in at any stage if you already have the input artifact. Review and commit are interchangeable in order — review `staged`/`working` before committing, or commit first and review the resulting branch (empty scope, first-parent vs default).
-- **Investigate a bug** — `/skill:discover "why does X fail"` → `/skill:research <questions artifact>`. Fix from the research output without writing a plan when the change is small.
-- **Adjust mid-implementation** — `/skill:revise <plan artifact>` → resume `/skill:implement`. Use when new constraints land after the plan is drafted.
-- **Review before shipping** — `/skill:code-review` ↔ `/skill:commit`. Order is your call: review `staged`/`working` before committing to catch issues at the smallest blast radius, or commit first and review the resulting branch (empty scope defaults to feature-branch-vs-default-branch, first-parent). Produces a Quality/Security/Dependencies artifact under `thoughts/shared/reviews/` with claim-verifier-grounded findings and `status: approved | needs_changes`.
-- **Audit a specific scope** — `/skill:code-review <commit|staged|working|hash|A..B|branch>`. Targeted lenses over a commit, range, staged/working tree, or PR branch; advisor adjudication applies when configured (`/advisor`).
-- **Review-driven plan revision** — `/skill:code-review` → `/skill:revise <plan artifact>` → resume `/skill:implement`. When a mid-stream review surfaces structural findings that the existing plan can't absorb as spot fixes.
-- **Scaffold manual UI test specs** — `/skill:outline-test-cases` → `/skill:write-test-cases <feature>`. Outline first via Frontend-First Discovery to map project scope and avoid duplicate coverage, then generate flow-based manual test cases (with a regression suite) under `.rpiv/test-cases/<feature>/`.
-- **Hand off across sessions** — `/skill:create-handoff` → (new session) `/skill:resume-handoff <doc>`. Preserves context when stopping mid-task.
-- **Onboard a fresh repo** — `/skill:annotate-guidance` once, then use the rest of the pipeline normally. Use `annotate-inline` instead if the project follows the `CLAUDE.md` convention.
+- **Form context before a task** - `/skill:discover "[topic]"` → `/skill:research <questions artifact>`. Produces a high-signal subspace of the codebase relevant to your topic, ready to feed directly into the next prompt.
+- **Compare approaches before designing** - `/skill:explore "[problem]"` → `/skill:design <solutions artifact>`. Use when multiple valid solutions exist; the solutions artifact is a first-class input to `design` alongside a `research` artifact.
+- **One-shot plan from research** - `/skill:research <questions>` → `/skill:blueprint <research artifact>` → `/skill:implement`. Fuses `design` + `plan` into a single pass with the same slice-by-slice rigor, but spawns only `codebase-pattern-finder` upfront (vs `design`'s 4-agent fan-out) by trusting the research artifact's integration/precedent sections. Use for solo work or when no one else needs to review the design before implementation; pick `design` → `plan` when the design is itself a deliverable or when research is thin and you want the fuller verification sweep.
+- **Full feature build** - `/skill:discover` → `research` → `design` → `plan` → `implement` → `validate` → (`code-review` ↔ `commit`). The default pipeline; jump in at any stage if you already have the input artifact. Review and commit are interchangeable in order - review `staged`/`working` before committing, or commit first and review the resulting branch (empty scope, first-parent vs default).
+- **Investigate a bug** - `/skill:discover "why does X fail"` → `/skill:research <questions artifact>`. Fix from the research output without writing a plan when the change is small.
+- **Adjust mid-implementation** - `/skill:revise <plan artifact>` → resume `/skill:implement`. Use when new constraints land after the plan is drafted.
+- **Review before shipping** - `/skill:code-review` ↔ `/skill:commit`. Order is your call: review `staged`/`working` before committing to catch issues at the smallest blast radius, or commit first and review the resulting branch (empty scope defaults to feature-branch-vs-default-branch, first-parent). Produces a Quality/Security/Dependencies artifact under `thoughts/shared/reviews/` with claim-verifier-grounded findings and `status: approved | needs_changes`.
+- **Audit a specific scope** - `/skill:code-review <commit|staged|working|hash|A..B|branch>`. Targeted lenses over a commit, range, staged/working tree, or PR branch; advisor adjudication applies when configured (`/advisor`).
+- **Review-driven plan revision** - `/skill:code-review` → `/skill:revise <plan artifact>` → resume `/skill:implement`. When a mid-stream review surfaces structural findings that the existing plan can't absorb as spot fixes.
+- **Scaffold manual UI test specs** - `/skill:outline-test-cases` → `/skill:write-test-cases <feature>`. Outline first via Frontend-First Discovery to map project scope and avoid duplicate coverage, then generate flow-based manual test cases (with a regression suite) under `.rpiv/test-cases/<feature>/`.
+- **Hand off across sessions** - `/skill:create-handoff` → (new session) `/skill:resume-handoff <doc>`. Preserves context when stopping mid-task.
+- **Onboard a fresh repo** - `/skill:annotate-guidance` once, then use the rest of the pipeline normally. Use `annotate-inline` instead if the project follows the `CLAUDE.md` convention.
 
 ### Skills
 
@@ -135,9 +135,9 @@ Invoke via `/skill:<name>` from inside a Pi Agent session.
 
 | Skill | Input | Output | Description |
 |---|---|---|---|
-| `discover` | — | `thoughts/shared/questions/` | Generate research questions from codebase discovery |
+| `discover` | - | `thoughts/shared/questions/` | Generate research questions from codebase discovery |
 | `research` | Questions artifact | `thoughts/shared/research/` | Answer questions via parallel analysis agents |
-| `explore` | — | `thoughts/shared/solutions/` | Compare solution approaches with pros/cons |
+| `explore` | - | `thoughts/shared/solutions/` | Compare solution approaches with pros/cons |
 | `design` | Research or solutions artifact | `thoughts/shared/designs/` | Design features via vertical-slice decomposition |
 
 #### Implementation
@@ -145,7 +145,7 @@ Invoke via `/skill:<name>` from inside a Pi Agent session.
 | Skill | Input | Output | Description |
 |---|---|---|---|
 | `plan` | Design artifact | `thoughts/shared/plans/` | Create phased implementation plans |
-| `blueprint` | Research or solutions artifact | `thoughts/shared/plans/` | Fused `design` + `plan`: vertical-slice decomposition with micro-checkpoints, emits implement-ready phased plan in one pass. Lighter on subagent fan-out than `design` — trusts the research artifact's integration/precedent sections instead of re-dispatching. Use when a separate design artifact isn't needed for review or handoff |
+| `blueprint` | Research or solutions artifact | `thoughts/shared/plans/` | Fused `design` + `plan`: vertical-slice decomposition with micro-checkpoints, emits implement-ready phased plan in one pass. Lighter on subagent fan-out than `design` - trusts the research artifact's integration/precedent sections instead of re-dispatching. Use when a separate design artifact isn't needed for review or handoff |
 | `implement` | Plan artifact | Code changes | Execute plans phase by phase |
 | `revise` | Plan artifact | Updated plan | Revise plans based on feedback |
 | `validate` | Plan artifact | Validation report | Verify plan execution |
@@ -154,15 +154,15 @@ Invoke via `/skill:<name>` from inside a Pi Agent session.
 
 | Skill | Input | Output | Description |
 |---|---|---|---|
-| `outline-test-cases` | — | `.rpiv/test-cases/` | Discover testable features with per-feature metadata |
+| `outline-test-cases` | - | `.rpiv/test-cases/` | Discover testable features with per-feature metadata |
 | `write-test-cases` | Outline metadata | Test case specs | Generate manual test specifications |
 
 #### Annotation
 
 | Skill | Input | Output | Description |
 |---|---|---|---|
-| `annotate-guidance` | — | `.rpiv/guidance/*.md` | Generate architecture guidance files |
-| `annotate-inline` | — | `CLAUDE.md` files | Generate inline documentation |
+| `annotate-guidance` | - | `.rpiv/guidance/*.md` | Generate architecture guidance files |
+| `annotate-inline` | - | `CLAUDE.md` files | Generate inline documentation |
 | `migrate-to-guidance` | CLAUDE.md files | `.rpiv/guidance/` | Convert inline docs to guidance format |
 
 #### Utilities
@@ -188,7 +188,7 @@ Invoke via `/skill:<name>` from inside a Pi Agent session.
 
 ### Agents
 
-Agents are dispatched automatically by skills via the `Agent` tool — you don't invoke them directly.
+Agents are dispatched automatically by skills via the `Agent` tool - you don't invoke them directly.
 
 | Agent | Purpose |
 |---|---|
@@ -199,7 +199,7 @@ Agents are dispatched automatically by skills via the `Agent` tool — you don't
 | `diff-auditor` | Walks a patch against a caller-supplied surface-list and emits `file:line \| verbatim \| surface-id \| note` rows |
 | `integration-scanner` | Maps inbound references, outbound dependencies, config registrations, and event subscriptions for a component |
 | `peer-comparator` | Compares a new file against a peer sibling and tags each invariant Mirrored / Missing / Diverged / Intentionally-absent |
-| `precedent-locator` | Finds similar past changes in git history — commits, blast radius, and follow-up fixes |
+| `precedent-locator` | Finds similar past changes in git history - commits, blast radius, and follow-up fixes |
 | `test-case-locator` | Catalogs existing manual test cases under `.rpiv/test-cases/` and reports coverage stats |
 | `thoughts-analyzer` | Performs deep-dive analysis on a research topic in `thoughts/` |
 | `thoughts-locator` | Discovers relevant documents in the `thoughts/` directory |
@@ -209,27 +209,27 @@ Agents are dispatched automatically by skills via the `Agent` tool — you don't
 
 ```
 rpiv-pi/
-├── extensions/rpiv-core/   — runtime extension: hooks, commands, guidance injection
-├── skills/                 — AI workflow skills (research → design → plan → implement)
-├── agents/                 — named subagent profiles dispatched by skills
-└── thoughts/shared/        — pipeline artifact store
+├── extensions/rpiv-core/   - runtime extension: hooks, commands, guidance injection
+├── skills/                 - AI workflow skills (research → design → plan → implement)
+├── agents/                 - named subagent profiles dispatched by skills
+└── thoughts/shared/        - pipeline artifact store
 ```
 
 Pi Agent discovers extensions via `"extensions": ["./extensions"]` and skills via `"skills": ["./skills"]` in `package.json`.
 
 ## Configuration
 
-- **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
-- **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)
+- **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
+- **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)
 
 ## Uninstall
 
 1. Remove rpiv-pi from Pi: `pi uninstall npm:@juicesharp/rpiv-pi`
-2. Optional — uninstall the subagent runtime if no other plugin needs it: `pi uninstall npm:@tintinweb/pi-subagents`
+2. Optional - uninstall the subagent runtime if no other plugin needs it: `pi uninstall npm:@tintinweb/pi-subagents`
 3. Restart Pi.
 
 ## Troubleshooting

package/agents/codebase-locator.md

@@ -1,6 +1,6 @@
 ---
 name: codebase-locator
-description: Locates files, directories, and components relevant to a feature or task. Call `codebase-locator` with human language prompt describing what you're looking for. Basically a "Super grep/find/ls tool" — Use it if you find yourself desiring to use one of these tools more than once.
+description: Locates files, directories, and components relevant to a feature or task. Call `codebase-locator` with a human-language prompt describing what you're looking for. A "super grep/find/ls" tool. Reach for it when you would otherwise reach for grep, find, or ls more than once.
 tools: grep, find, ls
 isolated: true
 ---

package/agents/diff-auditor.md

@@ -1,6 +1,6 @@
 ---
 name: diff-auditor
-description: "Row-only patch auditor. Walks a patch against a caller-supplied surface-list and emits one pipe-delimited row per finding — `file:line | verbatim | surface-id | note`. Use whenever a diff needs evidence-only enumeration of matching patterns, with no narrative or severity."
+description: "Row-only patch auditor. Walks a patch against a caller-supplied surface-list and emits one pipe-delimited row per finding (`file:line | verbatim | surface-id | note`). Use whenever a diff needs evidence-only enumeration of matching patterns, with no narrative or severity."
 tools: read, grep, find, ls
 isolated: true
 ---

package/agents/integration-scanner.md

@@ -1,6 +1,6 @@
 ---
 name: integration-scanner
-description: Finds what connects to a given component or area — inbound references, outbound dependencies, config registrations, event subscriptions. The reverse-reference counterpart to codebase-locator. Use when you need to understand what calls, depends on, or wires into a component.
+description: "Finds what connects to a given component or area: inbound references, outbound dependencies, config registrations, event subscriptions. The reverse-reference counterpart to codebase-locator. Use when you need to understand what calls, depends on, or wires into a component."
 tools: grep, find, ls
 isolated: true
 ---

package/agents/precedent-locator.md

@@ -1,6 +1,6 @@
 ---
 name: precedent-locator
-description: Finds similar past changes in git history — commits, blast radius, follow-up fixes, and lessons from related thoughts/ docs. Use when planning a change and you need to know what went wrong last time something similar was done.
+description: "Finds similar past changes in git history: commits, blast radius, follow-up fixes, and lessons from related thoughts/ docs. Use when planning a change and you need to know what went wrong last time something similar was done."
 tools: bash, grep, find, read, ls
 isolated: true
 ---

package/agents/test-case-locator.md

@@ -1,6 +1,6 @@
 ---
 name: test-case-locator
-description: Finds existing manual test cases in .rpiv/test-cases/ — catalogs by module, extracts frontmatter metadata (id, priority, status, tags), and reports coverage stats. Use before generating test cases to avoid duplicates, or to audit what test coverage already exists in a project.
+description: "Finds existing manual test cases in .rpiv/test-cases/. Catalogs them by module, extracts frontmatter metadata (id, priority, status, tags), and reports coverage stats. Use before generating new test cases to avoid duplicates, or to audit what test coverage already exists in a project."
 tools: grep, find, ls
 isolated: true
 ---

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

@@ -63,7 +63,10 @@ describe("injectRootGuidance", () => {
 		const { pi } = createMockPi();
 		injectRootGuidance(projectDir, pi);
 		expect(pi.sendMessage).toHaveBeenCalledTimes(1);
-		expect((pi.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0].content).toContain("body");
+		const content = (pi.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0].content;
+		expect(content).toContain("body");
+		expect(content).toContain("reference material, NOT a task");
+		expect(content).toContain("auto-loaded at session start");
 	});
 
 	it("is idempotent across calls within a session", () => {
@@ -132,5 +135,6 @@ describe("handleToolCallGuidance", () => {
 		const content = (pi.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0].content;
 		expect(content).toContain("root");
 		expect(content).toContain("src");
+		expect(content).toContain("auto-loaded because write touched src/x.ts");
 	});
 });

package/extensions/rpiv-core/guidance.ts

@@ -139,15 +139,10 @@ export function injectRootGuidance(cwd: string, pi: ExtensionAPI): void {
 	}
 	injectedGuidance.add(relativePath);
 
-	const label = formatLabel({
-		relativePath,
-		absolutePath,
-		content,
-		kind: "architecture",
-	});
+	const file: GuidanceFile = { relativePath, absolutePath, content, kind: "architecture" };
 	pi.sendMessage({
 		customType: MSG_TYPE_GUIDANCE,
-		content: `## Project Guidance: ${label}\n\n${content}`,
+		content: wrapGuidance(formatLabel(file), content, "auto-loaded at session start"),
 		display: !!pi.getFlag(FLAG_DEBUG),
 	});
 }
@@ -181,7 +176,8 @@ export function handleToolCallGuidance(
 		injectedGuidance.add(g.relativePath);
 	}
 
-	const contextParts = newFiles.map((g) => `## Project Guidance: ${formatLabel(g)}\n\n${g.content}`);
+	const trigger = `auto-loaded because ${event.toolName} touched ${shortenPath(filePath, ctx.cwd)}`;
+	const contextParts = newFiles.map((g) => wrapGuidance(formatLabel(g), g.content, trigger));
 
 	pi.sendMessage({
 		customType: MSG_TYPE_GUIDANCE,
@@ -190,6 +186,35 @@ export function handleToolCallGuidance(
 	});
 }
 
+/**
+ * Wrap guidance content in a non-task envelope. The opening disclaimer tells
+ * the agent this block is reference material — not an instruction — and states
+ * the trigger so the agent can judge whether the block is relevant to the
+ * current user request. Heading is `## Architecture Guidance:` to match the
+ * `PreToolUse:Read` hook output and the actual content (architecture.md).
+ */
+function wrapGuidance(label: string, content: string, trigger: string): string {
+	return [
+		`[rpiv-guidance — reference material, NOT a task. ${trigger}.`,
+		`Consult only if directly relevant to the user's current request; otherwise ignore.]`,
+		"",
+		`## Architecture Guidance: ${label}`,
+		"",
+		content,
+	].join("\n");
+}
+
+/**
+ * Render a project-relative, forward-slash-normalized path for the trigger
+ * disclaimer. Falls back to the absolute path if the file lives outside the
+ * project root (defensive — `handleToolCallGuidance` already short-circuits
+ * via `resolveGuidance` in that case, so this branch is unreachable today).
+ */
+function shortenPath(filePath: string, cwd: string): string {
+	const r = relative(cwd, filePath);
+	return r && !r.startsWith("..") ? r.split(sep).join("/") : filePath;
+}
+
 /**
  * Format a guidance file's heading label.
  *   extensions/rpiv-core/AGENTS.md          → "extensions/rpiv-core (AGENTS.md)"

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

@@ -142,6 +142,25 @@ describe("session_start hook — notifications", () => {
 	});
 });
 
+describe("session_compact hook", () => {
+	it("re-injects guidance + git-context after compaction (clears caches first)", async () => {
+		const exec = stubGitExec({ branch: "main", commit: "abc", user: "alice" });
+		const { pi, captured } = createMockPi({ exec: exec as never });
+		registerSessionHooks(pi);
+		// Prime the git-context cache first via session_start so compact's clear has work to do.
+		await captured.events.get("session_start")?.[0](
+			{ reason: "startup" } as never,
+			createMockCtx({ cwd: projectDir, hasUI: false }) as never,
+		);
+		const sendBefore = (pi.sendMessage as ReturnType<typeof vi.fn>).mock.calls.length;
+		await captured.events.get("session_compact")?.[0]({} as never, createMockCtx({ cwd: projectDir }) as never);
+		// After compact, the next pi.sendMessage call (from injectGitContext) should fire because
+		// resetInjectedMarker + clearGitContextCache make takeGitContextIfChanged re-emit.
+		const sendAfter = (pi.sendMessage as ReturnType<typeof vi.fn>).mock.calls.length;
+		expect(sendAfter).toBeGreaterThan(sendBefore);
+	});
+});
+
 describe("session_shutdown hook", () => {
 	it("clears git-context cache and allows takeGitContextIfChanged to re-emit", async () => {
 		const exec = stubGitExec({ branch: "main", commit: "abc", user: "alice" });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "1.1.3",
-  "description": "Skill-based development workflow for Pi Agent — discover, research, design, plan, implement, validate",
+  "version": "1.1.5",
+  "description": "A skill-based development workflow for Pi Agent. Six skills (discover, research, design, plan, implement, validate) and the shared subagents that compose its ship-loop.",
   "keywords": [
     "pi-package",
     "pi-extension",

package/skills/annotate-guidance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: annotate-guidance
-description: Generate architecture.md guidance files in .rpiv/guidance/ by analyzing architecture and patterns in parallel. Auto-detects architecture, proposes locations, and batch-writes compact documentation. Use for onboarding or improving AI assistant context.
+description: Generate architecture.md guidance files under .rpiv/guidance/ that document a project's architecture and patterns for AI assistants, written to a shadow tree alongside the source. Use when the user wants to onboard Claude, Cursor, or an AI agent to a codebase via the guidance system, document architecture, or asks to "annotate guidance". Prefer this over annotate-inline when the project uses the .rpiv/guidance/ shadow tree instead of inline CLAUDE.md files.
 argument-hint: [target-directory]
 allowed-tools: Agent, Read, Write, Glob, Grep
 ---

package/skills/annotate-inline/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: annotate-inline
-description: Generate CLAUDE.md files across a project by analyzing architecture and patterns in parallel. Auto-detects architecture, proposes locations, and batch-writes compact documentation. Use for onboarding or improving AI assistant context.
+description: Generate CLAUDE.md files placed inline next to source code across a project, documenting architecture and patterns for AI assistants. Use when the user wants to onboard Claude to a codebase via inline CLAUDE.md files, generate per-directory guidance, document architecture in-place, or asks to "annotate inline". Prefer this over annotate-guidance when CLAUDE.md should live alongside the code rather than in a shadow tree.
 argument-hint: [target-directory]
 allowed-tools: Agent, Read, Write, Glob, Grep
 ---

package/skills/blueprint/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: blueprint
-description: Plan features through iterative vertical-slice decomposition and progressive code generation with developer micro-checkpoints. One slice = one phase. For complex multi-component features touching 6+ files across multiple layers. Produces implement-ready phased plans in thoughts/shared/plans/. Always requires a research artifact from discover → research, or a solutions artifact from explore.
+description: Plan complex features by decomposing them into vertical slices (one slice equals one phase) with developer micro-checkpoints between phases, producing an implement-ready phased plan in thoughts/shared/plans/. Use for complex multi-component features touching 6+ files across multiple layers when iterative review between slices is valuable. Requires a research artifact (from discover then research) or a solutions artifact (from explore). Prefer blueprint over plan when mid-flight micro-checkpoints matter, and prefer plan when a straightforward phased breakdown is enough.
 argument-hint: [research artifact path]
 ---
 

package/skills/code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-review
-description: "Conduct comprehensive code reviews using specialist row-only agents (diff-auditor at Wave-2 Q+S, peer-comparator at Wave-1 PM, claim-verifier at Step 6) plus orchestrator-side Gap-Finder (set arithmetic, no agent). Row-only contracts structurally resist narrativisation. Produces review documents in thoughts/shared/reviews/."
+description: "Conduct comprehensive code reviews of pending changes, a branch, or a PR using parallel specialist agents that audit the diff, compare against peer code, and verify claims. Use when the user asks to 'review this', wants pending changes, a PR, a branch, or a diff reviewed, or asks for a code review. Produces review documents in thoughts/shared/reviews/. Internal mechanics like row-only agent contracts and Gap-Finder set arithmetic are documented in the skill body."
 argument-hint: "[scope]"
 ---
 

package/skills/commit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: commit
-description: Create structured git commits. Groups related changes logically with clear, descriptive messages. Use when code changes are ready to commit.
+description: Create structured git commits by analyzing staged and unstaged changes and grouping them logically into one or more commits with clear, descriptive messages. Use when the user asks to commit, says "commit this" or "commit my changes", wants help writing a commit message, or has finished a chunk of work that needs committing.
 argument-hint: [message]
 allowed-tools: Bash(git *), Read, Glob, Grep
 ---

package/skills/create-handoff/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-handoff
-description: Create context-preserving handoff documents for session transitions. Compacts essential context into concise documents. Use when context is getting large or before starting a fresh session.
+description: Create a context-preserving handoff document for session transitions, compacting the current task, decisions made, in-flight changes, and open questions into a single concise file so a fresh session can pick up where this one left off. Use when the user invokes /create-handoff, says context is getting large, asks to wrap up the session, or wants to hand off work to another session.
 argument-hint: [description]
 allowed-tools: Read, Write, Bash(git *), Glob, Grep
 disable-model-invocation: true

package/skills/design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design
-description: Design features through iterative vertical-slice decomposition and progressive code generation with developer micro-checkpoints. For complex multi-component features touching 6+ files across multiple layers. Produces design artifacts in thoughts/shared/designs/. Always requires a research artifact from discover → research, or a solutions artifact from explore.
+description: Design complex features by decomposing them into vertical slices and producing a design artifact (architecture decisions, slice breakdown, file map) in thoughts/shared/designs/. The design feeds the plan or blueprint skill. Use for complex multi-component features touching 6+ files across multiple layers, when the user wants a feature designed before implementation. Requires a research artifact (from discover then research) or a solutions artifact (from explore). Prefer design over plan or blueprint when the focus is architecture and decomposition rather than phased execution steps.
 argument-hint: [research artifact path]
 ---
 

package/skills/discover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: discover
-description: Generate trace-quality research questions from codebase discovery. Spawns discovery agents and reads key files for depth, then synthesizes into dense question paragraphs for the research skill. Produces question artifacts in thoughts/shared/questions/. First stage of the research pipeline.
+description: Generate structured research questions for a feature or change area by exploring the codebase in parallel and reading key files for depth, then synthesizing dense question paragraphs for the research skill to consume. First stage of the two-phase research pipeline. Use when the user wants to deeply understand a codebase area before changes, asks to "discover" or "explore questions", or needs research questions formulated for a ticket or task. Produces question artifacts in thoughts/shared/questions/.
 argument-hint: [research question or task/ticket description]
 ---
 

package/skills/explore/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: explore
-description: Analyze solution options for features or changes. Compares approaches with pros/cons and provides recommendations. Produces documents in thoughts/shared/solutions/. Use when multiple valid approaches exist.
+description: Analyze solution options for a feature or change, comparing approaches with pros, cons, trade-offs, and a recommended path. Use when the user is weighing approaches, asks "what are the options" or "how should we approach X", wants approaches compared, says "explore solutions", or faces a decision with multiple valid implementations. Produces solutions documents in thoughts/shared/solutions/, which can feed the design skill.
 argument-hint: [feature/change description]
 ---
 

package/skills/implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: implement
-description: Execute approved implementation plans phase by phase. Implements changes with verification against success criteria. Use when a plan is ready for implementation.
+description: Execute an approved implementation plan from thoughts/shared/plans/ phase by phase, applying changes and verifying each phase against its success criteria before moving on. Use when the user invokes /implement, asks to "implement this plan", or wants an existing phased plan executed. Pair with revise to update plans mid-flight and validate to confirm completion.
 argument-hint: "[plan-path] [Phase N]"
 allowed-tools: Read, Edit, Write, Bash(*), Glob, Grep
 disable-model-invocation: true

package/skills/migrate-to-guidance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: migrate-to-guidance
-description: Migrate existing CLAUDE.md files to .rpiv/guidance/ system. Finds all CLAUDE.md files, transforms references, and creates architecture.md files in the guidance shadow tree.
+description: Migrate a project's inline CLAUDE.md files to the .rpiv/guidance/ shadow-tree system. Finds every CLAUDE.md, transforms internal references, and creates equivalent architecture.md files under .rpiv/guidance/. Use when the user wants to move from inline CLAUDE.md to the guidance shadow tree, consolidate scattered CLAUDE.md files into one place, or invokes /migrate-to-guidance.
 argument-hint: [--delete-originals]
 allowed-tools: Bash, Read, Glob
 ---

package/skills/outline-test-cases/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: outline-test-cases
-description: Discover testable features via Frontend-First Discovery and create a folder outline under .rpiv/test-cases/ with per-feature metadata. Incremental runs use existing outlines as context for smarter discovery and diff-based checkpoints. Use before write-test-cases to map project scope.
+description: Discover testable features in a project (frontend-first) and create a folder outline under .rpiv/test-cases/ with per-feature metadata. Incremental runs reuse the existing outline for smarter discovery and diff-based checkpoints. Use before write-test-cases to map project scope, when the user wants to plan or inventory test coverage, asks to "outline test cases", or wants a test-case scaffold generated for a project.
 argument-hint: [target-directory]
 allowed-tools: Agent, Read, Write, Edit, Glob, Grep
 ---

package/skills/plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan
-description: Create phased implementation plans from design artifacts. Decomposes designs into parallelized atomic phases with success criteria in thoughts/shared/plans/. Use after design.
+description: Convert a design artifact into a phased implementation plan with parallelized atomic phases and explicit success criteria, written to thoughts/shared/plans/. Use after the design skill when the user wants a design turned into an actionable, phase-by-phase plan to hand to the implement skill. Prefer plan when a straightforward phased breakdown is sufficient, and prefer blueprint when iterative vertical-slice micro-checkpoints between phases are needed.
 argument-hint: [design artifact path]
 ---
 

package/skills/research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: research
-description: Answer structured research questions via targeted parallel analysis agents. Accepts either a questions artifact from discover OR a free-text prompt/task (in which case it auto-runs discover via an Agent). Produces research documents in thoughts/shared/research/.
+description: Answer structured research questions about a codebase using targeted parallel analysis agents, then synthesize findings into a research document in thoughts/shared/research/. Accepts either a questions artifact from discover OR a free-text prompt (auto-runs discover first). Use when the user wants in-depth research on a codebase area, asks to "research X", needs answers to architecture or behavior questions before designing changes, or has a discover artifact ready to consume.
 argument-hint: [path to discover artifact | free-text research prompt]
 ---
 

package/skills/resume-handoff/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: resume-handoff
-description: Resume work from a handoff document. Reads handoff, verifies current state, and continues implementation. Use at the start of a new session to pick up where you left off.
+description: Resume work from a handoff document produced by create-handoff. Reads the handoff, verifies current repo, branch, and state, and continues from where the previous session left off. Use at the start of a new session when the user references a handoff file, says "resume from handoff", "continue from where we left off", or invokes /resume-handoff.
 argument-hint: [handoff-path]
 ---
 

package/skills/revise/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: revise
-description: Update existing implementation plans based on feedback. Makes surgical edits while preserving structure and quality. Use when plans need adjustments after review or during implementation.
+description: Surgically update an existing implementation plan in thoughts/shared/plans/ based on review feedback, mid-implementation discoveries, or new constraints, preserving structure and quality rather than rewriting. Use when the user wants a plan adjusted after code-review feedback, has hit a blocker mid-implement, scope changed, or asks to "revise the plan".
 argument-hint: "[plan-path] [feedback]"
 ---
 

package/skills/validate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: validate
-description: Verify that an implementation plan was correctly executed. Runs success criteria checks and generates validation reports. Use after implementation is complete.
+description: Verify that an implementation plan was correctly executed by running each phase's success criteria against the working tree and producing a validation report. Use after the implement skill completes, when the user asks to "validate the plan", wants a post-implementation audit, or needs to confirm a feature is fully shipped per its plan.
 argument-hint: [plan-path]
 allowed-tools: Read, Bash(git *), Bash(make *), Glob, Grep, Agent
 ---

package/skills/write-test-cases/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: write-test-cases
-description: Generate manual test case specifications for a single feature by analyzing code in parallel. Consumes outline-test-cases _meta.md when available for warm-start. Produces flow-based test cases with regression suite and project-wide coverage map. Outputs to .rpiv/test-cases/{feature}/ in the target project.
+description: Generate manual test-case specifications for a single feature by analyzing the implementing code in parallel, producing flow-based test cases plus a regression suite and project-wide coverage map under .rpiv/test-cases/{feature}/. Consumes an outline-test-cases _meta.md when available for warm-start. Use when the user wants test cases written for a specific feature, asks for QA specs, or has run outline-test-cases and is ready to flesh out a feature.
 argument-hint: "[feature name, component path, feature slug, or _meta.md path] [additional instructions]"
 ---