archal 0.9.18 → 0.9.20

package/skills/seed/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: seed
+description: Craft and load explicit clone seed state for Archal, deterministically and with no LLM. This is the canonical "how to seed a clone" skill. Use it whenever you need to give a clone (github, stripe, supabase, slack, ...) a known starting state: writing or editing a JSON or SQL seed file, choosing a named catalog seed, wiring a scenario's seed, debugging "seed not found" / "seed_unavailable" / shape-mismatch / rollback errors, or deciding between an inline `## Seed State` block and a committed seed file. Reach for this any time the words seed, seed state, starting state, fixture data, or "set up the clone with..." appear.
+user-invocable: true
+argument-hint: "[clone + the state you want loaded]"
+---
+
+# Archal Seed State
+
+You craft and load explicit starting state for Archal clones. A seed is the
+clone's state before a run begins: the issues GitHub holds, the customers and
+subscriptions Stripe holds, the rows a Supabase database holds.
+
+The one rule that defines this skill: **seeds are explicit, committed, and
+deterministic. No LLM is involved.** You write the state, or you pick a named
+catalog seed someone already wrote. You never ask a model to invent it.
+
+The dedicated package that loads seed state, `@archal/seed-state`, says this in
+its own README and it is the mental model to hold:
+
+> This package intentionally contains no LLM calls, code generation, natural
+> language extraction, cache, repair, or scenario-to-state generation.
+
+## The four shapes a seed can take
+
+1. **A committed JSON seed file** — `clones/<clone>/seeds/<name>.json`. A
+   top-level object whose keys are the clone's collections and whose values are
+   arrays of entities. This is the common shape for object-graph clones
+   (github, stripe, slack, linear, jira). Example file:
+   `clones/github/seeds/small-project.json`.
+
+2. **A committed SQL seed file** — `clones/<clone>/seeds/<name>.sql`. A set of
+   `CREATE TABLE` + `INSERT` statements. The natural shape for relational
+   clones like `supabase`, whose seeds on disk are `.sql`, not `.json`. Example:
+   `clones/supabase/seeds/ecommerce.sql`.
+
+3. **A named catalog seed** — a seed that already lives on disk for a clone, so
+   you reference it by name instead of writing one. `github: small-project`,
+   `stripe: checkout-flow`, `supabase: saas-starter`. Browse them with
+   `archal seed list <clone>`.
+
+4. **An inline `## Seed State` block in a scenario** — explicit state written
+   directly in the scenario markdown. Use it when the state is small and tightly
+   coupled to that one scenario. For anything reused across scenarios, prefer a
+   committed file (shapes 1–3) so it has one home.
+
+Resolution on disk checks `<name>.json` first, then `<name>.sql`
+(`loadSeedStateFromPath` in `packages/seed-state/src/state.ts`). A clone can
+ship either form for a given seed name, not both.
+
+## How a scenario or the CLI selects a seed
+
+A seed value comes from one of two places, parsed identically:
+
+- The scenario `## Config` key `seed:`
+- The CLI flag `archal run --seed <name-or-path>`
+
+Both accept the same forms (verbatim from the `--seed` flag help):
+
+> Seed name (e.g. small-project), clone-prefixed name (github:small-project,
+> applies only to that clone), seed family (enterprise, stale, ...), or local
+> file path (.json / .md).
+
+So the two everyday shapes are:
+
+- **Bare name** — `seed: small-project`. Applies to every clone the scenario
+  declares.
+- **Clone-prefixed** — `seed: github:small-project`. Applies only to the named
+  clone. This matches `archal clone start --seed github:small-project`, so the
+  same string works in both commands.
+
+The prefix is validated: if you write `seed: payments:checkout-flow` but the
+scenario never declares a `payments` clone, you get a usage error naming the
+clones the scenario actually has, rather than a confusing `seed_unavailable`
+later from the runtime (`parseExplicitSeed` in
+`cli/src/runner/seed-resolution.ts`).
+
+One behavior to remember: a scenario with a `## Setup` section but **no**
+explicit `seed:` is forced to the `empty` seed, because Setup prose used to
+drive dynamic generation and a pre-populated seed would conflict with it. To
+combine a Setup description with a real seed, you must add an explicit `seed:`
+field. (See `resolveRunSeedPlan` in `cli/src/runner/seed-resolution.ts`.)
+
+### Command surface
+
+| Command | What it does |
+|---------|--------------|
+| `archal seed list` | One row per clone: clone, default seed, seed count |
+| `archal seed list <clone>` | Every seed for that clone, with the default marked |
+| `archal seed list <clone> --json` | Same, machine-readable |
+| `archal run <scenario>.md --seed <name-or-path>` | Override the seed for a run |
+| `archal run ... --fresh-seed` | On a reused clone session, reset and re-apply the seed |
+| `archal run ... --keep-state` | On a reused session, keep existing state, do not re-apply |
+| `archal clone start <clone> --seed <seeds...>` | Start a live clone pre-seeded |
+| `archal clone start <clone> --seed-file <path>` | Start a live clone, then load a JSON/markdown seed file |
+| `archal clone seed --file <path>` | Sideload a JSON seed file into a running clone |
+
+Prefer `archal seed list` over memorizing a seed table. The catalog is derived
+from `clones/<clone>/seeds/*.{json,sql}` on disk, so the CLI is always current.
+
+## The deterministic load flow
+
+When a run seeds a clone, the loader does this, in order
+(`packages/runtime/src/seed-loader.ts`):
+
+1. **Snapshot first.** `GET /state` on each target clone and keep the response
+   text. This is the rollback point (`snapshotSeedTargets` →
+   `fetchSeedStateSnapshot`).
+2. **Apply the seed.** `PUT /state` with the seed body — `application/json` for
+   a JSON seed, `text/sql` for a SQL seed — one clone at a time, tracking each
+   one that committed.
+3. **Roll back on failure.** If any clone's load throws, restore the clones that
+   already committed by replaying their snapshots, then re-throw the original
+   error (`restoreSeedTargets`). A clone is never left half-seeded.
+4. **Capture the baseline after seeding.** Once seeding succeeds, the post-seed
+   state is captured as the baseline (`captureBaselineStates` in
+   `packages/runtime/src/clone-client.ts`). Resets between runs restore *this*
+   seeded baseline, not an empty clone — so every run in a multi-run scenario
+   starts from the same seeded state.
+
+### How state reaches the clone (the `/state` endpoint)
+
+The clone server exposes `/state` (`clones/core/src/rest/rest-built-in-endpoints.ts`):
+
+- `GET /state` — read the current state (used for the snapshot and baseline).
+- `PUT /state` — load state. The handler branches on `Content-Type`:
+  - `text/sql` or `application/sql` → parsed and loaded as SQL (only when the
+    clone exposes SQL loading; otherwise it returns a 400 telling you to send
+    JSON).
+  - otherwise → loaded as JSON state.
+  - `PUT /state?seed=<name>` with a `{}` body → load a named catalog seed
+    server-side, without sending a state body at all.
+- `DELETE /state` — wipe state (used by `--fresh-seed` before re-applying).
+
+A successful `PUT` returns `{ ok: true }`. The content-type the CLI sends is set
+in one place — `text/sql` when there is SQL, `application/json` otherwise
+(`pushStateToCloud` in `cli/src/runner/execution/agent-http.ts`); named-seed
+loads always send `application/json` with an empty body.
+
+## Do not do these
+
+- **Do not synthesize seed data from scenario prose.** A `## Setup` paragraph is
+  context for the evaluator, not a source you extract state from. If you need
+  populated state, write a committed seed (or pick a named one) and reference it
+  with `seed:`.
+- **Do not call an LLM to generate, repair, or "fill in" a seed.** The old
+  dynamic seed-generation path is being removed; `@archal/seed-state` was built
+  specifically to have none of it. Explicit committed seeds only.
+- **Do not invent collection names.** A JSON seed must use the clone's real
+  collection keys (see "Writing a good JSON seed"). Unknown keys are dropped by
+  normalization, so a typo silently seeds nothing.
+- **Do not hand-tune both `.json` and `.sql` for the same name.** Pick one form
+  per seed name; resolution stops at the first that exists.
+- **Do not blow away a sideloaded session by accident.** On a reused
+  `archal clone start` session the loader probes for existing state before
+  re-applying. Use `--keep-state` to keep it or `--fresh-seed` to reset on
+  purpose, rather than fighting the guard.
+
+## Writing a good JSON seed
+
+The seed file must mirror the clone's real state shape. The fastest reliable way
+to get the shape right is to open an existing catalog seed for that clone and
+match its top-level keys and per-entity fields.
+
+A JSON seed is a top-level object: each key is a collection, each value is an
+array of entity objects.
+
+```jsonc
+{
+  "users":  [{ "id": "u1", "login": "octocat", "type": "User" }],
+  "repos":  [{ "id": "r1", "name": "demo", "fullName": "octocat/demo", "private": false }],
+  "issues": [{ "id": "i1", "repoId": "r1", "number": 1, "title": "First issue", "state": "open" }]
+}
+```
+
+Match the clone, not your imagination:
+
+- Use the same collection names the clone uses. `clones/github/seeds/small-project.json`
+  has `users`, `repos`, `issues`, `pullRequests`, `labels`, and more.
+- Give each entity the fields the clone expects, especially `id` and the foreign
+  keys that wire entities together (`repoId`, `issueNumber`, ...). The clone
+  maintains those relationships; broken references produce realistic errors at
+  runtime, not seed-time.
+- Only arrays survive normalization — non-array top-level values are dropped
+  (`normalizeSeedState`). Keep everything in collection arrays.
+
+## When SQL fits
+
+Use a `.sql` seed for relational clones whose state is naturally tables and
+rows — `supabase` is the canonical case, and its seeds on disk are `.sql`. The
+SQL seed is plain `CREATE TABLE` + `INSERT INTO ... VALUES (...)`:
+
+```sql
+CREATE TABLE customers (id serial, email text, name text);
+INSERT INTO customers (email, name) VALUES
+  ('ada@example.com', 'Ada Lovelace'),
+  ('alan@example.com', 'Alan Turing');
+```
+
+The SQL parser is deliberately small (`parseSqlSeed` in
+`packages/seed-state/src/state.ts`): it understands `CREATE TABLE` (including
+`IF NOT EXISTS`), `INSERT INTO ... VALUES`, schema-qualified and quoted
+identifiers, line and block comments, and auto-assigns serial `id`s. It is not a
+full SQL engine — anything other than `CREATE TABLE` / `INSERT` throws an
+"Unsupported SQL seed statement" error. Keep seeds to those two statements.
+
+## Failure taxonomy
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| `Could not resolve static seed "<name>"` / `seed_unavailable` | Seed name is misspelled, not in this clone's catalog, or the hosted session was started with a different seed | `archal seed list <clone>` to confirm the name; re-provision the session with the right seed |
+| `clone "<x>" is not part of this scenario` | Clone-prefixed seed names a clone the scenario doesn't declare | Add the clone to `clones:`, or drop the prefix |
+| Seed loads but state looks empty / partial | Wrong collection keys, or non-array top-level values dropped by normalization | Match an existing catalog seed's keys; keep every collection an array |
+| `Failed to parse seed file ...` | Malformed JSON | Validate the JSON; check trailing commas and quoting |
+| `Unsupported SQL seed statement: ...` | SQL beyond `CREATE TABLE` / `INSERT` | Reduce the seed to those two statements |
+| `…does not expose SQL state loading` (HTTP 400) | Sent SQL to a clone that only loads JSON | Send JSON state, or use a clone that supports SQL |
+| `Rollback failed after partial seed load` | A clone errored mid-load and the snapshot restore also failed | The clones may be in a mixed state; restart the clone session and retry |
+| Seed "not re-applied" warning on a reused session | The loader kept existing sideloaded state instead of overwriting it | `--fresh-seed` to reset and re-apply, or `--keep-state` to accept it on purpose |
+
+## What to report back
+
+After authoring or loading a seed, tell the user:
+
+- the clone(s) and the seed shape used (named catalog seed, JSON file, SQL file,
+  or inline `## Seed State`)
+- the seed name or file path, and how a scenario/run selects it (`seed:` or
+  `--seed`)
+- the entity counts loaded per clone (the loader logs e.g. `7 issues, 3 repos`)
+- for a new seed file, that it mirrors an existing catalog seed's shape
+- any blocker: missing seed name, shape mismatch, SQL parse error, or a rollback
+  that fired — with the exact next command
+
+## Docs
+
+- Seeds guide: https://docs.archal.ai/guides/seeds
+- Clones and seeds overview: https://docs.archal.ai/clones/overview
+- Writing scenarios: https://docs.archal.ai/guides/writing-scenarios