@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plugins/pbr/skills/import/SKILL.md

@@ -2,7 +2,7 @@
 name: import
 description: "Import external plans. Validates context, detects conflicts, generates PLAN.md."
 allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
-argument-hint: "<phase-number> [--from <filepath>] [--skip-checker]"
+argument-hint: "<phase-number> [--from <filepath>] [--skip-checker] | --prd <filepath>"
 ---
 
 **STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**
@@ -23,16 +23,22 @@ Then proceed to Step 1.
 
 You are the orchestrator for `/pbr:import`. This skill imports an external plan document (design doc, RFC, AI-generated plan, etc.) into the Plan-Build-Run planning format. It validates the imported document against project context, detects conflicts with locked decisions and existing architecture, and generates properly formatted PLAN.md files. Your job is to stay lean, do conflict detection inline, and delegate only the plan checker to a Task() subagent.
 
+## References
+
+- `references/ui-brand.md` — Status symbols, banners, checkpoint boxes for import display output
+- `references/questioning.md` — Questioning patterns for gap-fill prompts during PRD import
+
 ## Context Budget
 
 Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+Reference: `skills/shared/agent-type-resolution.md` for agent type fallback when spawning Task() subagents.
 
 Additionally for this skill:
 - **Minimize** reading subagent output — read only verdicts, not full reports
 
 ## Prerequisites
 
-- `.planning/config.json` exists (run `/pbr:begin` first)
+- `.planning/config.json` exists (run `/pbr:new-project` first)
 - `.planning/ROADMAP.md` exists with at least one phase
 - `.planning/REQUIREMENTS.md` exists (optional — if absent, skip requirement ID cross-referencing and warn the user: "No REQUIREMENTS.md found. Skipping REQ-ID validation.")
 
@@ -51,7 +57,15 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut and config
 1. Parse `$ARGUMENTS` for phase number
 2. Parse optional `--from <filepath>` flag (path to the external document to import)
 3. Parse optional `--skip-checker` flag (skip plan validation step)
+3b. Parse optional `--prd <filepath>` flag.
+    - If `--prd` is present: **branch into PRD Import Flow (Steps A–G below)** immediately after writing `.active-skill`.
+    - Do NOT proceed to Step 2 (standard import flow). The --prd branch is a completely separate execution path.
+    - If both `--prd` and `--from` are present: treat `--prd` as the primary flag; `--from` is ignored with an [INFO] note.
+    - If `--prd` is present but no filepath follows: display error "Missing filepath for --prd flag." and stop.
 4. **CRITICAL: Write .active-skill NOW.** Write the text "import" to `.planning/.active-skill` using the Write tool.
+
+**→ If --prd flag was set: jump to PRD Import Flow (Step A). Do not continue to Step 2.**
+
 5. Validate:
    - Phase exists in ROADMAP.md
    - Phase directory exists at `.planning/phases/{NN}-{slug}/`
@@ -63,6 +77,253 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut and config
 
 ---
 
+## PRD Import Flow
+
+> **Entered when `--prd <filepath>` is present in $ARGUMENTS. Steps A–G replace Steps 2–11 entirely for this path.**
+
+---
+
+### Step A: Read and Validate PRD File
+
+1. Read the file at the `--prd <filepath>` path.
+2. If the file does not exist: display the "Import file not found" error from the Error Handling section and stop.
+3. If the file is empty or < 100 characters: display error "PRD file appears empty or too short to extract meaningful content." and stop.
+4. Store the full PRD content for use in Steps B–E.
+
+---
+
+### Step B: Gap Detection — Identify Missing Sections (inline)
+
+Analyze the PRD content for the presence of these six required sections:
+
+| Section | What to look for |
+|---------|-----------------|
+| Project name / title | A clear product name or title |
+| Problem statement | What problem the product solves, who it's for |
+| Goals / success criteria | Measurable outcomes, KPIs, or acceptance tests |
+| Functional requirements | Feature list, user stories, or capabilities |
+| Non-functional requirements | Performance, security, reliability constraints |
+| Out of scope / deferred | Explicitly excluded features |
+
+For each section that is **absent or ambiguous**, record it as a gap.
+
+**If 1–3 gaps found:** Batch all gaps into ≤ 3 AskUserQuestion calls (max 4 options each). Ask the user to supply the missing info:
+
+- If 1 gap: one AskUserQuestion with a freeform prompt.
+- If 2–3 gaps: group into 2 AskUserQuestion calls of related topics (e.g., "Requirements" and "Constraints/Scope").
+- If > 3 gaps: group all into exactly 3 AskUserQuestion calls. Do NOT exceed 3 calls.
+
+Example AskUserQuestion for missing requirements:
+
+```
+Use AskUserQuestion:
+  question: "The PRD doesn't clearly specify functional requirements. Please describe the main features or capabilities this product must have."
+  header: "Fill Gap"
+  options: []   ← freeform (no options means free text input)
+  multiSelect: false
+```
+
+**If 0 gaps:** proceed directly to Step C with no prompts.
+
+Incorporate user answers into the extraction context used in Step C.
+
+---
+
+### Step C: Extract Project Files Inline (PROJECT.md with Context, REQUIREMENTS.md)
+
+Using the PRD content (plus any gap-fill answers from Step B), generate the content for two files. Context is merged into PROJECT.md (not a separate CONTEXT.md). Do this inline in your context — no subagents.
+
+**C1. Generate PROJECT.md content** using `templates/PROJECT.md.tmpl` as the structure:
+
+- `{project_name}`: extract from PRD title/header
+- `{ONE sentence core value statement}`: extract from problem statement / vision
+- Vision section: 2-3 sentences from PRD problem statement
+- Scope — In Scope: features from functional requirements section
+- Scope — Out of Scope: features from "out of scope" section (or mark "None specified" if absent)
+- Success Criteria: from goals/KPIs section
+- Stakeholders: extract if present; default to "Primary user: end users of the product"
+- Milestones line: leave as "Planned in {N} phases across 1 milestone — see .planning/ROADMAP.md"
+- **## Context section** (merged from brownfield variant TMPL-06):
+  - Locked Decisions: extract any explicit technology choices or constraints from PRD
+  - User Constraints: extract deployment, team size, budget, timeline if mentioned
+  - Deferred Ideas: items from "out of scope" section
+  - Claude's Discretion Areas: leave empty (executor will fill as they work)
+
+**C2. Generate REQUIREMENTS.md content** using `templates/REQUIREMENTS.md.tmpl` as the structure:
+
+- Functional Requirements: each feature/capability from PRD becomes one REQ-F-xxx row
+- Number from REQ-F-001 sequentially
+- Priority: "Must" for core features, "Should" for nice-to-haves (infer from PRD language)
+- Non-Functional Requirements: from performance/security/reliability section if present
+- Deferred Requirements: items from "out of scope" section
+- Traceability table: leave "Implemented In" and "Verified In" columns as "—"
+
+---
+
+### Step D: Confirmation Gate
+
+**Check config:** Read `.planning/config.json`. If `prd.auto_extract` is `true`, skip this step entirely and proceed directly to Step E.
+
+**If prd.auto_extract is false (default):**
+
+Display a preview of the three generated files (show first 10 lines of each with a `...` truncation).
+
+Then present the confirmation gate using the **approve-revise-abort** pattern from `skills/shared/gate-prompts.md`:
+
+```
+Use AskUserQuestion:
+  question: "Approve these extracted files? (PROJECT.md with Context section, REQUIREMENTS.md — ROADMAP.md will be generated next)"
+  header: "Approve?"
+  options:
+    - label: "Approve"          description: "Write files and generate ROADMAP.md"
+    - label: "Request changes"  description: "Describe what to adjust before writing"
+    - label: "Abort"            description: "Cancel PRD import"
+  multiSelect: false
+```
+
+- **Approve**: proceed to Step E.
+- **Request changes**: ask user what to change (AskUserQuestion freeform), revise the affected file(s) inline, and re-display the gate. Repeat until Approve or Abort.
+- **Abort**: delete `.planning/.active-skill` and stop with message: "PRD import cancelled."
+
+---
+
+### Step E: Check for Existing Files and Write PROJECT.md, REQUIREMENTS.md
+
+**CRITICAL (no hook) -- DO NOT SKIP: Write PROJECT.md and REQUIREMENTS.md to disk.**
+
+For each of the two files (`PROJECT.md`, `REQUIREMENTS.md` in `.planning/`):
+
+1. Check if the file already exists (Glob `.planning/PROJECT.md`, etc.).
+2. If it exists: use AskUserQuestion yes-no pattern:
+   ```
+   question: ".planning/{filename} already exists. Overwrite it?"
+   header: "Overwrite?"
+   options:
+     - label: "Yes"  description: "Replace existing file"
+     - label: "No"   description: "Keep existing, skip this file"
+   ```
+   - If No: skip writing that file.
+3. Write approved content to:
+   - `.planning/PROJECT.md` (includes ## Context section — do NOT create separate CONTEXT.md)
+   - `.planning/REQUIREMENTS.md`
+
+---
+
+### Step F: Delegate ROADMAP.md Generation to pbr:planner
+
+Display: `◆ Generating ROADMAP.md via planner...`
+
+Spawn the planner subagent:
+
+```
+Task({
+  subagent_type: "pbr:planner",
+  prompt: "
+You are the planner agent in Roadmap Mode.
+
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/PROJECT.md
+2. .planning/REQUIREMENTS.md
+3. .planning/CONTEXT.md
+</files_to_read>
+
+Generate `.planning/ROADMAP.md` from the project files above.
+
+Use the roadmap template at `${CLAUDE_PLUGIN_ROOT}/templates/ROADMAP.md.tmpl`.
+Apply Requirement Coverage Validation: every requirement in REQUIREMENTS.md must appear in at least one phase.
+Apply the Dual Format requirement: Quick-scan checklist at top + detailed phase descriptions.
+Wrap all phases in a Milestone section named after the project.
+
+Write ROADMAP.md to `.planning/ROADMAP.md`.
+Output your completion marker when done: ## PLANNING COMPLETE
+"
+})
+```
+
+After the Task() completes:
+
+- Confirm `.planning/ROADMAP.md` exists (Glob check).
+- If missing: display error "Planner failed to generate ROADMAP.md. Run /pbr:plan-phase to retry." and proceed to Step G anyway (the other 3 files are already written).
+
+---
+
+### Step G: State Updates, Commit, and Summary
+
+**CRITICAL (no hook) -- DO NOT SKIP: Initialize and update STATE.md.**
+
+**G1. Initialize STATE.md** (if it does not already exist):
+
+- Run: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load`
+- If STATE.md does not exist: create `.planning/STATE.md` with frontmatter fields:
+  ```
+  project: {project_name from PROJECT.md}
+  current_phase: 1
+  status: planning
+  source: prd-import
+  prd_file: {filepath}
+  ```
+
+**G2. Update STATE.md** with PRD import status:
+
+- Set `status: planning`
+- Note `source: prd-import` and `prd_file: {filepath}`
+
+**G3. Commit (if planning.commit_docs is true in config):**
+
+Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
+
+```
+docs(planning): init project docs from PRD import
+```
+
+Stage: `.planning/PROJECT.md`, `.planning/REQUIREMENTS.md`, `.planning/CONTEXT.md`, `.planning/ROADMAP.md` (if generated), `.planning/STATE.md`.
+
+**CRITICAL -- DO NOT SKIP:** **G4. Delete `.planning/.active-skill`.**
+
+**G5. Display completion banner:**
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► PRD IMPORT COMPLETE ✓                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Project**: {project_name}
+**Source**: {prd_filepath}
+
+Files generated:
+  ✓ .planning/PROJECT.md (includes ## Context section)
+  ✓ .planning/REQUIREMENTS.md
+  {✓ or ✗} .planning/ROADMAP.md
+
+Requirements extracted: {count} REQ-IDs
+Gaps filled: {count} (via interactive prompts)
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Plan Phase 1** — generate execution plans for the first phase
+
+`/pbr:plan-phase 1`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `/pbr:discuss-phase` — review and refine decisions before planning
+- `/pbr:progress` — see full project overview
+```
+
+---
+
+> **End of PRD Import Flow. Steps 2–11 below apply only to the standard --from flow.**
+
+---
+
 ### Step 2: Load Full Project Context (inline)
 
 Read all relevant context files. This context is used for conflict detection in Step 4.
@@ -71,7 +332,7 @@ Read all relevant context files. This context is used for conflict detection in
 1. ROADMAP.md — extract current phase goal, dependencies, requirements, success criteria
 2. REQUIREMENTS.md — extract REQ-IDs mapped to this phase
 3. CONTEXT.md (project-level, if exists) — extract locked decisions, deferred ideas, constraints
-4. Phase CONTEXT.md (if exists at .planning/phases/{NN}-{slug}/CONTEXT.md) — phase-specific locked decisions from /pbr:discuss
+4. Phase CONTEXT.md (if exists at .planning/phases/{NN}-{slug}/CONTEXT.md) — phase-specific locked decisions from /pbr:discuss-phase
 5. config.json — extract feature flags, depth, model settings
 6. Prior SUMMARY.md files — use digest-select depth per `skills/shared/digest-select.md` (direct deps: full body for conflict detection, transitive: frontmatter only, 2+ back: skip)
 7. Research SUMMARY.md (if exists at .planning/research/SUMMARY.md)
@@ -264,7 +525,7 @@ gap_closure: {false for standard plans, true if closing gaps}
 
 **If validation is enabled:**
 
-Display to the user: `◐ Spawning plan checker...`
+Display to the user: `◆ Spawning plan checker...`
 
 Spawn the plan checker Task():
 
@@ -281,6 +542,13 @@ NOTE: The pbr:plan-checker subagent type auto-loads the agent definition. Do NOT
 ```
 You are the plan-checker agent.
 
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/CONTEXT.md — locked decisions and constraints (if exists)
+2. .planning/STATE.md — current project state and progress
+3. .planning/ROADMAP.md — phase structure, goals, and dependencies
+</files_to_read>
+
 <plans_to_check>
 {For each generated PLAN.md:}
 --- Plan File: {filename} ---
@@ -311,7 +579,15 @@ Run all verification dimensions on these plans. Return your structured report.
 Do NOT write any files. Return your findings as your response text.
 ```
 
-**Process checker results — revision loop:**
+**Process checker results — completion marker check:**
+
+After the plan-checker completes, check for completion markers in the Task() output:
+
+- If `## CHECK PASSED` is present: skip the revision loop entirely and proceed to Step 7.
+- If `## ISSUES FOUND` is present: enter the revision loop below.
+- If neither marker is found: treat as issues found and enter the revision loop.
+
+**Revision loop:**
 
 Reference: `skills/shared/revision-loop.md` for the full Check-Revise-Escalate pattern (max 3 iterations).
 
@@ -324,6 +600,8 @@ Follow the revision loop with:
 
 ### Step 7: Write PLAN.md Files (inline)
 
+**CRITICAL (no hook) -- DO NOT SKIP: Write plan files to disk.**
+
 Write each plan to `.planning/phases/{NN}-{slug}/PLAN-{plan_num}.md`.
 
 If existing plans are being replaced (user confirmed in Step 1):
@@ -331,10 +609,22 @@ If existing plans are being replaced (user confirmed in Step 1):
 
 ---
 
+**Step 7b — Spot-check artifacts:**
+
+After writing plan files, verify they landed on disk:
+
+1. Glob `.planning/phases/{NN}-{slug}/PLAN-*.md` to confirm files exist
+2. Count matches — must equal the number of plans generated in Step 5
+3. If any are missing: re-attempt the write. If still missing, display an error listing the missing files.
+
+---
+
 ### Step 8: Update All State (inline)
 
 Perform all state updates in this order:
 
+**CRITICAL (no hook) -- DO NOT SKIP: Update ROADMAP.md progress table.**
+
 **8a. Update ROADMAP.md Progress table** (REQUIRED — do this BEFORE updating STATE.md):
 1. Open `.planning/ROADMAP.md`
 2. Find the `## Progress` table
@@ -343,6 +633,8 @@ Perform all state updates in this order:
 5. Update the `Status` column to `planned`
 6. Save the file — do NOT skip this step
 
+**CRITICAL -- DO NOT SKIP: Update STATE.md frontmatter AND body with import status.**
+
 **8b. Update STATE.md:**
 - Set current phase plan status to "planned"
 - Note source: "imported from {filepath}" or "imported from user input"
@@ -384,7 +676,7 @@ docs({phase}): import plans for phase {N} ({count} plans, {wave_count} waves)
 
 ### Step 10: Cleanup
 
-Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.
+**CRITICAL -- DO NOT SKIP:** Delete `.planning/.active-skill` if it exists. This must happen on all paths (success, partial, and failure) before reporting results.
 
 ### Step 11: Confirm (inline)
 
@@ -420,15 +712,15 @@ Requirements traced: {count}/{total} REQ-IDs covered
 
 **Build Phase {N}** — execute these imported plans
 
-`/pbr:build {N}`
+`/pbr:execute-phase {N}`
 
 <sub>`/clear` first → fresh context window</sub>
 
 
 
 **Also available:**
-- `/pbr:plan {N}` — re-plan from scratch if import needs rework
-- `/pbr:discuss {N}` — talk through details before building
+- `/pbr:plan-phase {N}` — re-plan from scratch if import needs rework
+- `/pbr:discuss-phase {N}` — talk through details before building
 
 
 ```
@@ -437,6 +729,8 @@ Requirements traced: {count}/{total} REQ-IDs covered
 
 ## Error Handling
 
+Reference: `skills/shared/error-reporting.md` for branded error output patterns.
+
 **IMPORTANT:** On ALL error exits below, delete `.planning/.active-skill` if it exists before displaying the error message.
 
 ### Phase not found
@@ -448,7 +742,7 @@ If the specified phase does not exist in ROADMAP.md, display:
 
 Phase {N} not found.
 
-**To fix:** Run `/pbr:status` to see available phases.
+**To fix:** Run `/pbr:progress` to see available phases.
 ```
 
 ### Missing prerequisites
@@ -460,7 +754,7 @@ If REQUIREMENTS.md or ROADMAP.md do not exist, display:
 
 Project not initialized.
 
-**To fix:** Run `/pbr:begin` first.
+**To fix:** Run `/pbr:new-project` first.
 ```
 
 ### Import file not found
@@ -475,6 +769,22 @@ File not found: {filepath}
 **To fix:** Check the path and try again.
 ```
 
+### PRD file too short
+If the PRD file is < 100 characters:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+PRD file appears empty or too short to extract meaningful content.
+
+**To fix:** Provide a more complete PRD document (minimum ~100 characters).
+```
+
+### PRD import cancelled
+If user selects "Abort" at the confirmation gate (Step D):
+Display: "PRD import cancelled." and delete `.planning/.active-skill`.
+
 ### Import document too vague
 If the imported document contains no actionable tasks, display:
 ```
@@ -484,7 +794,7 @@ If the imported document contains no actionable tasks, display:
 
 The imported document is too vague to convert into plans. No specific tasks, files, or implementation steps found.
 
-**To fix:** Provide a more detailed document, or use `/pbr:plan {N}` to generate plans from scratch.
+**To fix:** Provide a more detailed document, or use `/pbr:plan-phase {N}` to generate plans from scratch.
 ```
 
 ### Checker loops without resolution
@@ -507,7 +817,11 @@ Present remaining issues and ask user to decide: proceed or intervene.
 
 | File | Purpose | When |
 |------|---------|------|
-| `.planning/phases/{NN}-{slug}/PLAN-{NN}.md` | Imported plan files | Step 7 |
+| `.planning/phases/{NN}-{slug}/{NN}-{MM}-PLAN.md` | Imported plan files | Step 7 |
 | `.planning/ROADMAP.md` | Plans Complete + Status updated to `planned` | Step 8a |
 | `.planning/STATE.md` | Updated with plan status and import source | Step 8b |
 | `.planning/CONTEXT.md` | Updated if blockers surfaced new locked decisions | Step 8d |
+| `.planning/PROJECT.md` | Generated from PRD | Step E (PRD flow) |
+| `.planning/REQUIREMENTS.md` | Generated from PRD | Step E (PRD flow) |
+| `.planning/CONTEXT.md` | Generated from PRD | Step E (PRD flow) |
+| `.planning/ROADMAP.md` | Generated by planner subagent | Step F (PRD flow) |

package/plugins/pbr/skills/intel/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: intel
+description: "Refresh or query codebase intelligence (file graph, APIs, dependencies, architecture)."
+allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
+argument-hint: "[query <term>|refresh|status|diff]"
+---
+
+**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes tokens. Begin executing Step 0 immediately.**
+
+## Step 0 -- Banner
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► INTEL UPDATE                              ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+## Step 1 -- Config Gate
+
+Check if intel is enabled by reading `.planning/config.json` directly (do NOT use Bash for this -- `config get` throws on missing keys):
+
+1. Read `.planning/config.json`
+2. Check if `intel.enabled` is explicitly `false`
+3. If `false`, display:
+
+```
+Intel system is disabled. Enable with: /pbr:config set intel.enabled true
+```
+
+Then **STOP**. Do not proceed further.
+
+If enabled, not present, or no config file exists (all default to enabled), proceed to Step 2.
+
+---
+
+## Step 2 -- Parse Argument
+
+Parse the user's argument to determine the operation mode:
+
+| Argument | Action |
+|----------|--------|
+| `query <term>` | Run inline query (Step 2a) |
+| `status` | Run inline status check (Step 2b) |
+| `diff` | Run inline diff check (Step 2c) |
+| `refresh` or no argument | Spawn intel-updater agent (Step 3) |
+
+### Step 2a -- Query
+
+Run:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js intel query <term>
+```
+
+Format and display the results. Show matching entries grouped by intel file. If no results found, suggest running `refresh` first.
+
+**STOP** after displaying results. Do not spawn an agent.
+
+### Step 2b -- Status
+
+Run:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js intel status
+```
+
+Format and display staleness info for each intel file. Show last update times and whether files exist.
+
+**STOP** after displaying status. Do not spawn an agent.
+
+### Step 2c -- Diff
+
+Run:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js intel diff
+```
+
+Format and display changes since the last full refresh. Show which files have changed and summary of differences.
+
+**STOP** after displaying diff. Do not spawn an agent.
+
+---
+
+## Step 3 -- Refresh (Agent Spawn)
+
+**CRITICAL: Agent type rule** -- ALWAYS use `subagent_type: "pbr:intel-updater"`. NEVER use `general-purpose` or other non-PBR agent types. The PreToolUse hook will block non-PBR agents.
+
+Resolve the pbr-tools path for the agent. Use the plugin root or known path:
+```
+pbr-tools path: ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js
+```
+
+Spawn a Task with:
+- `subagent_type: "pbr:intel-updater"`
+- Spawn prompt containing:
+  - `pbr-tools path: ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js` (resolved path to CLI tool)
+  - `focus: full` (default) or `focus: partial --files <paths>` if user specified particular files
+  - Project root path (current working directory)
+  - Any existing `.planning/intel/stack.json` content (if it exists) for context
+
+Wait for agent completion.
+
+---
+
+## Step 4 -- Post-Refresh Summary
+
+After the agent completes, run:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js intel status
+```
+
+Display a summary showing:
+- Which intel files were written/updated
+- Last update timestamps
+- Brief overview of what was discovered
+
+---
+
+## Anti-Patterns
+
+1. DO NOT spawn an agent for query/status/diff operations -- these are inline CLI calls
+2. DO NOT read agent .md files -- auto-loaded via subagent_type
+3. DO NOT modify intel files directly -- the agent handles writes
+4. DO NOT skip the config gate check
+5. DO NOT use general-purpose agents -- always use `pbr:intel-updater`