Skip to content

Junhanliu-dev/espalier-engineering / skills/espalier-init

espalier-init

Verified

Analyze any existing codebase, discover its patterns and best practices, and generate an Espalier structure (rules, skills, wiki, pipeline) so AI coders produce code matching that project's language and conventions. Greenfield repos take the two-pass Decide-Then-Bind path (/espalier-map charts the conventions, init binds them); boilerplate repos run init normally, then map the product. Wires into Claude Code, Codex, and/or GitHub Copilot (.claude/, .agents/skills/ + .codex/, .github/).

FileKindSize
SKILL.mdskill md43.5 KB
hook-templates/check-layer-boundaries-go.shscript665 B
hook-templates/check-layer-boundaries-python.shscript821 B
hook-templates/check-layer-boundaries-typescript.shscript1.6 KB
hook-templates/copilot-hook-adapter.shscript2.4 KB
hook-templates/drift-detect.shscript5.7 KB
hook-templates/drift-helpers.shscript56.4 KB
hook-templates/espalier-outside.shexecutablescript28.8 KB
hook-templates/espalier-pr.shexecutablescript43.2 KB
hook-templates/espalier-stats.shexecutablescript27.3 KB
hook-templates/lookup-helpers.shscript9.5 KB
hook-templates/map-guard.shexecutablescript3.9 KB
hook-templates/maprun-dispatch.shexecutablescript21.0 KB
hook-templates/maprun-integration.shexecutablescript3.4 KB
hook-templates/maprun-merge.shexecutablescript2.9 KB
hook-templates/maprun-pr.shexecutablescript12.8 KB
hook-templates/maprun-verify.shexecutablescript5.0 KB
hook-templates/maprun.pyscript65.6 KB
hook-templates/parse-drift-blocks.pyscript1.1 KB
hook-templates/post-edit-wrapper.shscript2.0 KB
hook-templates/post-merge-backlink.shscript2.2 KB
hook-templates/pre-push-gate-wrapper.shscript3.0 KB
hook-templates/pre-push-gate.shscript18.1 KB
hook-templates/rebuild-commit-index.shscript2.6 KB
references/discovery-checklist.mdmarkdown18.5 KB
references/validation.mdmarkdown16.7 KB
references/wiki-templates.mdmarkdown710 B
references/wiring.mdmarkdown13.5 KB
templates/agent.mdmarkdown3.7 KB
templates/agents/harness-coder.mdmarkdown33.9 KB
templates/agents/harness-reviewer.mdmarkdown25.1 KB
templates/agents/harness-security.mdmarkdown14.0 KB
templates/agents/modes/fix-round.mdmarkdown3.0 KB
templates/agents/modes/re-review.mdmarkdown5.3 KB
templates/agents/modes/repo-audit.mdmarkdown2.8 KB
templates/agents/modes/simplification.mdmarkdown7.0 KB
templates/agents/modes/stage6-abuse-coverage.mdmarkdown1.3 KB
templates/agents/modes/wiki-sweep.mdmarkdown5.6 KB
templates/pipeline.mdmarkdown18.9 KB
templates/rules/coding-standards.mdmarkdown3.2 KB
templates/rules/development-process.mdmarkdown3.2 KB
templates/rules/engineering-structure.mdmarkdown1008 B
templates/rules/production-standards.mdmarkdown5.8 KB
templates/rules/security-standards.mdmarkdown5.6 KB
templates/scout-prompts.mdmarkdown9.0 KB
templates/skills/espalier-ask.mdmarkdown6.4 KB
templates/skills/espalier-audit.mdmarkdown10.0 KB
templates/skills/espalier-coding-references/platform-native.mdmarkdown9.4 KB
templates/skills/espalier-coding-spec.mdmarkdown496 B
templates/skills/espalier-coding.mdmarkdown4.0 KB
templates/skills/espalier-doctor.mdmarkdown8.0 KB
templates/skills/espalier-fix.mdmarkdown77.5 KB
templates/skills/espalier-grill.mdmarkdown21.5 KB
templates/skills/espalier-map.mdmarkdown20.0 KB
templates/skills/espalier-maprun.mdmarkdown31.1 KB
templates/skills/espalier-prune.mdmarkdown13.0 KB
templates/skills/espalier-repot.mdmarkdown7.6 KB
templates/skills/espalier-requirements.mdmarkdown4.7 KB
templates/skills/espalier-review.mdmarkdown4.5 KB
templates/skills/espalier-security.mdmarkdown5.6 KB
templates/skills/espalier-simplify.mdmarkdown25.0 KB
templates/skills/espalier-stages/1-2-requirements.mdmarkdown7.6 KB
templates/skills/espalier-stages/3-coding.mdmarkdown15.0 KB
templates/skills/espalier-stages/4-panel.mdmarkdown14.3 KB
templates/skills/espalier-stages/5-6-contract.mdmarkdown10.3 KB
templates/skills/espalier-stages/7-10-delivery.mdmarkdown16.8 KB
templates/skills/espalier-stages/simple.mdmarkdown14.0 KB
templates/skills/espalier-testing.mdmarkdown2.9 KB
templates/skills/espalier.mdmarkdown27.7 KB

templates/skills/espalier-maprun.md

View on GitHub
---
name: espalier-maprun
description: Master runner for a CLEARED Espalier map — drives its FILED change slices to completion over hours and days. One interactive pass reaps finished workers, merges what passed (opening one reviewable slice PR per ticket when the plan opts in), relays parked questions to the human, grills and dispatches up to N headless espalier pipelines in isolated worktrees, syncs optional trackers, then stops. Holds no state in context — everything is reconstructed from disk, so a master killed by quota exhaustion, network loss or a closed laptop resumes exactly where it stopped. Slash: /espalier-maprun
---

# Espalier Run

`/espalier-map` produces a cleared map and FILED change skeletons. `/espalier`
runs **one** of them. This lane runs **all of them**, over days, with a human in
the loop only where a human is genuinely needed.

## When to Use

- `/espalier-maprun <map-slug> plan` — author `plan/plan.json` for a CLEARED map
- `/espalier-maprun <map-slug>` — advance a map's run by one pass
- `/espalier-maprun` — advance the single map that has a `plan/` folder
- `/espalier-maprun <map-slug> status` — report without changing anything
- `/espalier-maprun <map-slug> pause [reason]` / `resume` — durable dispatch
  pause (`maprun.py <map> pause`): in-flight workers finish, merge and sync,
  but nothing new dispatches until resume. Survives every session boundary —
  the instruction lives in `state.json`, not in anyone's context.

Do NOT use for: a single change (`/espalier`), a map that is not yet CLEARED
(`/espalier-map`), or a bug (`/espalier-fix`).

The headless worker modes require a local headless CLI: Claude Code
(`claude -p`) or Codex (`codex exec`). Run the master from an interactive
Claude Code or Codex session. `worker_mode: inline` needs no headless CLI at
all — the master session does the work itself — which also makes it the one
mode available on a Copilot-only install.

## The Shape

Three moving parts, and the split between them is the whole design.

| Part | What it is | Why |
|---|---|---|
| **Master** | this session — interactive, invoked by a human | It is the ONLY thing that can ask a question. Every human decision routes here. |
| **Workers** | up to N headless sessions, one per git worktree — or, in `inline` mode, the master itself | Each headless worker is a real session with its own main loop, so it spawns its own coder/reviewer/security agents with no nesting problem. It outlives the master. |
| **State** | `plan.json` (static) + `state.json` (mutable), beside the map | The master holds **nothing** in context. Every pass rebuilds from disk. This is what makes the run survivable. |

**Two execution modes**, chosen once at plan time (`worker_mode`):

- **Headless** (`session` / `staged`) — the master supervises detached worker
  processes and never runs a pipeline itself. Workers keep grinding after the
  master's session ends; the operator watches them on the `watch` dashboard.
  Best for big maps, parallel slices, unattended runs.
- **Inline** (`inline`) — there are no detached workers: the master runs each
  ticket's pipeline **in this session**, spawning the stage agents
  (coder/reviewer/security) directly, exactly as a normal `/espalier` session
  would — but inside the ticket's prepared worktree. One ticket at a time,
  everything visible in the conversation, questions go straight to the human.
  Best for small maps, attended runs, or installs without a headless CLI.
  Nothing outlives the session, but the state machine makes that cheap: a
  killed session's half-done ticket is retried from `pipeline-state.md`.

In headless modes **the master never runs a pipeline itself and never spawns
pipeline subagents** — it supervises processes; that distinction is what lets
a worker keep grinding after the master's session ends. In `inline` mode that
rule inverts by design: the master IS the worker, one ticket at a time.

```
<map>/plan/
├── plan.json          tickets, dependency edges, branches, worker + sync config
├── state.json         mutable run state — the single source of truth
├── map-plan.md        the human-readable plan
├── questions/<key>.md parked questions awaiting a human
├── logs/<key>.log     worker output  (+ .pid, .heartbeat, generated helpers)
└── verify-report.md   integration verification result
```

## The Plan Step (once per map)

A cleared map carries decisions, not execution config. `plan` authors it:

1. Read the map's Spawned Changes table and each FILED skeleton's
   frontmatter (`charted_from:`, `tickets:`).
2. Propose the ticket list and dependency edges (derive candidates from the
   slices' ordering and their source decision tickets' `blocked_by` graphs).
   Put the edges to the human with `AskUserQuestion` — a wrong edge
   serializes or collides work, and it is the one thing worth a human minute.
3. Ask for: integration branch name, base branch, concurrency, worker
   platform (`claude`/`codex`), worker mode, model, and — optionally —
   ClickUp list/task ids and a Harvest project mapping.
   The **worker mode** question is the execution-mode choice — put the
   trade-off to the human plainly: `session`/`staged` = headless workers that
   outlive the session, watched on the dashboard, up to N in parallel;
   `inline` = the master works each ticket itself in-session (stage agents
   spawned directly, questions asked live, no headless CLI needed), one
   ticket at a time, with a fresh session recommended every 1–2 tickets.
   Ask the **PR opt-in** explicitly: with a `pr` config, the master pushes
   ticket branches and the integration branch and opens one reviewable slice
   PR per ticket (plus a final assembly PR) — name that rail change when you
   ask, because without `pr` nothing ever reaches the remote. If opted in,
   run `bash espalier/hooks/maprun-pr.sh <map-dir> setup` after `init` — it
   probes push capability and warns about `pull_request` workflows whose
   `branches:` filter would silently skip CI on slice PRs (that filter fix
   must land on the base branch before the first slice PR opens).
4. Seed `workspaces`, `verify`, `worker_env`, and `union_merge` from what
   init discovered (the same build/lint/test commands the pre-push gate
   runs); show the result for confirmation.
5. Write `plan/plan.json` + a human-readable `plan/map-plan.md`, and a
   `plan/.gitignore` containing `logs/`, `*.tmp`, `state.json`, and
   `questions/` — run state carries machine-local pids and absolute worktree
   paths, so it must never travel through git (plan.json and map-plan.md ARE
   tracked). Then:

```bash
python3 espalier/hooks/maprun.py <map-dir> init
```

## One Pass

Execute in order. Every step is idempotent — a pass interrupted anywhere is
safely repeated.

**Run each pass in a FRESH session** (`/clear` or a new terminal). Everything a
pass needs is on disk; anything remembered from a previous pass is either
duplicated there or stale — and stale beliefs about ticket states are how a
master relays a question twice or reports the wrong status. Continuing in an
old session is tolerable only if you treat prior knowledge as void and re-run
`status` before acting on anything.

### 0. Locate and load

Resolve the map directory, then:

```bash
python3 espalier/hooks/maprun.py <map-dir> status
```

Read it. That output — not your memory of a previous pass — is the truth.

### 1. Reap

```bash
python3 espalier/hooks/maprun.py <map-dir> reap
```

Classifies every `DISPATCHED` ticket by process liveness (pid + process
identity + heartbeat age), its outcome sentinel, its `pipeline-state.md`
stage, and a **git-state check** that confirms the worktree actually contains
the work its state file claims. A worker that died between writing state and
doing the work is caught here rather than resumed into corruption. Reap also
collects any in-worktree question file into `plan/questions/`.

Outcomes: `PASSED`, `ESCALATED`, `PARKED`, `QUOTA` (usage limit — resumable),
or back to `TODO` (died; retry). A worker that reports `MISBASED` (its branch
lacks the FILED skeleton) or `ABORTED` is classified `ESCALATED` — both mean
the run's ground truth is wrong and a human must look. A live pid with a
stale heartbeat is flagged `SUSPECT`, not trusted.

To see what a still-running worker is actually doing:

```bash
python3 espalier/hooks/maprun.py <map-dir> tail        # all DISPATCHED
python3 espalier/hooks/maprun.py <map-dir> tail <key>  # one
```

It parses the worker's streaming-JSON log into tool counts, recent tool
calls, recent assistant text, and the final result event. A worker with no
new events in ten minutes is worth investigating regardless of what its
heartbeat says. (Codex workers log plain text — read the log file directly.)

### 2. Escalations halt the run

If any ticket is `ESCALATED`, **stop the pass here**. Do not merge, do not
dispatch. Report each one with the reason and the relevant excerpt from its
worktree's `review-record.md` / `security-record.md`, sync trackers, and hand
back to the human.

Read those records through a subagent — one reader per escalated ticket,
returning only the decisive lines (the verdict sentinel and the P0/P1
findings or Escalation Reason block). Full records never enter the master's
context.

`reap` has already marked the whole downstream subtree `BLOCKED`, so the
report shows the true blast radius rather than discovering it one ticket at
a time.

### 3. Relay parked questions

For each `PARKED` ticket, read `plan/questions/<key>.md`. Put the questions to
the human with `AskUserQuestion` — you are the only part of this system that
can. Then:

1. Write the answers into that slice's `requirements.md` **in the integration
   worktree** (`bash espalier/hooks/maprun-integration.sh <map-dir>` prints
   its path), under a `## Answers relayed by the runner` heading, with the
   date.
2. Commit them to the integration branch (with a `pr` config, follow with
   `bash espalier/hooks/maprun-pr.sh <map-dir> sync` so the remote shows
   what workers will inherit).
3. Delete `plan/questions/<key>.md`.
4. `maprun.py <map-dir> mark <key> TODO` — it re-enters the frontier and
   resumes from its recorded stage on the next dispatch.

A parked question frees its slot and blocks only that ticket. It is **not** an
escalation and must not halt the run.

A `PARKED` ticket whose `plan/questions/<key>.md` is MISSING means a previous
pass crashed between relaying and re-marking: the answers already live in the
integration worktree's `requirements.md`. Just `mark <key> TODO` and move on.

### 4. Merge what passed

For each `PASSED` ticket, oldest first — **with a `pr` config, open the slice
PR before the merge** (order matters: once the merge is pushed, the branch is
contained in its base and the forge can no longer open a PR for it):

```bash
bash espalier/hooks/maprun-pr.sh <map-dir> open <key>    # pr config only
bash espalier/hooks/maprun-merge.sh <map-dir> <key>
```

- `open` exit 0 → the slice PR number/url are recorded in state. Exit 5 →
  the forge is unavailable (no gh, no auth, no push permission): **warn and
  continue** — the local merge never blocks on the forge; note in the report
  that this slice has no PR. Exit 1 → a rejected push; someone else wrote to
  a maprun branch on the remote — report it and do not force.
- merge exit 0 → `mark <key> MERGED`, then (pr config)
  `bash espalier/hooks/maprun-pr.sh <map-dir> sync` — the pushed integration
  branch now contains the slice branch, so the forge closes the slice PR as
  **merged** on its own, preserving its diff and CI verdict for review.
  Then `clickup <key>`, then log Harvest (below).
- merge exit 1 → an operational failure (not a conflict — the script prints
  what git said). Fix the environment and repeat the step; do not mark
  anything.
- merge exit 2 → a real conflict. `mark <key> ESCALATED --error "merge
  conflict: …"` and halt per step 2. Do not attempt to resolve it yourself:
  the declared `union_merge` rules already absorb the expected registry
  collisions, so anything reaching here is a genuine disagreement that needs
  a human. (An already-opened slice PR stays open — it is a good surface for
  the human to resolve on.)

Slice PRs are **advisory review, after the fact**: the run does not wait for
approvals or checks. Review comments become follow-up fix tickets (append to
the map, or `/espalier-fix`); nothing dispatches differently because a slice
PR has feedback.

### 5. Grill, then dispatch

```bash
python3 espalier/hooks/maprun.py <map-dir> frontier
```

For each key returned — **grill before you dispatch**:

1. Read that slice's `requirements.md`. If its frontmatter already carries
   `grilled: <timestamp>`, skip to dispatch.
2. Otherwise invoke `espalier-grill` with `mode=spec` against it, and put
   every question it raises to the human with `AskUserQuestion`. This is the
   ONE moment a human can shape the work — the worker runs `--no-grill` and
   cannot ask anything.
3. Write the answers into `requirements.md` in the integration worktree, add
   `grilled: <ISO timestamp>` to its frontmatter, and commit (with a `pr`
   config, `maprun-pr.sh <map-dir> sync` after the commit).
4. Dispatch:

```bash
bash espalier/hooks/maprun-dispatch.sh <map-dir> <key>
```

   Dispatch exit codes: **3** = syncing the integration branch into the
   ticket's existing worktree conflicted — `mark <key> ESCALATED --error
   "integration sync conflict"` and halt per step 2. **4** = an unanswered
   question still exists (master-side or un-reaped in the worktree) — run
   steps 1+3 for it first.

5. `maprun.py <map-dir> clickup <key>` (no-op without ClickUp config).

The worker branches off the integration branch, so it inherits every merge
and every grilled requirement that landed before it.

**Inline mode (`worker_mode: inline`)** — dispatch prepares the worktree,
marks the ticket `DISPATCHED`, spawns nothing, and hands the ticket to YOU:

1. Work tickets **one at a time**, in frontier order. For the current ticket,
   run the espalier pipeline stages 1–6 yourself — spawning the stage agents
   exactly as the `/espalier` skill directs — **inside the ticket's worktree**
   (dispatch printed its path; every stage agent must be told to operate on
   that directory, never on your main checkout). The change folder
   `espalier/changes/<type>/<slug>/` is already there with its drafted
   `requirements.md` — adopt it, keep `pipeline-state.md` current, commit to
   the ticket branch. Stop after Stage 6; never Stage 7+.
2. Questions need no parking: you are interactive — `AskUserQuestion` the
   human directly, write the answer into the slice's `requirements.md` in the
   worktree, commit, continue.
3. On stages 1–6 clean: `mark <key> PASSED`, run step 4 (merge, and the PR
   flow if configured) for it immediately, then take the next frontier ticket.
   On escalation: `mark <key> ESCALATED --error "…"` and halt per step 2.
4. **Context discipline:** after 1–2 tickets, finish the pass (report, stop)
   and continue in a fresh session — inline mode spends master context on
   pipeline work, and the state machine makes fresh sessions free. A session
   killed mid-ticket leaves `DISPATCHED` with no live process; the next
   session's reap retries it from `pipeline-state.md`, exactly like a dead
   headless worker.

Everything else — grill-before-dispatch, merge order, PR flow, verify,
halt-on-escalation — is identical in both modes.

### 6. Completion

When every ticket is `MERGED`:

```bash
bash espalier/hooks/maprun-verify.sh <map-dir>
```

Each ticket already built, tested and passed a review panel **alone**. This is
the only check that the *union* of them is coherent — it runs the plan's
declared build/test commands plus drift/forbidden-pattern/registration checks
on the assembled branch. On pass: mark every ticket `DONE`, set the run
`COMPLETE`, sync trackers — and with a `pr` config, open the assembly PR:

```bash
bash espalier/hooks/maprun-pr.sh <map-dir> final
```

Its body links every slice PR — the diff is big, but every line of it was
already reviewed on its slice PR; this one is the CI + sign-off gate, and
**merging it stays a human act**. Report, then offer (never auto-flip) the
map's `CLEARED → BUILT` transition. On fail: report the failures from
`verify-report.md` and halt — the run does not report COMPLETE on parts that
each work separately.

### 7. Report and stop

Tell the human, briefly: what moved, what is running now and roughly how long
it has been, what is waiting on them, and what the next pass will do. Then
**stop**. Do not loop, do not poll, do not schedule a wakeup. The workers
keep running without you; the human invokes the next pass.

## The Worker Contract

Every worker is spawned with these rules and must honour all of them. They are
embedded in the dispatch prompt; this is the reference.

1. **Stages 1–6 only.** Stop once the Stage 6 row is written — a
   `SKIPPED | folded` row or a delta-review PASS both count (the espalier
   skill's stage-row rules). Never Stage 7 (push), 8, 9 or 10. Commit
   locally to the ticket branch.
2. **The change folder is the ticket.** Adopt
   `espalier/changes/feat/<slug>/` — read its `requirements.md` as THE
   requirements document and keep its `pipeline-state.md` current
   (Current Stage, Stage History, the `- Status:` line) through every stage,
   exactly as the normal `/espalier` runner does. Missing skeleton →
   `MISBASED`, stop.
3. **Never push.** Blocked at git config level in the worktree — `pushurl` is
   set to an invalid scheme and `push.default` to `nothing`. Config, not
   instruction: an autonomous agent cannot talk its way past it.
4. **No grill.** Requirements were grilled by the map and again by the master.
5. **Read scope.** Its change folder, `espalier/rules/`, `espalier/wiki/`,
   the map's decision tickets and `findings/` digest under
   `espalier/maps/`, and the source tree — never sibling
   `espalier/changes/` folders, and it has no access to the master's `plan/`
   directory at all.
6. **Exactly one outcome sentinel**, written last, to
   `espalier/changes/feat/<slug>/.maprun-outcome`:
   `PASSED` · `ESCALATED` (reason underneath) · `PARKED` (question written to
   `.maprun-question.md` beside it first — reap carries it to the master) ·
   `MISBASED` (skeleton missing — reaped as an escalation).
   Before writing `PASSED` only: if requirements.md frontmatter has
   `charted_from: maps/{map-slug}` and Stage History recorded
   `ROUND {n} FAIL` rows, first write their bracketed finding lines (one
   per line) to
   `espalier/maps/{map-slug}/findings/{YYYY-MM-DD}-feat-{kebab}.md` — skip
   if the file exists — and commit it with the ticket branch. One writer
   per file, so the integration merge can never conflict;
   later-dispatched workers inherit it through the integration branch.
7. **Never guess in place of asking.** Park instead.
8. **Verify before resuming.** `pipeline-state.md` may claim more than the
   worktree contains (a predecessor died mid-write). Correct it down to what
   the git evidence supports before continuing — the worktree is the fact.

Workers run with `ESPALIER_UNATTENDED=1` so the espalier requirements gate
auto-approves — legitimate here precisely because the master already grilled
those requirements with a human in step 5 — plus any `worker_env` seeds the
plan declares (build-time placeholders, never real secrets).

**Worker modes** (`worker_mode` in plan.json): `session` (default) runs the
whole ticket in one headless session. `staged` runs one fresh session per
stage group (1–2, 3–4, 5–6), each resuming from `pipeline-state.md` — bounded
context for long tickets, finer crash/quota resume; the generated wrapper
owns the loop, so the worker still outlives the master. It escalates after
two legs without stage progress, and a leg that dies on a usage-limit
signature makes the wrapper exit sentinel-less so reap classifies the ticket
as resumable `QUOTA`, never an escalation. `inline` spawns no worker at all —
the master works the ticket itself per step 5-inline; the contract above
still binds it, except the question rules: an inline master asks the human
directly instead of parking, and marks state directly instead of writing
sentinels.

## State Vocabulary

| State | Meaning | Frees a slot |
|---|---|---|
| `TODO` | never started, or died and will retry | — |
| `DISPATCHED` | a worker is running | no |
| `PARKED` | waiting on a human answer | yes |
| `PASSED` | stages 1–6 clean, not yet merged | yes |
| `MERGED` | on the integration branch | yes |
| `QUOTA` | usage limit hit; resumable as-is | yes |
| `ESCALATED` | gave up — **halts the run** | yes |
| `BLOCKED` | an upstream ticket escalated | — |
| `DONE` | integration-verified at run end | — |

A ticket is dispatchable when it is `TODO` or `QUOTA`, all its dependencies
are `MERGED`/`DONE`, a slot is free, and **nothing anywhere is `ESCALATED`**.

## Watching the Run (for humans, not the master)

The operator never has to ask the master what is happening. Two read-only
commands work in a second terminal at any time — including while a master
pass is mid-flight (they never write state or move question files):

```bash
python3 espalier/hooks/maprun.py <map-dir> watch          # live dashboard, 10s refresh
python3 espalier/hooks/maprun.py <map-dir> watch 5        # faster refresh
python3 espalier/hooks/maprun.py <map-dir> feed <key> --follow   # one worker's
                                  # thinking / text / tool calls, streamed live
```

`watch` shows the run header (merged count, per-state totals, pause/halt) and
per ticket: name, state, current stage with its pipeline.md label (read live
from the worktree's pipeline-state.md), elapsed runtime, commits ahead of the
integration branch + dirty file count, whether the worker process is actually
alive, heartbeat age, a waiting outcome sentinel, the first line of any
parked question, unmet dependencies for TODO tickets, the worker's last
narration line ("say:"), and the last visible thing it did ("now:"). `feed` renders the worker's stream-json log as
greppable `THINK` / `SAY` / `TOOL` / `RES` lines (`feed <key> | grep TOOL`
gives the tool-call history). Codex logs are plain text and pass through raw.

These are observation surfaces only. Do not act on what you see there —
classification stays with `reap`, decisions stay with the master pass.

## Recovery

The failure you are designed to survive is being killed without warning.

- **Nothing lives in context.** Every pass rebuilds from `state.json`. A master
  that dies mid-pass loses at most that pass.
- **Liveness is measured by the supervisor, not the agent.** The dispatch
  script runs a heartbeat loop around the worker process, so a heartbeat means
  the process is alive — not that the agent chose to say so.
- **A stale heartbeat with a "live" pid is a suspect, not a worker.** After a
  reboot the pid may belong to someone else; `reap` cross-checks process
  identity and flags `SUSPECT`. Inspect with `tail <key>`; if the worker is
  truly gone, `mark <key> TODO`.
- **Death is diagnosed, not assumed.** A vanished process with no sentinel is
  checked against its log for usage-limit signatures (→ `QUOTA`, resumable)
  and against git for whether the worktree matches its claimed stage (→ retry,
  with the false stage claim cleared).
- **Worktrees are reused on resume.** Re-dispatching a `QUOTA` or `TODO`
  ticket picks up its existing worktree and branch; espalier resumes from the
  stage in its own `pipeline-state.md`. Dispatch first checkpoints any
  uncommitted work and merges the integration branch in, so relayed answers
  and merged sibling slices are visible to the resumed worker.
- **Quota exhaustion is expected, not exceptional.** Report which tickets are
  `QUOTA` and that the next pass will resume them; do not treat it as an
  error.

## ClickUp and Harvest (optional)

Configured under `clickup` and `harvest` in `plan.json`; absent config = the
sync commands are silent no-ops. Credentials read from `.local.env` at the
repo root and **never printed**.

- **ClickUp** — on every transition, `maprun.py clickup <key>` moves the
  task's status via `status_map` and leaves a comment. The board becomes the
  live view for anyone not reading state files.
- **ClickUp live stage mirror** — once per pass (any point after reap), run
  `maprun.py <map-dir> clickup-stages`: for each DISPATCHED ticket whose LIVE
  pipeline stage (read from its worktree) advanced since the last post, it
  maintains a single **"Pipeline: stage N — <label>" subtask** under the
  ticket's task (created on first stage, renamed on each advance; finalized
  by `clickup` at rest states — "merged ✓", "parked — waiting on a human
  answer", "escalated at stage N") and posts a `maprun: stage N` comment.
  Deduped via a sidecar in `plan/logs/`, never touches state.json — the
  operator may also run it from a cron or a second terminal for board
  updates between passes. Disable pieces with `"stage_subtask": false` /
  `"stage_comments": false` in the clickup config.
- **Harvest** — one time entry per ticket, on completion. The master is an
  interactive session, so post through your Harvest MCP rather than a stored
  credential:

  ```bash
  python3 espalier/hooks/maprun.py <map-dir> harvest-plan <key>   # → JSON payload
  ```
  then call the Harvest MCP's log-time tool with exactly those fields, then:
  ```bash
  python3 espalier/hooks/maprun.py <map-dir> harvest-record <key> <entry-id>
  ```

  `harvest-plan` returns `{"skip": …}` when unconfigured, already logged, or
  timing is missing — honour it and post nothing. Set `"mode": "record_only"`
  in the harvest config when the operator runs their own timer against the
  project: hours are recorded in `state.json` and never posted (no
  double-count). (`maprun.py harvest <key>`
  posts directly instead, but only if `HARVEST_ACCESS_TOKEN` /
  `HARVEST_ACCOUNT_ID` exist in `.local.env`.)

Both are best-effort. A missing credential or a network failure logs a line
and the pass continues — external sync must never block the build.

## Safety Rails

These are structural, not advisory:

- **Push is impossible from any worktree** (git config, worktree-scoped, both
  the ticket worktrees and the integration worktree — never the shared
  config, which would block the operator's own checkout).
- **Your working checkout is never touched.** All merges and edits happen in
  the integration worktree.
- **Without a `pr` config, nothing is ever pushed.** Getting work to the
  remote is a deliberate human act, after review.
- **With a `pr` config** (an explicit plan-time human opt-in), the MASTER —
  never a worker — pushes ticket branches and the integration branch and
  opens slice PRs. Merging the final assembly PR into the base branch
  remains a human act. Pushes are fast-forward only; a rejected push is
  reported, never forced.
- **Declared `union_merge` paths** absorb the registry collisions concurrent
  tickets are guaranteed to cause; anything else that conflicts is genuinely
  worth a human's time.
- Workers run with a permissive permission mode (`permission_mode` in
  `plan.json`) because a headless session that prompts is a hung session. The
  blast radius is one throwaway worktree that cannot reach a remote.
- Optional `worker_setting_sources` (e.g. `project,local`) strips user-level
  settings/hooks/memory injections from workers — keeps host-machine config
  from polluting long-horizon runs.

## plan.json Reference

```jsonc
{
  "map": "<map-slug>",
  "integration_branch": "feat/…",     // assembled here; never pushed
  "base_branch": "main",              // integration branch is cut from this
  "concurrency": 3,                   // max workers in flight
  "worktree_root": "../.espalier-worktrees",   // relative to repo root, or absolute
  "worker_platform": "claude",        // claude | codex (headless modes only)
  "worker_mode": "session",           // session | staged (headless; per-stage-group
                                      //   sessions) | inline (master works tickets
                                      //   in-session, one at a time — no headless CLI)
  "worker_setting_sources": "",       // optional --setting-sources for claude workers
  "permission_mode": "bypassPermissions",
  "model": "opus",
  "output_format": "stream-json",     // text buffers until exit — keep this
  "max_budget_usd": 0,                // optional per-worker cost cap; 0/omit = off
  "auto_dashboard": true,             // dispatch pops a read-only watch TUI window
                                      // (deduped per map; skipped headless/CI/
                                      //  MAPRUN_NO_DASHBOARD=1; false = never)
  "heartbeat_stale_seconds": 1800,
  "workspaces": [                     // dependency setup per workspace dir
    { "dir": "backend", "deps": "clone",   // clone | install | none
      "deps_dir": "node_modules",
      "install_cmd": "npm install --no-audit --no-fund" }
  ],
  "union_merge": ["backend/schemas/index.ts"],   // .gitattributes merge=union
  "worker_env": { "CI": "1" },        // build-time seeds; placeholders only
  "verify": {                         // integration verification (see maprun-verify.sh)
    "commands": [{ "name": "backend build", "dir": "backend", "run": "npm run build" }],
    "clean_after_build": [],
    "forbidden_patterns": [],
    "expected_registrations": { "file": "", "pattern": "", "min": 0 }
  },
  "pr": {                             // OPTIONAL — omit and nothing is pushed
    "remote": "origin",               // presence enables slice PRs (maprun-pr.sh)
    "draft": false,                   // open slice PRs as drafts
    "labels": []                      // labels applied to each slice PR
  },
  "clickup": {                        // OPTIONAL — omit for no sync
    "parent": "<task id>", "list": "<list id>",
    "status_map": { "TODO": "to do", "DISPATCHED": "in progress" }
  },
  "harvest": { "project_id": 0, "task_id": 0, "user_id": 0 },   // OPTIONAL
  "tickets": [
    { "key": "short-key",
      "slug": "<espalier/changes/feat/ slug>",
      "name": "Human readable",
      "clickup": "<task id>",         // optional per-ticket
      "deps": ["other-key"],
      "requirement": "feat: … (title of the slice's requirements.md)" }
  ]
}
```

## Anti-Patterns

- **NEVER loop or schedule a wakeup.** One pass, then stop. The human decides
  the cadence; the workers provide the autonomy.
- **NEVER let the master run a pipeline or spawn pipeline subagents in the
  headless modes.** Its whole value there is being cheap, interruptible and
  interactive. (`worker_mode: inline` is the deliberate exception — the plan
  chose to trade that for in-session execution; even then, one ticket at a
  time, in the ticket's worktree, never in the operator's checkout.)
- **NEVER dispatch past an escalation.** The halt rule exists so nothing gets
  built on top of a decision that went wrong.
- **NEVER auto-resolve a merge conflict** beyond the declared union-merged
  registries.
- **NEVER answer a parked question yourself.** It parked precisely because it
  could not be answered from the map, the rules and the requirements.
- **NEVER trust `state.json` over the worktree.** If they disagree, the
  worktree is the fact and the state file is the claim — that is what the
  git-state check in `reap` is for.
- **NEVER carry beliefs across passes.** New pass, new session; `status`
  output is the only memory. A master that "remembers" ticket states acts on
  the past.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall