zob-harness 0.2.0 → 0.3.1

package/.pi/zteams/agentic-spec-run.json

@@ -0,0 +1,42 @@
+{
+  "schema": "zob.zteam.v1",
+  "id": "agentic-spec-run",
+  "description": "Temporary run-scoped Agentic Spec Team for turning explicit sources plus mission text into a traceable implementation spec.",
+  "defaultRoom": "spec-control",
+  "activeRoom": "spec-control",
+  "rooms": [
+    { "id": "spec-control", "role": "coordination", "active": true },
+    { "id": "intake", "role": "source-intake", "active": true },
+    { "id": "data", "role": "data-analysis", "active": true },
+    { "id": "domain", "role": "domain-modeling", "active": true },
+    { "id": "ux", "role": "ux-analysis", "active": true },
+    { "id": "writing", "role": "spec-writing", "active": true },
+    { "id": "validation", "role": "acceptance-bdd", "active": true },
+    { "id": "handoff", "role": "implementation-handoff", "active": true },
+    { "id": "oracle", "role": "final-review", "active": true }
+  ],
+  "agents": [
+    { "id": "spec-chief", "alias": "spec_chief", "rooms": [{ "id": "spec-control", "alias": "spec_chief", "role": "lead", "active": true }] },
+    { "id": "source-intake-steward", "alias": "source_intake", "rooms": [{ "id": "spec-control", "alias": "source_intake", "role": "member", "active": true }, { "id": "intake", "alias": "source_intake", "role": "steward", "active": true }] },
+    { "id": "data-profile-analyst", "alias": "data_profile", "rooms": [{ "id": "spec-control", "alias": "data_profile", "role": "member", "active": true }, { "id": "data", "alias": "data_profile", "role": "analyst", "active": true }] },
+    { "id": "domain-modeler", "alias": "domain_modeler", "rooms": [{ "id": "spec-control", "alias": "domain_modeler", "role": "member", "active": true }, { "id": "domain", "alias": "domain_modeler", "role": "modeler", "active": true }] },
+    { "id": "ux-flow-analyst", "alias": "ux_flow", "rooms": [{ "id": "spec-control", "alias": "ux_flow", "role": "member", "active": true }, { "id": "ux", "alias": "ux_flow", "role": "analyst", "active": true }] },
+    { "id": "spec-writer", "alias": "spec_writer", "rooms": [{ "id": "spec-control", "alias": "spec_writer", "role": "member", "active": true }, { "id": "writing", "alias": "spec_writer", "role": "writer", "active": true }] },
+    { "id": "bdd-writer", "alias": "bdd_writer", "rooms": [{ "id": "spec-control", "alias": "bdd_writer", "role": "member", "active": true }, { "id": "validation", "alias": "bdd_writer", "role": "acceptance", "active": true }] },
+    { "id": "planner-handoff-writer", "alias": "handoff_writer", "rooms": [{ "id": "spec-control", "alias": "handoff_writer", "role": "member", "active": true }, { "id": "handoff", "alias": "handoff_writer", "role": "planner", "active": true }] },
+    { "id": "spec-oracle", "alias": "spec_oracle", "rooms": [{ "id": "spec-control", "alias": "spec_oracle", "role": "oracle", "active": true }, { "id": "oracle", "alias": "spec_oracle", "role": "oracle", "active": true }] }
+  ],
+  "communicationPolicy": {
+    "zpeerContact": true,
+    "allowedRooms": ["spec-control", "intake", "data", "domain", "ux", "writing", "validation", "handoff", "oracle"],
+    "parentVisible": true,
+    "hiddenPeerChat": false,
+    "bodyStored": false
+  },
+  "metadata": {
+    "entryAgent": "spec-chief",
+    "temporaryRunTeam": true,
+    "humanInterlocutor": "spec-chief",
+    "closePolicy": "close only after final-report/status PASS no_ship=false"
+  }
+}

package/.pi/zteams/agentic-spec-run.tmux.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PROJECT_DIR="/Users/cgarrot/zob/zob-harness"
+ENTRY_AGENT="spec-chief"
+PI_BIN="/Users/cgarrot/.nvm/versions/node/v24.14.0/bin/pi"
+AGENTS=(
+  "spec-chief"
+  "source-intake-steward"
+  "data-profile-analyst"
+  "domain-modeler"
+  "ux-flow-analyst"
+  "spec-writer"
+  "bdd-writer"
+  "planner-handoff-writer"
+  "spec-oracle"
+)
+
+require_tmux() {
+  command -v tmux >/dev/null 2>&1 || { echo "tmux is required" >&2; exit 1; }
+}
+
+safe_token() {
+  printf '%s' "${1:-}" | tr -c 'A-Za-z0-9_-' '-' | sed 's/^-*//; s/-*$//; s/--*/-/g' | cut -c1-120
+}
+
+session_name() {
+  local run_id="$(safe_token "${1:-}")"
+  [ -n "$run_id" ] || { echo "missing run_id" >&2; exit 2; }
+  printf 'agentic-spec-run-%s' "$run_id"
+}
+
+is_known_agent() {
+  local candidate="${1:-}"
+  local agent
+  for agent in "${AGENTS[@]}"; do
+    [ "$agent" = "$candidate" ] && return 0
+  done
+  return 1
+}
+
+resolve_agent() {
+  local requested="${1:-$ENTRY_AGENT}"
+  if ! is_known_agent "$requested"; then
+    echo "Unknown run agent/window: $requested" >&2
+    printf 'Known agents:\n' >&2
+    printf '  %s\n' "${AGENTS[@]}" >&2
+    exit 2
+  fi
+  printf '%s' "$requested"
+}
+
+session_exists() {
+  local session="$1"
+  tmux has-session -t "$session" 2>/dev/null
+}
+
+start_detached() {
+  require_tmux
+  local run_id="$(safe_token "${1:-}")"
+  local session="$(session_name "$run_id")"
+  cd "$PROJECT_DIR"
+
+  if session_exists "$session"; then
+    echo "session already running: $session"
+    return 0
+  fi
+
+  local first="${AGENTS[0]}"
+  tmux new-session -d -s "$session" -n "$first" -c "$PROJECT_DIR"
+  tmux send-keys -t "$session:$first" "cd '$PROJECT_DIR' && unset npm_config_prefix && AGENTIC_SPEC_RUN_ID='$run_id' ZOB_ZAGENT_ID=$first '$PI_BIN'" C-m
+
+  local agent
+  for agent in "${AGENTS[@]:1}"; do
+    tmux new-window -t "$session" -n "$agent" -c "$PROJECT_DIR"
+    tmux send-keys -t "$session:$agent" "cd '$PROJECT_DIR' && unset npm_config_prefix && AGENTIC_SPEC_RUN_ID='$run_id' ZOB_ZAGENT_ID=$agent '$PI_BIN'" C-m
+  done
+
+  tmux select-window -t "$session:$ENTRY_AGENT"
+  echo "session started detached: $session"
+}
+
+attach() {
+  require_tmux
+  local run_id="$(safe_token "${1:-}")"
+  local session="$(session_name "$run_id")"
+  local agent="$(resolve_agent "${2:-$ENTRY_AGENT}")"
+  if ! session_exists "$session"; then
+    echo "session not running: $session" >&2
+    echo "Run: $0 start-detached $run_id" >&2
+    exit 1
+  fi
+  tmux select-window -t "$session:$agent"
+  tmux attach -t "$session:$agent"
+}
+
+status() {
+  require_tmux
+  local run_id="$(safe_token "${1:-}")"
+  local session="$(session_name "$run_id")"
+  if session_exists "$session"; then
+    tmux list-windows -t "$session" -F '#{window_index}: #{window_name} #{pane_current_command} active=#{window_active} panes=#{window_panes}'
+  else
+    echo "session not running: $session"
+  fi
+}
+
+close() {
+  require_tmux
+  local run_id="$(safe_token "${1:-}")"
+  local session="$(session_name "$run_id")"
+  if session_exists "$session"; then
+    tmux kill-session -t "$session"
+    echo "session closed: $session"
+  else
+    echo "session not running: $session"
+  fi
+}
+
+list_agents() {
+  printf 'entry: %s\n' "$ENTRY_AGENT"
+  printf 'agents:\n'
+  printf '  %s\n' "${AGENTS[@]}"
+}
+
+case "${1:-}" in
+  start|start-detached) start_detached "${2:-}" ;;
+  attach|window) attach "${2:-}" "${3:-$ENTRY_AGENT}" ;;
+  status) status "${2:-}" ;;
+  close) close "${2:-}" ;;
+  list) list_agents ;;
+  session-name) session_name "${2:-}" ;;
+  *) echo "Usage: $0 start-detached <run_id>|status <run_id>|attach <run_id> [agent]|close <run_id>|list|session-name <run_id>" >&2; exit 2 ;;
+esac

package/.pi/zteams/templates/agent-factory-pacman-chief-kickoff.template.md

@@ -0,0 +1,71 @@
+# Agent Factory Pac-Man Multiplayer — Chief Kickoff
+
+Run id: {{RUN_ID}}
+Run directory: {{RUN_DIR}}
+Generated project target: {{PROJECT_DIR}}
+Team: agent-factory-pacman-multiplayer
+Shared room: pacman-factory
+
+You are `agent-factory-pacman-chief` / `@pacman_chief`.
+
+## Mission
+
+Coordinate the Agent Factory team so the **agents generate** a playable local Pac-Man-inspired multiplayer game under `{{PROJECT_DIR}}`.
+
+The game must not be prebuilt in `examples/agent-factory-pacman-multiplayer/`. That source folder is only the brief.
+
+This kickoff starts a demo workflow. It does not authorize commits, pushes, external network access, destructive commands, secret reads, or completion claims without evidence.
+
+## Read first
+
+- AGENTS.md
+- README.md
+- examples/agent-factory-pacman-multiplayer/AGENTS.md
+- examples/agent-factory-pacman-multiplayer/README.md
+- {{MISSION_REF}}
+- {{OUTPUT_CONTRACT_REF}}
+- {{RUN_MANIFEST_REF}}
+- {{ARTIFACT_CONTRACTS_REF}}
+
+## Team
+
+- `@game_designer`: gameplay rules, controls, scoring, acceptance criteria.
+- `@game_architect`: engine/UI/state boundaries and validation ladder.
+- `@engine_builder`: game engine, collision/scoring logic, tests.
+- `@frontend_builder`: browser rendering, controls, HUD, local multiplayer UX.
+- `@qa_oracle`: playability, test evidence, safety, no-ship verdict.
+
+## Communication protocol
+
+All proactive coordination happens in `pacman-factory`. Use:
+
+```text
+CONTEXT:
+ASK:
+EVIDENCE:
+URGENCY:
+BLOCKER:
+```
+
+Do not create hidden worker-to-worker chat. Ask direct peers when needed: frontend asks engine about state shape; engine asks architect about model boundaries; architect asks designer about rule semantics; QA interrupts on no-ship.
+
+## First turn required
+
+1. Confirm `READY`, restate run id and generated project target.
+2. Update `{{STATUS_REF}}` and `{{ITERATION_LOG_REF}}`.
+3. Dispatch bounded async asks to every worker.
+4. Require gameplay + architecture handoff before builders create broad module boundaries.
+5. Ensure all generated code lands under `{{PROJECT_DIR}}` only.
+6. Keep owner questions concise and only for true blockers.
+
+## Completion policy
+
+Final readiness requires:
+
+- generated Pac-Man multiplayer project scaffold under `{{PROJECT_DIR}}`;
+- documented controls and play instructions;
+- validation commands attempted/reported from the generated project;
+- engine/gameplay tests;
+- no secret/raw body issues;
+- QA/oracle PASS or WARN with no no-ship blockers;
+- final report under `{{RUN_DIR}}/final-report.json` or explicit blocker status.

package/.pi/zteams/templates/agent-factory-pacman-worker-kickoff.template.md

@@ -0,0 +1,59 @@
+# Agent Factory Pac-Man Multiplayer — Worker Kickoff
+
+Run id: {{RUN_ID}}
+Run directory: {{RUN_DIR}}
+Generated project target: {{PROJECT_DIR}}
+Agent id: {{AGENT_ID}}
+Alias: {{ALIAS}}
+Role: {{ROLE}}
+Shared room: pacman-factory
+
+## Your bounded mission
+
+{{MISSION}}
+
+The generated game project belongs under `{{PROJECT_DIR}}`. Do not create or modify game code in `examples/agent-factory-pacman-multiplayer/`; that folder is only the brief.
+
+## Read first
+
+- examples/agent-factory-pacman-multiplayer/AGENTS.md
+- examples/agent-factory-pacman-multiplayer/README.md
+- {{MISSION_REF}}
+- {{OUTPUT_CONTRACT_REF}}
+- {{RUN_MANIFEST_REF}}
+- {{ARTIFACT_CONTRACTS_REF}}
+- {{WORKGRAPH_REF}}
+
+## Communication protocol
+
+Send `READY` to `@pacman_chief` after reading. Communicate proactively in `pacman-factory` with:
+
+```text
+CONTEXT:
+ASK:
+EVIDENCE:
+URGENCY:
+BLOCKER:
+```
+
+Required peer routing:
+
+- Ask `@game_architect` for architecture/model/state ambiguity.
+- Ask `@game_designer` for gameplay/scoring/control ambiguity.
+- Ask `@engine_builder` before relying on game-state changes.
+- Ask `@frontend_builder` before changing UI-facing contracts.
+- Ask `@qa_oracle` for validation/no-ship review when ready or blocked.
+
+## Must not
+
+- Do not read secrets or raw sessions/coms bodies.
+- Do not persist prompt/output/chat bodies.
+- Do not use hidden worker chat.
+- Do not commit/push/tag.
+- Do not launch broad external network actions.
+- Do not write generated game code outside `{{PROJECT_DIR}}`.
+- Do not claim completion without validation evidence.
+
+## Final output
+
+Return result, changed files/artifacts, validation commands, blockers/risks, and compliance.