@juicesharp/rpiv-pi 1.1.5 → 1.2.1

package/README.md

@@ -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,11 +114,12 @@ 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.
+- **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. 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.
+- **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`).
@@ -135,8 +136,8 @@ 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 |
+| `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 |
 

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

@@ -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/integration-scanner.md

@@ -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

@@ -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/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

package/agents/web-search-researcher.md

@@ -37,7 +37,7 @@ When you receive a research query, you will:
 ## Search Strategies
 
 ### For API/Library Documentation:
-- Search for official docs first: "[library name] official documentation [specific feature]"
+- Search for official docs first: "{library name} official documentation {specific feature}"
 - Look for changelog or release notes for version-specific information
 - Find code examples in official repositories or trusted tutorials
 
@@ -65,26 +65,26 @@ Structure your findings as:
 
 ```
 ## Summary
-[Brief overview of key findings]
+{Brief overview of key findings}
 
 ## Detailed Findings
 
-### [Topic/Source 1]
-**Source**: [Name with link]
-**Relevance**: [Why this source is authoritative/useful]
+### {Topic/Source 1}
+**Source**: {Name with link}
+**Relevance**: {Why this source is authoritative/useful}
 **Key Information**:
 - Direct quote or finding (with link to specific section if possible)
 - Another relevant point
 
-### [Topic/Source 2]
-[Continue pattern...]
+### {Topic/Source 2}
+{Continue pattern...}
 
 ## Additional Resources
-- [Relevant link 1] - Brief description
-- [Relevant link 2] - Brief description
+- {Relevant link 1} - Brief description
+- {Relevant link 2} - Brief description
 
 ## Gaps or Limitations
-[Note any information that couldn't be found or requires further investigation]
+{Note any information that couldn't be found or requires further investigation}
 ```
 
 ## Quality Guidelines

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

@@ -68,8 +68,8 @@ describe("session_start hook", () => {
 		const ctx = createMockCtx({ cwd: projectDir, hasUI: true });
 		await handler?.({ reason: "startup" } as never, ctx as never);
 		for (const d of [
+			"thoughts/shared/discover",
 			"thoughts/shared/research",
-			"thoughts/shared/questions",
 			"thoughts/shared/designs",
 			"thoughts/shared/plans",
 			"thoughts/shared/handoffs",

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

@@ -20,8 +20,8 @@ import { clearInjectionState, handleToolCallGuidance, injectRootGuidance } from
 import { findMissingSiblings } from "./package-checks.js";
 
 const THOUGHTS_DIRS = [
+	"thoughts/shared/discover",
 	"thoughts/shared/research",
-	"thoughts/shared/questions",
 	"thoughts/shared/designs",
 	"thoughts/shared/plans",
 	"thoughts/shared/handoffs",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "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.",
+  "version": "1.2.1",
+  "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",
     "pi-extension",

package/skills/annotate-guidance/SKILL.md

@@ -26,11 +26,11 @@ Use the current working directory as the target project by default. If the user
 
    **Agent A — Project tree mapping:**
    - subagent_type: `codebase-locator`
-   - Prompt: "Map the full project tree structure for [target directory]. List all directories and their contents, respecting .gitignore. Focus on source code directories, configuration files, and build artifacts. Return a complete tree view."
+   - Prompt: "Map the full project tree structure for {target directory}. List all directories and their contents, respecting .gitignore. Focus on source code directories, configuration files, and build artifacts. Return a complete tree view."
 
    **Agent B — Architecture and conventions:**
    - subagent_type: `codebase-locator`
-   - Prompt: "Identify the architectural layout of [target directory] from path shape and manifest files — NO content analysis. Detect: (1) Architecture pattern inferred from folder shape — clean-arch via Domain/Application/Infrastructure dirs; MVC via Controllers/Models/Views; monorepo via packages/* + workspaces; microservices via services/* with individual manifests; hexagonal via ports/adapters. (2) Main layers/modules — top-level source directories + their names. (3) Frameworks and languages from manifest files (package.json dependencies, *.csproj TargetFramework, pyproject.toml, go.mod, Cargo.toml) and file extensions. (4) Build system from build-config filenames (vite/webpack/tsup/esbuild configs, Makefile, nx.json, turbo.json, dotnet .sln). For each main layer/module, check sub-directory composition. If sub-directories with distinct names/roles exist, flag each as a guidance target candidate with: (a) path, (b) role inferred from folder name (controllers/, services/, entities/, components/, stores/, etc.), (c) file count via ls, (d) how its sub-directory composition differs from sibling layers. Use grep/find/ls only. Do not read file contents. Pass 2 runs codebase-analyzer + codebase-pattern-finder per target folder for deep analysis."
+   - Prompt: "Identify the architectural layout of {target directory} from path shape and manifest files — NO content analysis. Detect: (1) Architecture pattern inferred from folder shape — clean-arch via Domain/Application/Infrastructure dirs; MVC via Controllers/Models/Views; monorepo via packages/* + workspaces; microservices via services/* with individual manifests; hexagonal via ports/adapters. (2) Main layers/modules — top-level source directories + their names. (3) Frameworks and languages from manifest files (package.json dependencies, *.csproj TargetFramework, pyproject.toml, go.mod, Cargo.toml) and file extensions. (4) Build system from build-config filenames (vite/webpack/tsup/esbuild configs, Makefile, nx.json, turbo.json, dotnet .sln). For each main layer/module, check sub-directory composition. If sub-directories with distinct names/roles exist, flag each as a guidance target candidate with: (a) path, (b) role inferred from folder name (controllers/, services/, entities/, components/, stores/, etc.), (c) file count via ls, (d) how its sub-directory composition differs from sibling layers. Use grep/find/ls only. Do not read file contents. Pass 2 runs codebase-analyzer + codebase-pattern-finder per target folder for deep analysis."
 
    - While agents run, read .gitignore yourself to understand exclusion rules
 
@@ -55,7 +55,7 @@ Use the current working directory as the target project by default. If the user
      ```
      ## Proposed Guidance Locations
 
-     Architecture detected: [pattern name]
+     Architecture detected: {pattern name}
 
      Files will be written to `.rpiv/guidance/` mirroring the project structure.
 
@@ -63,15 +63,15 @@ Use the current working directory as the target project by default. If the user
      - `/` (root) — Project overview (compact)
      - `src/core/` — Core domain layer
      - `src/services/` — Service layer
-     - [etc.]
+     - {etc.}
 
      ### Folders to skip:
      - `src/core/entities/` — Entity grouping, same pattern as parent
-     - [etc.]
+     - {etc.}
 
      Does this look right? Should I add or remove any locations?
      ```
-   - Use the `ask_user_question` tool with the following question: "[N] guidance targets across [M] layers. Proceed with analysis?". Options: "Proceed (Recommended)" (Analyze all proposed folders and write architecture.md files); "Add folders" (I want to add more folders to the target list); "Remove folders" (Some proposed folders should be skipped).
+   - Use the `ask_user_question` tool with the following question: "{N} guidance targets across {M} layers. Proceed with analysis?". Options: "Proceed (Recommended)" (Analyze all proposed folders and write architecture.md files); "Add folders" (I want to add more folders to the target list); "Remove folders" (Some proposed folders should be skipped).
    - Adjust the target list based on user feedback
 
 4. **Pass 2 — Analyze each layer (parallel analyzer agents):**
@@ -81,11 +81,11 @@ Use the current working directory as the target project by default. If the user
 
    **Analyzer agent:**
    - subagent_type: `codebase-analyzer`
-   - Prompt: "Analyze [folder path] in detail. Determine: 1) What is this layer's responsibility? 2) What are its dependencies (what does it import/use)? 3) Who consumes it (what imports/uses it)? 4) What are the key architectural boundaries and constraints? 5) What is the module structure — list DIRECTORIES with their roles, base types, and naming conventions. Use architectural annotations (e.g., 'one repo per entity', 'one controller per resource') instead of listing individual filenames. The structure should remain valid when non-architectural files are added. 6) What naming conventions are used (prefixes, suffixes, base classes)?"
+   - Prompt: "Analyze {folder path} in detail. Determine: 1) What is this layer's responsibility? 2) What are its dependencies (what does it import/use)? 3) Who consumes it (what imports/uses it)? 4) What are the key architectural boundaries and constraints? 5) What is the module structure — list DIRECTORIES with their roles, base types, and naming conventions. Use architectural annotations (e.g., 'one repo per entity', 'one controller per resource') instead of listing individual filenames. The structure should remain valid when non-architectural files are added. 6) What naming conventions are used (prefixes, suffixes, base classes)?"
 
    **Pattern finder agent:**
    - subagent_type: `codebase-pattern-finder`
-   - Prompt: "Find all distinct code patterns used in [folder path]. For each pattern found: 1) Name the pattern with a descriptive heading (e.g., 'Repository Boundary (CRITICAL: Plain Types, NOT Result<T>)'). 2) Provide an IDIOMATIC code example — a generalized, representative version that shows the pattern's essential shape (constructor, key method signatures, return types, error handling). Do NOT copy-paste a single file verbatim; instead synthesize the typical usage across the layer. 3) Add inline comments highlighting important conventions (e.g., '// DB int → boolean', '// throws on error — service wraps in Result'). 4) If the pattern involves a boundary between layers, show both sides. 5) Identify any repeatable workflows for adding new elements to this layer — backend entities (repositories, services, controllers) AND frontend elements (components, services, pages/routes, directives). For example: creating a new repository requires extending BaseRepository + registering in factory; adding a new Angular component requires extending BaseComponent + adding to routes + creating the template. Return these as step-by-step checklists. Return patterns with full code block examples."
+   - Prompt: "Find all distinct code patterns used in {folder path}. For each pattern found: 1) Name the pattern with a descriptive heading (e.g., 'Repository Boundary (CRITICAL: Plain Types, NOT Result<T>)'). 2) Provide an IDIOMATIC code example — a generalized, representative version that shows the pattern's essential shape (constructor, key method signatures, return types, error handling). Do NOT copy-paste a single file verbatim; instead synthesize the typical usage across the layer. 3) Add inline comments highlighting important conventions (e.g., '// DB int → boolean', '// throws on error — service wraps in Result'). 4) If the pattern involves a boundary between layers, show both sides. 5) Identify any repeatable workflows for adding new elements to this layer — backend entities (repositories, services, controllers) AND frontend elements (components, services, pages/routes, directives). For example: creating a new repository requires extending BaseRepository + registering in factory; adding a new Angular component requires extending BaseComponent + adding to routes + creating the template. Return these as step-by-step checklists. Return patterns with full code block examples."
 
    - Emit 1 analyzer + 1 pattern finder per folder as separate `Agent(...)` calls in the same tool-use batch
    - For the root architecture.md, use findings from ALL folders to create the overview
@@ -113,7 +113,7 @@ Use the current working directory as the target project by default. If the user
    Dependencies: Core (outbound), Controllers (inbound)
    Workflows detected: "Add new service" (4 steps)
 
-   [etc.]
+   {etc.}
    ```
 
    Then ask grounded questions — **one at a time**, waiting for the developer's answer before asking the next. Ask as many as the findings warrant — one per significant ambiguity or discovery gap. Use a **❓ Question:** prefix. Each question must reference real findings and pull NEW information from the developer — not confirm what you already found, and not ask about cosmetic issues (typos, formatting) or absences the developer can't add context to.
@@ -164,7 +164,7 @@ Use the current working directory as the target project by default. If the user
      - Root folder (LAST): Use the **Root Architecture Template** (compact overview). Draft root only after all subfolder files are finalized — this ensures the deduplication rule can be applied and cross-layer checklists can accurately reference subfolder content
    - **Output directory convention:** All architecture.md files are written under `.rpiv/guidance/` at the project root, mirroring the project's directory structure. For a target folder at `src/core/`, the output path is `.rpiv/guidance/src/core/architecture.md`. For the root target, the output path is `.rpiv/guidance/architecture.md`. Create intermediate directories as needed.
    - Enforce the 100-line limit on subfolder files — code examples are essential but keep them concise
-   - If the pattern-finder identified repeatable "add new entity" workflows, include them as `<important if="you are adding a new [entity] to this layer">` conditional sections
+   - If the pattern-finder identified repeatable "add new entity" workflows, include them as `<important if="you are adding a new {entity} to this layer">` conditional sections
    - If testing patterns were detected, include them as `<important if="you are writing or modifying tests for this layer">` conditional sections
    - Conditional sections are optional — only include when the pattern-finder found clear evidence of a repeatable workflow
    - Conditions must be narrow and action-specific (NOT "you are writing code" — too broad)
@@ -194,9 +194,9 @@ Use the current working directory as the target project by default. If the user
    After fixing all violations, re-scan the corrected drafts to confirm every check passes. Only proceed to writing when all checks are clean. Present a brief summary of what was fixed:
    ```
    ## Self-review results
-   - [file]: removed 2 utility deps (moment, xlsx-js-style)
-   - [file]: grouped Module Structure from 11 → 6 entries
-   - [file]: added "Adding a New Service" conditional
+   - {file}: removed 2 utility deps (moment, xlsx-js-style)
+   - {file}: grouped Module Structure from 11 → 6 entries
+   - {file}: added "Adding a New Service" conditional
    - Root: no violations found
    ```
 
@@ -213,17 +213,18 @@ Use the current working directory as the target project by default. If the user
      | .rpiv/guidance/architecture.md | 45 | Root project overview |
      | .rpiv/guidance/src/core/architecture.md | 78 | Core domain layer |
      | .rpiv/guidance/src/services/architecture.md | 65 | Service layer |
-     | [etc.] | | |
+     | {etc.} | | |
 
-     Total: [N] files created/updated
+     Total: {N} files created/updated
 
      Please review the files and let me know if you'd like any adjustments.
      ```
 
-10. **Handle follow-up adjustments:**
-   - If the user requests changes to specific files, edit them directly using the Edit tool
-   - If the user wants additional folders annotated, run a targeted Pass 2 (analyzer + pattern finder) for those folders, then write
-   - If the user wants a file removed, note that they can delete it themselves
+10. **Handle Follow-ups:**
+    - **Edit in-place.** If the user requests changes to specific files, edit them directly using the Edit tool — annotation files are pure markdown, no frontmatter to bump.
+    - **Re-dispatch narrowly.** If the user wants additional folders annotated, run a targeted Pass 2 (analyzer + pattern finder) for those folders, then write.
+    - **Removals.** If the user wants a file removed, note that they can delete it themselves — annotate does not delete.
+    - **When to re-invoke instead.** Re-run `/skill:annotate-guidance` for project-wide refresh after major architectural changes; for single-folder updates, prefer in-place edits.
 
 ## Root Architecture Template (compact):
 

package/skills/annotate-guidance/templates/root-architecture.md

@@ -1,16 +1,16 @@
 ```markdown
 # Project Overview
-[1-2 sentences: what it is, tech stack]
+{1-2 sentences: what it is, tech stack}
 
 # Architecture
-[monorepo structure tree + dependency flow diagram]
-[process architecture if applicable]
+{monorepo structure tree + dependency flow diagram}
+{process architecture if applicable}
 
 # Commands
-[key commands table — always bare, never wrapped in <important if>]
+{key commands table — always bare, never wrapped in <important if>}
 
 # Business Context
-[1-2 sentences if applicable]
+{1-2 sentences if applicable}
 ```
 
 The sections above (Overview, Architecture, Commands, Business Context) are foundational — they stay bare because they're relevant to virtually every task.
@@ -43,4 +43,4 @@ Good root conditions — things that span multiple layers:
 </important>
 ```
 
-Each block should contain only rules that share the same trigger condition. If a codebase has 3 distinct convention areas, that's 3 blocks — not 1 block with a broad condition. Layer-specific checklists (adding a controller, adding a repository) go in the subfolder architecture.md using `<important if="you are adding a new [entity] to this layer">`.
+Each block should contain only rules that share the same trigger condition. If a codebase has 3 distinct convention areas, that's 3 blocks — not 1 block with a broad condition. Layer-specific checklists (adding a controller, adding a repository) go in the subfolder architecture.md using `<important if="you are adding a new {entity} to this layer">`.