# @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](https://pi.dev/)** as skills + extension tools.

| | |
|--|--|
| **Install** | `pi install npm:@pelec/homer-pi` |
| **Core** | [`@pelec/homer`](https://www.npmjs.com/package/@pelec/homer) (CLI: `homer` · `homer-meta`) |
| **Gallery** | [pi.dev/packages/@pelec/homer-pi](https://pi.dev/packages/@pelec/homer-pi) |
| **Source** | [Retr0-rgb-lab/Homer](https://github.com/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**.

```text
  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 |

```text
  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:

```bash
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

```bash
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.

```bash
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`](https://www.npmjs.com/package/@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](https://github.com/Retr0-rgb-lab/Homer)