pi-ensemble AGENTS.md

Agent Guidelines for pi-ensemble

This document is auto-loaded by Pi when any agent works inside this repo. It establishes the rules, conventions, and project-specific constraints all development work follows. Read once; apply throughout.

ℹ️ Recursive context. pi-ensemble both uses Pi (when you, the agent, run inside it) and configures Pi (its actual purpose — building role prompts and an orchestrator extension). When this file says "the agent", it means you, the one reading this. When it says "subagents" / "role prompts" / "specialists", it means pi-ensemble's product surface.

---

1. 🚨 Pre-Push Quality Gates (BLOCKING)

CI is for VERIFICATION, not DISCOVERY. All gates pass locally before git push. Never push to "see if CI catches anything."

# 1. Build prompts (repo root) — generates dist/prompts/standard/*.md
bun run build

# 2. Type-check, lint, and smoke-test (extension/)
cd extension && bunx tsc --noEmit && bun run check && \
  for t in smoke-tests/test-*.ts; do \
    case "$t" in *-live.ts) continue;; esac; \
    bun run "$t" || exit 1; \
  done

If any check fails: fix the issue, re-run, only then push. Do NOT:

• ❌ Use --no-verify, --no-gpg-sign, or skip hooks
• ❌ Add // biome-ignore or // @ts-ignore to bypass — fix the code
• ❌ Push and hope CI catches it
• ❌ Run only the smoke test that exercises your change — they're all fast offline

Live smoke tests are NOT in the pre-push set

Files matching extension/smoke-tests/test-*-live.ts spawn real Pi children and cost real tokens (a few cents per run on Cerebras GLM-4.7). Run them only when:

• You changed spawn.ts (changes to child process behaviour)
• You bumped the Pi version pin in extension/package.json
• You're investigating a production-only failure mode

CI runs the offline tests only. Live tests are dev-machine only.

Six-pass review findings are blocking at MEDIUM severity and above. The fix loop continues until all MEDIUM, HIGH, and CRITICAL findings are resolved. Only LOW findings may be deferred or overridden with user confirmation.