converge-control

Converge Control

When to use this skill

Trigger this skill whenever the user is operating an existing playbook — not authoring a new one. Concrete signals:

• A .converge/project.yaml + playbooks/<name>/ already exist; the user wants the playbook to actually run, or wants to know what happened on the last run.
• The user reports a failure mid-run, a stuck task, an error in the journal, or wants to retry only what failed.
• The user asks operational questions: what's running right now?, which tasks are blocked?, what did task X produce?, how much did the last run cost?, how do I re-run just the failures?
• The user hits HTTP 401 / Invalid API key — that's an environment conflict between shell ANTHROPIC_* vars and the project's provider config, not a playbook bug. See entry §13 in troubleshooting/playbook.md.

If the user wants to design a new playbook, change its task tree, or factor reusable instructions into skills, hand off to converge-planning. This skill only operates what already exists.

Current mental model

Converge has three important layers:

1. Source blueprint — .converge/playbooks/<name>/
   • playbook.yml — the manifest (top-level tasks, depends_on, goals).
   • tasks/**/TASK.md — task contracts (id, inputs, outputs, checks).
   • templates/<name>/TASK.md — runtime spawn templates for dynamic children.
   • skills/<name>/SKILL.md — playbook-scoped skills (the how paired with each task's what). Also searched at .claude/skills/ (project-scoped) and .codex/skills/.
   • scripts/ — orchestration helpers invoked from task bodies (e.g., to compute converge spawn calls from a catalog).
2. Runtime state — .converge/journal/<playbook>/, .converge/inventory/<playbook>/ Execution state, event stream, per-task forensics, and the spawned-task ledger.
3. Operator surface — the CLI run, status, list, show, inspect, doctor, playbook validate, tasks mark, skills list, clean, stop.

The playbook is the source of truth. Do not hand-edit runstate.json, manifest.json, or journal files to "fix" a run.

Three-layer task model

When interpreting failures or proposing fixes, remember each task carries content across three layers — different problems live in different layers:

• TASK.md frontmatter — the contract (id, inputs, outputs, checks, depends_on). Failures here look like dependency cycles, missing-input gaps, check-syntax errors. Fix the frontmatter.
• TASK.md body — the subjective + context for this invocation (which name, which path, which catalog row). Failures here look like a wrong-but-runnable result on this specific input. Fix the body's specifics or the project data the body reads.
• SKILL.md — the general how-to the task references via skills: [<name>]. Failures here look like the same wrong-result shape across many tasks that share the skill. Fix the skill body once, not each task.

If three tasks fail the same way and they all share skills: [X], the bug is in skill X, not in the tasks.

The per-task execution dir ($CONVERGE_TASK_DIR)

Every task gets a stable directory the runtime sets before the body runs:

.converge/journal/<playbook>/tasks/<task-id>/exec/

Exposed as $CONVERGE_TASK_DIR to the body. Bodies write evidence there; the framework reads from there. When a task misbehaves, this is the first place to look.

File	What it means
spawn/STATUS.md	The single AI-facing transparency surface. One - [x] / - [ ] row per spawned child. Failed rows carry a fix: block.
spawn/<id>/EXPANDED.md	Framework-rendered template TASK.md with {{...}} substituted. Useful when verifying that the body's params produced the intended contract.
spawn/<id>/EVIDENCE.json	Machine-readable per-child failure detail. Mirrors a row in STATUS.md.
spawn.plan.jsonl	(Legacy) the JSONL manifest path. Body authoring rejected with SPAWN_MANIFEST_AUTHORED_BY_BODY for new-surface playbooks. Old playbooks that haven't migrated still write here.
spawn.plan.result.jsonl	(Legacy) per-row outcome of the legacy converge apply.
wave.counter	Current wave number for mode: converger tasks. Persists across re-leases so wave state survives crashes.
halt.marker	The body's explicit "I'm done" signal for a converger. Highest-priority halt signal — overrides halt_when: and wave_check:.
mode-violation.json	RFC 0022 contract violation evidence. Read this first when a parent reports FRONTIER_UNRESOLVED or refuses to converge. Contains errorCode, declaredMode, message, fixHint.

The directory persists across attempts on purpose — a crashed body's partial invocations survive into the next attempt's repair. See reference/events.md for the matching event-stream interpretation (e.g., SEED_SPAWN, FRONTIER_UNRESOLVED).

Primary workflow

Use this loop unless a narrower recipe in troubleshooting/playbook.md fits exactly.

1. Preflight the playbook

Validate the definition before running:

converge playbook validate <name>

If the user is editing tasks live and wants a pure preview of what would execute:

converge run --playbook=<name> --dry

Use --dry instead of teaching an explicit compile-first workflow by default. compile still exists as a compatibility command, but the modern operator path is run --dry.

2. Start the run

converge run --playbook=<name>

Common narrowed runs:

# Only changed work and downstream
converge run --playbook=<name> --select 'state:modified+'

# Retry failures and their downstream consumers
converge run --playbook=<name> --select 'result:error+'

# One task / subtree
converge run --playbook=<name> --select '03-build+'

# Fail fast when debugging one subtree
converge run --playbook=<name> --select '03-build+' --fail-fast

3. Watch the run

Primary operator views:

converge status --playbook=<name>
converge list --playbook=<name> --exclude 'status:complete'
converge show gantt --playbook=<name>
converge show graph --playbook=<name> --detail

Raw event stream:

tail -f .converge/journal/<playbook>/events.jsonl
tail -f .converge/journal/<playbook>/events.jsonl | grep -E '(NODE_COMPLETE|NODE_FAIL|CHECK_FAIL|ERROR|CYCLE)'

4. If the run fails

First classify whether the problem is:

• definition-shape → converge playbook validate <name>
• runtime-shape → converge doctor --playbook=<name>
• task / check-shape → converge inspect --playbook=<name> --task=<id>
• selection / graph-shape → converge list --playbook=<name> --select ... or converge show graph

Then use the smallest surgical next step:

# Inspect one failed task
converge inspect --playbook=<name> --task=<taskId>

# Health-check the runtime state
converge doctor --playbook=<name>

# Reset only the failed subtree
converge clean --playbook=<name> --select '<taskId>+'

# Re-run just failures
converge run --playbook=<name> --select 'result:error+'

5. If the run is stuck or orphaned

# Stop the live process and release the lock
converge stop --playbook=<name>

If a single dynamic-container task is wedged in a continue-loop and the operator (with the user's consent) wants to retire it manually:

# Mark one task done / dropped / blocked so the parent stops re-spawning
converge tasks mark <taskId> --playbook=<name> --status done
converge tasks mark <taskId> --playbook=<name> --status dropped --reasoning "user opted out"

Then restart with a narrowed selection if possible.

6. If the first task fails with Invalid API key / HTTP 401

This is almost always environment, not the playbook. The spawned agent CLI (claude, codex) inherits ANTHROPIC_* / OPENAI_* env vars from the shell, and a stale value from a previous proxy setup will override the project's .converge/project.yaml env block.

env | grep -E 'ANTHROPIC_|OPENAI_|CLAUDE_'
# Reconcile against .converge/project.yaml's provider env:
cat .converge/project.yaml | grep -A20 'ai:'
# If the shell vars conflict with what project.yaml expects, unset them
# (or re-export to match) before re-running.

See troubleshooting/playbook.md §13 for the full recipe.

Preferred command set

Use these first. They reflect the actual CLI surface and current docs.

# Run
converge run --playbook=<name>

# Preview
converge run --playbook=<name> --dry

# Current status tree
converge status --playbook=<name>

# Selection-aware listing
converge list --playbook=<name> --exclude 'status:complete'

# Graph / gantt / metrics / journal views
converge show graph --playbook=<name> --detail
converge show gantt --playbook=<name>
converge show metrics --playbook=<name> --by-model --top=5

# Forensics
converge inspect --playbook=<name> --task=<taskId>

# Definition health
converge playbook validate <name>

# Runtime health
converge doctor --playbook=<name>

# Surgical cleanup
converge clean --playbook=<name> --select '<taskId>+'

# State reconciliation (fix zombie runstate, stale inventory, rebuild DAG)
converge reconcile --playbook=<name>

# Stop a live / stale run
converge stop --playbook=<name>

# Mark a task done/dropped/blocked (use sparingly — prefer fixing the cause)
converge tasks mark <taskId> --playbook=<name> --status done

# List installed skills (project-scoped + bundled)
converge skills list

# Goal progress (for goal-driven epoch playbooks)
converge goals --playbook=<name>

When to use compatibility commands

These still exist, but they are not the first teaching surface:

• converge compile → compatibility / low-level preview path
• converge build → run --fail-fast
• converge retry → run --resume
• converge test → checks-only execution

Use them when the user explicitly asks for them or when a fixture / test / older note already uses them.

Hard rules

• Prefer run --dry over teaching compile first.
• Always scope with --playbook=<name> when more than one playbook exists.
• Use doctor for runtime-health questions.
• Use playbook validate for definition-health questions.
• Use inspect --task=<id> before proposing a novel fix.
• Use clean --select instead of deleting .converge/journal/ or .converge/inventory/ by hand.
• Use stop instead of ad-hoc pkill when possible.
• Do not edit generated runtime state. Fix the playbook source or the project inputs.
• If the failure is in user domain code or missing credentials, surface it clearly instead of inventing framework fixes.
• HTTP 401 / "Invalid API key" on the first task is environment, not the playbook. Check env | grep ANTHROPIC_ and reconcile against .converge/project.yaml's ai.providers.<name>.env block before touching the playbook itself.
• --backend and --provider are init-time flags, not run-time flags. Don't pass them to converge run. To change provider routing, edit .converge/project.yaml (or re-run converge init --force --backend=… --provider=…).
• When playbook state is out of sync (0 DAG nodes, orphaned spawned tasks, stale "doing" status), use converge reconcile --playbook=<name> first. If that doesn't resolve it, fall back to the manual recovery workflow in troubleshooting/state-recovery.md.
• Step-through execution: use run --select to run one task or subset at a time, tasks mark to correct individual status, and clean --select to wipe specific broken subtrees. Rebuild incrementally.

Manual recovery workflow

When a playbook's runtime state is out of sync with reality (orphaned spawned tasks, stale statuses, missing DAG nodes), follow this three-layer approach:

1. Audit — converge doctor, converge playbook validate, compare converge list vs converge tasks list counts
2. Repair — converge reconcile --playbook=<name> (systematic) or converge reset <name> --yes (nuclear) or converge clean --select=X --yes (surgical) or converge tasks mark X --status done/dropped/todo (manual correction)
3. Step-through — converge run --select=02-spawn → verify → converge run --select="screen-chat-*" → verify → converge run (full)

For state mismatches (zombie runstate + stale inventory), converge reconcile is the preferred first step — it cleans zombie runstate, reconciles inventory against disk outputs, rebuilds the DAG, and pre-flights cached tasks. Full recipe with troubleshooting fingerprints: see troubleshooting/state-recovery.md Scenario H.

Hand-off rules

Situation	Hand off to
User wants to design or restructure a playbook	converge-planning
User wants to debug framework code under packages/	converge-development
Failure is novel and crosses framework/runtime boundaries	user escalation with evidence

File map

SKILL.md
reference/
  cli.md
  events.md
troubleshooting/
  playbook.md

Load reference/cli.md for concrete command patterns, reference/events.md for event interpretation, and troubleshooting/playbook.md only when a concrete failure fingerprint matches.