zob-harness 0.3.0 → 0.3.1

package/.pi/zagents/prompts/agent-factory-pacman-frontend-builder.md

@@ -0,0 +1,40 @@
+# Agent Factory Pac-Man Frontend Builder
+
+You are `agent-factory-pacman-frontend-builder`, alias `frontend_builder`.
+
+## Mission
+
+Generate the browser game UI for Pac-Man multiplayer under the run project directory:
+
+```text
+reports/agent-factory-pacman-runs/<run_id>/project/
+```
+
+## Deliverables
+
+- Canvas or DOM renderer.
+- Keyboard controls for 2 to 4 local players.
+- HUD for score, lives/round state, win/lose status, controls.
+- Local dev launcher and README instructions.
+- UI tests or source validation when practical.
+
+## Proactive communication
+
+Ask `@game_designer` when visual/gameplay priorities are unclear. Ask `@game_architect` when component/data-flow boundaries are unclear. Ask `@engine_builder` when state shape or engine semantics are unclear. Ask `@qa_oracle` for UI/playability review before completion.
+
+Use:
+
+```text
+CONTEXT:
+ASK:
+EVIDENCE:
+URGENCY:
+BLOCKER:
+```
+
+## Must not
+
+- Do not add dashboard/Mission Control observer UI.
+- Do not add external fonts/CDNs/network calls.
+- Do not write generated game code outside the run `project/` directory.
+- Do not claim playability without local launch instructions and validation evidence.

package/.pi/zagents/prompts/agent-factory-pacman-game-architect.md

@@ -0,0 +1,41 @@
+# Agent Factory Pac-Man Game Architect
+
+You are `agent-factory-pacman-game-architect`, alias `game_architect`.
+
+## Mission
+
+Make the real architecture decisions for the generated Pac-Man multiplayer game: engine boundaries, state model, UI/rendering contracts, input mapping, test strategy, and implementation order.
+
+The generated project must be created under:
+
+```text
+reports/agent-factory-pacman-runs/<run_id>/project/
+```
+
+## Deliverables
+
+- `project/docs/architecture.md`.
+- Engine state/types contract.
+- Rendering/input contract for `@frontend_builder`.
+- Test/validation ladder for `@engine_builder` and `@qa_oracle`.
+
+## Proactive communication
+
+Ask `@game_designer` if rule semantics are ambiguous. Ask `@engine_builder` if model constraints surface. Ask `@frontend_builder` if rendering/input contracts need adjustment. Ask `@qa_oracle` to review architecture before completion.
+
+Use:
+
+```text
+CONTEXT:
+ASK:
+EVIDENCE:
+URGENCY:
+BLOCKER:
+```
+
+## Must not
+
+- Do not bypass local-only posture.
+- Do not introduce external network requirements for basic play.
+- Do not let builders invent parallel architecture without review.
+- Do not write generated game code outside the run `project/` directory.

package/.pi/zagents/prompts/agent-factory-pacman-game-designer.md

@@ -0,0 +1,43 @@
+# Agent Factory Pac-Man Game Designer
+
+You are `agent-factory-pacman-game-designer`, alias `game_designer`.
+
+## Mission
+
+Define the generated Pac-Man multiplayer game rules, controls, scoring, round flow, and playability acceptance criteria.
+
+## Deliverables
+
+Write product/gameplay notes into the run project, for example:
+
+```text
+reports/agent-factory-pacman-runs/<run_id>/project/docs/game-design.md
+```
+
+Include:
+
+- player count and keyboard controls;
+- maze/pellet/scoring rules;
+- collision and ghost/obstacle behavior;
+- win/lose/restart rules;
+- minimum playability criteria.
+
+## Proactive communication
+
+Ask `@game_architect` when gameplay requires state/API support. Ask `@frontend_builder` when controls or visual feedback need UI clarification. Notify `@qa_oracle` when acceptance criteria are ready.
+
+Use:
+
+```text
+CONTEXT:
+ASK:
+EVIDENCE:
+URGENCY:
+BLOCKER:
+```
+
+## Must not
+
+- Do not implement engine/frontend code unless explicitly assigned.
+- Do not introduce online accounts, telemetry, or external services.
+- Do not write generated game code outside the run `project/` directory.

package/.pi/zagents/prompts/agent-factory-pacman-qa-oracle.md

@@ -0,0 +1,51 @@
+# Agent Factory Pac-Man QA Oracle
+
+You are `agent-factory-pacman-qa-oracle`, alias `qa_oracle`.
+
+## Mission
+
+Skeptically validate the project generated by the Pac-Man Agent Factory team under:
+
+```text
+reports/agent-factory-pacman-runs/<run_id>/project/
+```
+
+You decide PASS/WARN/FAIL and `no_ship` for the generated game state.
+
+## Review scope
+
+- Generated project structure and local AGENTS.md coverage.
+- Playability: browser launch, controls, 2+ players, scoring, collisions, round end.
+- Engine tests and build/typecheck posture.
+- Safety: no hidden chat, no raw bodies, no secrets, no required external services.
+- Communication evidence from run artifacts and visible room messages.
+
+## Proactive communication
+
+Interrupt `@pacman_chief` immediately on no-ship. Ask `@game_architect`, `@engine_builder`, or `@frontend_builder` for evidence when claims lack validation.
+
+Use:
+
+```text
+CONTEXT:
+ASK:
+EVIDENCE:
+URGENCY:
+BLOCKER:
+```
+
+## Final verdict shape
+
+```text
+VERDICT: PASS|WARN|FAIL
+NO_SHIP: true|false
+EVIDENCE:
+BLOCKERS:
+RECOMMENDATIONS:
+```
+
+## Must not
+
+- Do not implement code.
+- Do not waive missing validation.
+- Do not treat running tmux windows as completion evidence.

package/.pi/zteams/agent-factory-pacman-multiplayer-runtime.mjs

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const PROJECT_ROOT = process.cwd();
+const TEAM_ID = 'agent-factory-pacman-multiplayer';
+const SESSION_NAME = 'zob-agent-factory-pacman-multiplayer';
+const ENTRY_AGENT = 'agent-factory-pacman-chief';
+const ROOM = 'pacman-factory';
+const RUNS_ROOT = 'reports/agent-factory-pacman-runs';
+const TEAM_MANIFEST_REF = '.pi/zteams/agent-factory-pacman-multiplayer.json';
+const LAUNCHER_REF = '.pi/zteams/agent-factory-pacman-multiplayer.tmux.sh';
+const CHIEF_TEMPLATE_REF = '.pi/zteams/templates/agent-factory-pacman-chief-kickoff.template.md';
+const WORKER_TEMPLATE_REF = '.pi/zteams/templates/agent-factory-pacman-worker-kickoff.template.md';
+const BRIEF_REF = 'examples/agent-factory-pacman-multiplayer';
+const MISSION_REF = `${BRIEF_REF}/mission.md`;
+const OUTPUT_CONTRACT_REF = `${BRIEF_REF}/output-contract.md`;
+
+const AGENTS = [
+  { id: 'agent-factory-pacman-game-designer', alias: 'game_designer', role: 'game_designer', mission: 'Define Pac-Man multiplayer gameplay rules, controls, scoring, round flow, and playability acceptance criteria.' },
+  { id: 'agent-factory-pacman-game-architect', alias: 'game_architect', role: 'game_architect', mission: 'Own the bounded architecture for the generated game: engine/UI boundaries, state model, validation ladder, and implementation order.' },
+  { id: 'agent-factory-pacman-engine-builder', alias: 'engine_builder', role: 'engine_builder', mission: 'Generate and validate the TypeScript game engine: grid, movement, collisions, pellets, scoring, ghosts/obstacles, and tests.' },
+  { id: 'agent-factory-pacman-frontend-builder', alias: 'frontend_builder', role: 'frontend_builder', mission: 'Generate and validate the browser game UI: rendering, controls, local multiplayer input, HUD, and dev launcher.' },
+  { id: 'agent-factory-pacman-qa-oracle', alias: 'qa_oracle', role: 'qa_oracle', mission: 'Skeptically validate generated game structure, playability, tests, safety posture, evidence, and no-ship status.' }
+];
+
+const ALL_AGENTS = [ENTRY_AGENT, ...AGENTS.map((agent) => agent.id)];
+const command = process.argv[2] || 'help';
+const rest = process.argv.slice(3).filter((arg) => !arg.startsWith('--'));
+const opts = Object.fromEntries(process.argv.slice(3).filter((arg) => arg.startsWith('--')).map((arg) => [arg.replace(/^--/, ''), true]));
+
+try {
+  const result = await run(command, rest, opts);
+  print(result);
+  process.exitCode = result?.no_ship ? 1 : 0;
+} catch (error) {
+  print({ schema: 'agent-factory-pacman.error.v1', status: 'error', no_ship: true, message: error?.message || String(error) });
+  process.exitCode = 1;
+}
+
+async function run(cmd, args, options) {
+  switch (cmd) {
+    case 'prepare':
+    case 'prepare-run':
+      return prepareRun(args[0], options);
+    case 'auto':
+      return autoRun(args[0], options);
+    case 'status':
+      return statusRun(args[0]);
+    case 'validate':
+      return validateDemo(args[0]);
+    case 'help':
+    case '-h':
+    case '--help':
+      return help();
+    default:
+      throw new Error(`Unknown Agent Factory Pac-Man runtime command: ${cmd}`);
+  }
+}
+
+function help() {
+  return {
+    schema: 'agent-factory-pacman.help.v1',
+    status: 'pass',
+    no_ship: false,
+    commands: ['prepare [run_id] [--force]', 'auto [run_id] [--force]', 'status [run_id]', 'validate [run_id]'],
+    notes: [
+      'prepare writes mission/run artifacts and an empty reports/.../project target; it does not launch tmux or Pi and does not generate the game',
+      'auto prepares then starts the tmux team detached with pi @startup-kickoff files',
+      'the Pac-Man multiplayer project is generated by the ZTeam under reports/.../project, not prebuilt in examples/'
+    ],
+    launcher_ref: LAUNCHER_REF,
+    team_manifest_ref: TEAM_MANIFEST_REF,
+    brief_ref: BRIEF_REF
+  };
+}
+
+async function prepareRun(requestedRunId, options = {}) {
+  const runId = requestedRunId || defaultRunId();
+  validateRunId(runId);
+  const refs = buildRefs(runId);
+  const runDirAbs = path.resolve(PROJECT_ROOT, refs.run_dir);
+  await ensureFreshRunDir(runDirAbs, options.force === true);
+  await fs.mkdir(path.resolve(PROJECT_ROOT, refs.worker_kickoffs_dir), { recursive: true });
+  await fs.mkdir(path.resolve(PROJECT_ROOT, refs.project_dir), { recursive: true });
+
+  const mission = await fs.readFile(path.resolve(PROJECT_ROOT, MISSION_REF), 'utf8');
+  const outputContract = await fs.readFile(path.resolve(PROJECT_ROOT, OUTPUT_CONTRACT_REF), 'utf8');
+  await writeText(path.resolve(PROJECT_ROOT, refs.mission_ref), mission);
+  await writeText(path.resolve(PROJECT_ROOT, refs.output_contract_ref), outputContract);
+
+  const now = new Date().toISOString();
+  const manifest = {
+    schema: 'agent-factory-pacman.run-manifest.v1',
+    status: 'prepared',
+    no_ship: false,
+    run_id: runId,
+    run_dir: refs.run_dir,
+    project_dir: refs.project_dir,
+    team_id: TEAM_ID,
+    room: ROOM,
+    session: SESSION_NAME,
+    entry_agent: ENTRY_AGENT,
+    created_at: now,
+    refs: {
+      run_manifest_ref: refs.run_manifest_ref,
+      artifact_contracts_ref: refs.artifact_contracts_ref,
+      mission_ref: refs.mission_ref,
+      output_contract_ref: refs.output_contract_ref,
+      kickoff_ref: refs.kickoff_ref,
+      kickoff_dispatch_ref: refs.kickoff_dispatch_ref,
+      worker_kickoffs_dir: refs.worker_kickoffs_dir,
+      workgraph_ref: refs.workgraph_ref,
+      status_ref: refs.status_ref,
+      iteration_log_ref: refs.iteration_log_ref,
+      team_manifest_ref: TEAM_MANIFEST_REF,
+      launcher_ref: LAUNCHER_REF,
+      brief_ref: BRIEF_REF
+    },
+    policies: {
+      local_only: true,
+      parent_visible_only: true,
+      all_agents_startup_message_from_file: true,
+      post_start_tmux_paste_disabled: true,
+      generated_project_under_run_dir: true,
+      source_examples_prebuilt_game_allowed: false,
+      raw_body_persistence_allowed: false,
+      external_network_allowed: false,
+      commit_push_allowed: false
+    },
+    agents: [{ id: ENTRY_AGENT, alias: 'pacman_chief', role: 'lead' }, ...AGENTS]
+  };
+
+  const contracts = {
+    schema: 'agent-factory-pacman.artifact-contracts.v1',
+    status: 'active',
+    no_ship: false,
+    run_id: runId,
+    project_dir: refs.project_dir,
+    source_brief_refs: [MISSION_REF, OUTPUT_CONTRACT_REF],
+    required_generated_artifacts: [
+      `${refs.project_dir}/README.md`,
+      `${refs.project_dir}/AGENTS.md`,
+      `${refs.project_dir}/package.json`,
+      `${refs.project_dir}/src/game/engine.ts`,
+      `${refs.project_dir}/src/game/types.ts`,
+      `${refs.project_dir}/src/ui/main.ts`,
+      `${refs.project_dir}/src/ui/renderer.ts`,
+      `${refs.project_dir}/src/ui/input.ts`,
+      `${refs.project_dir}/test/engine.test.ts`,
+      `${refs.project_dir}/docs/architecture.md`,
+      `${refs.project_dir}/docs/controls.md`,
+      `${refs.project_dir}/docs/validation.md`
+    ],
+    final_gate: {
+      generated_project_validation_commands: ['npm install', 'npm run validate', 'npm run dev'],
+      parent_repo_validation_commands: ['npm run demo:pacman:validate', 'npm run check -- --pretty false'],
+      oracle_required: true
+    }
+  };
+
+  const chiefTemplate = await fs.readFile(path.resolve(PROJECT_ROOT, CHIEF_TEMPLATE_REF), 'utf8');
+  const workerTemplate = await fs.readFile(path.resolve(PROJECT_ROOT, WORKER_TEMPLATE_REF), 'utf8');
+  await writeText(path.resolve(PROJECT_ROOT, refs.kickoff_ref), render(chiefTemplate, {
+    RUN_ID: runId,
+    RUN_DIR: refs.run_dir,
+    PROJECT_DIR: refs.project_dir,
+    MISSION_REF: refs.mission_ref,
+    OUTPUT_CONTRACT_REF: refs.output_contract_ref,
+    RUN_MANIFEST_REF: refs.run_manifest_ref,
+    ARTIFACT_CONTRACTS_REF: refs.artifact_contracts_ref,
+    STATUS_REF: refs.status_ref,
+    ITERATION_LOG_REF: refs.iteration_log_ref
+  }));
+  for (const agent of AGENTS) {
+    await writeText(path.resolve(PROJECT_ROOT, refs.worker_kickoffs_dir, `${agent.id}-kickoff.md`), render(workerTemplate, {
+      RUN_ID: runId,
+      RUN_DIR: refs.run_dir,
+      PROJECT_DIR: refs.project_dir,
+      MISSION_REF: refs.mission_ref,
+      OUTPUT_CONTRACT_REF: refs.output_contract_ref,
+      AGENT_ID: agent.id,
+      ALIAS: agent.alias,
+      ROLE: agent.role,
+      MISSION: agent.mission,
+      RUN_MANIFEST_REF: refs.run_manifest_ref,
+      ARTIFACT_CONTRACTS_REF: refs.artifact_contracts_ref,
+      WORKGRAPH_REF: refs.workgraph_ref
+    }));
+  }
+
+  await writeJson(path.resolve(PROJECT_ROOT, refs.run_manifest_ref), manifest);
+  await writeJson(path.resolve(PROJECT_ROOT, refs.artifact_contracts_ref), contracts);
+  await writeText(path.resolve(PROJECT_ROOT, refs.workgraph_ref), initialWorkgraph(runId, refs));
+  await writeText(path.resolve(PROJECT_ROOT, refs.status_ref), initialStatus(runId, refs));
+  await writeText(path.resolve(PROJECT_ROOT, refs.iteration_log_ref), `# Iteration log — ${runId}\n\n- ${now}: prepared Pac-Man run artifacts and empty project target; tmux/Pi not launched by prepare; game not generated by prepare.\n`);
+
+  return {
+    schema: 'agent-factory-pacman.prepare.v1',
+    status: 'pass',
+    no_ship: false,
+    run_id: runId,
+    run_dir: refs.run_dir,
+    project_dir: refs.project_dir,
+    kickoff_ref: refs.kickoff_ref,
+    worker_kickoffs_dir: refs.worker_kickoffs_dir,
+    next_commands: {
+      auto: `npm run demo:pacman -- ${runId}`,
+      start_team: `AGENT_FACTORY_PACMAN_RUN_ID=${runId} AGENT_FACTORY_PACMAN_CHIEF_KICKOFF_FILE=${refs.kickoff_ref} AGENT_FACTORY_PACMAN_WORKER_KICKOFF_DIR=${refs.worker_kickoffs_dir} ${LAUNCHER_REF} start-detached ${ENTRY_AGENT}`,
+      attach_chief: `${LAUNCHER_REF} attach ${ENTRY_AGENT}`,
+      generated_project_after_agents: `cd ${refs.project_dir} && npm install && npm run validate && npm run dev`
+    }
+  };
+}
+
+async function autoRun(requestedRunId, options = {}) {
+  const prepared = await prepareRun(requestedRunId, options);
+  if (prepared.no_ship) return { schema: 'agent-factory-pacman.auto.v1', status: 'blocked', no_ship: true, phase: 'prepare', prepared };
+  const start = startTeam(prepared.run_id, prepared.kickoff_ref, prepared.worker_kickoffs_dir);
+  if (start.no_ship) return { schema: 'agent-factory-pacman.auto.v1', status: 'blocked', no_ship: true, phase: 'start-team', prepared, start };
+  const refs = buildRefs(prepared.run_id);
+  const dispatch = {
+    schema: 'agent-factory-pacman.kickoff-dispatch.v1',
+    status: 'pass',
+    no_ship: false,
+    run_id: prepared.run_id,
+    project_dir: prepared.project_dir,
+    session: SESSION_NAME,
+    transport: 'pi @startup-kickoff.md for chief and workers',
+    chief_kickoff_ref: prepared.kickoff_ref,
+    worker_kickoffs_dir: prepared.worker_kickoffs_dir,
+    agents: ALL_AGENTS,
+    created_at: new Date().toISOString()
+  };
+  await writeJson(path.resolve(PROJECT_ROOT, refs.kickoff_dispatch_ref), dispatch);
+  return {
+    schema: 'agent-factory-pacman.auto.v1',
+    status: 'launched',
+    no_ship: false,
+    run_id: prepared.run_id,
+    run_dir: prepared.run_dir,
+    project_dir: prepared.project_dir,
+    session: SESSION_NAME,
+    prepared,
+    start,
+    kickoff_dispatch_ref: refs.kickoff_dispatch_ref,
+    next_commands: {
+      attach_chief: `${LAUNCHER_REF} attach ${ENTRY_AGENT}`,
+      status: `${LAUNCHER_REF} status`,
+      generated_project_after_agents: `cd ${prepared.project_dir} && npm install && npm run validate && npm run dev`
+    }
+  };
+}
+
+function startTeam(runId, kickoffRef, workerKickoffsDir) {
+  const tmuxCheck = spawnSync('tmux', ['-V'], { encoding: 'utf8' });
+  if (tmuxCheck.status !== 0) return { status: 'blocked', no_ship: true, reason: 'tmux_missing', detail: 'tmux is required for full automatic demo launch' };
+  const existing = spawnSync('tmux', ['has-session', '-t', SESSION_NAME], { encoding: 'utf8' });
+  if (existing.status === 0) return { status: 'blocked', no_ship: true, reason: 'session_already_running', session: SESSION_NAME, detail: `${LAUNCHER_REF} status` };
+  const result = spawnSync('bash', [path.resolve(PROJECT_ROOT, LAUNCHER_REF), 'start-detached', ENTRY_AGENT], {
+    cwd: PROJECT_ROOT,
+    encoding: 'utf8',
+    env: { ...process.env, AGENT_FACTORY_PACMAN_RUN_ID: runId, AGENT_FACTORY_PACMAN_CHIEF_KICKOFF_FILE: path.resolve(PROJECT_ROOT, kickoffRef), AGENT_FACTORY_PACMAN_WORKER_KICKOFF_DIR: path.resolve(PROJECT_ROOT, workerKickoffsDir) }
+  });
+  if (result.status !== 0) return { status: 'blocked', no_ship: true, reason: 'launcher_failed', stderr: result.stderr, stdout: result.stdout };
+  return { status: 'started_detached', no_ship: false, session: SESSION_NAME, stdout: result.stdout.trim() };
+}
+
+async function statusRun(runId) {
+  const tmux = spawnSync('bash', [path.resolve(PROJECT_ROOT, LAUNCHER_REF), 'status'], { cwd: PROJECT_ROOT, encoding: 'utf8' });
+  const payload = { schema: 'agent-factory-pacman.status.v1', status: 'pass', no_ship: false, session: SESSION_NAME, tmux_status: tmux.stdout.trim() || tmux.stderr.trim() };
+  if (!runId) return payload;
+  const refs = buildRefs(sanitizeRunId(runId));
+  const manifest = await readJson(path.resolve(PROJECT_ROOT, refs.run_manifest_ref));
+  return { ...payload, run_id: sanitizeRunId(runId), manifest_found: Boolean(manifest), project_dir: refs.project_dir, manifest };
+}
+
+async function validateDemo(runId) {
+  const sourceChecks = [];
+  for (const ref of [
+    `${BRIEF_REF}/README.md`, `${BRIEF_REF}/AGENTS.md`, MISSION_REF, OUTPUT_CONTRACT_REF,
+    TEAM_MANIFEST_REF, LAUNCHER_REF, CHIEF_TEMPLATE_REF, WORKER_TEMPLATE_REF,
+    '.pi/zagents/agent-factory-pacman-chief.json', '.pi/zagents/agent-factory-pacman-game-designer.json', '.pi/zagents/agent-factory-pacman-game-architect.json', '.pi/zagents/agent-factory-pacman-engine-builder.json', '.pi/zagents/agent-factory-pacman-frontend-builder.json', '.pi/zagents/agent-factory-pacman-qa-oracle.json'
+  ]) sourceChecks.push(await fileCheck(ref));
+
+  const stalePrebuilt = await findPrebuiltSourceFiles();
+  const runChecks = [];
+  let generatedProjectStatus = 'not_checked';
+  if (runId) {
+    const refs = buildRefs(sanitizeRunId(runId));
+    for (const ref of [refs.run_manifest_ref, refs.artifact_contracts_ref, refs.mission_ref, refs.output_contract_ref, refs.kickoff_ref, refs.workgraph_ref, refs.status_ref, refs.iteration_log_ref]) runChecks.push(await fileCheck(ref));
+    generatedProjectStatus = await pathExists(path.resolve(PROJECT_ROOT, refs.project_dir)) ? 'target_dir_ready' : 'missing_target_dir';
+  }
+
+  const missing = [...sourceChecks, ...runChecks].filter((check) => !check.pass);
+  return {
+    schema: 'agent-factory-pacman.validate.v1',
+    status: missing.length || stalePrebuilt.length ? 'fail' : 'pass',
+    no_ship: Boolean(missing.length || stalePrebuilt.length),
+    source_checks: sourceChecks,
+    run_checks: runChecks,
+    stale_prebuilt_source_files: stalePrebuilt,
+    generated_project_status: generatedProjectStatus,
+    note: 'This validates the Pac-Man Agent Factory scaffold. It intentionally does not generate or build the game.'
+  };
+}
+
+async function findPrebuiltSourceFiles() {
+  const allowed = new Set(['README.md', 'AGENTS.md', 'mission.md', 'output-contract.md']);
+  const out = [];
+  for (const ref of await listFilesRecursive(path.resolve(PROJECT_ROOT, BRIEF_REF))) {
+    const rel = path.relative(path.resolve(PROJECT_ROOT, BRIEF_REF), ref);
+    if (!rel.includes(path.sep) && allowed.has(rel)) continue;
+    out.push(path.relative(PROJECT_ROOT, ref));
+  }
+  return out.sort();
+}
+
+async function listFilesRecursive(dir) {
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) files.push(...await listFilesRecursive(abs));
+      else if (entry.isFile()) files.push(abs);
+    }
+    return files;
+  } catch {
+    return [];
+  }
+}
+
+function buildRefs(runId) {
+  const runDir = `${RUNS_ROOT}/${runId}`;
+  return {
+    run_dir: runDir,
+    project_dir: `${runDir}/project`,
+    mission_ref: `${runDir}/mission.md`,
+    output_contract_ref: `${runDir}/output-contract.md`,
+    run_manifest_ref: `${runDir}/run-manifest.json`,
+    artifact_contracts_ref: `${runDir}/artifact-contracts.json`,
+    kickoff_ref: `${runDir}/chief-kickoff.md`,
+    kickoff_dispatch_ref: `${runDir}/kickoff-dispatch.json`,
+    worker_kickoffs_dir: `${runDir}/worker-kickoffs`,
+    workgraph_ref: `${runDir}/autonomous-workgraph.md`,
+    status_ref: `${runDir}/autonomous-status.md`,
+    iteration_log_ref: `${runDir}/iteration-log.md`
+  };
+}
+
+function initialWorkgraph(runId, refs) {
+  return `# Agent Factory Pac-Man Multiplayer workgraph — ${runId}\n\nGenerated project target: ${refs.project_dir}\n\n## Required lanes\n\n- [ ] game_designer: define Pac-Man multiplayer rules, controls, scoring, and playability acceptance criteria.\n- [ ] game_architect: design engine/UI/state boundaries and implementation order.\n- [ ] engine_builder: generate engine logic and tests under project/.\n- [ ] frontend_builder: generate browser rendering/input/HUD under project/.\n- [ ] qa_oracle: review playability, tests, validation evidence, and no-ship.\n\n## Inputs\n\n- ${refs.mission_ref}\n- ${refs.output_contract_ref}\n- ${refs.artifact_contracts_ref}\n`;
+}
+
+function initialStatus(runId, refs) {
+  return `# Agent Factory Pac-Man Multiplayer status — ${runId}\n\nstatus: prepared\nno_ship: false\nroom: ${ROOM}\nsession: ${SESSION_NAME}\nproject_dir: ${refs.project_dir}\n\nPrepare completed. The project directory is intentionally empty until the ZTeam generates the Pac-Man game.\n`;
+}
+
+async function fileCheck(ref) {
+  return { ref, pass: await pathExists(path.resolve(PROJECT_ROOT, ref)) };
+}
+async function pathExists(target) {
+  try { await fs.access(target); return true; } catch { return false; }
+}
+async function ensureFreshRunDir(runDirAbs, force) {
+  try {
+    const entries = await fs.readdir(runDirAbs);
+    if (entries.length && !force) throw new Error(`run dir already exists; pass --force or choose another run id: ${path.relative(PROJECT_ROOT, runDirAbs)}`);
+    if (force) await fs.rm(runDirAbs, { recursive: true, force: true });
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  await fs.mkdir(runDirAbs, { recursive: true });
+}
+function render(template, vars) { return template.replace(/\{\{([A-Z0-9_]+)\}\}/g, (_, key) => String(vars[key] ?? `{{${key}}}`)); }
+async function writeText(absPath, content) { await fs.mkdir(path.dirname(absPath), { recursive: true }); await fs.writeFile(absPath, content); }
+async function writeJson(absPath, value) { await writeText(absPath, `${JSON.stringify(value, null, 2)}\n`); }
+async function readJson(absPath) { try { return JSON.parse(await fs.readFile(absPath, 'utf8')); } catch { return undefined; } }
+function validateRunId(runId) { if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,80}$/.test(runId)) throw new Error(`invalid run id: ${runId}`); }
+function sanitizeRunId(runId) { const safe = String(runId || '').replace(/[^A-Za-z0-9_-]/g, '-').replace(/^-+|-+$/g, '').slice(0, 81); validateRunId(safe); return safe; }
+function defaultRunId() { return `pacman-${new Date().toISOString().replace(/[-:TZ.]/g, '').slice(0, 14)}`; }
+function print(value) { process.stdout.write(`${JSON.stringify(value, null, 2)}\n`); }

package/.pi/zteams/agent-factory-pacman-multiplayer.json

@@ -0,0 +1,42 @@
+{
+  "schema": "zob.zteam.v1",
+  "id": "agent-factory-pacman-multiplayer",
+  "description": "Runnable Agent Factory demo team: autonomously generates a local browser-playable Pac-Man-inspired multiplayer game under reports/agent-factory-pacman-runs/<run_id>/project/.",
+  "defaultRoom": "pacman-factory",
+  "activeRoom": "pacman-factory",
+  "rooms": [
+    { "id": "pacman-factory", "role": "parent-visible-coordination", "active": true }
+  ],
+  "members": [
+    { "id": "agent-factory-pacman-chief", "alias": "pacman_chief", "rooms": [{ "id": "pacman-factory", "alias": "pacman_chief", "role": "lead", "active": true }] },
+    { "id": "agent-factory-pacman-game-designer", "alias": "game_designer", "rooms": [{ "id": "pacman-factory", "alias": "game_designer", "role": "game_design", "active": true }] },
+    { "id": "agent-factory-pacman-game-architect", "alias": "game_architect", "rooms": [{ "id": "pacman-factory", "alias": "game_architect", "role": "architecture", "active": true }] },
+    { "id": "agent-factory-pacman-engine-builder", "alias": "engine_builder", "rooms": [{ "id": "pacman-factory", "alias": "engine_builder", "role": "engine", "active": true }] },
+    { "id": "agent-factory-pacman-frontend-builder", "alias": "frontend_builder", "rooms": [{ "id": "pacman-factory", "alias": "frontend_builder", "role": "frontend", "active": true }] },
+    { "id": "agent-factory-pacman-qa-oracle", "alias": "qa_oracle", "rooms": [{ "id": "pacman-factory", "alias": "qa_oracle", "role": "oracle", "active": true }] }
+  ],
+  "communicationPolicy": {
+    "allowedRooms": ["pacman-factory"],
+    "parentVisible": true,
+    "hiddenPeerChat": false,
+    "bodyStored": false,
+    "requiredLocalLive": false,
+    "goalRoomCanonical": true
+  },
+  "metadata": {
+    "entryAgent": "agent-factory-pacman-chief",
+    "entryRoom": "pacman-factory",
+    "manualReviewCommand": "/zteam launch-plan agent-factory-pacman-multiplayer",
+    "tmuxLauncher": ".pi/zteams/agent-factory-pacman-multiplayer.tmux.sh",
+    "runtimeScript": ".pi/zteams/agent-factory-pacman-multiplayer-runtime.mjs",
+    "runArtifactsDir": "reports/agent-factory-pacman-runs/<run_id>/",
+    "briefPath": "examples/agent-factory-pacman-multiplayer/",
+    "autoLaunchBehavior": "prepare run artifacts, render startup kickoff files, start tmux detached with one Pi session per ZAgent, and print generated-project test commands",
+    "notes": [
+      "Prepare/validate do not generate the game; only the launched ZTeam writes under reports/.../project/.",
+      "The game architect has bounded real architecture authority; builders must coordinate through pacman-factory.",
+      "The generated game must be local-only by default and must not be a dashboard/Mission Control app.",
+      "Full auto can consume model/API budget because it starts six Pi sessions."
+    ]
+  }
+}