[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7191KDW677AJSSHGBCB7BBV":3,"skill-same:01M7191KDW677AJSSHGBCB7BBV":105},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":27,"publishedAt":48,"linkOnly":49,"markdownContent":50,"markdownBody":51,"frontMatter":52,"refName":53,"commitSha":54,"skillDirectory":55,"forksCount":56,"repositoryHtmlUrl":57,"repositoryHomepageUrl":58,"ownerHtmlUrl":59,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":60,"install":61,"resources":74},"01M7191KDW677AJSSHGBCB7BBV","converge-control",null,"Operate a Converge playbook end-to-end — start runs, monitor progress, narrow failures with `--select`, inspect runtime state, validate definitions, surgically reset subtrees, and stop stuck or orphaned runs. Use this skill whenever the user says \"run my playbook\", \"execute this\", \"monitor the run\", \"converge failed\", \"the run is stuck\", \"retry failures\", \"babysit this playbook\", \"what's the status?\", \"show me the gantt\", or asks how to use `converge run` \u002F `--select` \u002F `inspect` \u002F `doctor` \u002F `clean` \u002F `stop`. Also use it for `HTTP 401` \u002F `Invalid API key` failures on the first task — those are environment-not-playbook problems — and for any post-run cleanup work. Hand off to `converge-planning` if the user wants to design or restructure the playbook itself.","openplaybooks-dev\u002Fconverge","openplaybooks-dev","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F270560357?v=4","01M7191G17AHW5SXN63HJ0BEZV","01M7191G29922BDNWN8CFVG4PD",3,"MIT","https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-control\u002FSKILL.md",[17,22],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",{"categoryNo":23,"categoryName":24,"taxonomyType":25,"taxonomyTypeDesc":26},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47],"converge control","converge","control","end","inspect","hand","operate","retry","how to","reset","invalid","design","me","show","clean","work","select","show me","api","cleanup","2026-11-10 10:12:30",false,"---\nname: converge-control\ndescription: >-\n  Operate a Converge playbook end-to-end — start runs, monitor progress,\n  narrow failures with `--select`, inspect runtime state, validate definitions,\n  surgically reset subtrees, and stop stuck or orphaned runs. Use this skill\n  whenever the user says \"run my playbook\", \"execute this\", \"monitor the run\",\n  \"converge failed\", \"the run is stuck\", \"retry failures\", \"babysit this\n  playbook\", \"what's the status?\", \"show me the gantt\", or asks how to use\n  `converge run` \u002F `--select` \u002F `inspect` \u002F `doctor` \u002F `clean` \u002F `stop`. Also\n  use it for `HTTP 401` \u002F `Invalid API key` failures on the first task — those\n  are environment-not-playbook problems — and for any post-run cleanup work.\n  Hand off to `converge-planning` if the user wants to design or restructure\n  the playbook itself.\n---\n\n# Converge Control\n\n## When to use this skill\n\nTrigger this skill whenever the user is operating an existing playbook —\nnot authoring a new one. Concrete signals:\n\n- A `.converge\u002Fproject.yaml` + `playbooks\u002F\u003Cname>\u002F` already exist; the\n  user wants the playbook to actually run, or wants to know what\n  happened on the last run.\n- The user reports a failure mid-run, a stuck task, an error in the\n  journal, or wants to retry only what failed.\n- The user asks operational questions: *what's running right now?*,\n  *which tasks are blocked?*, *what did task X produce?*, *how much\n  did the last run cost?*, *how do I re-run just the failures?*\n- The user hits HTTP 401 \u002F Invalid API key — that's an environment\n  conflict between shell `ANTHROPIC_*` vars and the project's provider\n  config, not a playbook bug. See entry §13 in\n  `troubleshooting\u002Fplaybook.md`.\n\nIf the user wants to design a new playbook, change its task tree, or\nfactor reusable instructions into skills, **hand off to\n`converge-planning`**. This skill only operates what already exists.\n\n## Current mental model\n\nConverge has three important layers:\n\n1. **Source blueprint** — `.converge\u002Fplaybooks\u002F\u003Cname>\u002F`\n   - `playbook.yml` — the manifest (top-level tasks, `depends_on`, `goals`).\n   - `tasks\u002F**\u002FTASK.md` — task contracts (id, inputs, outputs, checks).\n   - `templates\u002F\u003Cname>\u002FTASK.md` — runtime spawn templates for dynamic children.\n   - `skills\u002F\u003Cname>\u002FSKILL.md` — **playbook-scoped skills** (the *how* paired with each task's *what*). Also searched at `.claude\u002Fskills\u002F` (project-scoped) and `.codex\u002Fskills\u002F`.\n   - `scripts\u002F` — orchestration helpers invoked from task bodies (e.g., to compute `converge spawn` calls from a catalog).\n2. **Runtime state** — `.converge\u002Fjournal\u002F\u003Cplaybook>\u002F`, `.converge\u002Finventory\u002F\u003Cplaybook>\u002F`\n   Execution state, event stream, per-task forensics, and the spawned-task ledger.\n3. **Operator surface** — the CLI\n   `run`, `status`, `list`, `show`, `inspect`, `doctor`, `playbook validate`, `tasks mark`, `skills list`, `clean`, `stop`.\n\nThe playbook is the source of truth. Do **not** hand-edit `runstate.json`, `manifest.json`, or journal files to \"fix\" a run.\n\n### Three-layer task model\n\nWhen interpreting failures or proposing fixes, remember each task carries content across three layers — different problems live in different layers:\n\n- **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.\n- **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.\n- **SKILL.md** — the *general how-to* the task references via `skills: [\u003Cname>]`. Failures here look like the same wrong-result shape across many tasks that share the skill. Fix the skill body once, not each task.\n\nIf three tasks fail the same way and they all share `skills: [X]`, the bug is in skill X, not in the tasks.\n\n### The per-task execution dir (`$CONVERGE_TASK_DIR`)\n\nEvery task gets a stable directory the runtime sets before the body runs:\n\n```\n.converge\u002Fjournal\u002F\u003Cplaybook>\u002Ftasks\u002F\u003Ctask-id>\u002Fexec\u002F\n```\n\nExposed 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.\n\n| File | What it means |\n|---|---|\n| `spawn\u002FSTATUS.md` | The single AI-facing transparency surface. One `- [x]` \u002F `- [ ]` row per spawned child. Failed rows carry a `fix:` block. |\n| `spawn\u002F\u003Cid>\u002FEXPANDED.md` | Framework-rendered template TASK.md with `{{...}}` substituted. Useful when verifying that the body's params produced the intended contract. |\n| `spawn\u002F\u003Cid>\u002FEVIDENCE.json` | Machine-readable per-child failure detail. Mirrors a row in STATUS.md. |\n| `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. |\n| `spawn.plan.result.jsonl` | (Legacy) per-row outcome of the legacy `converge apply`. |\n| `wave.counter` | Current wave number for `mode: converger` tasks. Persists across re-leases so wave state survives crashes. |\n| `halt.marker` | The body's explicit \"I'm done\" signal for a converger. Highest-priority halt signal — overrides `halt_when:` and `wave_check:`. |\n| `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`. |\n\nThe directory persists across attempts on purpose — a crashed body's partial invocations survive into the next attempt's repair. See `reference\u002Fevents.md` for the matching event-stream interpretation (e.g., `SEED_SPAWN`, `FRONTIER_UNRESOLVED`).\n\n## Primary workflow\n\nUse this loop unless a narrower recipe in `troubleshooting\u002Fplaybook.md` fits exactly.\n\n### 1. Preflight the playbook\n\nValidate the definition before running:\n\n```bash\nconverge playbook validate \u003Cname>\n```\n\nIf the user is editing tasks live and wants a pure preview of what would execute:\n\n```bash\nconverge run --playbook=\u003Cname> --dry\n```\n\nUse `--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`.\n\n### 2. Start the run\n\n```bash\nconverge run --playbook=\u003Cname>\n```\n\nCommon narrowed runs:\n\n```bash\n# Only changed work and downstream\nconverge run --playbook=\u003Cname> --select 'state:modified+'\n\n# Retry failures and their downstream consumers\nconverge run --playbook=\u003Cname> --select 'result:error+'\n\n# One task \u002F subtree\nconverge run --playbook=\u003Cname> --select '03-build+'\n\n# Fail fast when debugging one subtree\nconverge run --playbook=\u003Cname> --select '03-build+' --fail-fast\n```\n\n### 3. Watch the run\n\nPrimary operator views:\n\n```bash\nconverge status --playbook=\u003Cname>\nconverge list --playbook=\u003Cname> --exclude 'status:complete'\nconverge show gantt --playbook=\u003Cname>\nconverge show graph --playbook=\u003Cname> --detail\n```\n\nRaw event stream:\n\n```bash\ntail -f .converge\u002Fjournal\u002F\u003Cplaybook>\u002Fevents.jsonl\ntail -f .converge\u002Fjournal\u002F\u003Cplaybook>\u002Fevents.jsonl | grep -E '(NODE_COMPLETE|NODE_FAIL|CHECK_FAIL|ERROR|CYCLE)'\n```\n\n### 4. If the run fails\n\nFirst classify whether the problem is:\n\n- **definition-shape** → `converge playbook validate \u003Cname>`\n- **runtime-shape** → `converge doctor --playbook=\u003Cname>`\n- **task \u002F check-shape** → `converge inspect --playbook=\u003Cname> --task=\u003Cid>`\n- **selection \u002F graph-shape** → `converge list --playbook=\u003Cname> --select ...` or `converge show graph`\n\nThen use the smallest surgical next step:\n\n```bash\n# Inspect one failed task\nconverge inspect --playbook=\u003Cname> --task=\u003CtaskId>\n\n# Health-check the runtime state\nconverge doctor --playbook=\u003Cname>\n\n# Reset only the failed subtree\nconverge clean --playbook=\u003Cname> --select '\u003CtaskId>+'\n\n# Re-run just failures\nconverge run --playbook=\u003Cname> --select 'result:error+'\n```\n\n### 5. If the run is stuck or orphaned\n\n```bash\n# Stop the live process and release the lock\nconverge stop --playbook=\u003Cname>\n```\n\nIf a single dynamic-container task is wedged in a continue-loop and the\noperator (with the user's consent) wants to retire it manually:\n\n```bash\n# Mark one task done \u002F dropped \u002F blocked so the parent stops re-spawning\nconverge tasks mark \u003CtaskId> --playbook=\u003Cname> --status done\nconverge tasks mark \u003CtaskId> --playbook=\u003Cname> --status dropped --reasoning \"user opted out\"\n```\n\nThen restart with a narrowed selection if possible.\n\n### 6. If the first task fails with `Invalid API key` \u002F HTTP 401\n\nThis is almost always **environment**, not the playbook. The spawned\nagent CLI (`claude`, `codex`) inherits `ANTHROPIC_*` \u002F `OPENAI_*` env\nvars from the shell, and a stale value from a previous proxy setup\nwill override the project's `.converge\u002Fproject.yaml` env block.\n\n```bash\nenv | grep -E 'ANTHROPIC_|OPENAI_|CLAUDE_'\n# Reconcile against .converge\u002Fproject.yaml's provider env:\ncat .converge\u002Fproject.yaml | grep -A20 'ai:'\n# If the shell vars conflict with what project.yaml expects, unset them\n# (or re-export to match) before re-running.\n```\n\nSee `troubleshooting\u002Fplaybook.md` §13 for the full recipe.\n\n## Preferred command set\n\nUse these first. They reflect the actual CLI surface and current docs.\n\n```bash\n# Run\nconverge run --playbook=\u003Cname>\n\n# Preview\nconverge run --playbook=\u003Cname> --dry\n\n# Current status tree\nconverge status --playbook=\u003Cname>\n\n# Selection-aware listing\nconverge list --playbook=\u003Cname> --exclude 'status:complete'\n\n# Graph \u002F gantt \u002F metrics \u002F journal views\nconverge show graph --playbook=\u003Cname> --detail\nconverge show gantt --playbook=\u003Cname>\nconverge show metrics --playbook=\u003Cname> --by-model --top=5\n\n# Forensics\nconverge inspect --playbook=\u003Cname> --task=\u003CtaskId>\n\n# Definition health\nconverge playbook validate \u003Cname>\n\n# Runtime health\nconverge doctor --playbook=\u003Cname>\n\n# Surgical cleanup\nconverge clean --playbook=\u003Cname> --select '\u003CtaskId>+'\n\n# State reconciliation (fix zombie runstate, stale inventory, rebuild DAG)\nconverge reconcile --playbook=\u003Cname>\n\n# Stop a live \u002F stale run\nconverge stop --playbook=\u003Cname>\n\n# Mark a task done\u002Fdropped\u002Fblocked (use sparingly — prefer fixing the cause)\nconverge tasks mark \u003CtaskId> --playbook=\u003Cname> --status done\n\n# List installed skills (project-scoped + bundled)\nconverge skills list\n\n# Goal progress (for goal-driven epoch playbooks)\nconverge goals --playbook=\u003Cname>\n```\n\n## When to use compatibility commands\n\nThese still exist, but they are not the first teaching surface:\n\n- `converge compile` → compatibility \u002F low-level preview path\n- `converge build` → `run --fail-fast`\n- `converge retry` → `run --resume`\n- `converge test` → checks-only execution\n\nUse them when the user explicitly asks for them or when a fixture \u002F test \u002F older note already uses them.\n\n## Hard rules\n\n- **Prefer `run --dry` over teaching `compile` first.**\n- **Always scope with `--playbook=\u003Cname>` when more than one playbook exists.**\n- **Use `doctor` for runtime-health questions.**\n- **Use `playbook validate` for definition-health questions.**\n- **Use `inspect --task=\u003Cid>` before proposing a novel fix.**\n- **Use `clean --select` instead of deleting `.converge\u002Fjournal\u002F` or `.converge\u002Finventory\u002F` by hand.**\n- **Use `stop` instead of ad-hoc `pkill` when possible.**\n- **Do not edit generated runtime state. Fix the playbook source or the project inputs.**\n- **If the failure is in user domain code or missing credentials, surface it clearly instead of inventing framework fixes.**\n- **HTTP 401 \u002F \"Invalid API key\" on the first task is environment, not the playbook.** Check `env | grep ANTHROPIC_` and reconcile against `.converge\u002Fproject.yaml`'s `ai.providers.\u003Cname>.env` block before touching the playbook itself.\n- **`--backend` and `--provider` are init-time flags, not run-time flags.** Don't pass them to `converge run`. To change provider routing, edit `.converge\u002Fproject.yaml` (or re-run `converge init --force --backend=… --provider=…`).\n- **When playbook state is out of sync (0 DAG nodes, orphaned spawned tasks, stale \"doing\" status), use `converge reconcile --playbook=\u003Cname>` first.** If that doesn't resolve it, fall back to the manual recovery workflow in `troubleshooting\u002Fstate-recovery.md`.\n- **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.\n\n## Manual recovery workflow\n\nWhen a playbook's runtime state is out of sync with reality (orphaned spawned tasks, stale statuses, missing DAG nodes), follow this three-layer approach:\n\n1. **Audit** — `converge doctor`, `converge playbook validate`, compare `converge list` vs `converge tasks list` counts\n2. **Repair** — `converge reconcile --playbook=\u003Cname>` (systematic) or `converge reset \u003Cname> --yes` (nuclear) or `converge clean --select=X --yes` (surgical) or `converge tasks mark X --status done\u002Fdropped\u002Ftodo` (manual correction)\n3. **Step-through** — `converge run --select=02-spawn` → verify → `converge run --select=\"screen-chat-*\"` → verify → `converge run` (full)\n\nFor 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\u002Fstate-recovery.md` Scenario H.\n\n## Hand-off rules\n\n| Situation | Hand off to |\n|---|---|\n| User wants to design or restructure a playbook | `converge-planning` |\n| User wants to debug framework code under `packages\u002F` | `converge-development` |\n| Failure is novel and crosses framework\u002Fruntime boundaries | user escalation with evidence |\n\n## File map\n\n```\nSKILL.md\nreference\u002F\n  cli.md\n  events.md\ntroubleshooting\u002F\n  playbook.md\n```\n\nLoad `reference\u002Fcli.md` for concrete command patterns, `reference\u002Fevents.md` for event interpretation, and `troubleshooting\u002Fplaybook.md` only when a concrete failure fingerprint matches.\n","# Converge Control\n\n## When to use this skill\n\nTrigger this skill whenever the user is operating an existing playbook —\nnot authoring a new one. Concrete signals:\n\n- A `.converge\u002Fproject.yaml` + `playbooks\u002F\u003Cname>\u002F` already exist; the\n  user wants the playbook to actually run, or wants to know what\n  happened on the last run.\n- The user reports a failure mid-run, a stuck task, an error in the\n  journal, or wants to retry only what failed.\n- The user asks operational questions: *what's running right now?*,\n  *which tasks are blocked?*, *what did task X produce?*, *how much\n  did the last run cost?*, *how do I re-run just the failures?*\n- The user hits HTTP 401 \u002F Invalid API key — that's an environment\n  conflict between shell `ANTHROPIC_*` vars and the project's provider\n  config, not a playbook bug. See entry §13 in\n  `troubleshooting\u002Fplaybook.md`.\n\nIf the user wants to design a new playbook, change its task tree, or\nfactor reusable instructions into skills, **hand off to\n`converge-planning`**. This skill only operates what already exists.\n\n## Current mental model\n\nConverge has three important layers:\n\n1. **Source blueprint** — `.converge\u002Fplaybooks\u002F\u003Cname>\u002F`\n   - `playbook.yml` — the manifest (top-level tasks, `depends_on`, `goals`).\n   - `tasks\u002F**\u002FTASK.md` — task contracts (id, inputs, outputs, checks).\n   - `templates\u002F\u003Cname>\u002FTASK.md` — runtime spawn templates for dynamic children.\n   - `skills\u002F\u003Cname>\u002FSKILL.md` — **playbook-scoped skills** (the *how* paired with each task's *what*). Also searched at `.claude\u002Fskills\u002F` (project-scoped) and `.codex\u002Fskills\u002F`.\n   - `scripts\u002F` — orchestration helpers invoked from task bodies (e.g., to compute `converge spawn` calls from a catalog).\n2. **Runtime state** — `.converge\u002Fjournal\u002F\u003Cplaybook>\u002F`, `.converge\u002Finventory\u002F\u003Cplaybook>\u002F`\n   Execution state, event stream, per-task forensics, and the spawned-task ledger.\n3. **Operator surface** — the CLI\n   `run`, `status`, `list`, `show`, `inspect`, `doctor`, `playbook validate`, `tasks mark`, `skills list`, `clean`, `stop`.\n\nThe playbook is the source of truth. Do **not** hand-edit `runstate.json`, `manifest.json`, or journal files to \"fix\" a run.\n\n### Three-layer task model\n\nWhen interpreting failures or proposing fixes, remember each task carries content across three layers — different problems live in different layers:\n\n- **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.\n- **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.\n- **SKILL.md** — the *general how-to* the task references via `skills: [\u003Cname>]`. Failures here look like the same wrong-result shape across many tasks that share the skill. Fix the skill body once, not each task.\n\nIf three tasks fail the same way and they all share `skills: [X]`, the bug is in skill X, not in the tasks.\n\n### The per-task execution dir (`$CONVERGE_TASK_DIR`)\n\nEvery task gets a stable directory the runtime sets before the body runs:\n\n```\n.converge\u002Fjournal\u002F\u003Cplaybook>\u002Ftasks\u002F\u003Ctask-id>\u002Fexec\u002F\n```\n\nExposed 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.\n\n| File | What it means |\n|---|---|\n| `spawn\u002FSTATUS.md` | The single AI-facing transparency surface. One `- [x]` \u002F `- [ ]` row per spawned child. Failed rows carry a `fix:` block. |\n| `spawn\u002F\u003Cid>\u002FEXPANDED.md` | Framework-rendered template TASK.md with `{{...}}` substituted. Useful when verifying that the body's params produced the intended contract. |\n| `spawn\u002F\u003Cid>\u002FEVIDENCE.json` | Machine-readable per-child failure detail. Mirrors a row in STATUS.md. |\n| `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. |\n| `spawn.plan.result.jsonl` | (Legacy) per-row outcome of the legacy `converge apply`. |\n| `wave.counter` | Current wave number for `mode: converger` tasks. Persists across re-leases so wave state survives crashes. |\n| `halt.marker` | The body's explicit \"I'm done\" signal for a converger. Highest-priority halt signal — overrides `halt_when:` and `wave_check:`. |\n| `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`. |\n\nThe directory persists across attempts on purpose — a crashed body's partial invocations survive into the next attempt's repair. See `reference\u002Fevents.md` for the matching event-stream interpretation (e.g., `SEED_SPAWN`, `FRONTIER_UNRESOLVED`).\n\n## Primary workflow\n\nUse this loop unless a narrower recipe in `troubleshooting\u002Fplaybook.md` fits exactly.\n\n### 1. Preflight the playbook\n\nValidate the definition before running:\n\n```bash\nconverge playbook validate \u003Cname>\n```\n\nIf the user is editing tasks live and wants a pure preview of what would execute:\n\n```bash\nconverge run --playbook=\u003Cname> --dry\n```\n\nUse `--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`.\n\n### 2. Start the run\n\n```bash\nconverge run --playbook=\u003Cname>\n```\n\nCommon narrowed runs:\n\n```bash\n# Only changed work and downstream\nconverge run --playbook=\u003Cname> --select 'state:modified+'\n\n# Retry failures and their downstream consumers\nconverge run --playbook=\u003Cname> --select 'result:error+'\n\n# One task \u002F subtree\nconverge run --playbook=\u003Cname> --select '03-build+'\n\n# Fail fast when debugging one subtree\nconverge run --playbook=\u003Cname> --select '03-build+' --fail-fast\n```\n\n### 3. Watch the run\n\nPrimary operator views:\n\n```bash\nconverge status --playbook=\u003Cname>\nconverge list --playbook=\u003Cname> --exclude 'status:complete'\nconverge show gantt --playbook=\u003Cname>\nconverge show graph --playbook=\u003Cname> --detail\n```\n\nRaw event stream:\n\n```bash\ntail -f .converge\u002Fjournal\u002F\u003Cplaybook>\u002Fevents.jsonl\ntail -f .converge\u002Fjournal\u002F\u003Cplaybook>\u002Fevents.jsonl | grep -E '(NODE_COMPLETE|NODE_FAIL|CHECK_FAIL|ERROR|CYCLE)'\n```\n\n### 4. If the run fails\n\nFirst classify whether the problem is:\n\n- **definition-shape** → `converge playbook validate \u003Cname>`\n- **runtime-shape** → `converge doctor --playbook=\u003Cname>`\n- **task \u002F check-shape** → `converge inspect --playbook=\u003Cname> --task=\u003Cid>`\n- **selection \u002F graph-shape** → `converge list --playbook=\u003Cname> --select ...` or `converge show graph`\n\nThen use the smallest surgical next step:\n\n```bash\n# Inspect one failed task\nconverge inspect --playbook=\u003Cname> --task=\u003CtaskId>\n\n# Health-check the runtime state\nconverge doctor --playbook=\u003Cname>\n\n# Reset only the failed subtree\nconverge clean --playbook=\u003Cname> --select '\u003CtaskId>+'\n\n# Re-run just failures\nconverge run --playbook=\u003Cname> --select 'result:error+'\n```\n\n### 5. If the run is stuck or orphaned\n\n```bash\n# Stop the live process and release the lock\nconverge stop --playbook=\u003Cname>\n```\n\nIf a single dynamic-container task is wedged in a continue-loop and the\noperator (with the user's consent) wants to retire it manually:\n\n```bash\n# Mark one task done \u002F dropped \u002F blocked so the parent stops re-spawning\nconverge tasks mark \u003CtaskId> --playbook=\u003Cname> --status done\nconverge tasks mark \u003CtaskId> --playbook=\u003Cname> --status dropped --reasoning \"user opted out\"\n```\n\nThen restart with a narrowed selection if possible.\n\n### 6. If the first task fails with `Invalid API key` \u002F HTTP 401\n\nThis is almost always **environment**, not the playbook. The spawned\nagent CLI (`claude`, `codex`) inherits `ANTHROPIC_*` \u002F `OPENAI_*` env\nvars from the shell, and a stale value from a previous proxy setup\nwill override the project's `.converge\u002Fproject.yaml` env block.\n\n```bash\nenv | grep -E 'ANTHROPIC_|OPENAI_|CLAUDE_'\n# Reconcile against .converge\u002Fproject.yaml's provider env:\ncat .converge\u002Fproject.yaml | grep -A20 'ai:'\n# If the shell vars conflict with what project.yaml expects, unset them\n# (or re-export to match) before re-running.\n```\n\nSee `troubleshooting\u002Fplaybook.md` §13 for the full recipe.\n\n## Preferred command set\n\nUse these first. They reflect the actual CLI surface and current docs.\n\n```bash\n# Run\nconverge run --playbook=\u003Cname>\n\n# Preview\nconverge run --playbook=\u003Cname> --dry\n\n# Current status tree\nconverge status --playbook=\u003Cname>\n\n# Selection-aware listing\nconverge list --playbook=\u003Cname> --exclude 'status:complete'\n\n# Graph \u002F gantt \u002F metrics \u002F journal views\nconverge show graph --playbook=\u003Cname> --detail\nconverge show gantt --playbook=\u003Cname>\nconverge show metrics --playbook=\u003Cname> --by-model --top=5\n\n# Forensics\nconverge inspect --playbook=\u003Cname> --task=\u003CtaskId>\n\n# Definition health\nconverge playbook validate \u003Cname>\n\n# Runtime health\nconverge doctor --playbook=\u003Cname>\n\n# Surgical cleanup\nconverge clean --playbook=\u003Cname> --select '\u003CtaskId>+'\n\n# State reconciliation (fix zombie runstate, stale inventory, rebuild DAG)\nconverge reconcile --playbook=\u003Cname>\n\n# Stop a live \u002F stale run\nconverge stop --playbook=\u003Cname>\n\n# Mark a task done\u002Fdropped\u002Fblocked (use sparingly — prefer fixing the cause)\nconverge tasks mark \u003CtaskId> --playbook=\u003Cname> --status done\n\n# List installed skills (project-scoped + bundled)\nconverge skills list\n\n# Goal progress (for goal-driven epoch playbooks)\nconverge goals --playbook=\u003Cname>\n```\n\n## When to use compatibility commands\n\nThese still exist, but they are not the first teaching surface:\n\n- `converge compile` → compatibility \u002F low-level preview path\n- `converge build` → `run --fail-fast`\n- `converge retry` → `run --resume`\n- `converge test` → checks-only execution\n\nUse them when the user explicitly asks for them or when a fixture \u002F test \u002F older note already uses them.\n\n## Hard rules\n\n- **Prefer `run --dry` over teaching `compile` first.**\n- **Always scope with `--playbook=\u003Cname>` when more than one playbook exists.**\n- **Use `doctor` for runtime-health questions.**\n- **Use `playbook validate` for definition-health questions.**\n- **Use `inspect --task=\u003Cid>` before proposing a novel fix.**\n- **Use `clean --select` instead of deleting `.converge\u002Fjournal\u002F` or `.converge\u002Finventory\u002F` by hand.**\n- **Use `stop` instead of ad-hoc `pkill` when possible.**\n- **Do not edit generated runtime state. Fix the playbook source or the project inputs.**\n- **If the failure is in user domain code or missing credentials, surface it clearly instead of inventing framework fixes.**\n- **HTTP 401 \u002F \"Invalid API key\" on the first task is environment, not the playbook.** Check `env | grep ANTHROPIC_` and reconcile against `.converge\u002Fproject.yaml`'s `ai.providers.\u003Cname>.env` block before touching the playbook itself.\n- **`--backend` and `--provider` are init-time flags, not run-time flags.** Don't pass them to `converge run`. To change provider routing, edit `.converge\u002Fproject.yaml` (or re-run `converge init --force --backend=… --provider=…`).\n- **When playbook state is out of sync (0 DAG nodes, orphaned spawned tasks, stale \"doing\" status), use `converge reconcile --playbook=\u003Cname>` first.** If that doesn't resolve it, fall back to the manual recovery workflow in `troubleshooting\u002Fstate-recovery.md`.\n- **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.\n\n## Manual recovery workflow\n\nWhen a playbook's runtime state is out of sync with reality (orphaned spawned tasks, stale statuses, missing DAG nodes), follow this three-layer approach:\n\n1. **Audit** — `converge doctor`, `converge playbook validate`, compare `converge list` vs `converge tasks list` counts\n2. **Repair** — `converge reconcile --playbook=\u003Cname>` (systematic) or `converge reset \u003Cname> --yes` (nuclear) or `converge clean --select=X --yes` (surgical) or `converge tasks mark X --status done\u002Fdropped\u002Ftodo` (manual correction)\n3. **Step-through** — `converge run --select=02-spawn` → verify → `converge run --select=\"screen-chat-*\"` → verify → `converge run` (full)\n\nFor 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\u002Fstate-recovery.md` Scenario H.\n\n## Hand-off rules\n\n| Situation | Hand off to |\n|---|---|\n| User wants to design or restructure a playbook | `converge-planning` |\n| User wants to debug framework code under `packages\u002F` | `converge-development` |\n| Failure is novel and crosses framework\u002Fruntime boundaries | user escalation with evidence |\n\n## File map\n\n```\nSKILL.md\nreference\u002F\n  cli.md\n  events.md\ntroubleshooting\u002F\n  playbook.md\n```\n\nLoad `reference\u002Fcli.md` for concrete command patterns, `reference\u002Fevents.md` for event interpretation, and `troubleshooting\u002Fplaybook.md` only when a concrete failure fingerprint matches.\n",{"name":5,"description":7},"main","7d618d8bc059f1a0974706d1d15ec25f73cf1e1d",".claude\u002Fskills\u002Fconverge-control",1,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge","https:\u002F\u002Fplaybooks.to","https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev","2026-06-13 10:11:21",{"source":8,"skillName":5,"commands":62,"prompt":72,"zipAvailable":73},[63,66,69],{"tool":64,"command":65},"npx","npx skills add openplaybooks-dev\u002Fconverge --skill converge-control",{"tool":67,"command":68},"bunx","bunx skills add openplaybooks-dev\u002Fconverge --skill converge-control",{"tool":70,"command":71},"pnpm","pnpm dlx skills add openplaybooks-dev\u002Fconverge --skill converge-control","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-control\u002FSKILL.md",true,[75,81,85,89,93,97,101],{"path":76,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":79,"sourceHtmlUrl":80},"reference\u002Fcli.md","REFERENCE","参考文档",2396,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-control\u002Freference\u002Fcli.md",{"path":82,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":83,"sourceHtmlUrl":84},"reference\u002Fevents.md",5646,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-control\u002Freference\u002Fevents.md",{"path":86,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":87,"sourceHtmlUrl":88},"troubleshooting\u002Fdefinition-contract.md",5520,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-control\u002Ftroubleshooting\u002Fdefinition-contract.md",{"path":90,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":91,"sourceHtmlUrl":92},"troubleshooting\u002Fenv-config.md",4419,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-control\u002Ftroubleshooting\u002Fenv-config.md",{"path":94,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":95,"sourceHtmlUrl":96},"troubleshooting\u002Fplaybook.md",5705,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-control\u002Ftroubleshooting\u002Fplaybook.md",{"path":98,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":99,"sourceHtmlUrl":100},"troubleshooting\u002Fruntime-execution.md",7925,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-control\u002Ftroubleshooting\u002Fruntime-execution.md",{"path":102,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":103,"sourceHtmlUrl":104},"troubleshooting\u002Fstate-recovery.md",10268,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-control\u002Ftroubleshooting\u002Fstate-recovery.md",[106,130,139,161,181,188],{"skillNo":107,"name":108,"nameZh":6,"description":109,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":110,"categories":111,"keywords":113,"publishedAt":48},"01M71989MQF3GPZ7P5TX6S93PD","hello-checker","Use this skill when asked to \"verify\", \"check\", or \"validate\" a file's existence and content. It provides a reliable workflow for confirming files meet their spec.","https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002Ftests\u002Ftest-codex-real\u002F.converge\u002Fskills\u002Fhello-checker\u002FSKILL.md",[112],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},[114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129],"checker","hello checker","hello","it","use","content","validate","spec","verify","check","file","workflow","when","Meet","files","for",{"skillNo":131,"name":132,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":133,"categories":134,"keywords":136,"publishedAt":48},"01M7198823W79B3S15TPV97TCB","ask-skill","https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002Ftests\u002Ftest-ask-autonomous\u002F.converge\u002Fplaybooks\u002Fdefault\u002Fskills\u002Fask-skill\u002FSKILL.md",[135],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},[137,138],"ask skill","ask",{"skillNo":140,"name":141,"nameZh":6,"description":142,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":143,"categories":144,"keywords":149,"publishedAt":48},"01M71986EJ6VCM8YKGEM2YEDQV","html-review-artifact","Framework-wide guidance for crafting polished human-review artifacts as markdown or HTML","https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002Fskills\u002Fhtml-review-artifact\u002FSKILL.md",[145,148],{"categoryNo":146,"categoryName":147,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},[150,151,152,153,154,129,155,156,157,158,159,160],"html","artifact","review","html review artifact","as","framework","wide","guidance","markdown","human","artifacts",{"skillNo":162,"name":163,"nameZh":6,"description":164,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":165,"categories":166,"keywords":168,"publishedAt":48},"01M719833M2XWXG1VPBW30GW7J","converge-planning","Design a Converge playbook end-to-end. Use when the user says \"plan a project\", \"design a playbook\", \"decompose into tasks\", \"scaffold a Converge workflow\", \"onboard to Converge\", or asks how to write TASK.md \u002F playbook.yml. Two entry points: plan a new playbook or update an existing one. Hand off to `\u002Fconverge-control` after producing the playbook structure.","https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002Fskills\u002Fconverge-planning\u002FSKILL.md",[167],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},[29,169,170,171,125,172,118,173,33,174,175,176,177,178,179,39,36,31,180,126],"converge planning","planning","structure","tasks","decompose","write","plan","how","update","playbook","new","project",{"skillNo":182,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":183,"categories":184,"keywords":187,"publishedAt":48},"01M7197XZT1T9GDYAJGVGX1J60","https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002Fskills\u002Fconverge-control\u002FSKILL.md",[185,186],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":23,"categoryName":24,"taxonomyType":25,"taxonomyTypeDesc":26},[28,30,29,34,38,41,46,40,43,37,33,45,47,39,36,42,31,32,44,35],{"skillNo":189,"name":190,"nameZh":6,"description":191,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":192,"categories":193,"keywords":195,"publishedAt":48},"01M7197SCVN0QTD3CM4M83WYJH","repair-taskts","Fix task.ts definition issues — Seed syntax, missing .build(), empty checks, import errors, TypeScript errors","https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002Fpackages\u002Fcore\u002Fsrc\u002Fnavigator\u002Frepair\u002Fskill-templates\u002Frepair-taskts\u002FSKILL.md",[194],{"categoryNo":23,"categoryName":24,"taxonomyType":25,"taxonomyTypeDesc":26},[196,197,198,199,174,200,201,202,203,204,205,206,207,208,209,31,210,29,211,212],"repair taskts","repair","Bash","edit","read","line","at","spawn","code","analysis","number","errors","issues","fix","chain","definition","never"]