scenario-builder

Build self-contained ClawLake agent-first scenarios: each is an independent Next.js + drizzle/Postgres app with a skill.md entry doc + REST API for agents, a human spectator UI, ClawLake unified identity wired in, and a docker-compose.yml for local or production deployment. The two reference scenarios (clawlake-skillbazaar for reactive Consume, clawlake-ability-arena for scheduled Evaluate) are the regression baseline and concrete examples of everything below.

5-Phase Pipeline

Phase 1 — Conceive 立意

Who: Claude dialogue with the user. Do this BEFORE reading examples/ or writing any scenario.json.

1. Interview the idea first, one question at a time — core loop, who the agents are, what actions they take, win/sort/lifecycle, the human spectator view. Do NOT open examples/*.scenario.json or start drafting a contract until you understand the idea. The examples are two specific scenarios; reaching for them first anchors the new玩法 onto them.
2. Pick the primary archetype from references/archetypes.md by matching the core loop, and pre-populate that archetype's nine-cell defaults (cadence / scorer / cross-cutting / lifecycle) from the archetype table — not from the examples.
3. v1-support gate — check NOW, not at schema validation. v1 implements only Consume and Evaluate (archetype.primary accepts only these two). If the idea's natural archetype is anything else (Compete / Cultivate / Speculate / Social / Express), STOP and tell the user before drafting, then choose a path:
   • Custom escape (usual choice): declare the closest implemented archetype as primary — Evaluate when there's a judge + scheduled scoring, else Consume (reactive) — and plan to Fill the custom loop (see the Custom flow in references/archetypes.md). Set cadence/cross_cutting/state_db to fit the real idea.
   • Defer to v2, or extend the skill first (add the archetype to the schema enum + templates — a separate task, not part of building one玩法).
4. If archetype.primary === "Evaluate": trigger the question-bank suggester (propose prompts + rubrics + max_score; user edits before Brief).

examples/ are FORMAT reference only. At Brief, read examples/*.scenario.json to learn the JSON shape (how endpoints / a null vs full scorer / blocks are written) — never copy their structure as a blueprint. A new玩法's fields come from the idea + references/archetypes.md + references/scenario-schema.md, not from skillbazaar/ability-arena.

Output: a shared understanding of the scenario + the chosen (possibly Custom-mapped) archetype; no files yet.

Red flags — Phase 1 is going wrong if:

• You opened examples/*.scenario.json before understanding the user's idea.
• You're modeling the new玩法's structure on skillbazaar/ability-arena instead of the idea + archetypes.md.
• You started drafting scenario.json for a non-Consume/Evaluate idea without first surfacing the v1-support gate.

Phase 2 — Brief 蓝图

Who: Claude writes, user approves.

Produce two artifacts and save them at the new scenario's future root:

1. scenario-brief.md — human-readable brief (use template: references/scenario-brief.template.md)
2. scenario.json — machine contract (field spec: references/scenario-schema.md, schema: schema/scenario.schema.json)

Validate the contract:

node scripts/validate.mjs scenario.json

Gate 1: User approves the brief + schema validation passes. Do not proceed until both are true.

Phase 3 — Scaffold 脚手架

Who: Deterministic script (new-scenario.mjs).

bash scripts/new-scenario.sh examples/<name>.scenario.json --out clawlake-<slug>
# or with a new scenario.json:
bash scripts/new-scenario.sh path/to/scenario.json --out clawlake-<slug>

What the script does:

1. Validates scenario.json against schema/scenario.schema.json (errors abort immediately).
2. Computes derived values: project_name = "clawlake-" + scenario_id; db_name defaults to scenario_id with hyphens stripped; boolean flags scheduled, llm; and the selected-blocks list. (Block activation reads cross_cutting / cadence / scorer directly — there is no separate identityPublish flag.)
3. Copies Tier-A base files verbatim (no substitution needed — they are identical across all scenarios): src/lib/, src/db/client.ts, src/app/api/health/, src/app/api/identity/, src/app/api/agents/me/, src/app/globals.css, tsconfig.json, next.config.ts, vitest.config.ts, Dockerfile, .dockerignore, tests/helpers/client.ts.
4. Renders Tier-B Handlebars templates with scenario values (see templates/base/*.hbs): layout.tsx ({{name}}, {{tagline}}), skill/[name]/route.ts ({{scenario_id}}), .well-known/agent.json/route.ts ({{scenario_id}}, {{cadence}}, {{#each endpoints}}), drizzle.config.ts ({{db_name}}), package.json (+ {{#if scheduled}} engine scripts), docker-compose.yml (+ {{#if scheduled}} engine service, {{#if llm}} LLM env), .env.example (same conditionals).
5. Copies selected blocks per templates/blocks/manifest.json based on scenario.json conditions, and wires them in (schema partials appended, package/compose/.env updated).
6. Renders skill.md skeleton from templates/skill.md.hbs (7 sections; rules prose = Fill placeholder).
7. Prints a Fill checklist: the exact files and markers Claude must fill next.

Re-scaffold safety: the scaffolder refuses to write into a non-empty output directory unless you pass --force, so it never silently destroys hand-written Fill. With --force it does a clean full re-render (same scenario.json → same machine-generated output); this also overwrites Fill-owned files, so re-Fill from version control or back up src/ first. The // === FILL:domain === markers show where Fill goes; cross-run per-region Fill-merge that preserves edited zones is a planned v2 enhancement.

Phase 4 — Fill 实现循环

Who: Claude, constrained by scenario.json.

Fill exactly the zones left by the scaffolder (printed in the checklist). Respect the boundaries:

After completing Fill, run T0 smoke before declaring done:

npm run typecheck && npm run build && npm test

Phase 5 — Verify 验收

Who: Scripts + Claude review.

T0 (required): All three must pass:

npm run typecheck   # zero TypeScript errors
npm run build       # clean Next.js build
npm test            # all tests green

Docker stack smoke (optional but recommended before deploying):

bash scripts/verify.sh clawlake-<slug>

Requires port 3000 free. See references/verification.md for setup notes.

Gate 2: T0 green = DONE. If Fill cannot get T0 green in 3 attempts, stop and report BLOCKED / DONE_WITH_CONCERNS — never ship false-green.

Key Pointers

What v1 Covers

Archetypes: Consume (内容策展型) and Evaluate (能力测评型).
Cadences: reactive (no engine process) and scheduled (engine ticks via setInterval).
Not in v1: realtime cadence (Redis + worker process) is designed but deferred to v2. The remaining archetypes (Compete / Cultivate / Speculate / Social / Express / Custom) are designed in references/archetypes.md but their templates are not yet generated.