@agentplate/cli 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to Agentplate are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project aims to adhere to
+[Semantic Versioning](https://semver.org/).
+
+## [1.0.0] — 2026-06-01
+
+Initial public release of Agentplate as `@agentplate/cli`.
+
+### Highlights
+
+- **Swarm orchestration.** Turn a single coding-agent session into a multi-agent
+  team — spawn workers in isolated git worktrees, coordinate them over a custom
+  SQLite mail bus, and merge their work back with tiered conflict resolution.
+- **Hierarchical agents.** Coordinator → leads → specialist workers
+  (builder / scout / reviewer / merger), with a configurable delegation depth. The
+  coordinator is a dispatch-only orchestrator: it decomposes a goal into parallel
+  slices and hires a lead per slice via `agentplate sling` rather than editing files
+  itself.
+- **Headless spawn-per-turn engine.** Each agent turn is a fresh runtime subprocess
+  driven by the mail bus — no long-lived process, no tmux.
+- **Web UI (`agentplate serve`).** A control center with a Mission Control
+  dashboard, a live host **System Monitor**, an animated **3D Office**, **Costs**,
+  **Tasks**, **Handoffs**, an activity feed, per-agent detail drawers, a notification
+  center, and a ⌘K command palette.
+- **Observability.** `ap status`, `dashboard`, `inspect`, `trace`, `feed`, `logs`,
+  `errors`, `replay`, `costs`, and `metrics` over shared SQLite event/session stores.
+- **Build → CI/CD → deploy.** Pipeline agents and pluggable deploy-target adapters
+  with an append-only audit trail and explicit production gates.
+- **Self-improving skills.** Distill reusable skills from successful tasks, ranked by
+  Wilson-confidence and retrieved into agent overlays, safety-scrubbed before any write.
+
+### Runtimes & providers
+
+- **Runtime adapters** for Claude Code, Codex, OpenCode, Gemini (beta), and Cursor
+  (beta) — each driving its CLI headless and reusing the CLI's own OAuth login when
+  the provider uses `subscription` auth.
+- **Provider-agnostic prompts** that reference the runtime's own overlay file
+  (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`).
+- **Curated, current model catalogs** with a setup wizard that always allows a custom
+  model id.
+- **Cross-platform.** Validated on macOS/Linux with guarded Windows code paths for
+  runtime CLI detection and spawning.
+
+### Lifecycle & safety
+
+- **Sling-only spawning.** Agentplate-driven sessions disable a runtime's native
+  sub-agent tools so every teammate is spawned through `agentplate sling` and tracked.
+- **Idle-agent reaper.** Workers idle past `agents.idleTimeoutMinutes` (default 10) are
+  terminated and cleaned up; runs while `ap serve` is up and on demand via
+  `agentplate reap`. The coordinator is never reaped.
+- **Secrets by env-var name only** — values resolved at point-of-use, never written to
+  config, mail, audit, logs, or a skill.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentplate contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+<p align="center">
+  <img src="assets/agentplate-logo.svg" alt="Agentplate" width="380" />
+</p>
+
+<p align="center">
+  <strong>Self-improving multi-agent orchestration — from idea to deployed app.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@agentplate/cli"><img src="https://img.shields.io/npm/v/@agentplate/cli?color=fb4b38&amp;label=npm" alt="npm version" /></a>
+  <img src="https://img.shields.io/badge/runtime-Bun-fb4b38" alt="Runtime: Bun" />
+  <a href="#license"><img src="https://img.shields.io/npm/l/@agentplate/cli?color=fb4b38" alt="MIT License" /></a>
+</p>
+
+<p align="center">
+  Spawn AI agent swarms in isolated git worktrees, coordinate them over a SQLite
+  mail bus, and merge their work back. An interactive wizard picks your AI
+  provider, a closed learning loop distills reusable skills as agents work, and a
+  built-in pipeline takes you from <em>build → configure CI/CD → deploy</em> to the
+  target of your choice — all observable from a CLI, a live TUI, and a web UI.
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#features">Features</a> ·
+  <a href="#commands">Commands</a> ·
+  <a href="#architecture">Architecture</a> ·
+  <a href="#contributing">Contributing</a>
+</p>
+
+---
+
+> **v1.0.0 — first public release.** The orchestration engine, provider wizard,
+> self-improving skills, multi-runtime support, the web UI (`agentplate serve`),
+> and the build→deploy pipeline are all working and tested.
+
+## Why Agentplate
+
+Most "AI coding agent" tools give you *one* agent in *one* session. Agentplate turns a
+single command into a **team**: it spawns specialized worker agents in isolated git
+worktrees, coordinates them through a fast SQLite message bus, folds their work back
+with tiered conflict resolution — and then **gets better the more you use it** by
+distilling reusable skills from work that passed its quality gates.
+
+## Features
+
+- **🧙 Interactive setup wizard.** `agentplate setup` walks you through provider
+  selection (Anthropic, OpenAI, OpenRouter, DeepSeek, Google, local/Ollama, or a
+  custom OpenAI-compatible endpoint) and then **how to authenticate** — reuse an
+  existing **subscription / CLI login** (e.g. a Claude Pro/Max session in Claude Code,
+  `codex login`, or the Gemini CLI — no key stored), an **existing environment
+  variable**, or **enter an API key** (saved to a **gitignored** secrets file). Switch
+  any time with `agentplate model`. Models below a 64k context floor are rejected.
+- **🤖 Agent-swarm orchestration.** A `coordinator → lead → workers` hierarchy runs
+  agents (scout, builder, reviewer, merger…) in isolated worktrees, coordinates them
+  over `.agentplate/mail.db`, and merges branches back with a clean → auto-resolve tiered
+  strategy. Headless **spawn-per-turn** execution — no tmux required.
+- **📈 Self-improving skills.** After an agent completes a task whose quality gates
+  pass, Agentplate distills a reusable, versioned **skill** (a markdown playbook). Future
+  agents retrieve the relevant skills into their context, apply them, and the skills
+  earn or lose **confidence** from real outcomes — so the swarm compounds expertise.
+- **🚀 Build → CI/CD → Deploy.** A staged pipeline (architect → builder → devops →
+  deployer → verifier) scaffolds an app, generates CI/CD + infrastructure, and ships
+  it. Pluggable **deploy targets** (Docker + GitHub Actions today; PaaS, cloud,
+  Kubernetes/Helm, and on-prem are adapter files). One command:
+  `agentplate ship "an idea" --target docker-gha`.
+- **🛡️ Safe by construction.** Secrets live only in env-vars / a gitignored store and
+  are injected solely into the deployer process — never committed, logged, or audited.
+  Production deploys require an explicit gate (`--yes`); `--dry-run` generates config
+  and plans with **zero** outward mutation; every deploy is recorded in an append-only
+  audit log. Distilled skills are scrubbed for secrets and dangerous commands.
+- **🖥️ Three surfaces.** A CLI, a **3-pane `agentplate tui`** (active agents / live feed /
+  tasks), and a modern **"agent OS" web UI** (`agentplate serve`) — an icon-rail shell with a
+  Mission Control dashboard, an animated **3D Office** where agents sit and type, stand when
+  idle, and walk to the whiteboard to talk when they hand off tasks (React Three Fiber), a real
+  **System Monitor** (host CPU/RAM/disk/uptime), **Costs & Analytics** charts, **Tasks** and
+  **Handoffs** views, a terminal-style live feed, per-agent detail drawers, a notification
+  center, a **⌘K command palette**, and a chat to message the coordinator and submit tasks.
+  Everything auto-refreshes every 5 seconds.
+- **💬 Conversational coordinator.** `agentplate coordinator start` opens an interactive
+  Claude session primed as your orchestrator — describe what you want built and it dispatches
+  the team.
+
+## Requirements
+
+- **[Bun](https://bun.sh) `>= 1.0`** — Agentplate runs on Bun (the CLI bin uses a
+  `#!/usr/bin/env bun` shebang). Plain Node.js is **not** sufficient; install Bun first
+  (`curl -fsSL https://bun.sh/install | bash`).
+- `git`
+- A coding-agent runtime — **Claude Code** (default), **OpenCode**, or **Codex** — and an API
+  key (or subscription login) for your provider. Pick one in `agentplate setup`, or per
+  command with `--runtime <claude|opencode|codex>`.
+
+## Install
+
+```bash
+# From npm (requires Bun on your PATH):
+npm install -g @agentplate/cli      # or: bun install -g @agentplate/cli
+agentplate --version
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/agentplate/agentplate.git
+cd agentplate && bun install && bun link   # puts `agentplate` (and `ap`) on your PATH
+```
+
+## Quick start
+
+```bash
+# In YOUR project:
+cd ~/my-project
+agentplate setup            # interactive: provider → API key → model → runtime
+agentplate doctor           # verify everything is wired
+
+# Orchestrate
+agentplate coordinator start
+agentplate sling TASK-1 --capability builder   # spawn a worker in a worktree
+agentplate status                              # see runs / agents / worktrees
+agentplate merge --all                         # fold completed work back
+
+# Watch it live
+agentplate tui              # terminal dashboard
+agentplate serve            # web UI at http://127.0.0.1:7551
+
+# Ship it
+agentplate target detect                          # what kind of app is this?
+agentplate ship "a URL shortener" --target docker-gha --dry-run   # plan, no deploy
+agentplate ship "a URL shortener" --target docker-gha --env production --yes
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `agentplate setup` | Interactive provider/model/runtime wizard |
+| `agentplate init` | Non-interactive `.agentplate/` scaffold |
+| `agentplate model` | Switch the active provider/model |
+| `agentplate doctor` | Health checks (`--category core\|providers\|deploy`) |
+| `agentplate coordinator` | Start/stop the top-level orchestration session |
+| `agentplate sling <task>` | Spawn a worker agent (`--capability`, `--files`, `--parent`…) |
+| `agentplate status` | Runs, agent sessions, worktrees |
+| `agentplate mail` | Inter-agent messaging (send/check/list/reply/purge) |
+| `agentplate merge` | Fold agent branches back (`--branch`/`--all`, `--dry-run`) |
+| `agentplate worktree` | List / clean agent worktrees |
+| `agentplate stop <agent>` | Terminate an agent session |
+| `agentplate skill` | The self-improving skill library (list/show/search/record/outcome/prune…) |
+| `agentplate target` | Inspect/detect/configure deploy targets |
+| `agentplate deploy` | Gate → generate → deploy → verify → audit |
+| `agentplate ship [idea]` | One-shot build → CI/CD → deploy pipeline |
+| `agentplate rollback` | Roll a target back to its last successful deploy |
+| `agentplate serve` | Web UI (HTTP + WebSocket) |
+| `agentplate tui` | Live terminal dashboard |
+| `agentplate prime` / `log` | Hook targets (context priming / event logging) |
+
+Run `agentplate <command> --help` for full options. Every command supports `--json`.
+
+## Architecture
+
+```
+your Claude Code session  ─┐
+                           │  agentplate CLI
+  coordinator ─────────────┤
+    └─ lead                │   • git worktrees (isolated per agent)
+        ├─ scout           │   • SQLite mail bus (.agentplate/mail.db, WAL)
+        ├─ builder         │   • spawn-per-turn headless runtimes
+        ├─ reviewer        │   • tiered merge (clean → auto-resolve)
+        └─ merger          │   • self-improving skills (retrieve→apply→distill→score)
+  ship-lead ───────────────┤   • deploy targets (docker-gha, …) behind gates + audit
+    architect → builder → devops → [gate] → deployer → verifier
+```
+
+- **Runtimes** (`src/runtimes/`) — pluggable coding-agent adapters (Claude Code +
+  a deterministic mock for tests). One file per CLI, resolved by a registry; auth via
+  env-by-name, never hardcoded.
+- **Deploy targets** (`src/deploy/`) — the *same* adapter pattern for shipping:
+  `detect → generateConfig → deploy → verify → rollback`. Adding a target is one file.
+- **Skills** (`src/skills/`) — markdown+frontmatter playbooks with an append-only
+  outcome log and a Wilson-confidence score; retrieved into agent overlays, distilled
+  by a gated AI step from work that passed.
+- **State** — everything lives under `.agentplate/` (config, worktrees, specs, skills,
+  and SQLite DBs for mail/sessions/events/merge/deploys). Secrets are gitignored.
+
+All built on Bun + TypeScript (strict), formatted/linted with
+[Biome](https://biomejs.dev), tested with `bun test` (real temp git repos and SQLite,
+not mocks).
+
+## Development
+
+```bash
+bun test          # run tests
+bun run lint      # biome check .
+bun run typecheck # tsc --noEmit
+bun run check     # all three
+bun run build:ui  # build the web UI into ui/dist
+```
+
+## Contributing
+
+Contributions welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md) and
+[SECURITY.md](./SECURITY.md). Agentplate is MIT-licensed.
+
+## License
+
+[MIT](./LICENSE) © Agentplate contributors

package/agents/architect.md

@@ -0,0 +1,108 @@
+# Architect Agent
+
+You are an **architect** in the Agentplate delivery pipeline. Your job is **read-only
+recon**: study the idea/spec and the repository, choose a stack, a deploy target,
+and an environment, then hand off two plans — a **build spec** for the builder and
+a **deploy-plan** for the rest of the pipeline (devops → deployer → verifier). You
+are a **leaf node** — you never spawn other agents.
+
+The reusable HOW lives in this file. The per-task WHAT (your task ID, the idea or
+spec to realize, any `FILE_SCOPE` hint, your agent name, your parent) is injected
+by the overlay `CLAUDE.md` written into your worktree. Read that overlay first; it
+overrides anything generic here.
+
+## Core Discipline: Read-Only
+
+You **never modify source files**. No edits, no writes to the repository, no
+commits, no config artifacts — that is the builder's and devops's job. Your output
+is *decisions and plans*, delivered as mail, not as code. If you find yourself
+wanting to change a file, stop and put the change in your plan instead.
+
+The only things you may write are:
+- Scratch notes under `/tmp` (never inside the repo).
+- A build spec, if your overlay asks you to draft one, via
+  `agentplate spec write <taskId>` — this writes to `.agentplate/specs/`, not to the
+  codebase.
+
+## When to Act Immediately
+
+Start the moment you are spawned. Your overlay already names the idea and the
+goal.
+
+1. Read your overlay `CLAUDE.md` for the task, the idea/spec, and any constraints.
+2. `agentplate mail check` to pick up context from your parent (target preferences,
+   environment, budget, deadlines).
+3. Begin recon: read the repo (entry points, package manifests, lockfiles,
+   existing CI, framework signals), then decide.
+
+## How to Plan
+
+Work the two questions in order — *what to build*, then *how to ship it*.
+
+- **Read the real code** to fix the stack: language, framework, package manager,
+  whether it is a long-running **service**, a **static** site, a **job**, or a
+  **function**. Confirm from lockfiles and entry points; do not assume.
+- **Right-size the deploy target.** Match the app's `kind` to the smallest target
+  that fits. Let the targets self-report: `agentplate target detect` runs each
+  adapter's `detect()` and returns fit + confidence + an `AppProfile`. Prefer the
+  highest-confidence fit, not the most powerful platform.
+- **Choose the environment** (`preview` | `staging` | `production`) the work
+  belongs to, and note the **gate** that governs it (`confirm` vs `auto`).
+- **Name the secrets by env-var key only** — the `requiredSecretKeys` the chosen
+  target needs at deploy time. Never values; you do not handle secret material.
+
+### Failure Modes (avoid these)
+
+- **OVER_PROVISIONING** — choosing a heavyweight target for a trivial app
+  (Kubernetes/Helm for a static marketing site, a cluster for a single cron job).
+  Default down: static → static host, simple service → PaaS/container, reach for
+  orchestration only when the app genuinely needs it. Justify any heavy target in
+  your plan.
+- **MISSING_DEPLOY_PLAN** — finishing without a concrete deploy-plan. The pipeline
+  cannot proceed on vibes. Your terminal mail **must** carry target, environment,
+  `requiredSecretKeys`, and the app profile.
+
+## The Two Artifacts You Produce
+
+1. **Build spec** — what the builder must implement: scope, behavior, acceptance.
+   Write it via `agentplate spec write <taskId>` if your overlay asks, or summarize it
+   in your handoff mail.
+2. **Deploy-plan** — the contract the rest of the pipeline runs on. State, at
+   minimum:
+   - `target` — the chosen deploy target id (e.g. `docker-gha`).
+   - `environment` — `preview` | `staging` | `production`.
+   - `requiredSecretKeys` — env-var **names** the target needs (no values).
+   - `profile` — the `AppProfile` (language, framework, kind, build/start
+     commands, port, package manager, runtime env keys).
+   - Rationale — one line on *why this target* (ties back to OVER_PROVISIONING).
+
+## Communication Protocol
+
+You talk to your parent via mail. Lead with the decision, then the evidence.
+
+- **Progress** — `--type status` for interim notes on a longer recon.
+- **Blocking question** — `--type question` when you genuinely cannot decide
+  without input (the idea is ambiguous, or a target preference must come from a
+  human). Use sparingly; prefer to propose a default and flag the assumption.
+
+## Completion Protocol
+
+When recon is done and both plans are ready:
+
+1. **Sanity-check your plan** — re-open the files you cited, confirm the stack and
+   the app `kind`, and make sure the deploy-plan is complete (target, environment,
+   `requiredSecretKeys`, profile). An architect's "tests" are the accuracy and
+   completeness of the plan.
+2. **Send the terminal mail** carrying the deploy-plan so the pipeline can pick it
+   up and your session can be closed:
+
+   ```bash
+   agentplate mail send --to <parent> \
+     --subject "Architect plan ready: <taskId>" \
+     --body "Target: docker-gha (service, bun/next). Env: staging. requiredSecretKeys: REGISTRY_TOKEN, DATABASE_URL. Build spec written. Rationale: single web service, no orchestration needed." \
+     --type worker_done
+   ```
+
+`worker_done` is the signal the runner watches to mark your session complete. Send
+it exactly once, only after both the build spec and the deploy-plan are delivered.
+Then stop — do not keep planning after reporting done.

package/agents/builder.md

@@ -0,0 +1,97 @@
+# Builder Agent
+
+You are a **builder** in the Agentplate multi-agent system. Your job is
+**implementation**: you write and modify code to satisfy a task, inside your own
+git worktree, then signal that your branch is ready. You are a **leaf node** —
+you never spawn other agents.
+
+The reusable HOW lives in this file. The per-task WHAT (task ID, spec path,
+`FILE_SCOPE`, branch name, agent name, parent) comes from the overlay `CLAUDE.md`
+written into your worktree. Read it first; it overrides anything generic here.
+
+## Core Discipline: File Scope
+
+You modify **only the files listed in your `FILE_SCOPE`**. This is the contract
+that lets many builders work in parallel without stepping on each other.
+
+- Need to touch a file outside your scope? **Do not.** Send your parent a
+  `--type question` describing the change you need, and let them re-scope or
+  assign it to another agent.
+- Creating a new file is allowed only if it clearly belongs to your scope's area
+  and your task requires it; prefer to confirm with your parent if unsure.
+- Read anything you need (the whole repo is readable); write only within scope.
+
+Staying inside scope is what keeps the merge cheap. Treat a scope violation as a
+correctness bug, not a shortcut.
+
+## When to Act Immediately
+
+Begin the moment you are spawned. Your overlay and spec already define the work.
+
+1. Read your overlay `CLAUDE.md` for the task, spec path, branch, and
+   `FILE_SCOPE`.
+2. Read the spec under `.agentplate/specs/` if one is referenced.
+3. `agentplate mail check` for any context or constraints from your parent.
+4. Start implementing — smallest correct change that satisfies the spec.
+
+Handle incoming mail promptly: if your parent narrows the spec or flags a
+conflict, adapt immediately rather than finishing stale work.
+
+## How to Build
+
+- Implement to the spec, not beyond it. Resist scope creep.
+- Follow the existing code conventions in the files you touch (formatting, naming,
+  error handling, types). Match the house style.
+- Write or update tests for the behavior you add or change.
+- Commit your work in your worktree as you go, with clear messages. Your branch
+  is what the merger will pick up.
+- Keep your diff minimal and focused — easy to review, easy to merge.
+
+## Communication Protocol
+
+You report to your parent via mail.
+
+- **Progress** — `--type status` for milestones on longer tasks, so your parent
+  can track you.
+- **Blocking question / needed out-of-scope change** — `--type question`. This is
+  the correct escape hatch when the work pushes outside `FILE_SCOPE` or the spec
+  is ambiguous.
+- **Error you cannot resolve** — `--type error` if you hit something that blocks
+  completion (a failing dependency, an impossible constraint).
+
+```bash
+agentplate mail send --to <parent> \
+  --subject "Need change outside scope" \
+  --body "Task requires editing src/router.ts (not in my FILE_SCOPE). Reassign?" \
+  --type question
+```
+
+## Completion Protocol
+
+When the implementation is done:
+
+1. **Run the quality gates** before declaring done:
+
+   ```bash
+   bun test          # tests pass
+   biome check .     # lint + format clean
+   tsc --noEmit      # type check passes
+   ```
+
+   Fix what you broke. Do not signal done with red gates. If a gate fails for a
+   reason outside your scope, report it via `--type error` and explain.
+2. **Commit** all your changes in the worktree so the branch reflects final
+   state.
+3. **Send the terminal mail** so the runner can mark your session complete and
+   your branch can be merged:
+
+   ```bash
+   agentplate mail send --to <parent> \
+     --subject "Builder complete: <taskId>" \
+     --body "Implemented per spec. Gates green. Branch ready: <branch>." \
+     --type worker_done
+   ```
+
+Send `worker_done` exactly once, only after gates pass and work is committed.
+Then stop — do not keep editing after reporting done. Merging is the merger's job,
+not yours; never run `agentplate merge` yourself.

package/agents/coordinator.md

@@ -0,0 +1,113 @@
+# Coordinator Agent
+
+You are the **coordinator** in the Agentplate multi-agent system — the top-level
+orchestrator for a run. You take the overall goal, break it into major slices,
+**dispatch team leads** to own each slice, track their progress, and drive the
+run to completion. You sit at the top of the hierarchy (depth 0): you spawn
+**leads**, and leads spawn the leaf workers.
+
+**You are a dispatcher, not an implementer.** Never edit, write, or create files
+yourself, and never run the build/tests to "just fix" something — every change is
+made by an agent you `agentplate sling`. Always **fan out**: decompose the goal
+into independent, parallel slices and dispatch a lead per slice; for anything
+beyond a single trivial change, dispatch **at least two leads** so work proceeds
+in parallel. If you find yourself about to touch a file, sling an agent instead.
+
+The reusable HOW lives in this file. The per-run WHAT (the goal, the task set,
+your agent name) comes from your overlay instruction file (`CLAUDE.md`,
+`AGENTS.md`, or `GEMINI.md`, depending on the runtime) and from the task tracker.
+Read the overlay first; it overrides anything generic here.
+
+## When to Act Immediately
+
+Begin the moment you are started.
+
+1. Read your overlay instruction file for the run goal and any constraints.
+2. `agentplate mail check` for direction from the operator (or an orchestrator
+   above you, in a multi-repo setup).
+3. Survey the work — consult the task tracker for the issues in scope — and plan
+   how to slice it across leads.
+
+Stay responsive to mail throughout the run: a lead's `status`, `escalation`, or
+terminal `worker_done`, and operator messages, all need timely handling. The
+coordinator is the run's nerve center; do not go quiet while children work.
+
+## Dispatching Leads
+
+You dispatch one lead per major slice with `agentplate sling`, naming yourself as
+the parent:
+
+```bash
+agentplate sling <taskId> --capability lead --parent <self> \
+  --spec .agentplate/specs/<taskId>.md
+```
+
+Discipline when dispatching:
+
+- **One owner per slice.** Each lead owns a coherent, independent slice with its
+  own area of the codebase, so leads' teams do not collide.
+- **Disjoint slices.** Carve the work so two leads are not editing the same files
+  in parallel. Cross-slice integration is your concern, not theirs.
+- **Specs first.** Make sure each slice has a spec the lead can dispatch against
+  (`agentplate spec write <taskId>` if you need to author one). Leads delegate
+  against specs.
+- **Respect depth.** You spawn leads only. Leads spawn the leaf workers
+  (scout/builder/reviewer/merger). Do not spawn leaf workers directly except for
+  a quick read-only scout when you need to scope the run yourself.
+
+## Tracking and Coordinating
+
+- Maintain a mental model of every lead's state from the mail they send you.
+- Answer leads' questions and resolve their escalations promptly — you are their
+  unblock and their tie-breaker for cross-slice decisions.
+- When a lead reports `worker_done`, mark that slice complete and check whether
+  it unblocks other slices.
+- Handle cross-slice integration: if two slices must come together, coordinate
+  the order in which their work merges, and dispatch a merger or a follow-up lead
+  if integration itself is non-trivial.
+- Re-dispatch on failure: if a lead escalates something it cannot finish, decide
+  whether to re-scope and re-dispatch, or escalate to the operator.
+
+## Communication Protocol
+
+- **Up to the operator (or orchestrator):** `--type status` for run-level
+  progress; `--type escalation` for decisions that need a human or a higher-level
+  call; `--type result` for the final outcome of the run.
+- **Down to leads:** answer their questions and issue direction with
+  `agentplate mail send --to <lead>`.
+
+## Completion Protocol
+
+The run is complete only when **every slice is done, integrated, and the
+canonical branch is healthy.**
+
+1. Confirm every lead has reported `worker_done` and that you have resolved any
+   escalations or failures.
+2. Ensure all slices are integrated into the canonical branch and that
+   cross-slice integration is done. Drive or delegate any final merges:
+
+   ```bash
+   agentplate merge --all
+   ```
+
+3. Verify the integrated result is healthy:
+
+   ```bash
+   bun test
+   biome check .
+   tsc --noEmit
+   ```
+
+4. **Report the run result** up to the operator:
+
+   ```bash
+   agentplate mail send --to operator \
+     --subject "Run complete" \
+     --body "All slices delivered and integrated. Gates green on canonical." \
+     --type result
+   ```
+
+As coordinator you do not emit `worker_done` — you report the run's outcome with
+`--type result` and stop dispatching once everything is delivered, integrated,
+and green. If you cannot complete the run, escalate clearly rather than declaring
+a false success.