@openplaybooks/converge 0.2.0

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@openplaybooks/converge",
+  "version": "0.2.0",
+  "private": false,
+  "type": "module",
+  "description": "CLI for Converge - A build system for AI agents",
+  "license": "MIT",
+  "author": "Converge Framework Contributors",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openplaybooks-dev/converge.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "cli",
+    "converge",
+    "ai-agent",
+    "automation",
+    "orchestration"
+  ],
+  "bin": {
+    "converge": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.0",
+    "@clack/prompts": "^0.9.1",
+    "glob": "^11.1.0",
+    "yaml": "^2.8.3",
+    "@openplaybooks/agentfn": "0.2.0",
+    "@openplaybooks/converge-core": "0.2.0",
+    "@openplaybooks/deepcodefn": "0.1.0",
+    "@openplaybooks/claudefn": "0.1.0",
+    "@openplaybooks/openfn": "^0.1.0",
+    "@openplaybooks/codexfn": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "converge": "tsx src/main.ts"
+  }
+}

package/skills/converge-control/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: converge-control
+description: Use when the user wants to run a converge playbook, monitor execution, inspect status, diagnose failures, or re-run after changes. Triggers on "run my playbook", "monitor this run", "converge failed", "what's the status", "retry failures", or "babysit this playbook".
+---
+
+# Converge Control
+
+## Purpose
+
+Run, monitor, and unblock a playbook using the **current** Converge runtime surface.
+
+This skill is for:
+
+- starting a playbook run
+- watching progress
+- narrowing failures to one task / subtree
+- using the built-in operator commands (`status`, `list`, `show`, `doctor`, `playbook validate`)
+- re-running only what needs to move
+
+This skill is **not** for authoring a new playbook or redesigning its task tree. That belongs to **`converge-planning`**.
+
+## Current mental model
+
+Converge has three important layers:
+
+1. **Source blueprint** — `.converge/playbooks/<name>/`
+   Files like `playbook.yml`, `TASK.md`, `seed` scripts, templates, playbook-scoped skills.
+2. **Runtime state** — `.converge/journal/<playbook>/`, `.converge/inventory/<playbook>/`, `.converge/artifacts/<playbook>/`
+   Execution state, event stream, per-task forensics, spawned-task ledger, and produced outputs.
+3. **Operator surface** — the CLI
+   `run`, `status`, `list`, `show`, `inspect`, `doctor`, `playbook validate`, `clean`, `stop`.
+
+The playbook is the source of truth. Do **not** hand-edit `runstate.json`, `manifest.json`, or journal files to "fix" a run.
+
+## Primary workflow
+
+Use this loop unless a narrower recipe in `troubleshooting/playbook.md` fits exactly.
+
+### 1. Preflight the playbook
+
+Validate the definition before running:
+
+```bash
+converge playbook validate <name>
+```
+
+If the user is editing tasks live and wants a pure preview of what would execute:
+
+```bash
+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
+
+```bash
+converge run --playbook=<name>
+```
+
+Common narrowed runs:
+
+```bash
+# 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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+# 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
+
+```bash
+converge stop --playbook=<name>
+```
+
+Then restart with a narrowed selection if possible.
+
+## Preferred command set
+
+Use these first. They reflect the actual CLI surface and current docs.
+
+```bash
+# 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>+'
+
+# Stop a live / stale run
+converge stop --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.**
+
+## 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.

package/skills/converge-control/reference/cli.md

@@ -0,0 +1,128 @@
+# Converge CLI — operator cheatsheet
+
+The commands you actually use while running and babysitting a playbook.
+
+For the canonical contract, prefer:
+
+```bash
+converge <command> --help
+```
+
+## Recommended invocation style
+
+Prefer explicit playbook scoping:
+
+```bash
+converge run --playbook=<name>
+converge status --playbook=<name>
+converge list --playbook=<name>
+```
+
+Path-based invocation also exists, but `--playbook=<name>` is the clearer operator shape for the current docs and README.
+
+## Run / preview
+
+```bash
+# Full run
+converge run --playbook=<name>
+
+# Preview only
+converge run --playbook=<name> --dry
+
+# Changed work + downstream
+converge run --playbook=<name> --select 'state:modified+'
+
+# Retry failures
+converge run --playbook=<name> --select 'result:error+'
+
+# One subtree
+converge run --playbook=<name> --select '03-build+'
+
+# Fail fast while debugging
+converge run --playbook=<name> --select '03-build+' --fail-fast
+```
+
+## Status / visualization
+
+```bash
+# Current task tree
+converge status --playbook=<name>
+
+# Incomplete tasks only
+converge list --playbook=<name> --exclude 'status:complete'
+
+# DAG graph
+converge show graph --playbook=<name> --detail
+
+# Timeline
+converge show gantt --playbook=<name>
+
+# Cost / model view
+converge show metrics --playbook=<name> --by-model --top=5
+```
+
+## Forensics / health
+
+```bash
+# One failed task
+converge inspect --playbook=<name> --task=<taskId>
+
+# Runtime health
+converge doctor --playbook=<name>
+
+# Definition health
+converge playbook validate <name>
+```
+
+## Reset / stop
+
+```bash
+# Reset one subtree
+converge clean --playbook=<name> --select '<taskId>+'
+
+# Stop live or stale run
+converge stop --playbook=<name>
+```
+
+## Selection patterns
+
+```bash
+# One task
+--select '03-build'
+
+# One task + descendants
+--select '03-build+'
+
+# Ancestors + node
+--select '+03-build'
+
+# Full lineage
+--select '+03-build+'
+
+# Errors and downstream
+--select 'result:error+'
+
+# Changed and downstream
+--select 'state:modified+'
+
+# Subtract completed work
+--exclude 'status:complete'
+```
+
+## Compatibility commands
+
+These commands still exist but are not the primary operator teaching surface:
+
+```bash
+converge compile ...
+converge build ...
+converge retry ...
+converge test ...
+```
+
+Map them mentally to:
+
+- `compile` → low-level preview / compatibility
+- `build` → `run --fail-fast`
+- `retry` → `run --resume`
+- `test` → checks-only execution

package/skills/converge-control/reference/events.md

@@ -0,0 +1,165 @@
+# Converge run output — event catalog
+
+Every distinct event that appears in the `events.jsonl` stream, what it means, what to do.
+
+Use this when:
+
+- Composing the Monitor `grep -E` filter
+- Classifying an event during a run
+- Debugging "what was happening when the run stopped?"
+
+## How to read this file
+
+Each entry is:
+
+```
+  <event token (from events.jsonl)>
+  <one-line meaning>
+  → <action>
+```
+
+Events are newline-delimited JSON objects in `.converge/journal/<playbook>/events.jsonl`. Each object has a `type` field.
+
+## Recommended Monitor filter
+
+```bash
+tail -f .converge/journal/<playbook>/events.jsonl | grep -E '(NODE_START|NODE_COMPLETE|NODE_FAIL|CHECK_FAIL|DAG_LAYER|CYCLE|ERROR)'
+```
+
+This catches all structural signals. Drop `NODE_START` and `DAG_LAYER` for a quieter feed:
+
+```bash
+tail -f .converge/journal/<playbook>/events.jsonl | grep -E '(NODE_COMPLETE|NODE_FAIL|CHECK_FAIL|CYCLE|ERROR)'
+```
+
+---
+
+## Progress signals — keep watching
+
+```
+NODE_START <nodeId>
+```
+A node began execution. Forward progress.
+→ continue.
+
+```
+NODE_COMPLETE <nodeId> cached
+```
+Node's fingerprint matched the previous runstate. Skipped execution — outputs from the prior run are reused.
+→ continue. This is the common case for incremental runs.
+
+```
+NODE_COMPLETE <nodeId> fresh
+```
+Node executed and all checks passed. Outputs written and verified.
+→ continue.
+
+```
+DAG_LAYER 3/7
+```
+Executing topological layer 3 of 7. Nodes within a layer are independent and may run in parallel.
+→ continue. Progress signal.
+
+```
+CHECK_PASS <nodeId> <checkId>
+```
+A single check passed. Useful when watching a specific node's checks.
+→ continue.
+
+---
+
+## Node lifecycle — normal
+
+```
+SEED_SPAWN <parentId> → [<childId>, ...]
+```
+A seed function spawned child nodes into the DAG.
+→ continue. New nodes will appear in subsequent DAG_LAYER events.
+
+```
+ATTEMPT <nodeId> 2/3
+```
+Second attempt on this node. The AI agent read FEEDBACK.md and LEARN.md from attempt 1 and is retrying.
+→ continue unless attempt 3 arrives with the same failures.
+
+---
+
+## Structural failures — diagnose now
+
+```
+CHECK_FAIL <nodeId> <checkId>
+```
+A check failed on this attempt. The node may still converge on retry.
+→ if followed by NODE_COMPLETE on retry, it self-recovered. If repeated across all attempts for the same node, diagnose.
+
+```
+NODE_FAIL <nodeId> <reason>
+```
+Node failed all attempts. The runner will not retry. Downstream nodes are blocked.
+→ stop. Read `.converge/journal/<playbook>/tasks/<nodeId>/FEEDBACK.md` and `LEARN.md`. Apply a fix from `troubleshooting/playbook.md` or surface to the user.
+
+```
+CYCLE_DETECTED [id1 → id2 → id3 → id1]
+```
+A dependency cycle was found during compilation. The DAG is invalid.
+→ trace the `depends_on` edges between the listed nodes. Remove the edge that creates the cycle. Re-compile.
+
+```
+FRONTIER_UNRESOLVED <nodeId>
+```
+A seed parent was expected to spawn children (declared via `from_seed` with a catalog upstream) but produced no children. The catalog may be empty or the seed script errored.
+→ check the upstream catalog file. Check the seed script for errors. Re-compile with `--seed`.
+
+```
+INPUT_MISSING <nodeId> <path>
+```
+A node's declared `inputs:` file doesn't exist on disk. The upstream producer may have failed or the path is wrong.
+→ check whether the upstream node completed successfully. If the path is stale, fix the TASK.md `inputs:` and re-compile.
+
+---
+
+## Transients — runner handles, do nothing
+
+```
+ERROR <provider>: API Error: 529 Overloaded
+ERROR <provider>: network timeout
+```
+Provider overload or transient network issue. Runner retries automatically.
+→ continue. Don't kill the run.
+
+## Run-level events
+
+```
+RUN_START <playbook> <manifestHash>
+```
+Run began. The manifest hash identifies which compiled DAG is being executed.
+→ continue.
+
+```
+RUN_COMPLETE <playbook>
+```
+All nodes completed. Run succeeded.
+→ verify final state with `converge list --playbook=<name>`.
+
+```
+RUN_CANCELLED <playbook>
+```
+Run was interrupted (SIGTERM, process kill). `runstate.json` was saved — resuming is automatic.
+→ re-launch with the same command. Completed nodes are cached.
+
+---
+
+## Quick action lookup
+
+| You see... | You do... |
+|---|---|
+| `NODE_COMPLETE cached` | Nothing — it's a cache hit |
+| `NODE_FAIL <id>` | Read FEEDBACK.md / LEARN.md, diagnose |
+| `CYCLE_DETECTED` | Fix `depends_on` edges, re-compile |
+| `FRONTIER_UNRESOLVED` | Check upstream catalog, check seed script |
+| `INPUT_MISSING` | Check upstream node status, fix path |
+| `CHECK_FAIL` once then `NODE_COMPLETE` on retry | Self-recovered — continue |
+| `CHECK_FAIL` repeating across all attempts | Diagnose — load `troubleshooting/playbook.md` |
+| `ERROR <provider>: API Error: 529` | Nothing — runner retries |
+| Run process exits 0 | Verify with `converge list` |
+| Run process exits non-zero | Tail last 30 events, find the NODE_FAIL |