@ag-eco/agentplate-cli 0.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaymin West
+
+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,462 @@
+# Agentplate
+
+Multi-agent orchestration for AI coding agents.
+
+[![npm](https://img.shields.io/npm/v/@ag-eco/agentplate-cli)](https://www.npmjs.com/package/@ag-eco/agentplate-cli)
+[![CI](https://github.com/hgoudat/agentplate/actions/workflows/ci.yml/badge.svg)](https://github.com/hgoudat/agentplate/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Agentplate turns a single coding session into a multi-agent team by spawning worker agents in isolated git worktrees, coordinating them through a custom SQLite mail system, and merging their work back with tiered conflict resolution. New projects spawn Claude agents headless and surface them through a web UI (`ap serve`); `tmux attach` is the opt-in escape hatch for live steering. A pluggable `AgentRuntime` interface lets you swap between 11 runtimes — Claude Code, [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Aider](https://aider.chat), [Goose](https://github.com/block/goose), [Amp](https://amp.dev), or your own adapter.
+
+> **Warning: Agent swarms are not a universal solution.** Do not deploy Agentplate without understanding the risks of multi-agent orchestration — compounding error rates, cost amplification, debugging complexity, and merge conflicts are the normal case, not edge cases. Read [STEELMAN.md](STEELMAN.md) for a full risk analysis and the [Agentic Engineering Book](https://github.com/hgoudat/agentic-engineering-book) ([web version](https://hgoudat.com/agentic-engineering-book)) before using this tool in production.
+
+## Install
+
+Requires [Bun](https://bun.sh) v1.0+ and git. `tmux` is optional — only needed if you want to spawn workers with `--no-headless` or attach to a coordinator/worker pane directly. At least one supported agent runtime must be installed:
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude` CLI)
+- [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) (`pi` CLI)
+- [GitHub Copilot](https://github.com/features/copilot) (`copilot` CLI)
+- [Codex](https://github.com/openai/codex) (`codex` CLI)
+- [Gemini CLI](https://github.com/google-gemini/gemini-cli) (`gemini` CLI)
+- [Cursor CLI](https://cursor.com/docs/cli/overview) (`agent` CLI)
+- [Sapling](https://github.com/hgoudat/sapling) (`sp` CLI)
+- [OpenCode](https://opencode.ai) (`opencode` CLI)
+- [Aider](https://aider.chat) (`aider` CLI)
+- [Goose](https://github.com/block/goose) (`goose` CLI)
+- [Amp](https://amp.dev) (`amp` CLI)
+
+```bash
+bun install -g @ag-eco/agentplate-cli
+```
+
+Or try without installing:
+
+```bash
+npx @ag-eco/agentplate-cli --help
+```
+
+### Development
+
+```bash
+git clone https://github.com/hgoudat/agentplate.git
+cd agentplate
+bun install
+bun link              # Makes 'ap' available globally
+
+bun test              # Run all tests
+bun run lint          # Biome check
+bun run typecheck     # tsc --noEmit
+```
+
+## Quick Start
+
+```bash
+# Initialize agentplate in your project
+cd your-project
+ap init
+
+# Install hooks into .claude/settings.local.json
+ap hooks install
+
+# Start a coordinator (persistent orchestrator)
+ap coordinator start
+
+# Open the web UI — primary operator surface for the swarm
+ap serve   # then open http://localhost:7321
+```
+
+`ap serve` is where you watch the fleet, read the mail bus, and inspect
+per-agent timelines. New projects spawn Claude workers headless by default,
+so the UI sees them with full structured-event fidelity.
+
+Other common commands:
+
+```bash
+# Spawn an individual worker agent (coordinator usually does this for you)
+ap sling <task-id> --capability builder --name my-builder
+
+# Force a worker into tmux when you want to attach mid-session
+ap sling <task-id> --capability builder --name my-builder --no-headless
+tmux attach -t ap-my-builder
+
+# Inspect state from the CLI (also visible in the UI)
+ap status
+ap dashboard          # live TUI alternative to the web UI
+ap mail check --inject
+ap nudge <agent-name> # send a follow-up to a stalled agent
+```
+
+## Commands
+
+Every command supports `--json` where noted. Global flags: `-q`/`--quiet`, `--timing`, `--project <path>`. ANSI colors respect `NO_COLOR`.
+
+### Core Workflow
+
+| Command | Description |
+|---------|-------------|
+| `ap init` | Initialize `.agentplate/` and bootstrap ag-eco tools (`--yes`, `--name`, `--tools`, `--skip-loam`, `--skip-sprout`, `--skip-trellis`, `--skip-onboard`, `--json`) |
+| `ap sling <task-id>` | Spawn a worker agent (`--capability`, `--name`, `--spec`, `--files`, `--parent`, `--depth`, `--skip-scout`, `--skip-review`, `--max-agents`, `--dispatch-max-agents`, `--skip-task-check`, `--no-scout-check`, `--runtime`, `--base-branch`, `--profile`, `--headless`, `--no-headless`, `--recover`, `--json`) |
+| `ap stop <agent-name>` | Terminate a running agent (`--clean-worktree`, `--json`) |
+| `ap prime` | Load context for orchestrator/agent (`--agent`, `--compact`) |
+| `ap spec write <task-id>` | Write a task specification (`--body`) |
+| `ap discover` | Discover a brownfield codebase via coordinator-driven scout swarm (`--skip`, `--name`, `--attach`, `--watchdog`, `--json`) |
+| `ap update` | Refresh `.agentplate/` managed files from installed package (`--agents`, `--manifest`, `--hooks`, `--dry-run`, `--json`) |
+
+### Coordination
+
+| Command | Description |
+|---------|-------------|
+| `ap coordinator start` | Start persistent coordinator agent (`--attach`/`--no-attach`, `--watchdog`, `--monitor`, `--profile`) |
+| `ap coordinator stop` | Stop coordinator |
+| `ap coordinator status` | Show coordinator state |
+| `ap coordinator send` | Fire-and-forget message to coordinator (`--subject`) |
+| `ap coordinator ask` | Synchronous request/response to coordinator (`--subject`, `--timeout`) |
+| `ap coordinator output` | Show recent coordinator output (`--lines`) |
+| `ap coordinator check-complete` | Evaluate exit triggers, return completion status |
+| `ap orchestrator start` | Start multi-repo orchestrator agent (`--attach`/`--no-attach`, `--watchdog`, `--profile`) |
+| `ap orchestrator stop` | Stop orchestrator |
+| `ap orchestrator status` | Show orchestrator state |
+| `ap orchestrator send` | Fire-and-forget message to orchestrator (`--subject`) |
+| `ap orchestrator ask` | Synchronous request/response to orchestrator (`--subject`, `--timeout`) |
+| `ap orchestrator output` | Show recent orchestrator output (`--lines`) |
+| `ap supervisor start` | **[DEPRECATED]** Start per-project supervisor agent |
+| `ap supervisor stop` | **[DEPRECATED]** Stop supervisor |
+| `ap supervisor status` | **[DEPRECATED]** Show supervisor state |
+
+### Messaging
+
+| Command | Description |
+|---------|-------------|
+| `ap mail send` | Send a message (`--to`, `--subject`, `--body`, `--type`, `--priority`) |
+| `ap mail check` | Check inbox — unread messages (`--agent`, `--inject`, `--debounce`, `--json`) |
+| `ap mail list` | List messages with filters (`--from`, `--to`, `--unread`) |
+| `ap mail read <id>` | Mark message as read |
+| `ap mail reply <id>` | Reply in same thread (`--body`) |
+| `ap nudge <agent> [message]` | Send a text nudge to an agent (`--from`, `--force`, `--json`) |
+
+### Task Groups
+
+| Command | Description |
+|---------|-------------|
+| `ap group create <name>` | Create a task group for batch tracking |
+| `ap group status <name>` | Show group progress |
+| `ap group add <name> <issue-id>` | Add issue to group |
+| `ap group list` | List all groups |
+
+### Merge
+
+| Command | Description |
+|---------|-------------|
+| `ap merge` | Merge agent branches into canonical (`--branch`, `--all`, `--into`, `--dry-run`, `--json`) |
+
+### Observability
+
+| Command | Description |
+|---------|-------------|
+| `ap status` | Show all active agents, worktrees, tracker state (`--json`, `--verbose`, `--all`) |
+| `ap dashboard` | Live TUI dashboard for agent monitoring (`--interval`, `--all`) |
+| `ap inspect <agent>` | Deep per-agent inspection (`--follow`, `--interval`, `--no-tmux`, `--limit`, `--json`) |
+| `ap trace` | View agent/task timeline (`--agent`, `--run`, `--since`, `--until`, `--limit`, `--json`) |
+| `ap errors` | Aggregated error view across agents (`--agent`, `--run`, `--since`, `--until`, `--limit`, `--json`) |
+| `ap replay` | Interleaved chronological replay (`--run`, `--agent`, `--since`, `--until`, `--limit`, `--json`) |
+| `ap feed` | Unified real-time event stream (`--follow`, `--interval`, `--agent`, `--run`, `--json`) |
+| `ap logs` | Query NDJSON logs across agents (`--agent`, `--level`, `--since`, `--until`, `--follow`, `--json`) |
+| `ap costs` | Token/cost analysis and breakdown (`--live`, `--self`, `--agent`, `--run`, `--bead`, `--by-capability`, `--last`, `--json`) |
+| `ap metrics` | Show session metrics (`--last`, `--json`) |
+| `ap run list` | List orchestration runs (`--last`, `--json`) |
+| `ap run show <id>` | Show run details |
+| `ap run complete` | Mark current run as completed |
+
+### Infrastructure
+
+| Command | Description |
+|---------|-------------|
+| `ap hooks install` | Install orchestrator hooks to `.claude/settings.local.json` (`--force`) |
+| `ap hooks uninstall` | Remove orchestrator hooks |
+| `ap hooks status` | Check if hooks are installed |
+| `ap worktree list` | List worktrees with status |
+| `ap worktree clean` | Remove completed worktrees (`--completed`, `--all`, `--force`) |
+| `ap watch` | Start watchdog daemon — Tier 0 (`--interval`, `--background`) |
+| `ap monitor start` | Start Tier 2 monitor agent |
+| `ap monitor stop` | Stop monitor agent |
+| `ap monitor status` | Show monitor state |
+| `ap log <event>` | Log a hook event (`--agent`) |
+| `ap clean` | Clean up worktrees, sessions, artifacts (`--completed`, `--all`, `--run`) |
+| `ap doctor` | Run health checks on agentplate setup — 13 categories (`--category`, `--fix`, `--json`) |
+| `ap serve` | HTTP + WebSocket surface for the web UI (`--port`, `--host`, `--json`) |
+| `ap ecosystem` | Show ag-eco tool versions and health (`--json`) |
+| `ap upgrade` | Upgrade agentplate to latest npm version (`--check`, `--all`, `--json`) |
+| `ap agents discover` | Discover agents by capability/state/parent (`--capability`, `--state`, `--parent`, `--json`) |
+| `ap completions <shell>` | Generate shell completions (bash, zsh, fish) |
+
+## Architecture
+
+Agentplate uses instruction overlays and tool-call guards to turn agent sessions into orchestrated workers. Each agent runs in an isolated git worktree; new projects spawn Claude workers as headless subprocesses (stream-json over stdout) and surface them through `ap serve`'s web UI, with tmux available as an opt-in for live attach. Inter-agent messaging is handled by a custom SQLite mail system (WAL mode, ~1-5ms per query) with typed protocol messages and broadcast support. A FIFO merge queue with 4-tier conflict resolution merges agent branches back to canonical. A tiered watchdog system (Tier 0 mechanical daemon, Tier 1 AI-assisted triage, Tier 2 monitor agent) ensures fleet health. See [CLAUDE.md](CLAUDE.md) for full technical details.
+
+### Runtime Adapters
+
+Agentplate is runtime-agnostic. The `AgentRuntime` interface (`src/runtimes/types.ts`) defines the contract — each adapter handles spawning, config deployment, guard enforcement, readiness detection, and transcript parsing for its runtime. Set the default in `config.yaml` or override per-agent with `ap sling --runtime <name>`.
+
+Claude Code agents can run in **headless mode** (the default for new projects — `-p --output-format stream-json` subprocess, NDJSON events parsed by `ClaudeRuntime.parseEvents`, surfaced through `ap serve`'s web UI) or **tmux mode** (escape hatch for live attach — operator can `tmux attach` to watch and steer mid-session). `ap init` writes `runtime.claudeHeadlessByDefault: true` for new projects; legacy projects upgrading from earlier agentplate versions keep tmux until they edit config. Override per-spawn with `ap sling --no-headless` (force tmux) or `--headless` (force headless). Sapling is statically headless; Pi, Codex, and Cursor have no `buildDirectSpawn` and reject `--headless`.
+
+| Runtime | CLI | Guard Mechanism | Stability |
+|---------|-----|-----------------|-----------|
+| Claude Code | `claude` | `settings.local.json` hooks | Stable |
+| Sapling | `sp` | `.sapling/guards.json` | Stable |
+| Pi | `pi` | `.pi/extensions/` guard extension | Experimental |
+| Copilot | `copilot` | (none — `--allow-all-tools`) | Experimental |
+| Cursor | `agent` | (none — `--yolo`) | Experimental |
+| Codex | `codex` | OS-level sandbox (Seatbelt/Landlock) | Experimental |
+| Gemini | `gemini` | `--sandbox` flag | Experimental |
+| Aider | `aider` | (none — `--yes-always`) | Experimental |
+| Goose | `goose` | Profile-based permissions | Experimental |
+| Amp | `amp` | Built-in approval system | Experimental |
+| OpenCode | `opencode` | (none) | Experimental |
+
+## How It Works
+
+Instruction overlays + tool-call guards + the `ap` CLI turn your coding session into a multi-agent orchestrator. A persistent coordinator agent manages task decomposition and dispatch, while a mechanical watchdog daemon monitors agent health in the background.
+
+```
+Orchestrator (multi-repo coordinator of coordinators)
+  --> Coordinator (persistent orchestrator at project root)
+        --> Supervisor / Lead (team lead, depth 1)
+              --> Workers: Scout, Builder, Reviewer, Merger (depth 2)
+```
+
+### Agent Types
+
+| Agent | Role | Access |
+|-------|------|--------|
+| **Orchestrator** | Multi-repo coordinator of coordinators — dispatches coordinators per sub-repo | Read-only |
+| **Coordinator** | Persistent orchestrator — decomposes objectives, dispatches agents, tracks task groups | Read-only |
+| **Supervisor** | Per-project team lead — manages worker lifecycle, handles nudge/escalation | Read-only |
+| **Scout** | Read-only exploration and research | Read-only |
+| **Builder** | Implementation and code changes | Read-write |
+| **Reviewer** | Validation and code review | Read-only |
+| **Lead** | Team coordination, can spawn sub-workers | Read-write |
+| **Merger** | Branch merge specialist | Read-write |
+| **Monitor** | Tier 2 continuous fleet patrol — ongoing health monitoring | Read-only |
+
+### Key Architecture
+
+- **Agent Definitions**: Two-layer system — base `.md` files define the HOW (workflow), per-task overlays define the WHAT (task scope). Base definition content is injected into spawned agent overlays automatically.
+- **Messaging**: Custom SQLite mail system with typed protocol — 8 message types (`worker_done`, `merge_ready`, `dispatch`, `escalation`, etc.) for structured agent coordination, plus broadcast messaging with group addresses (`@all`, `@builders`, etc.)
+- **Worktrees**: Each agent gets an isolated git worktree — no file conflicts between agents
+- **Merge**: FIFO merge queue (SQLite-backed) with 4-tier conflict resolution
+- **Watchdog**: Tiered health monitoring — Tier 0 mechanical daemon (tmux/pid liveness), Tier 1 AI-assisted failure triage, Tier 2 monitor agent for continuous fleet patrol
+- **Tool Enforcement**: Runtime-specific guards (hooks for Claude Code, extensions for Pi) mechanically block file modifications for non-implementation agents and dangerous git operations for all agents
+- **Task Groups**: Batch coordination with auto-close when all member issues complete
+- **Session Lifecycle**: Checkpoint save/restore for compaction survivability, handoff orchestration for crash recovery
+- **Token Instrumentation**: Session metrics extracted from runtime transcript files (JSONL)
+
+## Project Structure
+
+```
+agentplate/
+  src/
+    index.ts                      CLI entry point (Commander.js program)
+    types.ts                      Shared types and interfaces
+    config.ts                     Config loader + validation
+    errors.ts                     Custom error types
+    json.ts                       Standardized JSON envelope helpers
+    commands/                     One file per CLI subcommand (38 commands)
+      agents.ts                   Agent discovery and querying
+      coordinator.ts              Persistent orchestrator lifecycle
+      supervisor.ts               Team lead management [DEPRECATED]
+      dashboard.ts                Live TUI dashboard (ANSI via Chalk)
+      hooks.ts                    Orchestrator hooks management
+      sling.ts                    Agent spawning
+      group.ts                    Task group batch tracking
+      nudge.ts                    Agent nudging
+      mail.ts                     Inter-agent messaging
+      monitor.ts                  Tier 2 monitor management
+      merge.ts                    Branch merging
+      status.ts                   Fleet status overview
+      prime.ts                    Context priming
+      init.ts                     Project initialization
+      worktree.ts                 Worktree management
+      watch.ts                    Watchdog daemon
+      log.ts                      Hook event logging
+      logs.ts                     NDJSON log query
+      feed.ts                     Unified real-time event stream
+      run.ts                      Orchestration run lifecycle
+      trace.ts                    Agent/task timeline viewing
+      clean.ts                    Worktree/session cleanup
+      doctor.ts                   Health check runner (13 check modules)
+      inspect.ts                  Deep per-agent inspection
+      spec.ts                     Task spec management
+      errors.ts                   Aggregated error view
+      replay.ts                   Interleaved event replay
+      stop.ts                     Agent termination
+      costs.ts                    Token/cost analysis
+      metrics.ts                  Session metrics
+      ecosystem.ts                ag-eco tool dashboard
+      update.ts                   Refresh managed files
+      upgrade.ts                  npm version upgrades
+      discover.ts                 Brownfield codebase discovery via coordinator-driven scout swarm
+      orchestrator.ts             Multi-repo coordination (PersistentAgentSpec)
+      completions.ts              Shell completion generation (bash/zsh/fish)
+      serve.ts                    HTTP + WebSocket surface for the web UI
+      serve/                      REST handlers, WebSocket broadcaster, static SPA fallback
+    trellis/
+      client.ts                   Trellis client (prompt rendering, listing, emission)
+    agents/                       Agent lifecycle management
+      manifest.ts                 Agent registry (load + query)
+      overlay.ts                  Dynamic CLAUDE.md overlay generator
+      identity.ts                 Persistent agent identity (CVs)
+      checkpoint.ts               Session checkpoint save/restore
+      lifecycle.ts                Handoff orchestration
+      hooks-deployer.ts           Deploy hooks + tool enforcement
+      copilot-hooks-deployer.ts   Deploy hooks config to Copilot worktrees
+      guard-rules.ts              Shared guard constants (tool lists, bash patterns)
+      mail-poll-detect.ts         Bash mail-poll pattern detector (runtime backstop)
+      scope-detect.ts             Soft FILE_SCOPE violation detection (builder/merger)
+    worktree/                     Git worktree + tmux management
+    mail/                         SQLite mail system (typed protocol, broadcast)
+    merge/                        FIFO queue + conflict resolution + sentinel-file lock + dry-run prediction
+    watchdog/                     Tiered health monitoring (daemon, triage, health)
+    logging/                      Multi-format logger + sanitizer + reporter + color control + shared theme/format
+    metrics/                      SQLite metrics + pricing + transcript parsing
+    doctor/                       Health check modules (13 checks)
+    utils/                        Shared utilities (bin, fs, pid, time, version)
+    insights/                     Session insight analyzer + quality-gate runner (success/partial/failure)
+    runtimes/                     AgentRuntime abstraction (registry + adapters: Claude, Pi, Copilot, Codex, Gemini, Sapling, OpenCode, Cursor, Aider, Goose, Amp)
+    tracker/                      Pluggable task tracker (beads + sprout backends)
+    loam/                        loam client (programmatic API + CLI wrapper)
+    e2e/                          End-to-end lifecycle tests
+  agents/                         Base agent definitions (.md, 9 roles) + skill definitions
+  templates/                      Templates for overlays and hooks
+```
+
+## Configuration
+
+### Gateway Providers
+
+Route agent API calls through custom gateway endpoints (z.ai, OpenRouter, self-hosted proxies). Configure providers in `.agentplate/config.yaml`:
+
+```yaml
+providers:
+  anthropic:
+    type: native
+  zai:
+    type: gateway
+    baseUrl: https://api.z.ai/v1
+    authTokenEnv: ZAI_API_KEY
+  openrouter:
+    type: gateway
+    baseUrl: https://openrouter.ai/api/v1
+    authTokenEnv: OPENROUTER_API_KEY
+models:
+  builder: zai/claude-sonnet-4-6
+  scout: openrouter/openai/gpt-4o
+```
+
+**How it works:** Model refs use `provider/model-id` format. Agentplate sets `ANTHROPIC_BASE_URL` to the gateway `baseUrl`, `ANTHROPIC_AUTH_TOKEN` from the env var named in `authTokenEnv`, and `ANTHROPIC_API_KEY=""` to prevent direct Anthropic calls. The agent receives `"sonnet"` as a model alias and Claude Code routes via env vars.
+
+**Environment variable notes:**
+- `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_API_KEY` are mutually exclusive per-agent
+- Gateway agents get `ANTHROPIC_API_KEY=""` and `ANTHROPIC_AUTH_TOKEN` from provider config
+- Direct Anthropic API calls (merge resolver, watchdog triage) still need `ANTHROPIC_API_KEY` in the orchestrator env
+
+**Validation:** `ap doctor --category providers` checks reachability, auth tokens, model-provider refs, and tool-use compatibility.
+
+**`ProviderConfig` fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | `native` or `gateway` | Yes | Provider type |
+| `baseUrl` | string | Gateway only | API endpoint URL |
+| `authTokenEnv` | string | Gateway only | Env var name holding auth token |
+
+## Troubleshooting
+
+### Recovering a dead lead (or any agent that exited mid-task)
+
+If a lead exits without sending `merge_ready` (process termination, watchdog kill, manual `ap stop`) and the task was already closed, both `ap nudge` and `ap sling` would normally refuse to re-engage:
+
+- `ap nudge <name>` reports `No active session for agent "..." (state: completed)`. The agent's process is gone, so there's nothing to send keystrokes to.
+- `ap sling <task-id> --capability lead` reports `Task "..." is not workable (status: closed)`.
+
+To re-dispatch a fresh lead against the same task, pass `--recover`:
+
+```bash
+ap sling <task-id> --capability lead --recover --name <fresh-name>
+```
+
+`--recover` bypasses the workable-status check so the new lead can pick up where the dead one left off (the task remains closed; the new lead reads the spec and proceeds). The terminal-state nudge error itself includes a copy-paste hint to this exact form.
+
+### Coordinator died during startup
+
+This error means the coordinator tmux session exited before the TUI became ready. The most common cause is slow shell initialization.
+
+**Step 1: Measure shell startup time**
+
+```bash
+time zsh -i -c exit   # For zsh
+time bash -i -c exit  # For bash
+```
+
+If startup takes more than 1 second, slow shell init is likely the cause.
+
+**Step 2: Common slow-startup causes**
+
+| Cause | Typical delay | Fix |
+|-------|---------------|-----|
+| oh-my-zsh with many plugins | 1-5s | Reduce plugins, switch to lighter framework (zinit with lazy loading) |
+| nvm (Node Version Manager) | 1-3s | Use `--no-use` + lazy-load nvm, or switch to fnm/volta |
+| pyenv init | 0.5-2s | Lazy-load pyenv |
+| rbenv init | 0.5-1s | Lazy-load rbenv |
+| starship prompt | 0.5-1s | Check starship timings |
+| conda auto-activate | 1-3s | `auto_activate_base: false` in `.condarc` |
+| Homebrew shellenv | 0.5-1s | Cache output instead of evaluating every shell start |
+
+**Step 3: Configure `shellInitDelayMs`** in `.agentplate/config.yaml`:
+
+```yaml
+runtime:
+  shellInitDelayMs: 3000
+```
+
+- Default: `0` (no delay)
+- Typical values: `1000`–`5000` depending on shell startup time
+- Values above `30000` (30s) trigger a warning
+- Inserts a delay between tmux session creation and TUI readiness polling
+
+**Step 4: Optimization examples**
+
+Lazy-load nvm (add to `~/.zshrc` or `~/.bashrc`):
+
+```bash
+# Lazy-load nvm — only activates when you first call nvm/node/npm
+export NVM_DIR="$HOME/.nvm"
+nvm() { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; nvm "$@"; }
+node() { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; node "$@"; }
+npm()  { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; npm  "$@"; }
+npx()  { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; npx  "$@"; }
+```
+
+Reduce oh-my-zsh plugins (edit `~/.zshrc`):
+
+```bash
+# Before: plugins=(git zsh-autosuggestions zsh-syntax-highlighting node npm python ruby rbenv pyenv ...)
+# After: keep only what you use regularly
+plugins=(git)
+```
+
+## Part of ag-eco
+
+Agentplate is part of the [ag-eco](https://github.com/hgoudat/ag-eco) AI agent tooling ecosystem.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hgoudat/ag-eco/main/branding/logo.png" alt="ag-eco" width="444" />
+</p>
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT

package/agents/ap-co-creation.md

@@ -0,0 +1,90 @@
+---
+name: ap-co-creation
+description: Co-creation workflow profile — human-in-the-loop at explicit decision gates
+---
+
+## propulsion-principle
+
+Read your assignment. For implementation work within an approved plan, execute immediately — no confirmation needed for routine decisions (naming, file organization, test strategy, implementation details within spec).
+
+PAUSE at decision gates. When you encounter an architectural choice, design fork, scope boundary, or tool selection, stop and do not proceed. Instead:
+
+1. Write a structured decision document (context, options, tradeoffs, recommendation).
+2. Send it as a decision_gate mail to the coordinator.
+3. Wait for a response before proceeding past the gate.
+
+Hesitation is the default at gates; action is the default within approved plans.
+
+## escalation-policy
+
+At decision points, present options rather than choosing. When you encounter a meaningful decision:
+
+1. Write a structured decision document: context, 2+ options with tradeoffs, and your recommendation.
+2. Send it as a decision_gate mail to the coordinator and wait.
+3. Do not proceed until you receive a reply selecting an option.
+
+Routine implementation decisions within an already-approved plan remain autonomous. Do not send decision gates for: variable names, file organization within spec, test strategy, or minor implementation choices that do not affect overall direction.
+
+Escalate immediately (not as a decision gate) when you discover: risks that could cause data loss, security issues, or breaking changes beyond scope; blocked dependencies outside your control.
+
+## artifact-expectations
+
+Decision artifacts come before code. Deliverables in order:
+
+1. **Option memos**: For any decision with multiple viable approaches, write a structured memo with options, tradeoffs, and a recommendation. Send as a decision_gate mail and await approval.
+2. **ADRs (Architecture Decision Records)**: For architectural choices, create a lightweight ADR capturing context, decision, and consequences.
+3. **Tradeoff matrices**: When comparing approaches across multiple dimensions, present a structured comparison.
+4. **Code and tests**: Implementation proceeds after decision artifacts are approved. Code must be clean, follow project conventions, and include automated tests.
+5. **Quality gates**: All lints, type checks, and tests must pass before reporting completion.
+
+Do not write implementation code before decisions are resolved. The human reviews and approves decision documents; implementation follows approval.
+
+## completion-criteria
+
+Work is complete when all of the following are true:
+
+- All quality gates pass: tests green, linting clean, type checking passes.
+- Changes are committed to the appropriate branch.
+- Any issues tracked in the task system are updated or closed.
+- A completion signal has been sent to the appropriate recipient (parent agent, coordinator, or human).
+
+Do not declare completion prematurely. Run the quality gates yourself — do not assume they pass. If a gate fails, fix the issue before reporting done.
+
+## human-role
+
+The human is an active co-creator at explicit decision gates — not a hands-off supervisor.
+
+- **Active at gates.** The human reviews decision documents and selects options via mail reply. The agent waits for this input before proceeding.
+- **Autonomous between gates.** Once a direction is approved, the agent executes without further check-ins. Implementation details within an approved plan are delegated.
+- **Milestone reviews.** The human reviews work at defined checkpoints (planning, prototype, final). These are collaborative reviews with explicit proceed signals.
+- **Minimal interruption between gates.** Do not ask questions that could be answered by reading the codebase or attempting something. Reserve interruptions for genuinely ambiguous requirements.
+
+## decision-gates
+
+When you reach a decision point (architectural choice, scope boundary, design fork, tool selection), follow this protocol:
+
+1. **Write a structured decision document** containing:
+   - **Context**: What problem are you solving? What constraints apply?
+   - **Options**: At least 2 viable approaches, each with: description, tradeoffs (pros/cons), and implementation implications.
+   - **Recommendation**: Which option you recommend and why.
+
+2. **Send a decision_gate mail** to the coordinator with the decision document in the body. Include a payload with the options array and brief context. Use --type decision_gate.
+
+3. **BLOCK and wait** for a reply. Do not continue past the gate without a response. Poll your inbox periodically while waiting.
+
+Decision gates are NOT for: variable names, file organization within spec, test strategy, or minor implementation choices within an approved design. They are for choices that meaningfully affect the direction of work.
+
+## milestone-reviews
+
+Send checkpoint reviews at three milestones:
+
+**After planning** (before any implementation begins):
+Send a status mail with: scope summary (what will be built), approach (high-level design with all decisions resolved via gates), file list (which files will be affected), and any open questions requiring confirmation before starting.
+
+**After prototyping** (when a working prototype exists):
+Send a status mail with: what works and what is rough, remaining decisions (if any), revised scope if it changed during prototyping, and an explicit request to proceed before final implementation.
+
+**Before final implementation** (after all gates resolved and prototype reviewed):
+Send a status mail summarizing: complete plan with all decisions incorporated, any deviations from original scope, and a confirmation request before beginning the final commit sequence.
+
+Each milestone review uses mail type status and clearly labels the milestone in the subject line.