smol-symphony 0.2.0 → 0.3.0

package/README.md

@@ -19,9 +19,9 @@ workspace for review.
 ┌──────────────────────────────────────────────────────────────────────────┐
 │  symphony (node host)                                                    │
 │                                                                          │
-│    ./issues/<state>/*.md  ──┐                                            │
-│    ./WORKFLOW.md            ├──▶  orchestrator  ──▶  agent runner        │
-│    ./WORKFLOW.template.md ──┘     poll · reconcile · dispatch            │
+│    ./issues/<state>/*.md     ──┐                                         │
+│    ./WORKFLOW.yaml             ├──▶  orchestrator  ──▶  agent runner     │
+│    ./WORKFLOW.template.yaml  ──┘     poll · reconcile · dispatch         │
 │                                                          │               │
 │                                                          ▼  ACP/RPC      │
 │                                       ┌───────────────────────────────┐  │
@@ -45,46 +45,96 @@ original architectural narrative, see
 
 ## Quick start
 
-Prerequisites:
-
-- Node.js ≥ 20.
-- The agent rootfs image. Gondolin is the in-process microVM substrate
-  (`@earendil-works/gondolin`), so there is no separate VM daemon to run. The
-  agent image is built **once** from `images/agents/` via `npm run build:image`:
-  it starts from `node:24-bookworm-slim`, installs base CLI tooling, npm-installs
-  every ACP-capable coding agent (`claude-agent-acp`, `codex-acp`, `opencode`),
-  and bakes the in-VM stdio launcher at `/opt/symphony/vm-agent.mjs` into the
-  image. The build prints a content-addressed build id; pin it (or a
-  `name:tag` ref like `symphony-agents:latest`) in `WORKFLOW.md`'s
-  `gondolin.image`. See [images/agents/README.md](./images/agents/README.md)
-  for the build steps and requirements.
-- For the default `acp.adapter: claude`: a credentials file at
-  `~/.claude/.credentials.json` on the host. Symphony reads it only on the
-  host side: the guest holds only a token-shaped placeholder, and the host
-  substitutes the real OAuth access token into the outbound request at
-  Gondolin egress (TLS-MITM). The credential file itself is never staged into
-  the VM.
-
-Run, against an existing workflow file in the current directory:
+The golden path from zero to your first dispatched issue. The details behind
+each step live in [Prerequisites in detail](#prerequisites-in-detail) below — you
+should not need them to get here.
 
 ```bash
-npx smol-symphony WORKFLOW.md
+# 1. Build the agent rootfs image once. This ships only `mise` (jdx/mise) — node +
+#    the coding-agent CLIs are mise-installed at dispatch, the launcher is injected —
+#    and tags the result `symphony-agents:latest` — the tag the scaffolded
+#    WORKFLOW.yaml pins, so a first run needs no edit.
+git clone https://github.com/dizk/smol-symphony.git
+cd smol-symphony && npm install && npm run build:image
+
+# 2. In your project, scaffold the minimal WORKFLOW.yaml. With no workflow file
+#    present, symphony offers to write a ~30-line starter (every key required,
+#    no power features), then exits so you can glance at it.
+cd /path/to/your/project
+npx smol-symphony WORKFLOW.yaml
+
+# 3. Verify the whole setup in one pass before the first dispatch. `symphony
+#    doctor` runs every adoption-prerequisite probe — Node version, the
+#    `gondolin.image` pin, each configured adapter's host credential, a
+#    writable `tracker.root`, and a bindable dashboard port — and prints a
+#    PASS/FAIL line per check with a one-line fix for each failure, exiting 0
+#    iff every check passes. Unlike startup (which bails on the first failure),
+#    it runs all probes so you see the whole picture at once.
+npx smol-symphony doctor WORKFLOW.yaml
+
+# 4. Drop one issue into the tracker.
+mkdir -p issues/Todo
+printf -- '---\ntitle: "Say hi"\n---\nAdd a hi() that returns "hi".\n' > issues/Todo/1.md
+
+# 5. Run symphony and watch it dispatch.
+npx smol-symphony WORKFLOW.yaml --port 8787
+# Open http://127.0.0.1:8787/ — issue 1 moves from "on disk" into a running
+# session as symphony boots a per-issue microVM and dispatches the agent.
 ```
 
-(Or `npm i -g smol-symphony` and then `symphony WORKFLOW.md` to skip the
-fetch.) Both invoke the `symphony` bin shipped in this package.
-
-Open the dashboard at `http://127.0.0.1:8787/`. Drop issues into
-`issues/Todo/` from the filesystem or the dashboard's `new issue` form;
-symphony dispatches them on the next poll.
-
-The console stays quiet: with the default log file configured, symphony prints
-a one-line-per-field startup banner (workflow, tracker root, dashboard URL,
-log-file path) and routes the structured `key=value` stream to
-`.symphony/logs/symphony.log` only. `tail -f` that file to follow the detail.
-Pass `--verbose` (alias `--foreground`) to mirror the structured stream back to
-the console for interactive debugging. With no log file configured (the
-`SYMPHONY_LOG_FILE=""` override), the structured stream stays on stderr.
+The same first-run scaffold also installs an issue-filing skill at
+`.claude/skills/symphony-issues/SKILL.md` (best-effort — it never blocks the
+workflow scaffold), so a coding agent in the freshly-onboarded repo can file
+well-formed tracker issues and decompose a large task into a `blocked_by` DAG
+from day one.
+
+The scaffolded file ([WORKFLOW.minimal.yaml](./WORKFLOW.minimal.yaml) is the shipped
+copy) runs as-is once `symphony-agents:latest` exists; the only edits a different
+setup needs are `gondolin.image` (if you pinned a build id) and the adapter
+credential for your chosen agent. When you want a power feature it omits — typed
+action DAGs, PR autopilot, per-state adapters, egress allowlists — graduate to
+the annotated [WORKFLOW.template.yaml](./WORKFLOW.template.yaml).
+
+(Or `npm i -g smol-symphony` and then `symphony doctor` / `symphony WORKFLOW.yaml`
+to skip the `npx` fetch — both invoke the `symphony` bin shipped in this
+package.)
+
+### Prerequisites in detail
+
+- **Node.js ≥ 20.**
+- **The agent rootfs image** (step 1). Gondolin is the in-process microVM
+  substrate (`@earendil-works/gondolin`), so there is no separate VM daemon to
+  run. The image is built **once** from `images/agents/` via
+  `npm run build:image`: it starts from `node:24-bookworm-slim`, installs base
+  CLI tooling, and ships only the `mise` (jdx/mise) binary. node + every
+  ACP-capable coding agent (`claude-agent-acp`, `codex-acp`, …) are
+  NO LONGER baked — they come from a mise SYSTEM config symphony stages into the
+  guest at dispatch (`assets/symphony-mise.system.toml`) and installs via
+  `mise install` into a warm-cached data dir; a consuming repo's own `mise.toml`
+  adds project toolchains (rust, go, kotlin+gradle, …) on top. The in-VM stdio
+  launcher is likewise injected at dispatch, not baked. So bumping an agent CLI is
+  a one-line edit to the staged mise config + a restart — no image rebuild + repin.
+  The build prints a content-addressed build id; pin it (or the
+  `symphony-agents:latest` tag) in `WORKFLOW.yaml`'s `gondolin.image`. See
+  [images/agents/README.md](./images/agents/README.md) for the build steps and
+  requirements, and `gondolin.mise` in
+  [WORKFLOW.template.yaml](./WORKFLOW.template.yaml) to tune the data dir or opt out.
+- **An adapter credential.** For the default `acp.adapter: claude`: a
+  credentials file at `~/.claude/.credentials.json` on the host. Symphony reads
+  it only on the host side: the guest holds only a token-shaped placeholder, and
+  the host substitutes the real OAuth access token into the outbound request at
+  Gondolin egress (TLS-MITM). The credential file itself is never staged into
+  the VM. (For `acp.adapter: codex`, see [WORKFLOW.template.yaml](./WORKFLOW.template.yaml).)
+- **Skipping the `npx` fetch.** `npm i -g smol-symphony` installs the `symphony`
+  bin globally so `symphony WORKFLOW.yaml` works without re-fetching; the image
+  build still needs a checkout (it lives in `images/agents/`).
+- **Console output.** With the default log file configured, symphony prints a
+  one-line-per-field startup banner (workflow, tracker root, dashboard URL,
+  log-file path) and routes the structured `key=value` stream to
+  `.symphony/logs/symphony.log` only. `tail -f` that file to follow the detail.
+  Pass `--verbose` (alias `--foreground`) to mirror the structured stream back
+  to the console for interactive debugging. With no log file configured (the
+  `SYMPHONY_LOG_FILE=""` override), the structured stream stays on stderr.
 
 ### From a checkout
 
@@ -95,7 +145,7 @@ git clone https://github.com/dizk/smol-symphony.git
 cd smol-symphony
 npm install
 npm run build
-npx symphony WORKFLOW.md     # the local bin
+npx symphony WORKFLOW.yaml     # the local bin
 ```
 
 `npm run dev` (via `tsx watch`) reruns on source edits.
@@ -104,7 +154,7 @@ npx symphony WORKFLOW.md     # the local bin
 
 Issues live as `.md` files under `tracker.root`. The parent directory is the
 issue state; the set of valid state directories comes from the `states:` block
-in `WORKFLOW.md` (see below) and is auto-mkdir'd on startup.
+in `WORKFLOW.yaml` (see below) and is auto-mkdir'd on startup.
 
 ```
 issues/
@@ -143,12 +193,14 @@ itself in response to `symphony.transition`. The agent inside the VM does
 **not** have filesystem access to the tracker root: it signals progress
 through the MCP server and the orchestrator does the file move.
 
-## WORKFLOW.md
+## WORKFLOW.yaml
 
-`WORKFLOW.md` is a YAML front matter block (orchestrator config) plus a
-[Liquid](https://liquidjs.com/)-templated prompt body. The shipped file in
-this repo is the canonical project workflow; see
-[WORKFLOW.template.md](./WORKFLOW.template.md) for the annotated reference
+`WORKFLOW.yaml` is a pure YAML config file (the orchestrator config). Each
+active state's prompt lives in its own `prompt_file` — a
+[Liquid](https://liquidjs.com/)-templated file under `prompts/`, wrapped in the
+shared `prompt.preamble_file`/`footer_file`. The shipped file in this repo is
+the canonical project workflow; see
+[WORKFLOW.template.yaml](./WORKFLOW.template.yaml) for the annotated reference
 covering every supported option, its type, default, and example.
 
 The workflow is a **state machine**. A required top-level `states:` block
@@ -156,14 +208,14 @@ declares every state an issue can occupy, its `role` (`active` — dispatched;
 `terminal` — triggers cleanup and handoff; `holding` — sits outside the
 dispatch loop, e.g. `Triage`), and optional per-state `adapter`, `model`,
 `max_turns`, and `allowed_transitions` overrides. A single issue can travel
-through any number of states with distinct adapters and instructions; the
-prompt body can branch on the current state with Liquid
-`{% case issue.state %}`. The shipped workflow uses a two-stage
-`Todo → Review → Done` flow (Claude implements, Codex reviews).
+through any number of states with distinct adapters and instructions; each
+active state names its own `prompt_file`, so the agent in each state sees only
+that state's instructions plus the shared preamble/footer. The shipped workflow
+uses a two-stage `Todo → Review → Done` flow (Claude implements, Codex reviews).
 
-Symphony watches the file and re-applies poll interval, concurrency, typed
-actions, prompt body, gondolin settings, etc. on change without restart.
-In-flight runs keep the settings they started with.
+Symphony watches the file and its prompt files, and re-applies poll interval,
+concurrency, typed actions, prompts, gondolin settings, etc. on change without
+restart. In-flight runs keep the settings they started with.
 
 ## Dashboard
 
@@ -233,7 +285,7 @@ the adapter reaches for inside the VM:
 | `claude`  | `claude-agent-acp` | placeholder + host egress swap    |
 | `codex`   | `codex-acp`        | placeholder + host egress swap    |
 
-`WORKFLOW.md`:
+`WORKFLOW.yaml`:
 
 ```yaml
 acp:
@@ -269,7 +321,7 @@ holds only the placeholder.
 On transition into the Done state the orchestrator runs that state's typed
 `actions:` block — two records, `push_branch` then `create_pr_if_missing` —
 which push the per-issue branch and open a PR when a GitHub repo is configured:
-set `workspace.github_repo: <owner>/<repo>` in `WORKFLOW.md` (or export
+set `workspace.github_repo: <owner>/<repo>` in `WORKFLOW.yaml` (or export
 `SYMPHONY_REPO=<owner>/<repo>`, which overrides the file). Each action's
 `if: $repo` predicate short-circuits to a no-op in local-only mode (neither
 set), so the branch is simply left in the workspace until cleanup; pick the
@@ -286,8 +338,8 @@ and snapshot plumbing replaces the old opaque shell-exit surface: on a
 rate-limit the `create_pr_if_missing` action surfaces "retrying in 60s" on the
 dashboard rather than failing silently.
 
-See `states.Done.actions` in [WORKFLOW.md](./WORKFLOW.md) for the canonical
-record pair and [WORKFLOW.template.md](./WORKFLOW.template.md) for the
+See `states.Done.actions` in [WORKFLOW.yaml](./WORKFLOW.yaml) for the canonical
+record pair and [WORKFLOW.template.yaml](./WORKFLOW.template.yaml) for the
 typed-action reference.
 
 ## Trust posture

package/SPEC.md

@@ -34,7 +34,7 @@ The service solves four operational problems:
   scripts.
 - It isolates agent execution in per-issue workspaces so agent commands run
   only inside per-issue workspace directories.
-- It keeps the workflow policy in-repo (`WORKFLOW.md`) so teams version the
+- It keeps the workflow policy in-repo (`WORKFLOW.yaml`) so teams version the
   agent prompt and runtime settings with their code.
 - It provides enough observability to operate and debug multiple concurrent
   agent runs.
@@ -59,7 +59,7 @@ Boundary:
 - Create deterministic per-issue workspaces and preserve them across runs.
 - Stop active runs when issue state changes make them ineligible.
 - Recover from transient failures with exponential backoff.
-- Load runtime behavior from a repository-owned `WORKFLOW.md` contract.
+- Load runtime behavior from a repository-owned `WORKFLOW.yaml` contract.
 - Expose operator-visible observability (at minimum structured logs).
 - Support tracker/filesystem-driven restart recovery without requiring a
   persistent database; exact in-memory scheduler state is not restored.
@@ -108,10 +108,12 @@ Fields:
 
 #### 3.1.2 Workflow Definition
 
-Parsed `WORKFLOW.md` payload:
+Parsed `WORKFLOW.yaml` payload:
 
-- `config` (map) — YAML front matter root object.
-- `prompt_template` (string) — Markdown body after front matter, trimmed.
+- `config` (map) — the decoded YAML config root object.
+- `prompt_templates` (map of state name → string, optional) — the per-state
+  prompt templates the loader assembles from each active state's `prompt_file`
+  (wrapped in the shared `prompt.preamble_file`/`footer_file`).
 
 #### 3.1.3 Service Config (Typed View)
 
@@ -160,7 +162,7 @@ attempt dispatches into).
 Workflow file path precedence:
 
 1. Explicit application/runtime setting (set by CLI startup path).
-2. Default: `WORKFLOW.md` in the current process working directory.
+2. Default: `WORKFLOW.yaml` in the current process working directory.
 
 Loader behavior:
 
@@ -169,22 +171,22 @@ Loader behavior:
 
 ### 4.2 File Format
 
-`WORKFLOW.md` is a Markdown file with OPTIONAL YAML front matter.
+`WORKFLOW.yaml` is a pure YAML config file. There is no inline prompt body;
+each active state's prompt lives in its own `prompt_file` (a Liquid template).
 
 Parsing rules:
 
-- If file starts with `---`, parse lines until the next `---` as YAML front
-  matter.
-- Remaining lines become the prompt body.
-- If front matter is absent, treat the entire file as prompt body and use an
-  empty config map.
-- YAML front matter MUST decode to a map/object; non-map YAML is an error.
-- Prompt body is trimmed before use.
+- The whole file decodes as a single YAML document → the config map.
+- The decoded YAML MUST be a map/object; a list or bare scalar is an error.
+- An empty/whitespace-only file decodes to an empty config map.
+- A leading `---` YAML document marker is tolerated (decoded as YAML), but
+  there is no front-matter fence and no Markdown body.
 
 Returned workflow object:
 
-- `config`: front matter root object (not nested under a `config` key).
-- `prompt_template`: trimmed Markdown body.
+- `config`: the decoded YAML config root object (not nested under a `config` key).
+- `prompt_templates`: per-state assembled prompt templates (built by the shell
+  loader from each active state's `prompt_file`; see §3.1.2).
 
 ### 4.3 Front Matter Schema
 
@@ -192,7 +194,7 @@ Top-level keys: `tracker`, `states`, `polling`, `workspace`, `agent`,
 `acp`. Unknown keys SHOULD be ignored for forward compatibility. Extensions
 MAY define additional top-level keys without changing the core schema.
 
-`WORKFLOW.template.md` is the annotated reference for every recognized field;
+`WORKFLOW.template.yaml` is the annotated reference for every recognized field;
 this section captures the contract the loader enforces.
 
 #### 4.3.1 `tracker` (object)
@@ -216,7 +218,7 @@ supported kind.
 
 - `root` (path string or `$VAR`, default `<system-temp>/symphony_workspaces`)
 - `~` is expanded; relative paths are resolved relative to the directory
-  containing `WORKFLOW.md`. The effective workspace root is normalized to an
+  containing `WORKFLOW.yaml`. The effective workspace root is normalized to an
   absolute path before use.
 
 #### 4.3.4 `agent` (object)
@@ -235,7 +237,7 @@ supported kind.
 Coding-agent launch is mediated by the Agent Client Protocol. The runtime
 selects an adapter profile and runs it inside the per-issue sandbox; the host
 opens an authenticated TCP bridge that the in-sandbox proxy dials back over
-to carry ACP frames. See `WORKFLOW.template.md` (`acp:` section) for the full
+to carry ACP frames. See `WORKFLOW.template.yaml` (`acp:` section) for the full
 annotated field list. Adapter credentials are handled out of band of this
 config — there is no credential-mode knob; see §6.3 for the host credential
 proxy and identity-staging contract.
@@ -251,7 +253,7 @@ Fields read by the runtime:
 - `stall_timeout_ms` (integer, default `300000`; `<= 0` disables stall
   detection)
 - `bridge` (object) — `bind_host`, `bind_port`, `reach_host`, `reach_url`,
-  `connect_timeout_ms`; see `WORKFLOW.template.md`.
+  `connect_timeout_ms`; see `WORKFLOW.template.yaml`.
 
 #### 4.3.6 `states` (map)
 
@@ -315,7 +317,8 @@ states, not named here.
 
 ### 4.4 Prompt Template Contract
 
-The Markdown body of `WORKFLOW.md` is the per-issue prompt template.
+Each active state's `prompt_file` (wrapped in the shared
+`prompt.preamble_file`/`footer_file`) is that state's per-issue prompt template.
 
 Rendering requirements:
 
@@ -332,8 +335,9 @@ Template input variables:
 
 Fallback prompt behavior:
 
-- If the workflow prompt body is empty, the runtime MAY use a minimal default
-  prompt (`You are working on an issue.`).
+- If a dispatched state has no assembled template (no `prompt_file`), or the
+  template renders empty, the runtime MAY use a minimal default prompt
+  (`You are working on an issue.`).
 - Workflow file read/parse failures are configuration/validation errors and
   SHOULD NOT silently fall back to a prompt.
 
@@ -660,7 +664,12 @@ active → holding); cleanup is driven by the target state's role
 
 Inputs to prompt rendering:
 
-- `workflow.prompt_template`
+- `workflow.prompt_templates[issue.state]` — the assembled prompt template for
+  the issue's current state, selected from the per-state `prompt_templates` map
+  (each entry built by the loader from that state's `prompt_file`, wrapped in
+  the shared `prompt.preamble_file`/`footer_file`; see §3.1.2 / §4.2). When no
+  template exists for the state (or it is empty), rendering falls back to the
+  generic prompt `You are working on an issue.`
 - normalized `issue` object
 - OPTIONAL `attempt` integer (retry/continuation metadata)
 

package/WORKFLOW.minimal.yaml

@@ -0,0 +1,34 @@
+# WORKFLOW.yaml — minimal starter scaffolded by smol-symphony.
+#
+# Run:  npx smol-symphony WORKFLOW.yaml --port 8787
+#
+# A workflow file is pure YAML config; each active state's prompt lives in its
+# own `prompt_file`. `npx smol-symphony` scaffolds this file plus prompts/Todo.md
+# next to it. For the full annotated reference — per-state adapters/models, typed
+# action DAGs, egress allowlists, PR autopilot, sleep-cycle reflection, and every
+# other optional power feature — see WORKFLOW.template.yaml:
+# https://github.com/dizk/smol-symphony/blob/main/WORKFLOW.template.yaml
+
+tracker:
+  kind: local           # issues are markdown files under <tracker.root>/<state>/
+                        # default root: ~/.symphony/trackers/<project> (outside
+                        # the repo; set tracker.root: to override)
+
+states:
+  Todo:
+    role: active        # dispatched — an agent picks the issue up here
+    adapter: claude     # the coding agent to run (claude | codex)
+    prompt_file: prompts/Todo.md   # this state's prompt template
+  Done:
+    role: terminal      # transitioning here ends the run and cleans up
+  Triage:
+    role: holding       # propose_issue lands here; never auto-dispatched
+
+gondolin:
+  # The agent rootfs each per-issue microVM boots. `managed` (the default) FETCHES a
+  # prebuilt asset from a published symphony release on first run — no docker, no
+  # `npm run build:image`. The image ships only `mise`; node + the agent CLIs are always
+  # mise-installed at dispatch (see gondolin.mise in WORKFLOW.template.yaml — mise
+  # provisioning is the only toolchain path). To pin your own asset instead, set this to a build id / name:tag from
+  # `npm run build:image`, or use gondolin.oci_image for an auto-converted OCI ref.
+  image: managed