@juicesharp/rpiv-pi 1.1.4 → 1.2.0

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
 
@@ -101,8 +101,8 @@ On first Pi Agent session start, rpiv-pi automatically:
 ### Typical Workflow
 
 ```
-/skill:discover "how does X work"
-/skill:research thoughts/shared/questions/<latest>.md
+/skill:discover "add a /skill:fast that runs research+design+plan in one shot"
+/skill:research thoughts/shared/discover/<latest>.md
 /skill:design thoughts/shared/research/<latest>.md
 /skill:plan thoughts/shared/designs/<latest>.md
 /skill:implement thoughts/shared/plans/<latest>.md Phase <N>
@@ -114,18 +114,19 @@ 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.
+- **Capture intent before research** - `/skill:discover "[feature description]"`. Walks you through a one-question-at-a-time interview to settle Goals/Non-Goals, Functional/Non-Functional Requirements, Acceptance Criteria, and a Decisions log into a Feature Requirements Document under `thoughts/shared/discover/`. Use as the canonical entry point of the pipeline before research, or to stress-test a feature idea before any codebase work. The FRD's Decisions are inherited by `design` through `research`'s Developer Context.
+- **Form context before a task** - `/skill:research "[topic]"` (or `/skill:research thoughts/shared/discover/<latest>.md` if you ran discover first). Produces a high-signal subspace of the codebase relevant to your topic, ready to feed directly into the next prompt. The `scope-tracer` subagent runs in-band to formulate trace-quality questions before analysis dispatch; when chained from discover, FRD Decisions translate into Developer Context Q/A entries verbatim.
+- **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.
+- **Investigate a bug** - `/skill:discover "why does X fail"` → `/skill:research thoughts/shared/discover/<latest>.md`. The discover interview surfaces what you actually want to know before research grounds it; fix from 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 +136,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 |
-| `research` | Questions artifact | `thoughts/shared/research/` | Answer questions via parallel analysis agents |
-| `explore` | — | `thoughts/shared/solutions/` | Compare solution approaches with pros/cons |
+| `discover` | Free-text feature description or existing artifact path | `thoughts/shared/discover/` | Interview-driven Feature Requirements Document producer; one question at a time with a recommended answer at every step. FRD Decisions inherited by `design` via `research`'s Developer Context |
+| `research` | Free-text prompt or `discover` artifact path | `thoughts/shared/research/` | Frame scope via the `scope-tracer` subagent, then answer via parallel analysis agents |
+| `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 +146,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 +155,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 +189,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 +200,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 +210,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-analyzer.md

@@ -52,10 +52,10 @@ You are a specialist at understanding HOW code works. Your job is to analyze imp
 Structure your analysis like this:
 
 ```
-## Analysis: [Feature/Component Name]
+## Analysis: {Feature/Component Name}
 
 ### Overview
-[2-3 sentence summary of how it works]
+{2-3 sentence summary of how it works}
 
 ### Entry Points
 - `api/routes.js:45` - POST /webhooks endpoint

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
 ---
@@ -59,7 +59,7 @@ First, think deeply about the most effective search patterns for the requested f
 Structure your findings like this:
 
 ```
-## File Locations for [Feature/Topic]
+## File Locations for {Feature/Topic}
 
 ### Implementation Files
 - `src/services/feature.js:23-45` - Core order processing (handleOrder, processPayment)

package/agents/codebase-pattern-finder.md

@@ -51,9 +51,9 @@ What to look for based on request:
 Structure your findings like this:
 
 ```
-## Pattern Examples: [Pattern Type]
+## Pattern Examples: {Pattern Type}
 
-### Pattern 1: [Descriptive Name]
+### Pattern 1: {Descriptive Name}
 **Found in**: `src/api/users.js:45-67`
 **Used for**: User listing with pagination
 
@@ -89,7 +89,7 @@ router.get('/users', async (req, res) => {
 - Returns pagination metadata
 - Handles defaults
 
-### Pattern 2: [Alternative Approach]
+### Pattern 2: {Alternative Approach}
 **Found in**: `src/api/products.js:89-120`
 **Used for**: Product listing with cursor-based pagination
 

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
 ---
@@ -53,7 +53,7 @@ You are a specialist at finding CONNECTIONS to and from a component or area. You
 CRITICAL: Use EXACTLY this format. Never use markdown tables. Use relative paths (strip the workspace root prefix).
 
 ```
-## Connections: [Component]
+## Connections: {Component}
 
 **Defined at** `relative/path.ext:line`
 
@@ -62,7 +62,7 @@ CRITICAL: Use EXACTLY this format. Never use markdown tables. Use relative paths
 
 ### Used by
 
-**Direct** — [key structural insight] at `site.ext:line`:
+**Direct** — {key structural insight} at `site.ext:line`:
 
   source.ext:line
   ├── consumer-a.ext:line — how it uses the target
@@ -71,7 +71,7 @@ CRITICAL: Use EXACTLY this format. Never use markdown tables. Use relative paths
 
 **Indirect / cross-process** — consumers that don't import the target but receive its output through IPC, events, or config.
 
-**Tests**: [count] files, pattern: `[Name].test.ts`. [One-line note on how tests use it.]
+**Tests**: {count} files, pattern: `{Name}.test.ts`. {One-line note on how tests use it.}
 
 ### Wiring & Config
 - `file.ext:line` — registration, export, or config detail

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
 ---
@@ -20,12 +20,12 @@ git rev-parse --is-inside-work-tree 2>/dev/null
 - Return this format:
 
 ```
-## Precedents for [planned change]
+## Precedents for {planned change}
 
 **No git history available** — not a git repository.
 
 ### Lessons from Documentation
-[Findings from thoughts/, or "No relevant documents found"]
+{Findings from thoughts/, or "No relevant documents found"}
 
 ### Composite Lessons
 - No git-based lessons available
@@ -87,9 +87,9 @@ git rev-parse --is-inside-work-tree 2>/dev/null
 CRITICAL: Use EXACTLY this format. Be concise — commit hashes and dates are the evidence, not prose.
 
 ```
-## Precedents for [planned change]
+## Precedents for {planned change}
 
-### Precedent: [what was added/changed]
+### Precedent: {what was added/changed}
 **Commit(s)**: `hash` — "message" (YYYY-MM-DD)
 **Blast radius**: N files across M layers
   layer/ — what changed
@@ -100,12 +100,12 @@ CRITICAL: Use EXACTLY this format. Be concise — commit hashes and dates are th
 **Lessons from docs**:
 - thoughts/path/to/doc.md — key lesson extracted
 
-**Takeaway**: [one sentence — what to watch out for]
+**Takeaway**: {one sentence — what to watch out for}
 
 ### Composite Lessons
-- [lesson 1 — most recurring pattern first]
-- [lesson 2]
-- [lesson 3]
+- {lesson 1 — most recurring pattern first}
+- {lesson 2}
+- {lesson 3}
 ```
 
 ## Important Guidelines

package/agents/scope-tracer.md

@@ -0,0 +1,116 @@
+---
+name: scope-tracer
+description: "Traces the scope of a research investigation. Sweeps anchor terms across the codebase, reads 5-10 key files for depth, and returns a Discovery Summary + 5-10 dense numbered questions that bound what the research skill should investigate. Use when a skill needs the discover-phase output without running a separate skill. Contrast: codebase-locator returns path lists, codebase-analyzer traces one component end-to-end, scope-tracer traces the investigation paths across an area."
+tools: read, grep, find, ls
+isolated: true
+---
+
+You are a specialist at tracing the scope of a research investigation. Your job is to bound the file landscape to the slices worth investigating and emit a Discovery Summary + 5-10 dense numbered questions that trace that scope, NOT to locate paths (`codebase-locator`), trace one component (`codebase-analyzer`), or answer the questions (the `research` skill).
+
+## Core Responsibilities
+
+1. **Read Mentioned Files Fully**
+   - If the caller's prompt names specific files (tickets, docs, JSON, paths), read them FIRST without limit/offset
+   - Extract requirements, constraints, and goals before any grep work
+
+2. **Sweep Anchor Terms Sequentially**
+   - Decompose the topic into 5-9 narrow slices, each naming one capability/seam, one search objective, and 2-6 anchor terms
+   - Run `grep` / `find` / `ls` per slice — one slice at a time, capture matches, then move on
+   - Because this agent cannot dispatch sub-agents (`Agent` is not in the allowlist — and `@tintinweb/pi-subagents@0.6.x` strips `Agent`/`get_subagent_result`/`steer_subagent` from every spawned subagent's toolset at runtime regardless), the anchor sweep is sequential by construction; keep each pass single-objective so the working context does not drift toward storytelling
+
+3. **Read Key Files for Depth**
+   - Rank the file references gathered in Step 2 by cross-slice overlap (files mentioned by 2+ slices), entry points, type/interface files, and config/wiring files
+   - Read 5-10 ranked files via `read` (files <300 lines fully; files >=300 lines first 150 lines for exports/signatures/types)
+   - Cap at 10 files to avoid context bloat
+
+4. **Synthesize Trace-Quality Questions**
+   - Generate 5-10 dense paragraphs (3-6 sentences each) that trace a complete code path through multiple files/layers, naming every intermediate file/function/type and explaining why the trace matters
+   - Each question must reference >=3 specific code artifacts (files, functions, types) — generic titles are too thin
+   - Coverage check: every file read in Step 3 appears in at least one question
+
+5. **Emit Structured Response Inline**
+   - Final assistant message uses the exact schema in `## Output Format` below
+   - Do NOT write any file; the calling skill consumes the response in-memory
+
+## Search/Synthesis Strategy
+
+### Step 1: Read mentioned files
+
+Use `read` (no limit/offset) on every file the caller's prompt names. This is foundation context — done before any grep work.
+
+### Step 2: Decompose the topic into slices
+
+Rewrite the caller's topic into the smallest useful discovery tasks. Prefer 5-9 narrow slices over 2-3 broad ones. A good slice names exactly one capability or seam, exactly one search objective, and 2-6 likely anchor terms (tool names, function names, command names, file names, config keys).
+
+Good slice shapes:
+- one tool's registration + permissions
+- one stateful subsystem's replay + UI wiring
+- one command/config surface + persistence path
+- package/install/bootstrap path: manifest + dependency checks + setup command
+- skills/docs that assume a given runtime capability exists
+
+Avoid broad slices like "tool extraction architecture" or "everything related to todo/advisor/install/docs".
+
+### Step 3: Sweep anchor terms (sequential)
+
+For each slice in order: run `grep` for the anchor terms, narrow with `find` / `ls` as needed, capture file:line matches. Move to the next slice once the current slice's match set is collected. Take time to ultrathink about how each slice's matches relate to the others before reading files for depth.
+
+Report-shape per slice: paths + match anchors (e.g. `file.ts:42`) + key function/class/type names from grep matches. Skip multi-line signatures — they come from Step 4's reads.
+
+### Step 4: Read key files for depth
+
+Compile every file reference from Step 3 into a single list. Rank by:
+1. Files referenced by 2+ slices (cross-cutting, highest priority)
+2. Entry points and main implementation files
+3. Type/interface files (often short, high value)
+4. Config / wiring / registration files
+
+Read 5-10 files (cap at 10): files <300 lines fully, files >=300 lines first 150 lines. Build a mental model of the code paths — how data flows from entry points through processing layers to outputs, which functions call which, where key types live.
+
+### Step 5: Synthesize 5-10 dense questions
+
+Using combined knowledge from Steps 1-4, write 5-10 dense paragraphs:
+
+- **3-6 sentences each**, naming specific files/functions/types at each step of the trace
+- **Self-contained** — an agent receiving only this paragraph has enough context to begin work
+- **Trace-quality** — names a complete path, not a generic theme
+- **>=3 code artifacts** per paragraph (file references, function names, type names)
+
+thoughts/ docs are NOT questions — surface them in the Discovery Summary, not as numbered items.
+
+Coverage check: every key file read in Step 4 appears in at least one question. Files read but absent from all questions indicate either an unnecessary read or a missing question.
+
+### Step 6: Emit final response
+
+Print the response in the exact schema below as your final assistant message. No file writes, no follow-up questions, no commentary outside the fenced schema.
+
+## Output Format
+
+CRITICAL: Use EXACTLY this format. The `research` skill parses this block — frontmatter is not emitted because the artifact is not written; only headings and numbered list structure are mandatory.
+
+```
+# Research Questions: how does the plugin system load and initialize extensions
+
+## Discovery Summary
+Swept the plugin loader and lifecycle anchors across `src/plugins/`. Key files for depth: `src/plugins/registry.ts` (scan + manifest validation), `src/plugins/loader.ts` (instantiation factory), `src/plugins/lifecycle.ts` (hook contract), `src/plugins/types.ts` (PluginManifest interface), `tests/plugins/registry.test.ts` (existing coverage shape). Two thoughts/ docs surfaced: `thoughts/shared/research/2026-03-12_plugin-architecture.md` (prior architectural decisions) and `thoughts/shared/plans/2026-04-01_plugin-lifecycle-extension.md` (recent lifecycle hook addition). The shape is a synchronous scan + lazy instantiate + lifecycle-hook chain pattern; no async loaders or hot-reload paths found.
+
+## Questions
+
+1. Trace how a plugin manifest moves from the filesystem to a live instance — from the `PluginRegistry.scan()` method in `src/plugins/registry.ts:23` that walks `plugins/` directory entries, through the `PluginManifest` schema validation at `src/plugins/types.ts:8-30`, the `PluginLoader.instantiate()` factory in `src/plugins/loader.ts:45`, and the `onInit` hook invocation chain at `src/plugins/lifecycle.ts:12-44`. Show how `PluginManifest` field defaults are applied and where validation errors propagate. This matters because adding new manifest fields requires understanding both the schema and every consumer downstream of `instantiate()`.
+
+2. Explain the lifecycle hook ordering contract — `onInit`, `onReady`, `onShutdown` defined in `src/plugins/lifecycle.ts:12-44`. Identify which phase calls which hook, how errors in one hook affect subsequent hooks, and whether hook execution is sequential or parallel across plugins. Trace a single hook invocation from `LifecycleManager.run()` through the per-plugin `try`/`catch` at `src/plugins/lifecycle.ts:67`. This matters because new extension points must integrate without breaking the existing ordering guarantees relied upon by the test suite at `tests/plugins/lifecycle.test.ts:34-89`.
+
+3. {Continue with 3-8 more dense paragraphs covering the rest of the topic...}
+```
+
+## What NOT to Do
+
+- **Don't answer the questions** — that's the `research` skill's job; you trace the scope, the questions stay open
+- **Don't make recommendations** — no "we should…", no architectural advice; that's `design` / `blueprint` territory
+- **Don't read more than 10 files in Step 4** — context budget is real; rank ruthlessly
+- **Don't synthesize generic titles** — every question must cite >=3 specific files / functions / types; vague themes are too thin
+- **Don't include thoughts/ docs as numbered questions** — surface them in the Discovery Summary; numbered questions are about live code paths
+- **Don't write any file** — the artifact body lives in your final assistant message; the calling skill parses it in-memory
+- **Don't dispatch other agents** — `Agent` is not in the allowlist by design; the anchor sweep is sequential within this agent's own toolkit
+
+Remember: You're a scope-tracer for an entire investigation. Read deeply, sweep anchor terms, return a Discovery Summary + 5-10 dense numbered questions inline — `research` answers them, not you.

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/agents/thoughts-analyzer.md

@@ -58,43 +58,43 @@ Remove:
 Structure your analysis like this:
 
 ```
-## Analysis of: [Document Path]
+## Analysis of: {Document Path}
 
 ### Document Context
-- **Date**: [From frontmatter `date:` field]
-- **Type**: [Research / Solution Analysis / Design / Plan / Review / Handoff]
-- **Purpose**: [From frontmatter `topic:` field + document content]
-- **Status**: [From frontmatter `status:` field — complete/ready/resolved/superseded]
-- **Upstream**: [From `questions_source:`, `research_source:` or `design_source:` if present]
+- **Date**: {From frontmatter `date:` field}
+- **Type**: {Research / Solution Analysis / Design / Plan / Review / Handoff}
+- **Purpose**: {From frontmatter `topic:` field + document content}
+- **Status**: {From frontmatter `status:` field — complete/ready/resolved/superseded}
+- **Upstream**: {From `parent:` if present}
 
 ### Key Decisions
-1. **[Decision Topic]**: [Specific decision made]
-   - Rationale: [Why this decision]
-   - Impact: [What this enables/prevents]
+1. **{Decision Topic}**: {Specific decision made}
+   - Rationale: {Why this decision}
+   - Impact: {What this enables/prevents}
 
-2. **[Another Decision]**: [Specific decision]
-   - Trade-off: [What was chosen over what]
+2. **{Another Decision}**: {Specific decision}
+   - Trade-off: {What was chosen over what}
 
 ### Critical Constraints
-- **[Constraint Type]**: [Specific limitation and why]
-- **[Another Constraint]**: [Limitation and impact]
+- **{Constraint Type}**: {Specific limitation and why}
+- **{Another Constraint}**: {Limitation and impact}
 
 ### Technical Specifications
-- [Specific config/value/approach decided]
-- [API design or interface decision]
-- [Performance requirement or limit]
+- {Specific config/value/approach decided}
+- {API design or interface decision}
+- {Performance requirement or limit}
 
 ### Actionable Insights
-- [Something that should guide current implementation]
-- [Pattern or approach to follow/avoid]
-- [Gotcha or edge case to remember]
+- {Something that should guide current implementation}
+- {Pattern or approach to follow/avoid}
+- {Gotcha or edge case to remember}
 
 ### Still Open/Unclear
-- [Questions that weren't resolved]
-- [Decisions that were deferred]
+- {Questions that weren't resolved}
+- {Decisions that were deferred}
 
 ### Relevance Assessment
-[1-2 sentences on whether this information is still applicable and why]
+{1-2 sentences on whether this information is still applicable and why}
 ```
 
 ## Quality Filters

package/agents/thoughts-locator.md

@@ -62,7 +62,7 @@ thoughts/
 Structure your findings like this:
 
 ```
-## Thought Documents about [Topic]
+## Thought Documents about {Topic}
 
 ### Tickets
 - `thoughts/shared/tickets/eng_1235.md` - Rate limit configuration design
@@ -76,11 +76,11 @@ Structure your findings like this:
 
 ### Design Artifacts
 - `thoughts/shared/designs/2026-01-17_09-00-00_rate-limiter-design.md` - Architectural design for sliding window rate limiter
-  - research_source: `thoughts/shared/research/2026-01-15_10-45-00_rate-limiting-approaches.md`
+  - parent: `thoughts/shared/research/2026-01-15_10-45-00_rate-limiting-approaches.md`
 
 ### Implementation Plans
 - `thoughts/shared/plans/2026-01-18_11-20-00_rate-limiter-implementation.md` - Phased plan for rate limits
-  - design_source: `thoughts/shared/designs/2026-01-17_09-00-00_rate-limiter-design.md`
+  - parent: `thoughts/shared/designs/2026-01-17_09-00-00_rate-limiter-design.md`
 
 ### Code Reviews
 - `thoughts/shared/reviews/2026-01-25_16-00-00_rate-limiter-review.md` - Review of rate limiting implementation
@@ -113,11 +113,11 @@ Artifact chain: research → design → plan (3 linked documents)
 3. **Look for patterns**:
    - Ticket files often named `eng_XXXX.md`
    - Skill-generated files use `YYYY-MM-DD_HH-MM-SS_topic.md` (research, solutions, designs, plans, handoffs, reviews)
-   - Documents have YAML frontmatter with searchable `topic:`, `tags:`, `status:`, `questions_source:`, `research_source:`, `design_source:` fields
+   - Documents have YAML frontmatter with searchable `topic:`, `tags:`, `status:`, `parent:` fields
 
 4. **Follow artifact chains**:
    - Research Questions → Research → Solutions → Designs → Plans → Reviews → Handoffs
-   - Check `questions_source:`, `research_source:` and `design_source:` in frontmatter to find related documents
+   - Check `parent:` in frontmatter to find related documents
    - When you find one artifact, look for upstream/downstream artifacts on the same topic
 
 ## Important Guidelines