[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7191RYSEV1FSX5BV1CAJRP3":3,"skill-same:01M7191RYSEV1FSX5BV1CAJRP3":93},{"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},"01M7191RYSEV1FSX5BV1CAJRP3","converge-development",null,"Use when the user wants to develop, debug, or improve the converge framework itself — running an example as a test bed, running the self-improvement loop, observing framework behavior, diagnosing framework bugs, and editing source under packages\u002F. Triggers on phrases like \"debug converge\", \"fix the framework\", \"run the self-improvement loop\", \"autonomous framework improvement\", \"why does the runner do X\", \"improve the journal\", \"add a feature to the CLI\", \"use this example to find bugs in converge\".","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-development\u002FSKILL.md",[17,22],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000008","测试与质量","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","development","converge development","framework","add","source","improvement loop","why","run","cli","packages","self","when","loop","autonomous","journal","improve","fix","runner","bed","2026-11-10 10:12:30",false,"---\nname: converge-development\ndescription: Use when the user wants to develop, debug, or improve the converge framework itself — running an example as a test bed, running the self-improvement loop, observing framework behavior, diagnosing framework bugs, and editing source under packages\u002F. Triggers on phrases like \"debug converge\", \"fix the framework\", \"run the self-improvement loop\", \"autonomous framework improvement\", \"why does the runner do X\", \"improve the journal\", \"add a feature to the CLI\", \"use this example to find bugs in converge\".\n---\n\n# Converge Development — observe-diagnose-fix the framework itself\n\n## Purpose\n\nUse a real example playbook as a test bed. Run it. Watch what the framework does internally — not just the stdout event stream, but the target directory, runstate, and per-attempt forensics the runner writes to disk. When the framework misbehaves (crashes, corrupts state, fails to retry, mishandles a provider response), trace the symptom to the package and module responsible, patch `packages\u002F**` source, rebuild, and re-run the example to verify.\n\nThis skill is **only** for changes to framework source under `packages\u002F` or for running framework-improvement playbooks that target `packages\u002F`. It is the framework-developer counterpart to `converge-control` (which babysits a *user's* playbook and treats the framework as a black box).\n\n## Two modes\n\n- **Interactive:** reproduce a named framework bug, patch `packages\u002F**`, rebuild, verify.\n- **Autonomous:** run `self-improvement-loop` for bounded framework hardening, then use its artifacts as the evidence trail.\n\n## When to invoke\n\nTrigger on user requests like:\n\n- \"Debug converge using \u003Cexample>\" \u002F \"Use this example to find bugs in the framework\"\n- \"Why does the DAG runner \u003Cdo X>?\" \u002F \"Why is the execution \u003Cdoing Y>?\"\n- \"Fix the framework — \u003Csymptom>\" \u002F \"There's a bug in the manifest\u002Fmode\u002Fdispatcher\u002FCLI\"\n- \"Improve \u003Csubsystem>\" \u002F \"Add a feature to the CLI\" \u002F \"Refactor a DAG action\"\n- \"Run the self-improvement loop\" \u002F \"Autonomously improve the framework\"\n- \"Profile \u002F instrument \u002F add logging to \u003Cmodule>\"\n\nDo **not** invoke for:\n\n- Running a *user's* playbook to completion → **`converge-control`**\n- Fixing a stuck user playbook (stale outputs, stall, foreign-playbook hijack) → **`converge-control`**\n- Designing a new playbook or setting up `.converge\u002F` from scratch → **`converge-planning`**\n\nIf the symptom is purely user-shape (the playbook author made a mistake), route to `converge-control`. If the symptom is framework-shape (the runner mishandles a *valid* user playbook), continue here.\n\n## Autonomous mode: self-improvement-loop\n\nRun bounded framework hardening with:\n\n```bash\nconverge run --playbook=self-improvement-loop --select improve+\n```\n\nUse only these surfaces unless debugging the playbook itself:\n\n- source: `.converge\u002Fplaybooks\u002Fself-improvement-loop\u002FREADME.md`, `tasks\u002Fimprove\u002FTASK.md`, `templates\u002Fepoch\u002FTASK.md`, `scripts\u002F*.mjs`;\n- evidence: `.converge\u002Fartifacts\u002Fself-improvement-loop\u002F{journal.md,metrics.jsonl,backlog.jsonl,touched-files.jsonl,convergence.md,epochs\u002F\u003CNNN>\u002F}`.\n\nKeep epochs maintainer-grade: clean non-artifact start, real observations before selection, one evidence-backed framework change, patch manifest from `git diff`, mapped regression commands, command-backed `verify\u002Fresult.json`, and stop rather than repeat low-value cleanup.\n\nIf the loop exposes a clear framework bug, use the interactive dev loop below for the patch and let the playbook verify the epoch.\n\n## The dev loop\n\nEight steps, in order. Stay in this loop until the example passes cleanly or you hit a structural decision that needs the user.\n\n### 1. Pick a test bed\n\nIf the user named a test fixture or example in the trigger phrase, use it. The smallest one that exercises the suspected subsystem is best — see the fixture→subsystem table at the bottom of `reference\u002Fframework-map.md`.\n\n**Test fixtures** (under `tests\u002F`) are the primary dev-loop test beds — they're small, fast, and have corresponding vitest runners. Prefer these for most framework debugging:\n\n| Subsystem | Fixture |\n|-----------|---------|\n| Navigator \u002F convergence | `tests\u002Ftest-simple-run` |\n| Compile \u002F discovery \u002F manifest | `tests\u002Ftest-compile-discover` |\n| Multi-provider \u002F agentfn routing | `tests\u002Ftest-mixed-model` |\n| `mode: spawner` \u002F dynamic spawn | `tests\u002Ftest-seeding`, `tests\u002Ftest-queue-pattern` |\n| Gap detection (input\u002Foutput) | `tests\u002Ftest-gap-blocked-input`, `tests\u002Ftest-gap-missing-output` |\n| Buggy-check relaxation | `tests\u002Ftest-buggy-check` |\n| Loop detection | `tests\u002Ftest-loop-detection` |\n| Multi-attempt convergence | `tests\u002Ftest-multi-attempt` |\n| Crash-safe resume | `tests\u002Ftest-resume` |\n\n**Full examples** (under `examples\u002F`) are heavier multi-phase projects. Use when debugging end-to-end behavior that doesn't surface in a single fixture.\n\n### 2. Build current state\n\n```bash\ncd \u003Crepo-root>\npnpm build\n```\n\nConfirm it exits clean. **If the build is already broken, that *is* the first bug** — skip to step 5 with the build error as the symptom.\n\nFor faster iteration when changes are scoped to one package:\n\n```bash\npnpm --filter @openplaybooks\u002Fconverge-core build && pnpm --filter @openplaybooks\u002Fconverge build\n```\n\n### 3. Run the test bed & monitor\n\nFrom the test fixture or example directory:\n\n```bash\ncd tests\u002F\u003Cfixture-name>\nnode \u003Crepo-root>\u002Fpackages\u002Fcli\u002Fdist\u002Findex.js playbook validate default\nnode \u003Crepo-root>\u002Fpackages\u002Fcli\u002Fdist\u002Findex.js run --playbook=default --dry\nnode \u003Crepo-root>\u002Fpackages\u002Fcli\u002Fdist\u002Findex.js run --playbook=default\n```\n\nIf the fixture uses a non-default playbook name, swap `default` for the actual name.\n\nCommon flags for debugging:\n\n| Flag | Use |\n|---|---|\n| `--force` | Force-run a task even if completed\u002Fcached |\n| `--select \u003Cexpr>` | Run only matching tasks (`--select '02-something+'` = task + descendants) |\n| `--dry` | Plan only — show what would execute without running |\n| `--verbose, -v` | Verbose output |\n\nArm a Monitor on the event stream:\n\n```bash\ntail -f .converge\u002Fjournal\u002F\u003Cplaybook>\u002Fevents.jsonl | grep -E '(NODE_START|NODE_COMPLETE|NODE_FAIL|CHECK_FAIL|ERROR)'\n```\n\nThen — and this is what makes this skill different from `converge-control` — also read the *internal* state:\n\n```bash\n# DAG state after run\ncat .converge\u002Fjournal\u002F\u003Cplaybook>\u002Frunstate.json\n\n# Per-task forensics\nls .converge\u002Fjournal\u002F\u003Cplaybook>\u002Ftasks\u002F\u003CtaskId>\u002F\ncat .converge\u002Fjournal\u002F\u003Cplaybook>\u002Ftasks\u002F\u003CtaskId>\u002FFEEDBACK.md\ncat .converge\u002Fjournal\u002F\u003Cplaybook>\u002Ftasks\u002F\u003CtaskId>\u002FLEARN.md\n```\n\nFull observability surface: **`reference\u002Fobservability.md`**.\n\n### 4. Classify the symptom\n\n| Symptom shape | Class | Action |\n|---|---|---|\n| Example completes cleanly, no anomalies | none | nothing to fix; ask the user what they wanted to investigate |\n| Stale paths, missing inputs from user playbook | user-shape | wrong skill; route to **`converge-control`** |\n| DAG runner crashes \u002F unhandled exception during execution | framework | continue to step 5 |\n| Runstate corruption (node status flip-flops, fingerprint mismatch cascade) | framework | continue to step 5 |\n| `mode: spawner` apply fails despite valid `converge spawn` calls (or, for legacy playbooks, a valid `spawn.plan.jsonl`) | framework | continue to step 5 |\n| agentfn provider throws on a valid response | framework | continue to step 5 |\n| Node retries without progress (same CHECK_FAIL across attempts) | framework | continue to step 5 |\n| Fingerprint caching broken (unchanged node re-executed unnecessarily) | framework | continue to step 5 |\n| CLI arg parsing \u002F exit code wrong | framework | continue to step 5 |\n\n### 5. Diagnose\n\nOpen **`reference\u002Fframework-map.md`**. Find the subsystem that owns the symptom. Read the source files listed there. Form a hypothesis.\n\nThen check **`troubleshooting\u002Fplaybook.md`** for a matching past entry. If found → apply the recipe.\n\nIf the diagnosis is straightforward and confined to one file, proceed. If it crosses package boundaries (e.g. `core\u002Fnavigator` ↔ an agentfn provider, or `core\u002Fjournal` ↔ `cli\u002Fcommands-clean`), **STOP and surface the hypothesis to the user before editing**. Same escalation pattern as `converge-control`.\n\n### 6. Edit + rebuild\n\nPatch `packages\u002F**`. Then rebuild — the CLI runs from `dist\u002F`, not source:\n\n```bash\n# whole monorepo (safe default)\npnpm build\n\n# or single package (faster when the change is scoped)\npnpm --filter @openplaybooks\u002F\u003Cpackage-name> build\n```\n\n### 7. Verify\n\nClear target state from the failing run (so you're testing the fix, not a stale runstate):\n\n```bash\n# Remove runtime state for a clean re-run\nrm -rf tests\u002F\u003Cfixture>\u002F.converge\u002Fjournal\nrm -rf tests\u002F\u003Cfixture>\u002F.converge\u002Finventory\n# Also clean output files the fixture may have produced\nrm -f tests\u002F\u003Cfixture>\u002F*.txt\n```\n\nOr use the CLI for targeted cleanup:\n\n```bash\nnode packages\u002Fcli\u002Fdist\u002Findex.js clean --select '*' --dir=tests\u002F\u003Cfixture>\n```\n\nRe-run from step 3. Confirm:\n\n- Original symptom is gone.\n- No new symptoms appeared.\n- Run reaches exit 0 clean.\n\n**Run the existing vitest suite** for the subsystem you touched:\n\n```bash\n# Run tests for the fixture you're using\nnpx vitest run tests\u002F\u003Cfixture-related>.test.ts\n\n# Or run all tests (slower, use for hot-path changes)\nnpx vitest run tests\u002F\n```\n\nIf no vitest runner exists for the fixture, create one (see `tests\u002Fcompile-discover.test.ts` for the pattern — compile + run + verify outputs).\n\nIf the symptom returns or a new one shows up → loop back to step 5.\n\n### 8. Record the recipe\n\nAppend a new entry to **`troubleshooting\u002Fplaybook.md`** in the format established there: **Symptom** \u002F **Root cause** \u002F **Fix** \u002F **Verification** \u002F **Files touched**. Skip if the fix was a one-off typo. The point is to grow institutional memory so the *next* invocation of this skill recognizes the symptom faster.\n\n## Hard rules — STOP and re-route\n\n- **Don't edit framework source without first reproducing the bug against an example.** No speculative fixes. The reproducible run is also the verification baseline for step 7.\n- **Don't skip `pnpm build` between source edit and re-run.** The CLI binary runs from `packages\u002Fcli\u002Fdist\u002Findex.js`, not source. Edits to `packages\u002F**\u002Fsrc\u002F*.ts` have zero effect until rebuilt.\n- **Don't clear state mid-debug with `converge clean --all`.** That wipes fingerprints and can mask caching bugs. Use `rm -rf .converge\u002Fjournal\u002F\u003Cplaybook> .converge\u002Finventory\u002F\u003Cplaybook>` to clear state for a clean re-run.\n- **Don't bundle unrelated improvements.** One bug, one patch (CLAUDE.md §3 — surgical changes). If you notice adjacent dead code or a refactor opportunity, mention it to the user; don't ship it in the diagnostic fix.\n- **Don't run `pnpm test` as a gate for every edit.** Too slow for the dev loop. But if your fix touches a hot path — `core\u002Fsrc\u002Fdag\u002F`, `core\u002Fsrc\u002Fmanifest\u002F`, `core\u002Fsrc\u002Fjournal\u002F` — flag that to the user and suggest *they* run `pnpm test` before commit.\n- **Don't leave `console.log` debugging in the source.** If you added logging to diagnose, remove it before declaring the fix done.\n- **Apply known recipes; ask before novel ones.** If `troubleshooting\u002Fplaybook.md` has a matching entry → apply and continue. If it doesn't, and the diagnosis crosses package boundaries → STOP, state hypothesis, wait for approval.\n- **Use current terminology.** Runtime state lives under `.converge\u002Fjournal\u002F\u003Cplaybook>\u002F`; the task inventory (spawned manifests + ledger) lives under `.converge\u002Finventory\u002F\u003Cplaybook>\u002F`. Use `runstate.json`, not `checkpoint.json`. Use `DAG node`, not `epic`. Use `fingerprint caching`, not `resume checkpoint`.\n\n## Testing\n\n### Running tests\n\n```bash\n# All root-level integration tests\nnpx vitest run tests\u002F\n\n# Single test file (fast feedback)\nnpx vitest run tests\u002Fplaybook-compile.test.ts\n\n# Watch mode (re-run on file changes)\nnpx vitest tests\u002Fplaybook-compile.test.ts\n\n# Per-package unit tests\npnpm --filter @openplaybooks\u002Fconverge-core test\npnpm --filter @openplaybooks\u002Fagentfn test\n\n# Full monorepo test suite\npnpm test\n```\n\n### Test file anatomy\n\nRoot-level tests live in `tests\u002F*.test.ts`. They follow a pattern:\n\n```ts\n\u002F\u002F 1. Spawn converge CLI with spawnSync\nconst CLI = resolve(__dirname, \"..\", \"packages\u002Fcli\u002Fdist\u002Findex.js\");\nconst result = spawnSync(\"node\", [CLI, \"run\", \"--dir=\u003Cdir>\"], {\n  cwd: REPO_ROOT, encoding: \"utf-8\",\n  stdio: [\"ignore\", \"pipe\", \"pipe\"],\n});\n\n\u002F\u002F 2. Verify outputs on disk\nexpect(existsSync(resolve(PROJECT_DIR, \"EXPECTED_OUTPUT.txt\"))).toBe(true);\n\n\u002F\u002F 3. Verify journal\u002Fmanifest state\nconst manifest = JSON.parse(readFileSync(manifestPath, \"utf-8\"));\nexpect(manifest.nodes[\"task-id\"]).toBeDefined();\n```\n\n**Key conventions:**\n- Fixtures live under `tests\u002Ftest-\u003Cname>\u002F` with full `.converge\u002F` structure\n- Clean journal before each test (`beforeAll`), clean outputs after\n- Use `describe.skip` + binary check for tests requiring external CLIs (claude, codex)\n- `vitest.config.ts` has `fileParallelism: false` — tests run serially, safe to share fixture dirs\n- For compile-only tests, use the parameterized pattern from `tests\u002Fplaybook-compile.test.ts`\n- For DAG structure tests, use the pattern from `tests\u002Fplaybook-dag.test.ts`\n- For mode\u002Fstructure tests (no AI needed), use the pattern from `tests\u002Ftask\u002Fmode-*.test.ts` and `tests\u002Ftask\u002Frun-spawner.test.ts`\n\n### When to add tests\n\n- **Always** when fixing a bug that manifested in a specific fixture — add a regression test\n- **Always** when adding a new config schema field (`ai:`, new frontmatter key) — add a compile test\n- **Optionally** when the fix is a comment, error message, or logging change\n- **Never** skip adding a test for a bug that can reproduce deterministically\n\n## Hand-off\n\n| Situation | Hand off to |\n|---|---|\n| User wants to *run* a user playbook (not develop the framework) | **`converge-control`** |\n| User wants bounded autonomous framework improvement | run `self-improvement-loop` here, then use its artifacts as evidence |\n| User wants to design a new playbook | **`converge-planning`** |\n| Bug is in the user's example\u002Fplaybook (TASK.md typo, missing input, wrong path) | **the user** — surface it, don't patch the framework around bad user data |\n| Fix touches a hot path and needs full test coverage before merge | **the user** — flag the path, suggest `pnpm test` |\n\n## File map\n\n```\nSKILL.md                         (this file — entry point and dev loop)\nreference\u002F\n  framework-map.md               (subsystem → packages\u002F location → symptoms → reproducer)\n  observability.md               (what to read on disk during a run)\ntroubleshooting\u002F\n  playbook.md                    (symptom → root cause → fix recipes; grows over time)\n```\n\nLoad **one** file per gap. Return here between.\n","# Converge Development — observe-diagnose-fix the framework itself\n\n## Purpose\n\nUse a real example playbook as a test bed. Run it. Watch what the framework does internally — not just the stdout event stream, but the target directory, runstate, and per-attempt forensics the runner writes to disk. When the framework misbehaves (crashes, corrupts state, fails to retry, mishandles a provider response), trace the symptom to the package and module responsible, patch `packages\u002F**` source, rebuild, and re-run the example to verify.\n\nThis skill is **only** for changes to framework source under `packages\u002F` or for running framework-improvement playbooks that target `packages\u002F`. It is the framework-developer counterpart to `converge-control` (which babysits a *user's* playbook and treats the framework as a black box).\n\n## Two modes\n\n- **Interactive:** reproduce a named framework bug, patch `packages\u002F**`, rebuild, verify.\n- **Autonomous:** run `self-improvement-loop` for bounded framework hardening, then use its artifacts as the evidence trail.\n\n## When to invoke\n\nTrigger on user requests like:\n\n- \"Debug converge using \u003Cexample>\" \u002F \"Use this example to find bugs in the framework\"\n- \"Why does the DAG runner \u003Cdo X>?\" \u002F \"Why is the execution \u003Cdoing Y>?\"\n- \"Fix the framework — \u003Csymptom>\" \u002F \"There's a bug in the manifest\u002Fmode\u002Fdispatcher\u002FCLI\"\n- \"Improve \u003Csubsystem>\" \u002F \"Add a feature to the CLI\" \u002F \"Refactor a DAG action\"\n- \"Run the self-improvement loop\" \u002F \"Autonomously improve the framework\"\n- \"Profile \u002F instrument \u002F add logging to \u003Cmodule>\"\n\nDo **not** invoke for:\n\n- Running a *user's* playbook to completion → **`converge-control`**\n- Fixing a stuck user playbook (stale outputs, stall, foreign-playbook hijack) → **`converge-control`**\n- Designing a new playbook or setting up `.converge\u002F` from scratch → **`converge-planning`**\n\nIf the symptom is purely user-shape (the playbook author made a mistake), route to `converge-control`. If the symptom is framework-shape (the runner mishandles a *valid* user playbook), continue here.\n\n## Autonomous mode: self-improvement-loop\n\nRun bounded framework hardening with:\n\n```bash\nconverge run --playbook=self-improvement-loop --select improve+\n```\n\nUse only these surfaces unless debugging the playbook itself:\n\n- source: `.converge\u002Fplaybooks\u002Fself-improvement-loop\u002FREADME.md`, `tasks\u002Fimprove\u002FTASK.md`, `templates\u002Fepoch\u002FTASK.md`, `scripts\u002F*.mjs`;\n- evidence: `.converge\u002Fartifacts\u002Fself-improvement-loop\u002F{journal.md,metrics.jsonl,backlog.jsonl,touched-files.jsonl,convergence.md,epochs\u002F\u003CNNN>\u002F}`.\n\nKeep epochs maintainer-grade: clean non-artifact start, real observations before selection, one evidence-backed framework change, patch manifest from `git diff`, mapped regression commands, command-backed `verify\u002Fresult.json`, and stop rather than repeat low-value cleanup.\n\nIf the loop exposes a clear framework bug, use the interactive dev loop below for the patch and let the playbook verify the epoch.\n\n## The dev loop\n\nEight steps, in order. Stay in this loop until the example passes cleanly or you hit a structural decision that needs the user.\n\n### 1. Pick a test bed\n\nIf the user named a test fixture or example in the trigger phrase, use it. The smallest one that exercises the suspected subsystem is best — see the fixture→subsystem table at the bottom of `reference\u002Fframework-map.md`.\n\n**Test fixtures** (under `tests\u002F`) are the primary dev-loop test beds — they're small, fast, and have corresponding vitest runners. Prefer these for most framework debugging:\n\n| Subsystem | Fixture |\n|-----------|---------|\n| Navigator \u002F convergence | `tests\u002Ftest-simple-run` |\n| Compile \u002F discovery \u002F manifest | `tests\u002Ftest-compile-discover` |\n| Multi-provider \u002F agentfn routing | `tests\u002Ftest-mixed-model` |\n| `mode: spawner` \u002F dynamic spawn | `tests\u002Ftest-seeding`, `tests\u002Ftest-queue-pattern` |\n| Gap detection (input\u002Foutput) | `tests\u002Ftest-gap-blocked-input`, `tests\u002Ftest-gap-missing-output` |\n| Buggy-check relaxation | `tests\u002Ftest-buggy-check` |\n| Loop detection | `tests\u002Ftest-loop-detection` |\n| Multi-attempt convergence | `tests\u002Ftest-multi-attempt` |\n| Crash-safe resume | `tests\u002Ftest-resume` |\n\n**Full examples** (under `examples\u002F`) are heavier multi-phase projects. Use when debugging end-to-end behavior that doesn't surface in a single fixture.\n\n### 2. Build current state\n\n```bash\ncd \u003Crepo-root>\npnpm build\n```\n\nConfirm it exits clean. **If the build is already broken, that *is* the first bug** — skip to step 5 with the build error as the symptom.\n\nFor faster iteration when changes are scoped to one package:\n\n```bash\npnpm --filter @openplaybooks\u002Fconverge-core build && pnpm --filter @openplaybooks\u002Fconverge build\n```\n\n### 3. Run the test bed & monitor\n\nFrom the test fixture or example directory:\n\n```bash\ncd tests\u002F\u003Cfixture-name>\nnode \u003Crepo-root>\u002Fpackages\u002Fcli\u002Fdist\u002Findex.js playbook validate default\nnode \u003Crepo-root>\u002Fpackages\u002Fcli\u002Fdist\u002Findex.js run --playbook=default --dry\nnode \u003Crepo-root>\u002Fpackages\u002Fcli\u002Fdist\u002Findex.js run --playbook=default\n```\n\nIf the fixture uses a non-default playbook name, swap `default` for the actual name.\n\nCommon flags for debugging:\n\n| Flag | Use |\n|---|---|\n| `--force` | Force-run a task even if completed\u002Fcached |\n| `--select \u003Cexpr>` | Run only matching tasks (`--select '02-something+'` = task + descendants) |\n| `--dry` | Plan only — show what would execute without running |\n| `--verbose, -v` | Verbose output |\n\nArm a Monitor on the event stream:\n\n```bash\ntail -f .converge\u002Fjournal\u002F\u003Cplaybook>\u002Fevents.jsonl | grep -E '(NODE_START|NODE_COMPLETE|NODE_FAIL|CHECK_FAIL|ERROR)'\n```\n\nThen — and this is what makes this skill different from `converge-control` — also read the *internal* state:\n\n```bash\n# DAG state after run\ncat .converge\u002Fjournal\u002F\u003Cplaybook>\u002Frunstate.json\n\n# Per-task forensics\nls .converge\u002Fjournal\u002F\u003Cplaybook>\u002Ftasks\u002F\u003CtaskId>\u002F\ncat .converge\u002Fjournal\u002F\u003Cplaybook>\u002Ftasks\u002F\u003CtaskId>\u002FFEEDBACK.md\ncat .converge\u002Fjournal\u002F\u003Cplaybook>\u002Ftasks\u002F\u003CtaskId>\u002FLEARN.md\n```\n\nFull observability surface: **`reference\u002Fobservability.md`**.\n\n### 4. Classify the symptom\n\n| Symptom shape | Class | Action |\n|---|---|---|\n| Example completes cleanly, no anomalies | none | nothing to fix; ask the user what they wanted to investigate |\n| Stale paths, missing inputs from user playbook | user-shape | wrong skill; route to **`converge-control`** |\n| DAG runner crashes \u002F unhandled exception during execution | framework | continue to step 5 |\n| Runstate corruption (node status flip-flops, fingerprint mismatch cascade) | framework | continue to step 5 |\n| `mode: spawner` apply fails despite valid `converge spawn` calls (or, for legacy playbooks, a valid `spawn.plan.jsonl`) | framework | continue to step 5 |\n| agentfn provider throws on a valid response | framework | continue to step 5 |\n| Node retries without progress (same CHECK_FAIL across attempts) | framework | continue to step 5 |\n| Fingerprint caching broken (unchanged node re-executed unnecessarily) | framework | continue to step 5 |\n| CLI arg parsing \u002F exit code wrong | framework | continue to step 5 |\n\n### 5. Diagnose\n\nOpen **`reference\u002Fframework-map.md`**. Find the subsystem that owns the symptom. Read the source files listed there. Form a hypothesis.\n\nThen check **`troubleshooting\u002Fplaybook.md`** for a matching past entry. If found → apply the recipe.\n\nIf the diagnosis is straightforward and confined to one file, proceed. If it crosses package boundaries (e.g. `core\u002Fnavigator` ↔ an agentfn provider, or `core\u002Fjournal` ↔ `cli\u002Fcommands-clean`), **STOP and surface the hypothesis to the user before editing**. Same escalation pattern as `converge-control`.\n\n### 6. Edit + rebuild\n\nPatch `packages\u002F**`. Then rebuild — the CLI runs from `dist\u002F`, not source:\n\n```bash\n# whole monorepo (safe default)\npnpm build\n\n# or single package (faster when the change is scoped)\npnpm --filter @openplaybooks\u002F\u003Cpackage-name> build\n```\n\n### 7. Verify\n\nClear target state from the failing run (so you're testing the fix, not a stale runstate):\n\n```bash\n# Remove runtime state for a clean re-run\nrm -rf tests\u002F\u003Cfixture>\u002F.converge\u002Fjournal\nrm -rf tests\u002F\u003Cfixture>\u002F.converge\u002Finventory\n# Also clean output files the fixture may have produced\nrm -f tests\u002F\u003Cfixture>\u002F*.txt\n```\n\nOr use the CLI for targeted cleanup:\n\n```bash\nnode packages\u002Fcli\u002Fdist\u002Findex.js clean --select '*' --dir=tests\u002F\u003Cfixture>\n```\n\nRe-run from step 3. Confirm:\n\n- Original symptom is gone.\n- No new symptoms appeared.\n- Run reaches exit 0 clean.\n\n**Run the existing vitest suite** for the subsystem you touched:\n\n```bash\n# Run tests for the fixture you're using\nnpx vitest run tests\u002F\u003Cfixture-related>.test.ts\n\n# Or run all tests (slower, use for hot-path changes)\nnpx vitest run tests\u002F\n```\n\nIf no vitest runner exists for the fixture, create one (see `tests\u002Fcompile-discover.test.ts` for the pattern — compile + run + verify outputs).\n\nIf the symptom returns or a new one shows up → loop back to step 5.\n\n### 8. Record the recipe\n\nAppend a new entry to **`troubleshooting\u002Fplaybook.md`** in the format established there: **Symptom** \u002F **Root cause** \u002F **Fix** \u002F **Verification** \u002F **Files touched**. Skip if the fix was a one-off typo. The point is to grow institutional memory so the *next* invocation of this skill recognizes the symptom faster.\n\n## Hard rules — STOP and re-route\n\n- **Don't edit framework source without first reproducing the bug against an example.** No speculative fixes. The reproducible run is also the verification baseline for step 7.\n- **Don't skip `pnpm build` between source edit and re-run.** The CLI binary runs from `packages\u002Fcli\u002Fdist\u002Findex.js`, not source. Edits to `packages\u002F**\u002Fsrc\u002F*.ts` have zero effect until rebuilt.\n- **Don't clear state mid-debug with `converge clean --all`.** That wipes fingerprints and can mask caching bugs. Use `rm -rf .converge\u002Fjournal\u002F\u003Cplaybook> .converge\u002Finventory\u002F\u003Cplaybook>` to clear state for a clean re-run.\n- **Don't bundle unrelated improvements.** One bug, one patch (CLAUDE.md §3 — surgical changes). If you notice adjacent dead code or a refactor opportunity, mention it to the user; don't ship it in the diagnostic fix.\n- **Don't run `pnpm test` as a gate for every edit.** Too slow for the dev loop. But if your fix touches a hot path — `core\u002Fsrc\u002Fdag\u002F`, `core\u002Fsrc\u002Fmanifest\u002F`, `core\u002Fsrc\u002Fjournal\u002F` — flag that to the user and suggest *they* run `pnpm test` before commit.\n- **Don't leave `console.log` debugging in the source.** If you added logging to diagnose, remove it before declaring the fix done.\n- **Apply known recipes; ask before novel ones.** If `troubleshooting\u002Fplaybook.md` has a matching entry → apply and continue. If it doesn't, and the diagnosis crosses package boundaries → STOP, state hypothesis, wait for approval.\n- **Use current terminology.** Runtime state lives under `.converge\u002Fjournal\u002F\u003Cplaybook>\u002F`; the task inventory (spawned manifests + ledger) lives under `.converge\u002Finventory\u002F\u003Cplaybook>\u002F`. Use `runstate.json`, not `checkpoint.json`. Use `DAG node`, not `epic`. Use `fingerprint caching`, not `resume checkpoint`.\n\n## Testing\n\n### Running tests\n\n```bash\n# All root-level integration tests\nnpx vitest run tests\u002F\n\n# Single test file (fast feedback)\nnpx vitest run tests\u002Fplaybook-compile.test.ts\n\n# Watch mode (re-run on file changes)\nnpx vitest tests\u002Fplaybook-compile.test.ts\n\n# Per-package unit tests\npnpm --filter @openplaybooks\u002Fconverge-core test\npnpm --filter @openplaybooks\u002Fagentfn test\n\n# Full monorepo test suite\npnpm test\n```\n\n### Test file anatomy\n\nRoot-level tests live in `tests\u002F*.test.ts`. They follow a pattern:\n\n```ts\n\u002F\u002F 1. Spawn converge CLI with spawnSync\nconst CLI = resolve(__dirname, \"..\", \"packages\u002Fcli\u002Fdist\u002Findex.js\");\nconst result = spawnSync(\"node\", [CLI, \"run\", \"--dir=\u003Cdir>\"], {\n  cwd: REPO_ROOT, encoding: \"utf-8\",\n  stdio: [\"ignore\", \"pipe\", \"pipe\"],\n});\n\n\u002F\u002F 2. Verify outputs on disk\nexpect(existsSync(resolve(PROJECT_DIR, \"EXPECTED_OUTPUT.txt\"))).toBe(true);\n\n\u002F\u002F 3. Verify journal\u002Fmanifest state\nconst manifest = JSON.parse(readFileSync(manifestPath, \"utf-8\"));\nexpect(manifest.nodes[\"task-id\"]).toBeDefined();\n```\n\n**Key conventions:**\n- Fixtures live under `tests\u002Ftest-\u003Cname>\u002F` with full `.converge\u002F` structure\n- Clean journal before each test (`beforeAll`), clean outputs after\n- Use `describe.skip` + binary check for tests requiring external CLIs (claude, codex)\n- `vitest.config.ts` has `fileParallelism: false` — tests run serially, safe to share fixture dirs\n- For compile-only tests, use the parameterized pattern from `tests\u002Fplaybook-compile.test.ts`\n- For DAG structure tests, use the pattern from `tests\u002Fplaybook-dag.test.ts`\n- For mode\u002Fstructure tests (no AI needed), use the pattern from `tests\u002Ftask\u002Fmode-*.test.ts` and `tests\u002Ftask\u002Frun-spawner.test.ts`\n\n### When to add tests\n\n- **Always** when fixing a bug that manifested in a specific fixture — add a regression test\n- **Always** when adding a new config schema field (`ai:`, new frontmatter key) — add a compile test\n- **Optionally** when the fix is a comment, error message, or logging change\n- **Never** skip adding a test for a bug that can reproduce deterministically\n\n## Hand-off\n\n| Situation | Hand off to |\n|---|---|\n| User wants to *run* a user playbook (not develop the framework) | **`converge-control`** |\n| User wants bounded autonomous framework improvement | run `self-improvement-loop` here, then use its artifacts as evidence |\n| User wants to design a new playbook | **`converge-planning`** |\n| Bug is in the user's example\u002Fplaybook (TASK.md typo, missing input, wrong path) | **the user** — surface it, don't patch the framework around bad user data |\n| Fix touches a hot path and needs full test coverage before merge | **the user** — flag the path, suggest `pnpm test` |\n\n## File map\n\n```\nSKILL.md                         (this file — entry point and dev loop)\nreference\u002F\n  framework-map.md               (subsystem → packages\u002F location → symptoms → reproducer)\n  observability.md               (what to read on disk during a run)\ntroubleshooting\u002F\n  playbook.md                    (symptom → root cause → fix recipes; grows over time)\n```\n\nLoad **one** file per gap. Return here between.\n",{"name":5,"description":7},"main","7d618d8bc059f1a0974706d1d15ec25f73cf1e1d",".claude\u002Fskills\u002Fconverge-development",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-development",{"tool":67,"command":68},"bunx","bunx skills add openplaybooks-dev\u002Fconverge --skill converge-development",{"tool":70,"command":71},"pnpm","pnpm dlx skills add openplaybooks-dev\u002Fconverge --skill converge-development","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-development\u002FSKILL.md",true,[75,81,85,89],{"path":76,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":79,"sourceHtmlUrl":80},"reference\u002Fframework-map.md","REFERENCE","参考文档",19935,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-development\u002Freference\u002Fframework-map.md",{"path":82,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":83,"sourceHtmlUrl":84},"reference\u002Fglossary.md",554,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-development\u002Freference\u002Fglossary.md",{"path":86,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":87,"sourceHtmlUrl":88},"reference\u002Fobservability.md",7894,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-development\u002Freference\u002Fobservability.md",{"path":90,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":91,"sourceHtmlUrl":92},"troubleshooting\u002Fplaybook.md",6147,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-development\u002Ftroubleshooting\u002Fplaybook.md",[94,119,128,149,173,197],{"skillNo":95,"name":96,"nameZh":6,"description":97,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":103,"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",[100],{"categoryNo":101,"categoryName":102,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发",[104,105,106,107,108,109,110,111,112,113,114,115,40,116,117,118],"checker","hello checker","hello","it","use","content","validate","spec","verify","check","file","workflow","Meet","files","for",{"skillNo":120,"name":121,"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":122,"categories":123,"keywords":125,"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",[124],{"categoryNo":101,"categoryName":102,"taxonomyType":20,"taxonomyTypeDesc":21},[126,127],"ask skill","ask",{"skillNo":129,"name":130,"nameZh":6,"description":131,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":132,"categories":133,"keywords":138,"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",[134,137],{"categoryNo":135,"categoryName":136,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":101,"categoryName":102,"taxonomyType":20,"taxonomyTypeDesc":21},[139,140,141,142,143,118,31,144,145,146,147,148],"html","artifact","review","html review artifact","as","wide","guidance","markdown","human","artifacts",{"skillNo":150,"name":151,"nameZh":6,"description":152,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":153,"categories":154,"keywords":156,"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",[155],{"categoryNo":101,"categoryName":102,"taxonomyType":20,"taxonomyTypeDesc":21},[28,157,158,159,115,160,108,161,162,163,164,165,166,167,168,169,170,171,172,40],"converge planning","planning","structure","tasks","decompose","hand","write","plan","how","update","playbook","new","design","how to","end","project",{"skillNo":174,"name":175,"nameZh":6,"description":176,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":177,"categories":178,"keywords":181,"publishedAt":48},"01M7197XZT1T9GDYAJGVGX1J60","converge-control","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.","https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002Fskills\u002Fconverge-control\u002FSKILL.md",[179,180],{"categoryNo":101,"categoryName":102,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":23,"categoryName":24,"taxonomyType":25,"taxonomyTypeDesc":26},[182,183,28,184,185,186,187,188,189,190,162,191,192,169,170,193,171,194,195,196],"converge control","control","operate","invalid","show","api","me","work","reset","show me","cleanup","clean","inspect","select","retry",{"skillNo":198,"name":199,"nameZh":6,"description":200,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":201,"categories":202,"keywords":204,"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",[203],{"categoryNo":23,"categoryName":24,"taxonomyType":25,"taxonomyTypeDesc":26},[205,206,207,208,163,209,210,211,212,213,214,215,216,217,45,171,218,28,219,220],"repair taskts","repair","Bash","edit","read","line","at","spawn","code","analysis","number","errors","issues","chain","definition","never"]