rpiv-pi

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.

Skill-based development workflow for Pi Agent - 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.

Prerequisites

• Node.js - required by Pi Agent

• Pi Agent - install globally so the pi command is available:

  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:

  • 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):

    {
      "providers": {
        "zai": {
          "baseUrl": "https://api.z.ai/api/coding/paas/v4",
          "api": "openai-completions",
          "apiKey": "XXXXXXXXX",
          "compat": {
            "supportsDeveloperRole": false,
            "thinkingFormat": "zai"
          },
          "models": [
            {
              "id": "glm-5.1",
              "name": "glm-5.1 [coding plan]",
              "reasoning": true,
              "input": ["text"],
              "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
              "contextWindow": 204800,
              "maxTokens": 131072
            }
          ]
        }
      }
    }
    

• git (recommended) - rpiv-pi works without it, but branch and commit context won't be available to skills.

Quick Start

1. Install rpiv-pi:

pi install npm:@juicesharp/rpiv-pi

2. Start a Pi Agent session and install sibling plugins:

/rpiv-setup

3. Restart your Pi Agent session.

4. (Optional) Configure web search:

/web-search-config

First Session

On first Pi Agent session start, rpiv-pi automatically:

• Copies agent profiles to <cwd>/.pi/agents/
• Detects outdated or removed agents on subsequent starts
• Scaffolds thoughts/shared/ directories for pipeline artifacts
• Shows a warning if any sibling plugins are missing

Usage

Typical Workflow

/skill:discover "how does X work"
/skill:research thoughts/shared/questions/<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>

Each skill produces an artifact consumed by the next. Run them in order, or jump in at any stage if you already have the input artifact.

Recipes

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.

Skills

Invoke via /skill:<name> from inside a Pi Agent session.

Research & Design

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
design	Research or solutions artifact	thoughts/shared/designs/	Design features via vertical-slice decomposition

Implementation

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

Testing

Skill	Input	Output	Description
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
migrate-to-guidance	CLAUDE.md files	.rpiv/guidance/	Convert inline docs to guidance format

Utilities

Skill	Description
code-review	Comprehensive code reviews using specialist row-only agents (diff-auditor, peer-comparator, claim-verifier) at narrativisation-prone dispatch sites
commit	Structured git commits grouped by logical change
create-handoff	Context-preserving handoff documents for session transitions
resume-handoff	Resume work from a handoff document

Commands

Command	Description
/rpiv-setup	Install all sibling plugins in one go
/rpiv-update-agents	Sync rpiv agent profiles: add new, update changed, remove stale
/advisor	Configure advisor model and reasoning effort
/btw	Ask a side question without polluting the main conversation
/languages	Pick the UI language for rpiv-* TUI strings (Deutsch / English / Español / Français / Português / Português (Brasil) / Русский / Українська)
/todos	Show current todo list
/web-search-config	Set Brave Search API key

Agents

Agents are dispatched automatically by skills via the Agent tool - you don't invoke them directly.

Agent	Purpose
claim-verifier	Grounds each supplied code-review claim against repository state and tags it Verified / Weakened / Falsified
codebase-analyzer	Analyzes implementation details for specific components
codebase-locator	Locates files, directories, and components relevant to a feature or task
codebase-pattern-finder	Finds similar implementations and usage examples with concrete code snippets
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
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
web-search-researcher	Researches modern web-only information via deep search and fetch

Architecture

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

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)

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
3. Restart Pi.

Troubleshooting

Symptom	Cause	Fix
Warning about missing siblings on session start	Sibling plugins not installed	Run /rpiv-setup
/rpiv-setup fails on a package	Network or registry issue	Check connection, retry with pi install npm:<pkg>, re-run /rpiv-setup
/rpiv-setup says "requires interactive mode"	Running in headless mode	Install manually: pi install npm:<pkg> for each sibling
web_search or web_fetch errors	Brave API key not configured	Run /web-search-config or set BRAVE_SEARCH_API_KEY
advisor tool not available after upgrade	Advisor model selection lost	Run /advisor to re-select a model
Skills hang or serialize agent calls	Agent concurrency too low	Open /agents, raise Settings → Max concurrency

License

MIT