zob-harness 0.2.0 → 0.3.1

package/README.md

@@ -1,114 +1,160 @@
 # ZOB Harness
 
-**A governed Pi harness for human-controlled agentic engineering.**
+**A governed Agent Factory for Pi.**
 
-ZOB Harness turns an open-ended coding-agent chat into a governed engineering loop: clear contracts, specialist agents, mode-aware workflows, safety gates, evidence reports, skeptical oracle review, and repeatable software factories.
+Launch teams of agents that communicate, build, validate, and turn repeatable workflows into reusable factories.
 
-It is for developers and evaluators who want agents to help with real repository work without losing the plot, touching secrets, silently committing, or declaring victory without proof.
+ZOB turns Pi from a single coding-agent chat into a supervised factory system: define a team, start a run, watch agent communication, review artifacts, and package successful workflows into factories that can create the next thing.
 
 ```text
 Human intent
-  -> six-part contract
-  -> scoped mode and tools
-  -> specialist agent or local implementation
-  -> validation evidence
-  -> oracle review / no-ship decision
-  -> reusable workflow when the pattern repeats
+  -> governed Agent Factory
+  -> chief / scout / builder / oracle / custom roles
+  -> visible agent communication
+  -> tmux-backed Pi sessions when useful
+  -> artifacts under reports/<run_id>/
+  -> validation + oracle/no-ship review
+  -> reusable factory for the next run
 ```
 
-ZOB is not an “unleash the agent” project. It is a control plane for making agent work reviewable, bounded, and repeatable.
+ZOB is not “unleash an agent and hope.” ZOB is “launch a team, keep the work observable, preserve evidence, and reuse the pattern once it works.”
 
-## Why ZOB exists
+## Why this is different
 
-Normal coding-agent sessions can be impressive and still fail in predictable ways:
+Most agent tools optimize the single assistant session. ZOB optimizes the **agent factory loop**:
 
-- The agent drifts from the task or expands scope.
-- Research, planning, implementation, and review blur together.
-- Delegated work comes back without enough evidence.
-- Generated artifacts mix with source files.
-- Safety rules live in prose instead of enforceable gates.
-- “Done” is claimed before commands, diffs, and blockers are visible.
+- **Teams, not tabs** — model a chief, scouts, builders, reviewers, oracles, and custom roles as ZAgents/ZTeams.
+- **Visible communication** — agents coordinate through parent-visible messages instead of hidden worker chat.
+- **tmux-backed runs** — launch real Pi sessions in local tmux windows when a workflow benefits from persistent roles.
+- **Run artifacts as truth** — manifests, kickoff files, workgraphs, status files, validation output, and oracle reports outlive the chat.
+- **Factories create factories** — a successful workflow can become a reusable manifest, launcher, checkpoint set, and validation ladder.
+- **Governed by default** — scoped tools, path rules, evidence gates, no-ship review, and governed commits keep the owner in control.
 
-ZOB adds an operating layer around Pi so each step has a job, a boundary, and an audit trail.
+## Try the six-agent Pac-Man factory
 
-## What you get
+The fastest way to understand ZOB is to run the demo factory. The repository does **not** contain a prebuilt game. The factory prepares a run, launches a six-agent team, and asks that team to generate a local browser-playable Pac-Man-inspired multiplayer game under `reports/`.
 
-### 1. Contract-first delegation
+Prepare and validate run artifacts only. This does not launch tmux/Pi and does not generate the game:
 
-Every delegated task can be expressed as a six-part contract:
+```bash
+RUN_ID="pacman-demo"
+npm run demo:pacman:prepare -- "$RUN_ID" --force
+npm run demo:pacman:validate -- "$RUN_ID"
+```
 
-```text
-1. TASK: [atomic goal]
-2. EXPECTED OUTCOME: [observable deliverable/verdict]
-3. REQUIRED TOOLS: [allowed tools only]
-4. MUST DO: [positive constraints]
-5. MUST NOT DO: [hard stops]
-6. CONTEXT: [paths, prior evidence, downstream use]
+Launch the full tmux-backed Agent Factory team:
+
+```bash
+RUN_ID="pacman-demo"
+npm run demo:pacman -- "$RUN_ID" --force
 ```
 
-This keeps child work bounded and makes review easier: what changed, what was verified, what remains risky, and what should stop shipment.
+Observe or stop only this demo team:
 
-### 2. Mode-aware engineering loops
+```bash
+bash .pi/zteams/agent-factory-pacman-multiplayer.tmux.sh status
+bash .pi/zteams/agent-factory-pacman-multiplayer.tmux.sh attach agent-factory-pacman-chief
+bash .pi/zteams/agent-factory-pacman-multiplayer.tmux.sh close
+```
 
-ZOB separates the work into explicit modes:
+After the agents finish, test the generated project from the reported run directory, typically:
 
-- **Explore** — inspect and map facts without editing.
-- **Plan** — turn evidence into a bounded implementation path.
-- **Implement** — change the smallest safe file set and verify it.
-- **Oracle** — review skeptically and surface no-ship blockers.
-- **Factory** — convert repeatable workflows into manifests, checkpoints, sentinels, and smoke gates.
-- **Orchestrator** — coordinate goals, TODO graphs, and specialist handoffs without bypassing safety.
+```bash
+cd reports/agent-factory-pacman-runs/$RUN_ID/project
+npm install
+npm run validate
+npm run dev
+```
+
+See [`examples/agent-factory-pacman-multiplayer/`](examples/agent-factory-pacman-multiplayer/) for the demo brief and [`examples/agent-factory-tmux-comms/`](examples/agent-factory-tmux-comms/) for the small generic tmux + visible communication playbook.
 
-For non-trivial work, the default loop is:
+## Agents communicate visibly
+
+ZOB teams coordinate with short, structured, parent-visible messages. The goal is to keep multi-agent work debuggable without persisting raw hidden chat as the source of truth.
 
 ```text
-Explore -> Plan -> Implement -> Oracle
+CONTEXT: what changed or what the agent is working on
+ASK: exact answer, review, or action needed
+EVIDENCE: safe file refs, artifact refs, command names, or TODO ids
+URGENCY: low|normal|high|critical
+BLOCKER: yes/no
 ```
 
-### 3. Specialist agents and domain skills
+Example chief → scout ask:
 
-The repo includes reusable operating assets for focused work:
+```text
+CONTEXT: We are preparing the first implementation slice for the settings workflow.
+ASK: Identify the smallest files needed for a safe plan; return evidence refs only.
+EVIDENCE: README.md, docs/settings.md, TODO SETTINGS-001
+URGENCY: normal
+BLOCKER: no
+```
 
-- [`.pi/agents/`](.pi/agents/) — specialist roles for exploration, planning, implementation, QA, oracle review, synthesis, ProjectDNA, and more.
-- [`.pi/skills/`](.pi/skills/) — domain instructions for commits, coms, factories, sandboxing, ProjectDNA, autonomy checks, goal/TODO trees, oracle review, and harness routing.
-- [`.pi/output-contracts/`](.pi/output-contracts/) — structured completion contracts for child results and other governed outputs.
-- [`.pi/capabilities/`](.pi/capabilities/) — runtime capability registry that maps public tools/commands to modes, skills, docs, and no-ship notes.
+Example builder → oracle review request:
 
-The goal is not to make prompts longer. The goal is to route the right instructions only when a task needs them.
+```text
+CONTEXT: Builder generated the first game loop under the Pac-Man run project.
+ASK: Review game rules and validation output before the chief calls this done.
+EVIDENCE: reports/agent-factory-pacman-runs/pacman-demo/project/src/game.ts, npm run validate
+URGENCY: normal
+BLOCKER: no
+```
 
-### 4. Evidence-gated completion
+Communication is coordination. **Artifacts are the source of truth.**
 
-A ZOB result should make review straightforward. Agents are expected to report:
+## A factory that creates factories
 
-- exact files changed;
-- exact commands run;
-- command outcomes;
-- evidence references;
-- unresolved risks and blockers;
-- compliance with forbidden paths, commit policy, and scope.
+ZOB is designed for the moment when an agent workflow works once and should not remain an ad hoc prompt forever.
 
-That evidence posture is built into the project instructions in [AGENTS.md](AGENTS.md), the source map in [SOURCE_INDEX.md](SOURCE_INDEX.md), and the validation helpers in [scripts/README.md](scripts/README.md).
+A ZOB factory can define:
 
-### 5. Safety-first local operation
+- a ZTeam topology and role aliases;
+- role-specific ZAgent prompts and domain skills;
+- tmux launch/status/attach/close scripts;
+- startup kickoff files passed as `pi @file`;
+- run manifests and dispatch metadata;
+- parent-owned workgraphs and TODO trees;
+- validation checkpoints, sentinels, and smoke gates;
+- oracle/no-ship review requirements;
+- generated artifact directories under `reports/<run_id>/`;
+- npm scripts that make the workflow repeatable.
 
-ZOB is deliberately conservative around risky actions:
+The output of a ZOB run can be another ZOB factory: a reusable manifest, launcher, kickoff set, workgraph, and validation ladder for the next class of work.
 
-- no `.env`, private key, SSH, AWS, or credential reads;
-- no destructive shell/git operations without explicit approval;
-- no direct commits, pushes, tags, or force pushes by default;
-- governed commits go through `/zcommit` only when explicitly authorized;
-- generated reports, ledgers, sessions, and local coordination state stay local;
-- autonomy checks are supervised evidence, not a claim of unrestricted autonomy.
+Existing factory-shaped surfaces include:
+
+- [`examples/agent-factory-tmux-comms/`](examples/agent-factory-tmux-comms/) — smallest teaching shape for a chief, scout, builder, and oracle.
+- [`examples/agent-factory-pacman-multiplayer/`](examples/agent-factory-pacman-multiplayer/) — runnable generative team demo.
+- [`.pi/factories/`](.pi/factories/) — safe factory scaffolds for repeatable workflows such as ProjectDNA, agentic spec work, budget preflight, code review matrices, and factory forging.
 
-The safety posture is backed by [`.pi/damage-control-rules.json`](.pi/damage-control-rules.json), [`.pi/git-policy.json`](.pi/git-policy.json), the child-safety extension, and smoke scripts under [`scripts/`](scripts/README.md).
+## What a ZOB run produces
 
-### 6. Factories for repeatable work
+A serious run should leave reviewable evidence, not just a chat transcript:
+
+```text
+reports/<run_id>/
+  run-manifest.json
+  chief-kickoff.md
+  worker-kickoffs/
+  autonomous-workgraph.md
+  autonomous-status.md
+  iteration-log.md
+  validation-output.*
+  oracle-report.*
+  project/ or generated-artifacts/
+```
 
-When a workflow repeats, ZOB can turn it into a factory-shaped process: manifest, checkpoints, sentinels, smoke/pilot/batch gates, artifacts, and oracle review. The repository includes safe scaffolds under [`.pi/factories/`](.pi/factories/) and validation commands for public, reproducible workflows.
+The exact shape depends on the factory, but the posture is consistent: bounded inputs, visible coordination, durable artifacts, validation commands, and explicit risks/blockers.
 
-### 7. Local code knowledge with ProjectDNA
+## Core concepts
 
-ProjectDNA scaffolding helps turn approved local code scan artifacts into bounded, cited context packs and sample/spec outputs. The public posture is intentionally safe: read-only approved sources, generated artifacts under `reports/`, and no external knowledge-backend import/sync/embed/write unless explicitly approved.
+- **ZAgent** — a full Pi session with identity, role, allowed posture, and optional ZPeer presence.
+- **ZTeam** — topology for rooms, aliases, owner-facing entry points, and communication policy.
+- **Chief / orchestrator** — the parent-facing role that owns the workgraph, status, and final synthesis.
+- **Scout / builder / oracle** — common role pattern for context discovery, artifact production, and skeptical review.
+- **Kickoff file** — bounded startup context passed as `pi @file`, safer than pasting long prompts into live panes.
+- **Goal/TODO graph** — parent-owned work breakdown where child claims are reviewed before acceptance.
+- **No-ship gate** — explicit blocker status that prevents unsupported “done” claims.
 
 ## Quick start
 
@@ -117,19 +163,20 @@ ProjectDNA scaffolding helps turn approved local code scan artifacts into bounde
 - Node.js **22+**; Node 24 is recommended.
 - npm.
 - Pi installed and available on `PATH`.
+- tmux for tmux-backed Agent Factory demos.
 
 ### Install from npm for normal Pi use
 
 After the package is published to npm, install the pinned Pi package:
 
 ```bash
-pi install npm:zob-harness@0.1.0
+pi install npm:zob-harness@0.3.1
 ```
 
-Then verify that Pi can load the package extension set and return a deterministic response:
+Verify Pi can load the package extension set and return a deterministic response:
 
 ```bash
-pi -e npm:zob-harness@0.1.0 --offline --no-session -p "Reply exactly: zob-harness-ok"
+pi -e npm:zob-harness@0.3.1 --offline --no-session -p "Reply exactly: zob-harness-ok"
 ```
 
 Expected result:
@@ -141,13 +188,13 @@ zob-harness-ok
 If `pi install` cannot find the package, confirm the npm release is visible first:
 
 ```bash
-npm view zob-harness@0.1.0 version
+npm view zob-harness@0.3.1 version
 ```
 
 Expected result:
 
 ```text
-0.1.0
+0.3.1
 ```
 
 Pi package discovery on `pi.dev/packages` is based on the npm `pi-package` keyword and may lag behind npm publication.
@@ -160,6 +207,7 @@ Use this path when developing or validating a release candidate before npm publi
 git clone https://github.com/cgarrot/zob-harness.git
 cd zob-harness
 npm install
+npm run validate:script-surface
 npm run check -- --pretty false
 npm run pi:check
 npm run pack:dry-run
@@ -167,9 +215,10 @@ npm run pack:dry-run
 
 Expected results:
 
-- TypeScript completes with exit code 0 and no diagnostics.
-- Pi loads the local configured ZOB extension offline and replies with `zob-harness-ok`.
-- `npm pack --dry-run --json` lists the Pi manifest, extensions, prompts, skills, agents, and validation scripts in the tarball.
+- script references validate;
+- TypeScript completes with exit code 0 and no diagnostics;
+- Pi loads the local configured ZOB extension offline and replies with `zob-harness-ok`;
+- `npm pack --dry-run --json` lists the Pi manifest, extensions, prompts, skills, agents, examples, and validation scripts in the tarball.
 
 ### Start Pi with the local harness checkout
 
@@ -187,49 +236,54 @@ Inside Pi, try:
 
 You should see ZOB modes, specialist agents, and the six-part delegation contract helper.
 
-### Public smoke baseline
+## Common workflows
 
-```bash
-npm run validate:script-surface
-npm run smoke:harness
-npm run check -- --pretty false
-npm run pack:dry-run
-```
+### Launch a tmux-backed Agent Factory team
 
-These commands verify the public script surface, core path/child-goal smokes, TypeScript baseline, and npm package surface.
+Use an Agent Factory when the job needs multiple persistent roles rather than one transient assistant. The pattern is:
 
-## Common workflows
+1. define a ZTeam manifest with parent-visible rooms and `bodyStored=false`;
+2. prepare startup kickoff files so each agent begins with bounded instructions;
+3. launch one Pi session per ZAgent through a tmux launcher when useful;
+4. coordinate with async ZPeer/Goal Room-style messages using `CONTEXT / ASK / EVIDENCE / URGENCY / BLOCKER`;
+5. treat artifacts, validation commands, and oracle review as completion evidence.
+
+### Turn repeated work into a factory
 
-### A safe single-agent implementation loop
+When a process repeats, stop re-prompting it by hand. Capture the workflow as:
 
 ```text
-1. Ask for Explore: inspect files and state a gap verdict.
-2. Ask for Plan: name the smallest file set and validation ladder.
-3. Ask for Implement: edit only that slice.
-4. Ask for Oracle: verify evidence and decide whether no-ship remains.
+manifest + team topology + kickoff templates + workgraph + checkpoints + validator + oracle gate
 ```
 
-This keeps implementation from starting before the repo facts and stop conditions are clear.
+Then expose it through an npm script or project-local launcher so the next run starts from a known shape.
 
-### Delegating work to a specialist
+### Use a safe single-agent loop
 
-Use `/contract` to create a bounded handoff, then route to an appropriate specialist agent. A good delegated result should come back with changed files, validation commands, evidence refs, risks, and no-ship status for parent/oracle review.
+```text
+Explore -> Plan -> Implement -> Oracle
+```
 
-### Goal-linked TODO work
+- **Explore** — inspect and map facts without editing.
+- **Plan** — turn evidence into a bounded implementation path.
+- **Implement** — change the smallest safe file set and verify it.
+- **Oracle** — review skeptically and surface no-ship blockers.
 
-Use `/goal`, `/todo`, and `/goal_gate` when work needs a parent-owned TODO graph. Child agents return claims; the parent decides acceptance. This prevents children from marking parent work done without review.
+### Delegate to a specialist
 
-### Governed commits
+Use `/contract` to create a bounded six-part handoff, then route to the appropriate specialist agent. A good delegated result should return changed files, validation commands, evidence refs, risks, and no-ship status for parent/oracle review.
 
-ZOB does not encourage invisible git operations. When a user explicitly asks for a commit, agents must use `/zcommit` and follow [`.pi/git-policy.json`](.pi/git-policy.json). Autocommit and autopush are off by default.
+### Use goal-linked TODOs
 
-### Repeatable factory runs
+Use `/goal`, `/todo`, and `/goal_gate` when work needs a parent-owned TODO graph. Child agents return claims; the parent decides acceptance. This prevents children from marking parent work done without review.
 
-For recurring tasks, use factory scaffolds rather than ad hoc repetition. Factories should keep manifests, checkpoints, sentinels, generated artifacts, smoke gates, and oracle evidence visible.
+### Use ProjectDNA context
 
-### Bounded ProjectDNA context
+ProjectDNA turns approved local code scan artifacts into bounded, cited context packs and sample/spec outputs. Keep scans approved, artifacts local, and writeback proposal-only unless the parent explicitly authorizes more.
 
-Use ProjectDNA commands and scripts when a task needs cited local code context. Keep scans approved, artifacts local, and writeback proposal-only unless the parent explicitly authorizes more.
+### Use governed commits
+
+ZOB does not encourage invisible git operations. When a user explicitly asks for a commit, agents must use `/zcommit` or the governed `zob_zcommit_run` tool and follow [`.pi/git-policy.json`](.pi/git-policy.json). Autocommit and autopush are off by default.
 
 ## Command cheat sheet
 
@@ -260,14 +314,17 @@ npm run smoke:worker-pool          # worker-pool static smoke
 npm run smoke:zpeer                # static + local ZPeer smoke
 npm run validate:project-dna       # ProjectDNA scaffold validation
 npm run pack:dry-run               # npm package dry-run surface check
+npm run demo:pacman:prepare        # prepare Pac-Man factory run artifacts
+npm run demo:pacman:validate       # validate Pac-Man factory run artifacts
+npm run demo:pacman                # launch the full Pac-Man Agent Factory demo
 ```
 
 Published package install/check:
 
 ```bash
-pi install npm:zob-harness@0.1.0
-pi -e npm:zob-harness@0.1.0 --offline --no-session -p "Reply exactly: zob-harness-ok"
-npm view zob-harness@0.1.0 version
+pi install npm:zob-harness@0.3.1
+pi -e npm:zob-harness@0.3.1 --offline --no-session -p "Reply exactly: zob-harness-ok"
+npm view zob-harness@0.3.1 version
 ```
 
 See [scripts/README.md](scripts/README.md) for the script family map.
@@ -281,6 +338,7 @@ See [scripts/README.md](scripts/README.md) for the script family map.
 - [SOURCE_INDEX.md](SOURCE_INDEX.md) — tracked source and local/generated area map.
 - [package.json](package.json) — package metadata, Pi wiring, and npm scripts.
 - [scripts/README.md](scripts/README.md) — public script surface guide.
+- [`examples/`](examples/) — Agent Factory examples, including the generic tmux/coms playbook and the runnable Pac-Man multiplayer generative demo.
 - [`.pi/extensions/zob-harness/`](.pi/extensions/zob-harness/) — main Pi extension.
 - [`.pi/extensions/zob-child-safety/`](.pi/extensions/zob-child-safety/) — child-agent safety extension.
 - [`.pi/agents/`](.pi/agents/) — specialist agent definitions.
@@ -293,9 +351,24 @@ See [scripts/README.md](scripts/README.md) for the script family map.
 
 Local/generated areas such as `reports/`, `plans/`, `.pi/sessions/`, `.pi/logs/`, `.pi/tmp/`, coms ledgers, workspace claims, worker pools, and merge queues are not part of the normal source surface. See [SOURCE_INDEX.md](SOURCE_INDEX.md) for the current classification.
 
+## Safety model
+
+ZOB is deliberately conservative around risky actions:
+
+- no `.env`, private key, SSH, AWS, or credential reads;
+- no destructive shell/git operations without explicit approval;
+- no direct commits, pushes, tags, or force pushes by default;
+- governed commits go through `/zcommit` or `zob_zcommit_run` only when explicitly authorized;
+- tmux is a launch/observation layer, not the source of truth;
+- generated reports, ledgers, sessions, and local coordination state stay local;
+- autonomy checks are supervised evidence, not a claim of unrestricted autonomy;
+- completion requires concrete artifacts, validation evidence, and oracle/no-ship review when required.
+
+The safety posture is backed by [AGENTS.md](AGENTS.md), [`.pi/damage-control-rules.json`](.pi/damage-control-rules.json), [`.pi/git-policy.json`](.pi/git-policy.json), the child-safety extension, and smoke scripts under [`scripts/`](scripts/README.md).
+
 ## Current status and limits
 
-ZOB Harness is an early, conservative, governed harness. The public repo is useful for evaluating the operating model, extension wiring, skills, agents, safety posture, and smoke validations. It should not be described as unrestricted autonomy, a production deployment system, or a benchmark-winning agent framework.
+ZOB Harness is an early, conservative, governed harness. The public repo is useful for evaluating the Agent Factory operating model, extension wiring, skills, agents, safety posture, and smoke validations. It should not be described as unrestricted autonomy, a production deployment system, or a benchmark-winning agent framework.
 
 Current limits are intentional:
 
@@ -330,12 +403,12 @@ For a public npm release, maintainers should additionally run:
 
 ```bash
 npm whoami
-npm view zob-harness@0.1.0 version || true
+npm view zob-harness@0.3.1 version || true
 npm publish --dry-run
 npm publish
-npm view zob-harness@0.1.0 version
-pi install npm:zob-harness@0.1.0
-pi -e npm:zob-harness@0.1.0 --offline --no-session -p "Reply exactly: zob-harness-ok"
+npm view zob-harness@0.3.1 version
+pi install npm:zob-harness@0.3.1
+pi -e npm:zob-harness@0.3.1 --offline --no-session -p "Reply exactly: zob-harness-ok"
 ```
 
 `npm publish` may require npm two-factor authentication in the browser or a one-time password. Do not paste OTPs, tokens, or secrets into issue reports or agent transcripts.

package/SOURCE_INDEX.md

@@ -31,11 +31,15 @@ This file is the human-facing map of the tracked source surface. It is intention
 
 See `scripts/README.md` for the script surface map.
 
+## Examples
+
+- `examples/` — documentation examples for safe ZOB patterns, including `agent-factory-tmux-comms/` and the active `agent-factory-pacman-multiplayer/` generative demo brief. These examples must stay inert by default and must not launch agents, tmux, network access, commits, or destructive commands unless a human runs the documented command explicitly.
+
 ## Local/generated areas
 
 These are intentionally local/generated and should not be committed by default:
 
-- `docs/` — legacy/internal docs for now; future curated docs should be recreated intentionally.
+- `docs/` — curated architecture/refactor docs plus local/generated planning docs; classify generated reports separately before commit.
 - `plans/` — captured planning artifacts.
 - `reports/` — generated reports and evidence.
 - `.pi/tmp/`, `.pi/logs/`, `.pi/sessions/`, `.pi/agent-sessions/` — runtime local state.

package/examples/agent-factory-mission-control/AGENTS.md

@@ -0,0 +1,10 @@
+# Deprecated Mission Control example
+
+This directory is no longer active. The former dashboard-focused team has been removed and replaced by:
+
+```text
+examples/agent-factory-pacman-multiplayer/
+.pi/zteams/agent-factory-pacman-multiplayer.json
+```
+
+Do not add generated source code here.

package/examples/agent-factory-mission-control/README.md

@@ -0,0 +1,17 @@
+# Deprecated example — replaced by Pac-Man multiplayer
+
+This former Mission Control dashboard brief is deprecated and no longer wired to active npm scripts, ZAgents, or ZTeams.
+
+Use the current generative demo instead:
+
+```text
+examples/agent-factory-pacman-multiplayer/
+```
+
+```bash
+npm run demo:pacman:prepare
+npm run demo:pacman:validate
+npm run demo:pacman
+```
+
+No game or dashboard code should be generated in this deprecated directory.

package/examples/agent-factory-mission-control/apps/api/AGENTS.md

@@ -0,0 +1,3 @@
+# Deprecated placeholder
+
+The old Mission Control API demo was removed from active launch paths. Do not add source code here.

package/examples/agent-factory-mission-control/apps/dashboard/AGENTS.md

@@ -0,0 +1,3 @@
+# Deprecated placeholder
+
+The old Mission Control dashboard demo was removed from active launch paths. Do not add source code here.

package/examples/agent-factory-mission-control/mission.md

@@ -0,0 +1,3 @@
+# Deprecated mission
+
+The Mission Control dashboard mission is retired. Use `examples/agent-factory-pacman-multiplayer/mission.md`.

package/examples/agent-factory-mission-control/output-contract.md

@@ -0,0 +1,3 @@
+# Deprecated output contract
+
+The Mission Control dashboard output contract is retired. Use `examples/agent-factory-pacman-multiplayer/output-contract.md`.

package/examples/agent-factory-mission-control/packages/domain/AGENTS.md

@@ -0,0 +1,3 @@
+# Deprecated placeholder
+
+The old Mission Control domain package was removed from active launch paths. Do not add source code here.

package/examples/agent-factory-mission-control/packages/snapshot-reader/AGENTS.md

@@ -0,0 +1,3 @@
+# Deprecated placeholder
+
+The old Mission Control snapshot-reader package was removed from active launch paths. Do not add source code here.

package/examples/agent-factory-pacman-multiplayer/AGENTS.md

@@ -0,0 +1,27 @@
+# Agent Factory Pac-Man Multiplayer brief rules
+
+This directory is a source brief only. The generated game belongs under:
+
+```text
+reports/agent-factory-pacman-runs/<run_id>/project/
+```
+
+## Allowed source files here
+
+- `README.md`
+- `AGENTS.md`
+- `mission.md`
+- `output-contract.md`
+
+## MUST DO
+
+- Keep this folder as a brief/contract surface only.
+- Tell agents to generate Pac-Man multiplayer code under the run `project/` directory.
+- Keep communication parent-visible and local-only.
+
+## MUST NOT
+
+- Do not add generated game source files here.
+- Do not create a dashboard/Mission Control app.
+- Do not read secrets, `.pi/sessions`, `.pi/coms` raw bodies, or private transcripts.
+- Do not commit/push/tag.

package/examples/agent-factory-pacman-multiplayer/README.md

@@ -0,0 +1,84 @@
+# Agent Factory Pac-Man Multiplayer — generative demo brief
+
+This folder is **not** the game. It is the brief used by a ZOB Agent Factory team.
+
+Run artifacts are prepared under:
+
+```text
+reports/agent-factory-pacman-runs/<run_id>/
+```
+
+The agents must generate the actual Pac-Man multiplayer project under:
+
+```text
+reports/agent-factory-pacman-runs/<run_id>/project/
+```
+
+## What the team should generate
+
+A local browser-playable Pac-Man-inspired multiplayer game:
+
+- 2 to 4 local players by default;
+- maze/grid movement, pellets, score, collisions, win/lose conditions;
+- ghosts or hostile obstacles;
+- deterministic game engine/state model with tests;
+- browser UI using Canvas or DOM rendering;
+- clear controls and README instructions;
+- local-only by default, no external services.
+
+The team may choose a small dependency-light stack, but it must validate whatever it generates.
+
+## Communication and tmux guide
+
+Before running the full demo, read [`../agent-factory-tmux-comms/`](../agent-factory-tmux-comms/) for the communication pattern:
+
+- one parent-visible room;
+- short `CONTEXT / ASK / EVIDENCE / URGENCY / BLOCKER` messages;
+- startup kickoff files passed as `pi @file`;
+- tmux as a local launcher/observer only;
+- artifacts and validation as completion evidence.
+
+## Safe dry run
+
+Prepare run artifacts only; this does **not** launch tmux/Pi and does **not** generate the game:
+
+```bash
+RUN_ID="pacman-demo"
+npm run demo:pacman:prepare -- "$RUN_ID" --force
+npm run demo:pacman:validate -- "$RUN_ID"
+```
+
+## Full autonomous launch
+
+This may launch multiple Pi sessions in tmux and consume model/API budget:
+
+```bash
+RUN_ID="pacman-demo"
+npm run demo:pacman -- "$RUN_ID" --force
+```
+
+## Observe or stop the tmux team
+
+```bash
+bash .pi/zteams/agent-factory-pacman-multiplayer.tmux.sh status
+bash .pi/zteams/agent-factory-pacman-multiplayer.tmux.sh attach agent-factory-pacman-chief
+bash .pi/zteams/agent-factory-pacman-multiplayer.tmux.sh close
+```
+
+## Test the generated game
+
+After agents finish, test the generated game from the reported project directory, typically:
+
+```bash
+cd reports/agent-factory-pacman-runs/$RUN_ID/project
+npm install
+npm run validate
+npm run dev
+```
+
+## Important boundaries
+
+- Do not generate game code in this `examples/` folder.
+- Do not read secrets or raw session/coms bodies.
+- Do not commit/push from the demo team.
+- Treat tmux as a local launcher only; communication must stay parent-visible.