@juicesharp/rpiv-pi
Advanced tools
A skill-based development workflow for Pi Agent. Five skills (research, design, plan, implement, validate) and the shared subagents that compose its ship-loop.
Pi compatibility -
rpiv-pi0.14.xtracks@mariozechner/pi-coding-agent0.70.xand@tintinweb/pi-subagents0.6.x. If you see peer-dep resolution issues after a Pi upgrade, open an issue.
⚠️ Upgrading from
0.13.x-1.0.0swaps the subagent provider fromnpm:pi-subagents(nicobailon fork) back tonpm:@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-setuponce and restart Pi. The setup dialog previews both changes (install@tintinweb/pi-subagents, removenpm:pi-subagentsfrom~/.pi/agent/settings.json) and applies them only after you confirm. After restart, run/rpiv-update-agentsto refresh the 12 bundled specialist frontmatters. Customised<cwd>/.pi/agents/*.mdfiles are not touched. The tool name reverts fromsubagent→Agent(paramsubagent_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.
thoughts/shared/.codebase-analyzer, codebase-locator, codebase-pattern-finder, claim-verifier, and 8 more, dispatched automatically by skills.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.
pi install npm:@juicesharp/rpiv-pi
/rpiv-setup
Restart your Pi Agent session.
(Optional) Configure web search:
/web-search-config
On first Pi Agent session start, rpiv-pi automatically:
<cwd>/.pi/agents/thoughts/shared/ directories for pipeline artifacts/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>
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.
Skills compose. Pick the entry point that matches your intent:
/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./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./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./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./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./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./skill:revise <plan artifact> → resume /skill:implement. Use when new constraints land after the plan is drafted./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./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)./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./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>/./skill:create-handoff → (new session) /skill:resume-handoff <doc>. Preserves context when stopping mid-task./skill:annotate-guidance once, then use the rest of the pipeline normally. Use annotate-inline instead if the project follows the CLAUDE.md convention.Invoke via /skill:<name> from inside a Pi Agent session.
| Skill | Input | Output | Description |
|---|---|---|---|
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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 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 |
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.
/web-search-config to set the Brave Search API key, or set the BRAVE_SEARCH_API_KEY environment variable/advisor to select a reviewer model and reasoning effort/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/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/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.<cwd>/.pi/agents/; sync from bundled defaults with /rpiv-update-agents (overwrites rpiv-managed files, preserves your custom agents)pi uninstall npm:@juicesharp/rpiv-pipi uninstall npm:@tintinweb/pi-subagents| 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 |
MIT
FAQs
A skill-based development workflow for Pi Agent. Five skills (research, design, plan, implement, validate) and the shared subagents that compose its ship-loop.
We found that @juicesharp/rpiv-pi demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Five malicious NuGet packages impersonate Chinese .NET libraries to deploy a stealer targeting browser credentials, crypto wallets, SSH keys, and local files.
Security News
pnpm 11 turns on a 1-day Minimum Release Age and blocks exotic subdeps by default, adding safeguards against fast-moving supply chain attacks.
Security News
The remediated findings include organization permission bugs, stale project access after transfers, OIDC replay edge cases, audit logging gaps, and an IDOR in API token deletion.