pi-compound

A small, verifier-centered engineering workflow for pi, built on pi-subagents.

Set an executable target, then an unattended verify-fix loop runs against it — on a branch, fenced by a guardrail hook, capped by a budget, with a deterministic verifier that can't be faked or weakened. The model is your stand-in's tool; the verifier is what lets you leave the room.

Why

Orchestration is the commodity part of a coding harness; the verifier sets the quality ceiling. So pi-compound keeps the loop thin (prompts the parent follows, like pi-subagents' /review-loop) and puts the engineering into the thing that determines whether autonomy is safe: the acceptance check.

What it is

• Two commands (prompt templates): /workflow-issue (direct) and /workflow-feature (with brainstorm). Each drives planner → /review-loop → worker autonomously, pausing only at human gates.
• A deterministic verifier (check_acceptance tool): the acceptance verdict is the real exit code of a project-defined acceptance.sh, not a model's opinion — so a model can't hallucinate "PASS."
• Anti-reward-hack defenses: you approve the target before work; the test must fail-then-pass (red-green); once approved it's frozen (the hook blocks edits to it); you can seed examples.
• Branch isolation: every work item runs on pi-compound/<slug>; the loop never touches main and the hook blocks git push. You review the branch diff and merge.
• Guardrail hook: blocks edits to sensitive paths (.env, lockfiles, constitution.md) — and, because pi-subagents children auto-load this extension, it governs every child agent too.

Install

pi-compound is a pi package: install it once globally, or pin it per project.

Prerequisites

pi install npm:pi-subagents      # required (spawning + /review-loop + /parallel-research)
pi install npm:pi-web-access     # optional (research fan-out: `/parallel-research`)

Global (all projects)

pi install npm:@shekhardhangar/pi-compound
pi install git:github.com/ShekharDhangar/pi-compound
pi install /path/to/pi-compound  # local clone

Extension + prompts load automatically whenever you run pi in any project.

Project-local (team pin)

cd your-project
pi install -l npm:@shekhardhangar/pi-compound
pi install -l git:github.com/ShekharDhangar/[email protected]
pi install -l /path/to/pi-compound

Writes to .pi/settings.json; teammates get the same package after trusting the project.

Try without installing

pi -e npm:@shekhardhangar/pi-compound
pi -e git:github.com/ShekharDhangar/pi-compound

Per-project bootstrap (one time)

Copy the bundled template and edit the constitution for your repo:

# npm install (global):
cp ~/.pi/agent/npm/node_modules/@shekhardhangar/pi-compound/templates/AGENTS.template.md ./AGENTS.md

# npm install (project-local, -l):
cp .pi/npm/node_modules/@shekhardhangar/pi-compound/templates/AGENTS.template.md ./AGENTS.md

# git or local path install:
cp /path/to/pi-compound/templates/AGENTS.template.md ./AGENTS.md

Usage

In any project with pi-compound installed and AGENTS.md bootstrapped:

/workflow-issue fix the broken README install link
/workflow-feature add user-facing settings for dark mode
/research-coach event-driven sync for MFD profile updates

For software-engineering research: /research-coach — fan-out searches practitioner sources (blogs, docs, GitHub, forums) by default, not academic papers unless you ask. Synthesizer runs pass 1 + pass 2 over cumulative outputs.

See templates/AGENTS.template.md for the full loop, artifacts, gates, and verifier rules.

Files

| File | What | |---|---| | index.ts | the extension: guardrail hook · frozen-acceptance enforcement · set_stage footer · check_acceptance | | prompts/ | the orchestration — workflow-issue.md, workflow-feature.md, review-rubric.md, coding-guidelines.md, research-coach.md | | agents/ | research-coach (requirements) · research-synthesizer (cumulative iteration) | | skills/research-coach/ | requirements → fan-out → synthesizer iteration (sufficient ≠ stop); /workflow-feature | | skills/writing-great-skills/ | skill-authoring reference (Matt Pocock); invoke when writing or editing package skills | | templates/research-brief.template.md | brief schema before parallel research | | templates/AGENTS.template.md | workflow map + constitution template (copy to AGENTS.md in each repo) | | SMOKE-TEST.md | how to verify the hook, child inheritance, and a workflow run |

Status

Milestone 1, verified end-to-end via headless runs (full workflow, child-governance, the deterministic verifier catching a planted bug, frozen acceptance, git push blocked). The compounding/meta-harness loop (/learn) is Milestone 2 — and it needs real run traces first.