@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.

| | | |--|--| | Install | pi install npm:@pelec/homer-pi | | Core | @pelec/homer (CLI: homer · homer-meta) | | Gallery | pi.dev/packages/@pelec/homer-pi | | Source | Retr0-rgb-lab/Homer |

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:

| Pain | What happens in practice | Homer’s answer | |------|--------------------------|----------------| | Interface drift | Sub-agents “agree in chat” on APIs, then ship incompatible shapes | L0 human-approved + L1 frozen — no peer renegotiation of the contract | | Write races | Two agents edit the same paths; merges and blame become noise | Path leases (claim) — concurrent work only when leases are disjoint | | Fake done | Green chat, missing tests, undeclared touches; no machine check | Evidence + gate — return.json is the only “done” signal |

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

| | Homer (required for gates) | Homer-meta (optional outer loop) | |--|--------------------------------|--------------------------------------| | Job | Make this wave correct and auditable | Make the next wave plan smarter | | Board | .homer/ | .homer-meta/ (only reads .homer) | | CLI | homer | homer-meta | | Loop | freeze → claim → implement → evidence → gate | prepare → wave open → record outcomes → close → human promote |

  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:

| Capability | Meaning | |------------|---------| | D1 decomposition | Learn better task breakdowns from past waves | | D2 path splits | Improve how claims/leases are carved (fewer conflicts) | | D5 recovery | Record failures and recovery actions; feed into the next brief | | Playbooks | Successful patterns become reusable only after a human promote |

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

| Skill | Role | |-------|------| | homer-orchestrate | Lead: draft L0/L1, human approve, freeze, claim split, dispatch, gate; optional meta loop | | homer-implementer | Sub: cold-start + lease only, honest return.json, no peer API chat |

Extension tools

| Tool | CLI | |------|-----| | homer_version | homer version | | homer_status | homer status | | homer_init | homer init | | homer_freeze | homer freeze | | homer_claim | homer claim | | homer_release | homer release | | homer_validate | homer validate | | homer_gate | homer gate |

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)

| Approach | Strength | Gap Homer fills | |----------|----------|-----------------| | Subagent / crew packages | Fan-out & roles | Contracts, leases, machine gates | | Spec-only workflows | Good docs | Path ownership + parallel safety | | Pure multi-agent chat | Fast demos | Drift, races, unverifiable “done” | | Methodology skills alone | Process guidance | Enforced board + CLI gate |

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

Package boundary

| Package | Role | |---------|------| | @pelec/homer | Control-plane CLI + schemas + templates (homer · homer-meta) | | @pelec/homer-pi | Pi package: skills + tools so Pi can drive that plane |

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