@pelec/homer-pi

Stop multi-agent coding from turning into renegotiated APIs, file races, and “looks done in chat.”

Homer is a control plane for long-horizon multi-agent work: frozen contracts, path leases, and machine-checked evidence gates. This package brings that plane into Pi as skills + extension tools.

Named after the poet who stitched long narratives into one continuous work. The design idea is Jointer: separate responsibility and quality control for sub-agent execution—without becoming another chat mesh.

The pain this solves

When a lead agent fans out implementers on a multi-hour / multi-file task without a frozen contract and path discipline, three failure modes show up again and again:

Most multi-agent tooling optimizes conversation and fan-out. Homer optimizes what may change, who owns which paths, and whether completion is verifiable.

  Without Homer                         With Homer
  ─────────────                         ──────────
  lead ⇄ sub ⇄ sub  (mesh chat)         lead ──► freeze / claim / gate
  “done?” = vibes                       implementers ──► board + leased paths only
  APIs renegotiated mid-flight          star topology · no peer API chat

What Homer is not: not a full agent runtime, not an IDE, not “just more prompts,” not a replacement for Pi’s subagent packages. Pi (or pi-subagents, etc.) can still spawn; Homer constrains and gates.

Two layers: reliability + self-improvement

  lead agent  ──►  homer freeze / claim / gate     (.homer)
       │
       └── optional outer loop ──►  homer-meta prepare / wave / promote
                                         (.homer-meta)

Homer — reliability control plane

1. Human L0 approve — six-section intent page; freeze only after a person signs off
2. freeze — L0 + L1 become the versioned contract of record
3. claim — lease path globs so implementers cannot legally collide
4. Evidence — implementer writes structured return.json (files touched, real command exit codes)
5. gate — machine check; chat green is never enough

Homer-meta — self-improving dispatch (same install)

Homer alone is a one-shot control plane: after gate, nothing automatically improves how the next wave is split or recovered.

Homer-meta adds dispatch memory so the lead agent gets better over waves:

Hard guarantees:

• Meta never auto-promotes — only a human runs promote / reject
• Meta never rewrites contracts, claims, or gate outcomes — it only reads .homer/
• You can delete .homer-meta/ anytime; Homer alone remains valid

Typical meta flow:

npx homer-meta init --with-skills
npx homer-meta prepare                      # brief with D1/D2/D5 hints + playbooks
npx homer-meta wave open --id w001 --brief-id <id> --claims c1
# … normal homer freeze / claim / gate …
npx homer-meta record-outcome --claim c1 --wave w001
npx homer-meta wave close --id w001         # proposals for human review
npx homer-meta promote --proposal <id>      # human only
npx homer-meta prepare                      # next brief includes playbooks_applied

Why install this on Pi

Pi is aggressively extensible: many teams bolt on subagents, goals, and workflows. @pelec/homer-pi adds the missing contract + lease + gate layer so multi-agent runs stay:

• Auditable — frozen L0/L1 and evidence on disk under .homer/
• Parallel-safe — path-disjoint claims before fan-out
• Honest about done — gate is machine-checked, not social
• Improvable — optional Homer-meta loop without changing gate semantics

This package is Pi-facing only (skills + tools). It does not change Grok/Kimi skill trees; those hosts keep using @pelec/homer + homer init --hosts ….

Install

pi install npm:@pelec/homer-pi
# project-local:
pi install npm:@pelec/homer-pi -l

# try once without persisting:
pi -e npm:@pelec/homer-pi

Brings in @pelec/homer so both homer and homer-meta CLIs are available to the tools/shell.

Quick start (inside Pi)

1. Open a project root (git/npm workspace).
2. homer_init / npx homer init — create .homer/ board.
3. Fill .homer/contracts/_draft/L0.md (six sections) and L1.json.
4. Human approves L0 → homer_freeze.
5. homer_claim path-disjoint leases → implementers work only in-lease.
6. Implementer writes .homer/evidence/<id>/return.json → homer_gate.
7. (Optional) wrap the wave with homer-meta prepare / open / outcomes / close / promote.

npx homer init
npx homer freeze --approved-by you
npx homer claim --paths "src/**" --owner agent-a --id c1
# implementer: write evidence/c1/return.json
npx homer gate --claim c1
npx homer status

What this package ships

Skills

Extension tools

Also: slash-style /homer-status (when the extension is loaded).

CLI resolution: HOMER_BIN → homer on PATH → npx --yes --package=@pelec/homer homer ….

Meta is available via shell as npx homer-meta … (same dependency). Extension tools currently wrap the core homer surface; meta remains first-class CLI for prepare/wave/promote.

Comparison (positioning, not a ranking)

Wedge: L0 human approve + L1 freeze + artifact handoff + file leases + gate + optional meta playbook evolution.

Package boundary

Security

Pi packages run with full system access. Extensions execute code; skills can instruct the model to run shell. Review source before installing third-party packages. Board state lives under .homer/ (and optional .homer-meta/) in the project.

License

MIT © Retr0-rgb-lab · Homer monorepo