Add 5 pi extensions: pi-subagents, pi-crew, rpiv-pi, pi-interactive-shell, pi-intercom

2026-05-08 15:59:25 +10:00
parent d0d1d9b045
commit 31b4110c87
457 changed files with 85157 additions and 0 deletions
--- a/extensions/rpiv-pi/skills/explore/SKILL.md
+++ b/extensions/rpiv-pi/skills/explore/SKILL.md
@@ -0,0 +1,359 @@
+---
+name: explore
+description: Analyze solution options for a feature or change, comparing approaches with pros, cons, trade-offs, and a recommended path. Use when the user is weighing approaches, asks "what are the options" or "how should we approach X", wants approaches compared, says "explore solutions", or faces a decision with multiple valid implementations. Produces solutions documents in thoughts/shared/solutions/, which can feed the design skill.
+argument-hint: [feature/change description]
+---
+
+# Research Solutions
+
+You are tasked with analyzing solution options for new features or changes by invoking parallel skills and synthesizing their findings into actionable recommendations optimized for design consumption.
+
+## Initial Setup:
+
+When this command is invoked, respond with:
+```
+I'm ready to research solution options. Please provide:
+- What feature/change you want to explore
+- Any requirements or constraints you know about
+- Reference to relevant ticket or research documents if available
+
+I'll analyze the current codebase, generate solution options, and provide recommendations.
+```
+
+Then wait for the user's request.
+
+## Steps
+
+### Step 1: Read Mentioned Files
+
+- If user mentions tickets, research docs, or other files, read them FULLY first
+- **IMPORTANT**: Use Read tool WITHOUT limit/offset parameters
+- **CRITICAL**: Read these files in main context before invoking skills
+- Extract requirements, constraints, and goals
+- Identify what problem we're solving
+
+### Step 2: Generate Candidates and Dimensions
+
+**Generate 2–4 named candidates** from three sources, then merge into one shortlist:
+
+- **Ecosystem scan** — spawn `web-search-researcher` for any topic where the candidate space includes external libraries, frameworks, or services. Prompt it to return 2–4 named options with one-line "what it is" + canonical doc link per option. Skip only when the topic is wholly internal (e.g., "how to organize this service layer") and the orchestrator's design-space enumeration plus the user shortlist already cover the space.
+- **Design-space enumeration** — orchestrator names abstract shapes from first principles when applicable (pub/sub vs direct-call vs event-bus; sync vs async; manual mapping vs auto-mapper). One-line "what it is" per shape.
+- **User shortlist** — if the user pre-named candidates in the entry prompt ("compare TanStack Query vs SWR"), include those verbatim.
+
+Merge to 2–4 candidates total. Name each with a short noun phrase ("TanStack Query", "Direct event bus"). Deduplicate.
+
+**Default dimension list** (presented at Step 3; developer may drop irrelevant ones):
+
+- **approach-shape** (hybrid) — what category of solution the candidate is, what core moving parts it requires.
+- **precedent-fit** (codebase-anchored) — does the existing code already use this pattern; how many call sites would adopt the new option.
+- **integration-risk** (codebase-anchored) — which existing seams the candidate would touch; what breaks if it lands.
+- **migration-cost** (external-anchored for libraries; codebase-anchored for in-house code) — work to introduce the candidate plus work to remove the incumbent if there is one.
+- **verification-cost** (codebase-anchored) — test/CI surface needed to make the candidate safe to adopt.
+- **novelty** (external-anchored) — how recently the candidate emerged, ecosystem momentum, deprecation risk.
+
+Hold the candidate set and default dimension list in working state for the Step 3 checkpoint. Do not dispatch fit agents yet.
+
+### Step 3: Candidate Checkpoint
+
+Present the candidate set and default dimensions to the developer before per-candidate fit dispatch.
+
+1. **Show candidates and dimensions:**
+
+   ```
+   ## Candidates for: {Topic}
+
+   1. {Candidate A} — {one-line what it is}
+   2. {Candidate B} — {one-line what it is}
+   ...
+
+   Dimensions (default 6; drop any that don't apply):
+   - approach-shape · precedent-fit · integration-risk
+   - migration-cost · verification-cost · novelty
+   ```
+
+2. **Confirm via the `ask_user_question` tool with the following question:** "{N} candidates, {D} dimensions. Begin per-candidate fit dispatch?". Header: "Candidates". Options: "Proceed (Recommended)" (Begin per-candidate fit dispatch with all {N} candidates and all {D} dimensions); "Adjust candidates or dimensions" (Rename, add, or drop candidates; drop dimensions that don't apply); "Re-generate candidates" (Candidates look wrong — re-run Step 2 with adjusted scope).
+
+3. **Handle developer input:**
+
+   **"Proceed"**: lock the candidate × dimension set; advance to Step 4.
+
+   **"Adjust candidates or dimensions"**: ask the follow-up free-text question with prefix `❓ Question:` — "Which candidates and dimensions should be added, dropped, or renamed?" — apply edits to the working set, re-present, and confirm again with the same three-option `ask_user_question`.
+
+   **"Re-generate candidates"**: ask the follow-up free-text question with prefix `❓ Question:` — "What should be different in candidate generation? (narrower/wider scope, different ecosystem, exclude approach X, …)" — return to Step 2 with the updated scope, then re-enter Step 3.
+
+   Loop until "Proceed" is selected.
+
+### Step 4: Per-Candidate Fit Dispatch (parallel agents)
+
+For each confirmed candidate, dispatch up to two agents in parallel — total ≤ 2 × N agents:
+
+- **One `codebase-analyzer` per candidate** — when ≥1 kept dimension is codebase-anchored (precedent-fit, integration-risk, often migration-cost and verification-cost). The agent scores the candidate on every kept codebase-anchored dimension in a single pass, returning evidence per dimension with `file:line` references.
+- **One `web-search-researcher` per candidate** — when ≥1 kept dimension is external-anchored (novelty, often migration-cost for libraries, approach-shape for ecosystem options). The agent scores the candidate on every kept external-anchored dimension in a single pass, returning evidence per dimension with doc/source links.
+
+Skip either agent for a candidate when no dimension of that anchor-type was kept. Hybrid dimension `approach-shape` is scored by the orchestrator after both agents return, by combining their per-candidate findings.
+
+**Per-candidate prompt shape** (use the same outer template, fill in candidate name and kept dimensions):
+
+```
+Candidate: {name} — {one-line what it is}
+Topic: {topic from Step 1}
+
+Score this single candidate on the following dimensions, each with concrete evidence ({file:line} for codebase, doc/source link for external). Report findings as one section per dimension.
+
+Dimensions for this run:
+- {dimension name} — {one-line of what to look for}
+- ...
+
+Do NOT compare against other candidates; another agent handles each one separately. Focus on depth of evidence for THIS candidate.
+```
+
+Wait for ALL agents to complete before proceeding.
+
+**Coverage check**: every (candidate × kept-dimension) cell is filled — by an agent's evidence or by an explicit `null` ("does not apply to this candidate"). Cells silently dropped indicate a missing dispatch — re-run that candidate's agent.
+
+### Step 5: Synthesize and Recommend
+
+- Cross-reference per-candidate findings — fill the candidate × dimension grid with evidence per cell.
+- Apply the fit filter qualitatively per candidate: a candidate "clears" when no kept dimension surfaces a blocking concern (integration-risk that breaks load-bearing seams, migration-cost that exceeds the topic's scope, verification-cost with no path to coverage).
+- **If ≥1 candidate clears the fit filter**: pick the strongest, document rationale with evidence, and explain why alternatives weren't chosen. Identify conditions that would change the recommendation.
+- **If every candidate fails the fit filter**: produce a "no-fit" recommendation — list each candidate's blocking dimension with evidence, recommend re-scoping the question or expanding the candidate pool, and set Step 7 frontmatter `confidence: low` and `status: blocked`.
+
+### Step 6: Determine Metadata and Filename
+
+- Filename format: `thoughts/shared/solutions/YYYY-MM-DD_HH-MM-SS_{topic}.md`
+  - YYYY-MM-DD_HH-MM-SS: Current date and time (e.g., 2025-10-11_14-30-22)
+  - {topic}: Brief kebab-case description
+- Repository name: from git root basename, or current directory basename if not a git repo
+- Use the git branch and commit from the git context injected at the start of the session (or run `git branch --show-current` / `git rev-parse --short HEAD` directly)
+- Timestamp: run `date +"%Y-%m-%dT%H:%M:%S%z"` — raw for `date:` and `last_updated:`, first 19 chars (`T`→`_`, `:`→`-`) for filename slug.
+- Author: use the User from the git context injected at the start of the session (fallback: "unknown")
+- If metadata unavailable: use "unknown" for commit/branch
+
+### Step 7: Generate Solutions Document
+
+- Use the metadata gathered in step 6
+- Structure the document with YAML frontmatter followed by content:
+
+  ```markdown
+  ---
+  date: {Current date and time with timezone in ISO format}
+  author: {Author name}
+  commit: {Current commit hash}
+  branch: {Current branch name}
+  repository: {Repository name}
+  topic: "{Feature/Problem}"
+  confidence: high | medium | low
+  complexity: low | medium | high
+  status: ready | awaiting_input | blocked
+  tags: [solutions, component-names]
+  last_updated: {Same ISO timestamp as `date:` above}
+  last_updated_by: {Author name}
+  ---
+
+  # Solution Analysis: {Feature/Problem}
+
+  **Date**: {Current date and time with timezone from step 6}
+  **Author**: {Author name from step 6}
+  **Commit**: {Current commit hash from step 6}
+  **Branch**: {Current branch name from step 6}
+  **Repository**: {Repository name}
+
+  ## Research Question
+  {Original user query}
+
+  ## Summary
+  **Problem**: {What we're solving}
+  **Recommended**: {Option name} - {One sentence why}
+  **Effort**: {Low/Med/High} ({N days})
+  **Confidence**: {High/Med/Low}
+
+  ## Problem Statement
+
+  **Requirements:**
+  - {Requirement 1}
+  - {Requirement 2}
+
+  **Constraints:**
+  - {Hard constraint - must respect}
+  - {Soft constraint - should consider}
+
+  **Success criteria:**
+  - {What "done" looks like}
+
+  ## Current State
+
+  **Existing implementation:**
+  {What exists with file:line references}
+
+  **Relevant patterns:**
+  - {Pattern 1}: `file.ext:line` - Used in {N} places
+  - {Pattern 2}: `file.ext:line` - Used in {N} places
+
+  **Integration points:**
+  - `file.ext:line` - {Where feature hooks in}
+  - `file.ext:line` - {Another integration point}
+
+  ## Solution Options
+
+  ### Option 1: {Name}
+  **How it works:**
+  {2-3 sentence description + implementation approach}
+
+  **Pros:**
+  - {Advantage with evidence from codebase}
+  - {Advantage with evidence}
+
+  **Cons:**
+  - {Disadvantage with impact}
+
+  **Complexity:** {Low/Med/High} (~{N} days)
+  - Files to create: {N} (~{X} lines)
+  - Files to modify: {N} (~{X} lines)
+  - Risk level: {Low/Med/High}
+
+  ### Option 2: {Alternative Name}
+  {Same structure as Option 1}
+
+  ### Option 3: {Another Alternative}
+  {Same structure as Option 1}
+
+  ## Comparison
+
+  | Criteria | Option 1 | Option 2 | Option 3 |
+  |----------|----------|----------|----------|
+  | Complexity | {L/M/H} | {L/M/H} | {L/M/H} |
+  | Codebase fit | {H/M/L} | {H/M/L} | {H/M/L} |
+  | Risk | {L/M/H} | {L/M/H} | {L/M/H} |
+
+  ## Recommendation
+
+  <!-- Render exactly ONE of the two blocks below, based on Step 5's fit-filter outcome. -->
+
+  **(A) When ≥1 candidate clears the fit filter:**
+
+  **Selected:** {Option N}
+
+  **Rationale:**
+  - {Key reason with evidence}
+  - {Key reason with evidence}
+  - ...
+
+  **Why not alternatives:**
+  - Option X: {Reason}
+
+  **Trade-offs:**
+  - Accepting {limitation} for {benefit}
+
+  **Implementation approach:**
+  1. {Phase 1} - {What to build}
+  2. ...
+
+  **Integration points:**
+  - `file.ext:line` - {Specific change}
+  - `file.ext:line` - {Specific change}
+
+  **Patterns to follow:**
+  - {Pattern}: `file.ext:line`
+
+  **Risks:**
+  - {Risk}: {Mitigation}
+
+  **(B) When every candidate fails the fit filter:**
+
+  **No-fit:** every candidate surfaced a blocking concern on at least one kept dimension.
+
+  **Per-candidate blockers:**
+  - {Option 1}: {blocking dimension} — {evidence with file:line or doc link}
+  - {Option 2}: {blocking dimension} — {evidence}
+  - ...
+
+  **Recommended next step:**
+  - {Re-scope the question} — {how the topic should narrow/widen so candidates can clear}
+  - OR {Expand the candidate pool} — {what new candidate sources to enumerate; e.g., named ecosystem option not surfaced by Step 2}
+
+  **Frontmatter overrides:** set `confidence: low` and `status: blocked`.
+
+  ## Scope Boundaries
+  - {What we're building}
+  - {What we're NOT doing}
+
+  ## Testing Strategy
+
+  **Unit tests:**
+  - {Key test scenario 1}
+  - ...
+
+  **Integration tests:**
+  - {End-to-end scenario 1}
+  - ...
+
+  **Manual verification:**
+  - [ ] {Manual test 1}
+  - [ ] ...
+
+  ## Open Questions
+  **Resolved during research:**
+  - {Question that was answered} - {Answer with evidence from file:line}
+
+  **Requires user input:**
+  - {Business or design question} - {Default assumption for planning}
+
+  **Blockers:**
+  - {Critical unknown that prevents implementation} - {How to unblock}
+
+  ## References
+
+  - `thoughts/shared/research/{file}.md` - {Context}
+  - `src/file.ext:line` - {Similar implementation}
+  - `thoughts/shared/{file}.md` - {Historical decision}
+  ```
+
+### Step 8: Present Findings
+
+Print a concise summary, highlight key integration points, then close with the standardized footer:
+
+```
+Solutions document written to:
+`thoughts/shared/solutions/{filename}.md`
+
+{N} candidates evaluated, {M} dimensions scored, recommendation: {chosen}.
+
+---
+
+💬 Follow-up: describe the change in chat to append a timestamped Follow-up section to this artifact. Re-run `/skill:explore` for a fresh artifact.
+
+**Next step:** `/skill:design thoughts/shared/solutions/{filename}.md` — turn the chosen option into a design artifact (or `/skill:blueprint thoughts/shared/solutions/{filename}.md` for the fast path on smaller tasks).
+
+> 🆕 Tip: start a fresh session with `/new` first — chained skills work best with a clean context window.
+```
+
+### Step 9: Handle Follow-ups
+
+- **Append, never rewrite.** Edit the artifact to add a `## Follow-up Analysis {ISO 8601 timestamp}` section. Prior candidate scoring and verdicts stay immutable.
+- **Bump frontmatter.** Update `last_updated` + `last_updated_by`; set `last_updated_note: "<one-line summary of follow-up>"`.
+- **Re-dispatch narrowly.** Spawn ≤1–2 fresh agents scoped to the new candidate or dimension. Do NOT re-run the full skill.
+- **When to re-invoke instead.** If the candidate set or dimensions shift materially, re-run `/skill:explore` for a fresh artifact. The previous block's `Next step:` stays valid for the existing artifact.
+
+## Important Notes
+
+- Parallel Agent dispatch — every `Agent(...)` call in the same assistant message (multiple tool_use blocks in one response), never one per turn. Call shape: `Agent({ subagent_type: "<agent-name>", description: "<3-5 word task label>", prompt: "<task>" })`.
+- Always spawn fresh research to validate current state - never rely on old research docs as source of truth
+- Old research documents can provide historical context but must be validated against current code
+- Generate 2-4 named candidates in Step 2; confirm them with the developer at Step 3 before per-candidate fit dispatch
+- Web-search-researcher is a first-class Step 2 agent for ecosystem candidate-source — skip only when the topic is wholly internal and design-space enumeration plus user shortlist cover the space
+- Per-candidate fit dispatch caps at two agents per candidate (one codebase-analyzer, one web-search-researcher) — skip either when no dimension of its anchor-type was kept
+- Solutions documents should be self-contained with all necessary context
+- Each agent prompt should be specific and focused on a single candidate scored on the kept dimensions
+- Quantify pattern precedent — count usage in codebase, don't just say "follows pattern"
+- Ground complexity estimates in actual similar work from git history
+- Think like a software architect — option-shopping output is 2–4 comparable candidates plus an honest fit verdict
+- Keep the main agent focused on synthesis and comparison, not deep implementation details
+- Encourage agents to find existing patterns and examples, not just describe possibilities
+- Resolve technical unknowns during research — don't leave critical questions for design
+- **File reading**: Always read mentioned files FULLY (no limit/offset) before invoking skills
+- **Critical ordering**: Follow the numbered steps exactly
+  - ALWAYS read mentioned files first before invoking skills (step 1)
+  - ALWAYS generate candidates and run the Step 3 checkpoint before per-candidate dispatch (steps 2 → 3 → 4)
+  - ALWAYS wait for all per-candidate agents to complete before synthesizing (step 4)
+  - ALWAYS gather metadata before writing the document (step 6 before step 7)
+  - NEVER write the solutions document with placeholder values