@openplaybooks/converge 0.2.0

package/skills/converge-planning/references/phases.md

@@ -0,0 +1,168 @@
+# Phases Reference
+
+Step-by-step execution guide for converge-planning. Read during active planning when you need detailed instructions with commands.
+
+---
+
+## Process Overview
+
+```
+1. EXTRACT GOAL     → clear one-sentence deliverable goal
+2. GATHER REQS      → exhaustive list of must-haves, should-haves, constraints, non-goals
+3. DECOMPOSE        → sub-goal tree (recursive, until leaves are workable)
+4. CONTRACT         → write TASK.md + playbook.yml from the goal tree
+5. VALIDATE         → contract review + requirement coverage gate
+```
+
+These aren't separate phases producing separate files — they're the thinking steps you go through before writing contracts. The only files produced are the playbook structure.
+
+---
+
+## Step 1 — Extract Goal
+
+Reduce the user's request to one sentence: what complete, usable thing must exist when this is done?
+
+**Good:** "A deployed blog with post CRUD, comments, RSS feed, and responsive design."
+**Bad:** "A blog." (too vague)
+**Bad:** "Plan, design, implement, and test a blog." (process, not result)
+
+If the user hasn't stated a clear goal, ask. If the goal is too broad ("Build me a SaaS platform"), narrow it with follow-up questions before proceeding.
+
+---
+
+## Step 2 — Gather Requirements
+
+Extract every requirement from the user's prompt and from discovery questions. Capture them as specific, testable statements.
+
+**Discovery questions (ask if not already answered):**
+
+1. **Vision** — what is this project, what problem does it solve?
+2. **Core features** — top 3–5, ranked by priority.
+3. **User flows** — the main journey through the product.
+4. **Data & APIs** — entities, external services, integrations.
+5. **Constraints** — deadlines, tech stack, compliance, budget.
+6. **Non-goals** — what are we explicitly NOT building? (Prevents scope creep.)
+
+**Capture format:**
+
+```
+R1: [must] Authors can create, edit, publish, and delete posts
+R2: [must] Readers can submit comments on published posts
+R3: [must] RSS feed of latest published posts at /feed.xml
+R4: [should] Comments support threaded replies
+R5: [must] Posts support markdown with syntax highlighting
+R6: [constraint] Tech stack: Node.js + PostgreSQL + React
+R7: [non-goal] No user registration beyond author account
+```
+
+Tag each as `[must]`, `[should]`, `[constraint]`, or `[non-goal]`. Number them. This list is your requirement coverage checklist in later steps.
+
+**Surfacing goals from requirements:** When the work is large, replayable, or reactive — and the user describes a measurable end state — surface these as candidate **playbook goals**. Goals are different from sub-goal deliverables:
+- **Sub-goals** are things that must *exist* (a database, an API endpoint, a UI page)
+- **Goals** are conditions that must be *true* (all tests pass, type checking is clean, coverage reaches 90%)
+
+A requirement like "the codebase must have zero type errors" is a goal. It may require many sub-goal deliverables to achieve, but the goal itself is the completion condition. Goals become the `goals:` list in `playbook.yml` and drive a goal-driven epoch loop. See `references/patterns.md` § Goal-Driven Epoch Loop.
+
+**Existing codebase?** Run these before gathering requirements:
+
+```bash
+ls package.json pyproject.toml go.mod Cargo.toml 2>/dev/null     # runtime
+cat package.json 2>/dev/null | jq -r '.dependencies // {} | keys[]' | head -20    # framework
+find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | sort    # structure
+git log --oneline -10 2>/dev/null && git status --short 2>/dev/null    # state
+ls -la .converge/ 2>/dev/null    # existing converge
+```
+
+Capture tech stack, conventions, and existing state. These inform constraints but don't produce a separate deliverable file.
+
+---
+
+## Step 3 — Decompose into Sub-Goals
+
+Decompose the user's goal into deliverable sub-goals. Each sub-goal is a **complete, independently verifiable result**.
+
+### Decomposition rules
+
+- **3–7 children per level.** Less than 3 → no real decomposition. More than 7 → group into an intermediate level.
+- **Name by deliverable, not activity.** "Database schema" not "Design database." "Working API endpoints" not "Build API."
+- **Each child produces a complete thing.** Not a stage of producing a thing.
+- **Children form a complete cover.** Reading all children's deliverables together achieves the parent goal.
+
+### Recursive application
+
+For each sub-goal, ask: *can one agent produce this complete deliverable in one session?*
+
+- **Yes** → it's a leaf. Stop decomposing.
+- **No** → decompose further. Split by sub-feature, by entity, by endpoint — not by workflow stage.
+- **Same shape repeats N times** → use a runtime template plus `converge spawn` (see `references/static-dynamic.md`).
+
+### Requirement mapping
+
+Before proceeding, run the requirement coverage check:
+
+```
+R1 → Sub-goal A  ✓
+R2 → Sub-goal B  ✓
+R3 → Sub-goal C  ✓
+R4 → ???        ← GAP: add a sub-goal or expand existing scope
+```
+
+Every `[must]` requirement must map to at least one sub-goal. Unmapped requirements are gaps. Sub-goals with no mapped requirements are scope creep.
+
+### Pattern recognition (after decomposition)
+
+Once the goal tree exists, recognize its shape to sanity-check the design:
+
+- Linear dependencies between sub-goals → ordered stages
+- N identical sub-goals from a catalog → seed fan-out
+- Iterative improvement until quality threshold → epoch loop
+- N distinct domains with their own sub-trees → domain split
+
+The shape confirms the decomposition; it doesn't drive it. If the shape looks wrong, the decomposition might be wrong.
+
+---
+
+## Step 4 — Write Contracts
+
+Write contracts from the goal tree. Start at the root, one layer at a time.
+
+### For each leaf task
+
+Write `TASK.md` with:
+- **title + description:** What complete deliverable this produces
+- **inputs:** Files it reads (upstream outputs, project data)
+- **outputs:** Specific paths for its complete deliverable
+- **checks:** Deterministic verification commands (exit 0 = pass)
+- **depends_on:** Tasks that must complete first
+
+### For each container task
+
+Write `TASK.md` + `PLAN.md`. The TASK.md body describes:
+1. **Decomposition** — what sub-goals exist and why
+2. **Convergence** — how to integrate children's deliverables, what cross-child validation to run, what the converged output is
+
+### Playbook-level
+
+Write `playbook.yml` referencing top-level tasks with `depends_on` edges. Add playbook-level checks (e.g., `npx tsc --noEmit`, `npm test`).
+
+Write the root `PLAN.md` capturing:
+- **Goal:** The user's one-sentence goal
+- **Decision:** Why this decomposition
+- **Children:** Each top-level sub-goal with id, kind, objective, inputs, dependencies, outputs, checks
+- **Requirements:** The full numbered list with sub-goal mappings
+- **Open questions:** Things unknown at plan time
+
+---
+
+## Step 5 — Validate
+
+Run contract review on every TASK.md. See SKILL.md §7 for the full checklist.
+
+Key gates:
+- Every output has a deterministic check
+- Every input traces to an upstream output
+- Every requirement maps to ≥1 task
+- No middle work — every leaf produces a complete, usable deliverable
+- No verb-named siblings
+
+When validation passes, the plan is ready for `converge run`.

package/skills/converge-planning/references/schema.md

@@ -0,0 +1,313 @@
+# Schema Reference
+
+Format reference for converge planning artifacts. Read when you need to write or validate TASK.md frontmatter, playbook.yml, checks, container behavior, and spawn templates.
+
+For the contract model that explains *why* these fields exist, see `../SKILL.md` or `model.md`.
+
+---
+
+## `playbook.yml`
+
+Playbook manifest. Defines the top-level task list, dependencies, run config, and playbook-level checks.
+
+**Location:** `.converge/playbooks/{name}/playbook.yml`
+
+```yaml
+name: default
+description: End-to-end app generation
+run:
+  mode: autonomous
+  maxIterations: 50
+  maxTaskAttempts: 3
+tasks:
+  - path: prepare
+  - path: design-system
+  - path: build-screens
+checks:
+  - id: type-check
+    cmd: npx tsc --noEmit
+```
+
+---
+
+## `TASK.md`
+
+The delegation contract. One per task directory. **Same schema at every nesting level** — top-level tasks and deeply nested children use identical TASK.md format.
+
+**Location:** `.converge/playbooks/{name}/tasks/{path-to-task}/TASK.md`
+
+```yaml
+---
+id: task-name
+title: Human-Readable Title
+description: What this task accomplishes in one sentence
+depends_on:
+  - upstream-task-id
+  - prepare.catalog              # Cross-branch dotted path
+inputs:
+  - path/to/input.md
+outputs:
+  - path/to/output.md
+skills:
+  - skill-name
+checks:
+  - id: check-id
+    cmd: shell-command-returns-0
+    description: What this validates
+---
+
+# Task Title
+
+[Concrete, step-by-step instructions for the executor]
+```
+
+### Three practical TASK.md roles
+
+- **Leaf task** — produces outputs directly.
+- **Static container** — owns child tasks under `tasks/` and converges their results.
+- **Dynamic container** — marked `passthrough: true`; its body orchestrates work, emits `converge spawn ...`, and relies on a `converge` post-check contract to decide whether to continue.
+
+### Frontmatter fields
+
+| Field | Required | Contract role | Type | Description |
+|-------|----------|---------------|------|-------------|
+| `id` | Yes | identity | string | Unique kebab-case slug (`prepare`, `build-screens`). No numeric prefix. |
+| `title` | Yes | scope | string | Human-readable title |
+| `description` | Recommended | scope | string | One-line purpose |
+| `inputs` | If reads | **Context In** | string[] | Files this task reads (must be upstream outputs) |
+| `outputs` | Yes | **Context Out** | string[] | Files this task produces |
+| `checks` | Yes | acceptance | Check[] | Deterministic validation commands |
+| `depends_on` | If needed | deps | string[] | Sibling/cross-branch task IDs that must complete first |
+| `skills` | If using | resources | string[] | Converge skills to invoke |
+| `references` | Optional | resources | string[] | Skill libraries to reference |
+| `vars` | Optional | resources | object | Template variables passed to seed/children |
+| `passthrough` | Dynamic/container tasks | execution | boolean | Run shell body directly; common for orchestration parents that emit `converge spawn ...` |
+| `converge` | Looping/container tasks | convergence | string/object | Post-body verdict prompt that decides continue vs halt |
+| `tags` | Optional | metadata | string[] | Categorization labels |
+| `blocking` | Optional | scheduling | boolean | If true, blocks all downstream until done |
+| `executor` | Optional | execution | object | Execution method override |
+| `allowed-tools` | Optional | sandbox | string[] | Restrict available tools |
+
+A leaky contract is one where any field above is missing, vague, or over-broad.
+
+### Recommended dynamic-container shape
+
+Use this when a parent task needs to adapt at runtime:
+
+```yaml
+---
+id: build
+title: Build
+passthrough: true
+checks:
+  - id: finished
+    cmd: test -f output/done.flag
+converge: |
+  Decide whether this task should continue or halt.
+---
+```
+
+Then in the body:
+
+- write evidence files
+- emit `converge spawn <id> <template> --var ...` commands as needed
+- use idempotency markers so repeat body runs do not duplicate-spawn
+- call `converge tasks mark <id> --status done` when the stop condition is reached
+
+---
+
+## Dependency formats
+
+```yaml
+# Sibling (same level)
+depends_on:
+  - upstream-task
+
+# Cross-branch (dotted path from playbook root)
+depends_on:
+  - prepare.catalog
+
+# Tag-based (any task with this tag)
+depends_on:
+  - tag:setup
+
+# Mixed
+depends_on:
+  - setup
+  - prepare.catalog
+  - tag:foundation
+```
+
+**Rules:**
+- No cycles. If you find one, split the task.
+- Minimize: depend only on what you actually consume.
+- Dependencies are declared in `TASK.md` `depends_on` — each task owns its own edges.
+- playbook.yml lists task paths only (no dependency wiring).
+
+---
+
+## Check schema
+
+```yaml
+checks:
+  - id: string         # Unique kebab-case identifier
+    cmd: string        # Shell command (exit 0 = pass, non-zero = fail)
+    description: string # Human-readable description
+```
+
+### Common patterns
+
+```yaml
+# File exists
+- id: exists
+  cmd: test -f output.md
+  description: Output file exists
+  tags: [fast]
+
+# Non-empty
+- id: nonempty
+  cmd: test -s output.md
+  description: Output file is not empty
+  tags: [fast]
+
+# Valid JSON
+- id: valid-json
+  cmd: jq empty data.json
+  description: Valid JSON format
+  tags: [fast]
+
+# JSON Schema validation
+- id: valid-schema
+  cmd: jq -e '.items | type == "array" and length >= 3' data.json
+  description: Items array has at least 3 entries
+  tags: [fast]
+
+# Valid YAML
+- id: valid-yaml
+  cmd: python3 -c "import yaml; yaml.safe_load(open('config.yaml'))"
+  description: Valid YAML format
+  tags: [fast]
+
+# Has required section
+- id: has-overview
+  cmd: grep -q "## Overview" output.md
+  description: Has Overview section
+  tags: [fast]
+
+# TypeScript compiles
+- id: compiles
+  cmd: npx tsc --noEmit
+  description: TypeScript compiles
+  tags: [slow, build]
+
+# Tests pass
+- id: tests-pass
+  cmd: npm test -- --passWithNoTests
+  description: All tests passing
+  tags: [slow, build]
+
+# File count
+- id: screens-generated
+  cmd: test $(ls screens/*.html 2>/dev/null | wc -l) -ge 3
+  description: At least 3 screens generated
+  tags: [fast]
+
+# Cross-reference: every catalog entry has a corresponding output
+- id: all-catalog-entries-built
+  cmd: |
+    count=$(jq '.items | length' tokens-catalog.json)
+    built=$(ls tokens/*.json 2>/dev/null | wc -l)
+    test "$built" -eq "$count"
+  description: One output file per catalog entry
+  tags: [slow]
+
+# Cross-task consistency: every screen in catalog has a source file
+- id: screens-consistent
+  cmd: |
+    jq -r '.screens[].id' screens.json | while read id; do
+      test -f "lib/screens/$id.html" || exit 1
+    done
+  description: Every screen in catalog has a generated file
+  tags: [slow]
+
+# No broken references
+- id: no-broken-refs
+  cmd: |
+    ! grep -r "\[\[missing" output/ 2>/dev/null
+  description: No unresolved [[wikilinks]] in output
+  tags: [fast]
+```
+
+**Rules:**
+- Every output gets at least one check (existence + non-empty minimum).
+- Code outputs add a compilation check. Data outputs add format validation.
+- Container tasks add cross-child consistency checks (count match, every-catalog-entry).
+- Playbook-level checks validate cross-task invariants.
+- Tag checks by cost: `fast` for file/grep checks, `slow` for compilation/test suites.
+- Never use exact string matching — too brittle.
+
+---
+
+## Dynamic work shapes
+
+Current Converge uses one primary dynamic-work mechanism in source playbooks:
+
+**Runtime spawn templates** in `templates/<name>/TASK.md`
+
+Use them with `converge spawn <id> <template>` from a passthrough task body when the task needs to materialize children at runtime.
+
+---
+
+## Spawn-template pattern
+
+Use runtime templates when the same child shape repeats:
+
+```bash
+converge spawn sprint-3 sprint --var wave=3 --var sprint_id=sprint-3
+```
+
+The template resolves to:
+
+```text
+.converge/playbooks/<name>/templates/sprint/TASK.md
+```
+
+Recommended usage:
+
+- keep repeated child shapes in `templates/`
+- pass runtime data with `--var`
+- use idempotency markers in the parent body so repeated runs do not duplicate-spawn
+- pair spawn with checks plus a `converge` verdict that decides whether to continue
+
+---
+
+## Directory naming
+
+Static tasks live under `.converge/playbooks/{name}/tasks/`. Runtime-spawn templates live under `.converge/playbooks/{name}/templates/`.
+
+```
+tasks/{id}/TASK.md       → static task contract (executable or container)
+tasks/{id}/PLAN.md       → container blueprint
+templates/{name}/TASK.md → runtime spawn template
+```
+
+- IDs are plain kebab-case slugs (`prepare`, `build-screens`, `per-character`).
+- **Static children** under a parent's `tasks/` subdirectory MUST use `\d{2,3}-` prefixes (e.g., `01-prepare`, `02-build-screens`). This is required by `discoverStaticChildren` which matches `^\d{2,3}-` to discover child TASK.md files. The numeric prefix controls execution order within the parent.
+- **Top-level tasks** and **templates** use kebab-case without numeric prefixes — order comes from `depends_on` edges in `playbook.yml`.
+- `tasks/` and `templates/` are siblings at the playbook root.
+- Spawned children are materialized by the runtime, not written during init.
+
+```
+playbooks/default/
+├── playbook.yml
+├── PLAN.md
+├── tasks/
+│   └── build/
+│       ├── TASK.md
+│       └── PLAN.md
+└── templates/
+    ├── sprint/
+    │   └── TASK.md
+    └── phase/
+        └── TASK.md
+```

package/skills/converge-planning/references/static-dynamic.md

@@ -0,0 +1,38 @@
+# Static vs. Dynamic Subtask Reference
+
+Decision guide for static vs. dynamic subtask decomposition. Read when planning a container and deciding whether to hand-write children or use runtime spawn templates.
+
+---
+
+## Static vs. Dynamic Subtasks
+
+**The core decomposition choice: when you split a task into subtasks, each subtask is either static or dynamic.**
+
+| Subtask type | How it's created | When it's knowable | Use when |
+|---|---|---|---|
+| **Static** | Hand-written `TASK.md` file | Compile time (*concrete*) | Fixed set, known at plan time, ≤ ~7 children |
+| **Dynamic** | parent body spawns it from a template at runtime | After the parent runs (*expected* or *adaptive*) | Data-driven list, unknown at plan time, N > 7, or N may grow |
+
+**Static subtasks** are the default. Write each child's `TASK.md` by hand. The DAG is fully concrete at compile time — every node exists on disk, every edge is declared.
+
+**Dynamic subtasks** use runtime templates. The parent task body emits `converge spawn <id> <template>` for each child. Two sub-cases:
+
+- **Expected** — an upstream "catalog" task produces a structured file (e.g., `tokens-catalog.json`) listing what entities exist. The parent reads it and spawns children from it. Children's IDs and count are predictable from the catalog.
+- **Adaptive** — no catalog exists. The parent decides what to spawn at runtime. Children are unknowable until the parent runs.
+
+**The catalog pattern** (prefer `expected` over `frontier`):
+
+```
+upstream catalog task          →  downstream dynamic container
+writes tokens-catalog.json     →  reads it, spawns per-token children
+(concrete)                     →  (children are expected)
+```
+
+One extra task makes the rest of the DAG queryable. See `examples/game-assets-video` for the worked example.
+
+**Decision heuristic:**
+- ≤ 7 items, known at plan time → **static subtasks** (hand-write each `TASK.md`)
+- > 7 items, or the list comes from data → **catalog task + dynamic container** (dynamic, expected)
+- The list requires runtime reasoning to determine → **dynamic container** (adaptive)
+
+**Mixed containers:** a container can have both static and dynamic children. A `03-build-screens` phase might have one static `001-design-system` task plus a body that spawns per-screen children. Both coexist in the same DAG.

package/skills/converge-planning/references/tests.md

@@ -0,0 +1,91 @@
+# Checks Reference
+
+Full check reference for converge-planning. Read when you need to design deterministic checks for tasks, wire reusable helpers through `scripts/`, or plan convergence loops that rely on post-check evidence.
+
+---
+
+## Checks are part of the contract
+
+Write checks during planning, not after. For every task contract, add checks that validate:
+- the output exists
+- the output is well-formed
+- the output satisfies the actual task contract
+
+Examples:
+
+```yaml
+checks:
+  - id: file-exists
+    cmd: test -f output.md
+  - id: schema-valid
+    cmd: jq empty data.json
+  - id: section-present
+    cmd: grep -q "## Required Section" output.md
+```
+
+Use checks at every level:
+- Leaf task: its own outputs exist and are valid.
+- Container task: child outputs are complete and internally consistent.
+- Playbook: cross-task invariants still hold.
+
+---
+
+## Reusable helpers live in `scripts/`
+
+There is no `.test.md` registry and no `checks/` folder. If a check needs shared logic, put the helper under the playbook's `scripts/` tree and call it directly from `cmd`.
+
+```text
+playbooks/default/
+  scripts/
+    file-exists.sh
+    backend-configured.js
+```
+
+```yaml
+checks:
+  - id: idea-exists
+    cmd: bash scripts/file-exists.sh idea.md
+  - id: backend-configured
+    cmd: node scripts/backend-configured.js image-generate
+```
+
+Rules:
+- The command is the API. Keep it explicit.
+- If a command references `scripts/...`, that file must actually exist.
+- Do not rely on named test registries, `type: test`, or auto-discovered helper folders.
+
+When to extract a helper into `scripts/`:
+- the same command logic appears in multiple tasks
+- the check needs real control flow or parsing
+- the check needs a stable interface that several tasks can call
+
+When not to extract:
+- one-off shell checks
+- tiny checks that stay readable inline
+
+---
+
+## Dynamic containers and post-check loops
+
+For dynamic or adaptive parents, the checks should describe the real stop condition. The body does work and spawns children; the `converge` prompt decides whether another wave is needed after the checks run.
+
+Typical shape:
+
+```yaml
+id: improve
+passthrough: true
+checks:
+  - id: backlog-empty
+    cmd: test ! -s artifacts/backlog.txt
+  - id: report-valid
+    cmd: node scripts/verify-report.js artifacts/report.json
+converge: |
+  Review the current evidence and decide whether to continue or halt.
+```
+
+The important split:
+- body: gather evidence, write state, `converge spawn ...`
+- checks: verify the current state
+- `converge`: decide continue vs halt based on the checked evidence
+
+That is the current self-correcting loop model.