roach-pi Technical Briefing
The Problem
Engineering teams using the pi coding agent lack structured discipline primitives for multi-agent orchestration. Without built-in review pipelines, plan validation, and phase isolation, code quality depends on ad-hoc agent behavior rather than enforceable workflows.
What This Does
The roach-pi extension adds agentic orchestration to the pi coding agent, providing 13+ CLI commands (/clarify, /plan, /ultraplan, /review, /ultrareview) that enforce engineering discipline. It operates across the extensions/ directory (146 files, 89 code files), introducing autonomous agent spawning, sandbox execution with approval stores, and multi-perspective code review. The framework uses React on the frontend with npm as package manager and GitHub Actions for CI. Eight extension entry points exist: extensions/fff-search/index.ts, extensions/agentic-harness/index.ts, extensions/autonomous-dev/index.ts, and extensions/session-loop/index.ts among them.
How It Is Wired
Execution starts at execute in extensions/fff-search/index.ts:433, which reaches 119 functions and is the sole entry point with no callers within the repo. The orchestrator start in extensions/autonomous-dev/orchestrator.ts:139 reaches 23 functions and is similarly isolated. Key hub modules include extensions/agentic-harness/index (3 callers, 17 imports, instability 0.85) and extensions/agentic-harness/subagent (4 callers, 9 imports, instability 0.69). Cryptographic operations occur via randomBytes(8).toString in extensions/agentic-harness/subagent.ts. The internal call graph contains 510 resolved edges; updateActivity is called from 11 places, logEvent from 10. Five files show high branching density (6+ branch points over ~165 lines), and four files are oversized (643 code lines), creating cognitive load for maintenance.
How To Use It
After installing via pi install git:github.com/tmdgusya/pi-engineering-discipline-extension, run /setup first — this is not optional. It configures quietStartup: true in ~/.pi/agent/settings.json so the ROACH PI banner replaces default startup output. Warning: if the superpowers skill is installed, remove it before using this extension, as skill name conflicts can cause unexpected behavior. Commands span ambiguity resolution (/clarify), plan generation (/plan), multi-perspective review (/ultraplan), single-pass review (/review), and loop scheduling (/loop <interval> <prompt>). Configuration requires no additional env vars beyond the pi agent's existing settings.
Real-World Use
A team adopting roach-pi for a new service can run /ultraplan to generate an implementation plan, then use /ultrareview to execute a 3-stage review pipeline: 10 subagents run in parallel across five reviewer roles (feasibility, architecture, risk, dependency, user value), a verifier deduplicates findings, and synthesis produces a structured report saved to docs/engineering-discipline/reviews/YYYY-MM-DD-<topic>-review.md. This mirrors local claude-code bughunter pipelines without cloud teleport.
Code Health & Issues
Static analysis of 91 code files found 13 medium-severity findings across 4 kinds: high branching density in extensions/agentic-harness/agents.ts, extensions/agentic-harness/sandbox/approval-store.ts, and extensions/agentic-harness/runner-cli.ts; oversized files at extensions/agentic-harness/subagent.ts, extensions/agentic-harness/index.ts, and extensions/fff-search/index.ts; deep nesting (max depth 6) in extensions/fff-search/index.ts and extensions/workspace-memory/index.ts; and duplicated 6-line blocks across extensions/agentic-harness/compaction.ts, extensions/agentic-harness/index.ts, and test files. The code health audit adds 5 findings: [HIGH] no LICENSE file at root; [HIGH] CI does not invoke the existing 41 test suite; [MEDIUM] no Dependabot/Renovate configuration for 6 manifests; [MEDIUM] no dependency vulnerability scanning on pull requests; [LOW] missing timeout-minutes on 2 workflow jobs.
The Bottom Line
This extension delivers concrete agentic orchestration primitives for the pi coding agent, with measurable command coverage and a transparent codebase. The main drawbacks are the absent license (blocking reuse) and CI that has tests but never runs them. Teams needing structured multi-agent workflows will find value here; those requiring out-of-the-box licensing or fully automated dependency governance will need to address the audit findings first.