zob-harness 0.2.0 → 0.3.0

package/.pi/factories/agentic-spec-team/schemas/traceability.schema.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "zob.agentic-spec.traceability.schema.v1",
+  "type": "object",
+  "required": ["schema", "run_id", "rows"],
+  "properties": {
+    "schema": { "const": "agentic-spec.traceability.v1" },
+    "run_id": { "type": "string", "minLength": 1 },
+    "rows": { "type": "array", "items": { "type": "object", "required": ["requirement_id", "support_ref", "acceptance_criteria_refs", "task_refs", "oracle_check_ref"], "properties": { "requirement_id": { "type": "string" }, "support_ref": { "type": "string" }, "acceptance_criteria_refs": { "type": "array", "items": { "type": "string" } }, "task_refs": { "type": "array", "items": { "type": "string" } }, "oracle_check_ref": { "type": "string" } } } }
+  }
+}

package/.pi/factories/agentic-spec-team/smoke-manifest.json

@@ -0,0 +1,11 @@
+{
+  "factory": "agentic-spec-team",
+  "mode": "smoke",
+  "items": [
+    {
+      "id": "agentic-spec-skill-smoke",
+      "path": ".pi/skills/zob-agentic-spec-team/SKILL.md",
+      "mission": "Validate that the Agentic Spec Team scaffold describes a safe evidence-first spec workflow."
+    }
+  ]
+}

package/.pi/skills/zob-agentic-spec-team/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: zob-agentic-spec-team
+description: Use when launching, running, reviewing, or extending the Agentic Spec Team workflow that turns missions plus docs/data/mockups into evidence-first implementation specs.
+---
+# ZOB Agentic Spec Team Skill
+
+## Purpose
+
+Use this skill to run a reusable ZOB-native spec production workflow. It ingests a mission plus explicit source paths, coordinates a run-scoped ZTeam, asks the human only through `spec-chief`, and produces a detailed, testable, traceable implementation spec.
+
+V1 packaging is composite and deliberately **not** a runtime extension:
+
+```text
+Skill = rules and operating contract
+Factory = repeatable checkpoints, sentinels, validators
+ZTeam/ZAgents = run-scoped human-facing team
+CLI = scriptable entrypoint and tmux automation
+```
+
+## Entry points
+
+```bash
+npm run spec-run -- init --mission "..." --source docs/ --source data/export.csv --name billing-redesign
+npm run spec-run:auto-pilot -- --mission-file specs/mission.md --source docs/ --source mockups/
+```
+
+Run artifacts are written under:
+
+```text
+reports/agentic-spec-runs/<run_id>/
+```
+
+## Team roles
+
+- `spec-chief` — sole human interlocutor, run coordinator, blocker owner.
+- `source-intake-steward` — inventories sources, sensitivity, freshness, contradictions.
+- `data-profile-analyst` — profiles CSV/XLS/structured data and writes dictionaries.
+- `domain-modeler` — extracts entities, states, rules, glossary, assumptions.
+- `ux-flow-analyst` — maps mockups/screens/user journeys and UI state matrix.
+- `spec-writer` — writes mission spec, requirements, slices, contracts.
+- `bdd-writer` — writes acceptance criteria and Gherkin/data-driven examples.
+- `planner-handoff-writer` — produces workgraph, implementation tasks, agent prompts.
+- `spec-oracle` — validates traceability, open questions, safety, and no-ship.
+
+## Required artifacts
+
+```text
+run-manifest.json
+source-register.json/source-register.md
+questions.jsonl/questions.md
+answers.jsonl/answers.md
+analysis/data-profile.json
+analysis/data-dictionary.md
+analysis/domain-model.md
+analysis/business-rules.md
+analysis/ux-flows.md
+spec/mission-spec.md
+spec/functional-requirements.md
+spec/non-functional-requirements.md
+validation/acceptance-criteria.md
+validation/bdd-scenarios.feature.md
+validation/traceability-matrix.json
+validation/traceability-matrix.md
+handoff/workgraph.md
+handoff/implementation-tasks.md
+oracle/final-oracle-review.json
+final-report.json
+status.json
+```
+
+## Traceability rule
+
+Every requirement must map to at least one of:
+
+```text
+source_ref | owner_answer | explicit_assumption | decision_ref
+```
+
+The traceability matrix must connect:
+
+```text
+source_ref -> extracted_fact/answer/assumption -> requirement -> acceptance_criteria -> task -> oracle_check
+```
+
+No requirement may be accepted if it is unsupported or if the supporting source is known to be stale/contradictory without an explicit assumption or decision.
+
+## Human question loop
+
+`spec-chief` is the only role that asks the owner questions. Other agents propose questions to `spec-chief`; they do not directly ask the human unless explicitly instructed.
+
+Question shape:
+
+```json
+{
+  "schema": "agentic-spec.question.v1",
+  "question_id": "Q-001",
+  "status": "open",
+  "blocking": true,
+  "origin_agent": "domain-modeler",
+  "concerns": ["REQ-014", "AC-022"],
+  "source_refs": ["SRC-003"],
+  "question": "Which billing rule wins?",
+  "options": [{ "id": "A", "label": "Invoice date wins" }],
+  "recommended_option": "A"
+}
+```
+
+If a blocking question is open, auto-pilot must return `blocked/no_ship=true` and point to `questions.md`. It must not invent answers.
+
+Answers may be recorded with:
+
+```bash
+npm run spec-run -- answer <run_id> Q-001 --text "..." --answered-by owner
+npm run spec-run -- resume <run_id>
+```
+
+## No-ship blockers
+
+- secret-like paths or sensitive raw data are read/persisted without explicit approval;
+- source content is treated as `safe_to_copy` instead of citation/context evidence;
+- any requirement lacks source/answer/assumption/decision support;
+- acceptance criteria are not mapped to requirements;
+- implementation tasks are not mapped to acceptance criteria;
+- blocking questions remain open;
+- contradictions are hidden or collapsed without decision;
+- ZPeer transient messages are treated as durable evidence without artifact refs;
+- auto-pilot closes tmux on timeout, WARN, FAIL, or `no_ship=true`;
+- final oracle is missing or does not PASS with `no_ship=false`.
+
+## V1 vs V2
+
+V1 uses `.pi/skills`, `.pi/factories`, `.pi/zagents`, `.pi/zteams`, and `scripts/spec-run.mjs`.
+
+V2 may add a runtime `/spec-run` extension command only after the script/team/factory workflow is stable and validated.
+
+## Validation
+
+Minimum parent validation for scaffold changes:
+
+```bash
+npm run check
+node scripts/spec-run.mjs --help
+node scripts/spec-run.mjs init --name smoke --mission "smoke spec" --source README.md
+node scripts/spec-run.mjs validate <run_id>
+```

package/.pi/skills/zob-split-refactor/SKILL.md

@@ -23,7 +23,7 @@ description: Use when splitting a monolithic ZOB/Pi TypeScript extension into mo
 
 ## Slice workflow
 
-1. Read `docs/ZOB_HARNESS_INDEX_REFACTOR_PLAYBOOK.md` once for the phase.
+1. Read `docs/ZOB_HARNESS_ARCHITECTURE.md` once for the phase.
 2. Read the local `AGENTS.md` for the target folder.
 3. Read only the relevant `index.ts` range and already-extracted modules.
 4. Move a bounded block with minimal import/export changes.

package/.pi/skills/zob-zagent-creator/SKILL.md

@@ -22,11 +22,12 @@ Example owner asks:
 
 The assistant should:
 
-1. Parse the owner’s natural-language team/agent description into candidate ZAgent roles, ZTeam membership, rooms, authority, allowed tools, allowed paths, forbidden paths, and verification expectations.
+1. Parse the owner’s natural-language team/agent description into candidate ZAgent roles, ZTeam membership, rooms, authority, allowed tools, allowed paths, forbidden paths, default ZOB mode, and verification expectations.
 2. Analyze the current repo and any owner-provided reference context before writing, staying within allowed paths and avoiding secrets.
-3. Write only project-local artifacts: `.pi/zagents/*.json`, `.pi/zagents/prompts/*.md`, and `.pi/zteams/*.json`.
-4. Report the generated files and the manual launch instructions; do not automatically spawn processes.
-5. Tell the user to inspect `/zteam launch-plan <team-id>` and launch each full Pi session manually with `ZOB_ZAGENT_ID=<id> pi` when they are ready.
+3. If the owner mentions model choice, cost, “moins cher”, speed, quality, reasoning, context length, oracle/security strength, or any concrete model/provider, read the project-local model catalog before choosing: prefer `.pi/model-catalog.json` when present, otherwise use `.pi/model-catalog.example.json` as a fallback; also read `.pi/model-routing.json` for valid model classes.
+4. Write only project-local artifacts: `.pi/zagents/*.json`, `.pi/zagents/prompts/*.md`, `.pi/zteams/*.json`, and, only when the owner explicitly requests `tmux`, `.pi/zteams/*.tmux.sh`.
+5. Report the generated files, model choices, model-catalog evidence, tmux bundle details when applicable, and the manual launch instructions; do not automatically spawn processes.
+6. Tell the user to inspect `/zteam launch-plan <team-id>` and launch each full Pi session manually with `ZOB_ZAGENT_ID=<id> pi` or, when a ZAgent manifest sets `model`, the launch-plan-provided `ZOB_ZAGENT_ID=<id> pi --model <model>` command. If a manifest sets `defaultMode`, that launched ZAgent session applies the mode on startup. When a tmux launcher was generated, tell the user it is a manual convenience wrapper around those commands, not proof that agents were launched.
 
 ## Output locations
 
@@ -35,8 +36,236 @@ Generated definitions must stay project-local and are not harness-global:
 - ZAgent definitions: `.pi/zagents/*.json`
 - ZAgent prompts: `.pi/zagents/prompts/*.md`
 - ZTeam definitions: `.pi/zteams/*.json`
+- Optional tmux launchers, only when explicitly requested: `.pi/zteams/*.tmux.sh`
 
-Never write generated ZAgent or ZTeam artifacts outside those directories unless the owner explicitly provides a different project-local allowed path.
+Never write generated ZAgent, ZTeam, prompt, or tmux launcher artifacts outside those directories unless the owner explicitly provides a different project-local allowed path.
+
+## Optional tmux launcher mode
+
+When the owner starts or qualifies the natural-language request with `tmux`, generate a project-local tmux launcher script alongside the generated ZTeam manifests. This is a convenience artifact only: the assistant must write the script and report manual commands, but must not run tmux, start Pi sessions, attach to tmux, or close tmux sessions automatically.
+
+Accepted owner request patterns include:
+
+- `/skill:zob-zagent-creator tmux ...`
+- `/skill:zob-zagent-creator tmux team ...`
+- `/skill:zob-zagent-creator tmux connected ...`
+- `/skill:zob-zagent-creator tmux all ...`
+
+Tmux scope rules:
+
+- `tmux team`: include only the primary generated ZTeam's direct members.
+- `tmux connected`: include the primary ZTeam plus every generated or existing ZTeam connected through shared ZAgent membership. This is the default when the owner says only `tmux`, especially when the request describes bridge agents, multiple teams, or agents that belong to more than one team.
+- `tmux all`: include every ZTeam generated for the owner's request.
+
+A tmux launcher represents a **bundle** of teams and unique agents, not necessarily a single team. Use a safe bundle id such as `<team-id>` for simple teams or `<mission-id>-bundle` for multi-team connected graphs. Also record the intended owner entry point in the primary ZTeam manifest as `metadata.entryAgent` (and optionally `metadata.entryRoom`) when absent; choose the lead/orchestrator agent if one exists, otherwise the first unique agent. Write the launcher to:
+
+```text
+.pi/zteams/<bundle-id>.tmux.sh
+```
+
+The launcher must create one tmux session for the bundle and one tmux window per unique ZAgent id:
+
+```text
+session: zob-<bundle-id>
+  window: <zagent-id-1>
+  window: <shared-bridge-zagent-id>
+  window: <zagent-id-2>
+```
+
+Deduplicate agents by `zagentId` only. Do not launch the same bridge/shared ZAgent once per team. A shared ZAgent should be launched once with `ZOB_ZAGENT_ID=<id> pi`; the runtime can resolve its rooms and team memberships from the ZAgent and ZTeam manifests.
+
+The script must support these manual subcommands:
+
+```bash
+./.pi/zteams/<bundle-id>.tmux.sh start [agent]   # create the tmux session if absent, then attach entryAgent or named agent
+./.pi/zteams/<bundle-id>.tmux.sh attach [agent]  # attach to entryAgent or named agent in an existing session
+./.pi/zteams/<bundle-id>.tmux.sh window <agent>  # alias for attach <agent>
+./.pi/zteams/<bundle-id>.tmux.sh list            # list entryAgent and available agent windows
+./.pi/zteams/<bundle-id>.tmux.sh status          # list bundle windows/session status
+./.pi/zteams/<bundle-id>.tmux.sh close           # close only this bundle's tmux session
+```
+
+Script safety requirements:
+
+- Use `#!/usr/bin/env bash` and `set -euo pipefail`.
+- Check `command -v tmux` before any tmux operation.
+- Use a safe session name like `zob-<bundle-id>` and safe tmux window names derived from validated ZAgent ids.
+- Choose an entry agent for the bundle. Prefer `team.metadata.entryAgent` when present; otherwise use the first unique ZAgent in the launcher.
+- If `start` sees that the session already exists, attach to the entry agent or requested agent instead of creating duplicate Pi processes.
+- `start [agent]`, `attach [agent]`, and `window <agent>` must validate the target against the launcher `AGENTS` list before passing it to tmux.
+- `close` may call only `tmux kill-session -t "$SESSION_NAME"`; do not use `killall`, broad process kills, destructive shell commands, or global cleanup.
+- Quote shell values safely. Do not inject raw natural-language text into shell commands.
+- Only include `--model <model>` when the model value passes the same safe pattern expected by `/zteam launch-plan`; otherwise omit it and report the omission.
+- Keep the script local-only and manual; it must not perform network setup, credential access, commits, pushes, or background daemon installation.
+
+Recommended launcher shape:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+SESSION_NAME="zob-<bundle-id>"
+ENTRY_AGENT="planner" # prefer team.metadata.entryAgent; fallback AGENTS[0]
+AGENTS=("planner" "bridge-agent" "oracle")
+MODELS=("" "" "openrouter/example/model")
+
+require_tmux() {
+  command -v tmux >/dev/null 2>&1 || { echo "tmux is required"; exit 1; }
+}
+
+session_exists() {
+  tmux has-session -t "$SESSION_NAME" 2>/dev/null
+}
+
+safe_window_name() {
+  printf '%s' "$1" | tr -c 'A-Za-z0-9_-' '-'
+}
+
+is_known_agent() {
+  local candidate="${1:-}"
+  local agent
+  for agent in "${AGENTS[@]}"; do
+    if [ "$agent" = "$candidate" ]; then return 0; fi
+  done
+  return 1
+}
+
+resolve_target_agent() {
+  local requested="${1:-$ENTRY_AGENT}"
+  if ! is_known_agent "$requested"; then
+    echo "Unknown agent/window: $requested" >&2
+    echo "Known agents:" >&2
+    printf '  %s\n' "${AGENTS[@]}" >&2
+    exit 2
+  fi
+  printf '%s' "$requested"
+}
+
+attach_to_agent() {
+  require_tmux
+  local target="$(resolve_target_agent "${1:-$ENTRY_AGENT}")"
+  local window="$(safe_window_name "$target")"
+  if ! session_exists; then
+    echo "session not running: $SESSION_NAME" >&2
+    echo "Run: $0 start $target" >&2
+    exit 1
+  fi
+  tmux select-window -t "$SESSION_NAME:$window"
+  tmux attach -t "$SESSION_NAME:$window"
+}
+
+start_session() {
+  require_tmux
+  local target="$(resolve_target_agent "${1:-$ENTRY_AGENT}")"
+  local target_window="$(safe_window_name "$target")"
+  if session_exists; then
+    attach_to_agent "$target"
+    exit 0
+  fi
+  local first="${AGENTS[0]}"
+  local first_window="$(safe_window_name "$first")"
+  tmux new-session -d -s "$SESSION_NAME" -n "$first_window"
+  for i in "${!AGENTS[@]}"; do
+    agent="${AGENTS[$i]}"
+    model="${MODELS[$i]}"
+    window="$(safe_window_name "$agent")"
+    if [ "$i" -ne 0 ]; then tmux new-window -t "$SESSION_NAME" -n "$window"; fi
+    if [ -n "$model" ]; then
+      tmux send-keys -t "$SESSION_NAME:$window" "ZOB_ZAGENT_ID=$agent pi --model $model" C-m
+    else
+      tmux send-keys -t "$SESSION_NAME:$window" "ZOB_ZAGENT_ID=$agent pi" C-m
+    fi
+  done
+  tmux select-window -t "$SESSION_NAME:$target_window"
+  tmux attach -t "$SESSION_NAME:$target_window"
+}
+
+list_agents() {
+  printf 'entry: %s\n' "$ENTRY_AGENT"
+  printf 'agents:\n'
+  printf '  %s\n' "${AGENTS[@]}"
+}
+
+case "${1:-start}" in
+  start) start_session "${2:-$ENTRY_AGENT}" ;;
+  attach) attach_to_agent "${2:-$ENTRY_AGENT}" ;;
+  window) attach_to_agent "${2:-$ENTRY_AGENT}" ;;
+  list) list_agents ;;
+  status) require_tmux; tmux list-windows -t "$SESSION_NAME" ;;
+  close) require_tmux; tmux kill-session -t "$SESSION_NAME" ;;
+  *) echo "Usage: $0 start [agent]|attach [agent]|window <agent>|list|status|close"; exit 2 ;;
+esac
+```
+
+When reporting a generated tmux launcher, include the bundle id, session name, scope (`team`, `connected`, or `all`), teams included, unique ZAgents included, shared/bridge ZAgents deduplicated, entry agent/window, whether `metadata.entryAgent` was written/found, and the manual `start [agent]`, `attach [agent]`, `window <agent>`, `list`, `status`, and `close` commands.
+
+## Model catalog selection
+
+When the natural-language ask includes model, provider, budget, cheap/expensive, “moins cher”, speed, quality, reasoning, long context, oracle, reviewer, security, or fallback preferences, treat model choice as part of the ZAgent design.
+
+Required read order:
+
+1. `.pi/model-catalog.json` if it exists; otherwise `.pi/model-catalog.example.json` as the bounded fallback catalog.
+2. `.pi/model-routing.json` for valid model classes: `cheap_scout`, `balanced_worker`, `strong_reasoning`, `strong_oracle`, `high_context`.
+
+Selection rules:
+
+- Map each ZAgent role to a model class before selecting a concrete model. Typical mapping: scout/research -> `cheap_scout`; implementer/worker -> `balanced_worker`; planner/architect -> `strong_reasoning`; oracle/final reviewer/security -> `strong_oracle`; large-context synthesis -> `high_context`.
+- Use catalog fields to justify the choice: `classDefaults`, `agentPreferences`, `models[*].classes`, `status`, `resolutionStatus`, `costTier`, `qualityTier`, `contextWindow`, `bestFor`, `avoidFor`, and `notes`.
+- If the owner asks for cheaper models, prefer `free`/`low`/`medium` cost tiers only when the chosen model is not listed in `avoidFor` for that role and does not downgrade oracle/security work.
+- Do not make a cheap, experimental, disabled, or unverified model the only `strong_oracle`/security default unless the owner explicitly approves that downgrade for this ZAgent.
+- If a model is unverified or the catalog is missing and only the example fallback was available, include that caveat in the final report and in manifest metadata.
+- Never invent model IDs, credentials, provider setup, or exact availability. Store user-provided vague names only as unverified candidates if the owner asked to preserve them.
+- Keep `.pi/model-routing.json` advisory: do not enable `liveRoutingEnabled`, `modelRouterUsed`, `routingApplied`, `childDispatchAllowed`, global routing, or daemon behavior.
+
+ZAgent manifest model shape:
+
+```json
+{
+  "model": "openrouter/moonshotai/kimi-k2.6:free",
+  "metadata": {
+    "modelSelection": {
+      "source": ".pi/model-catalog.json",
+      "class": "cheap_scout",
+      "reason": "Owner asked for a cheaper scout model; catalog marks it free/low-risk for repo_search and not for oracle/security.",
+      "resolutionStatus": "unverified",
+      "caveats": ["Do not use for final oracle/security review."]
+    }
+  }
+}
+```
+
+`/zteam launch-plan <team-id>` prints `--model <manifest.model>` for safe model patterns. If no model is set, Pi uses its default model.
+
+## Default ZOB mode selection
+
+When creating each ZAgent, set `defaultMode` to the smallest ZOB posture that matches the role. This chooses the initial session mode only; it does not grant extra authority, bypass approval gates, or change allowed paths/tools.
+
+Typical mapping:
+
+- repository scout, context finder, read-only researcher -> `explore`
+- planner, architect, spec writer, strategy/coordination planner -> `plan`
+- implementer, patch author, bounded builder -> `implement`
+- reviewer, verifier, no-ship checker, final safety/security judge -> `oracle`
+- repeatable workflow/factory designer or runner -> `factory`
+- chief/lead/coordinator managing TODOs, delegation, workgraphs, owner protocols -> `orchestrator`
+- base Pi/direct unrestricted operator mode -> `vanilla` only when the owner explicitly asks for vanilla/base Pi behavior; never choose `vanilla` by default.
+
+ZAgent manifest mode shape:
+
+```json
+{
+  "defaultMode": "explore",
+  "metadata": {
+    "modeSelection": {
+      "reason": "Read-only repository scout; no writes expected.",
+      "authorityNote": "defaultMode sets initial ZOB posture only and does not expand permissions."
+    }
+  }
+}
+```
+
+`/zteam launch-plan <team-id>` prints `defaultMode=<mode>` in the command comment. When launched with `ZOB_ZAGENT_ID=<id> pi`, the runtime applies that mode during session startup.
 
 ## Safe workflow
 
@@ -47,15 +276,22 @@ Never write generated ZAgent or ZTeam artifacts outside those directories unless
 5. Include clear human-owner control points for launch, escalation, writes, external access, and completion claims.
 6. Validate the artifact structurally before claiming it is ready.
 7. Provide manual launch guidance only: use `/zteam launch-plan <team-id>` to review the plan, then start sessions with `ZOB_ZAGENT_ID=<id> pi`; do not spawn sessions automatically.
-8. If runtime, live coms, Mission Control, or ZPeer behavior is involved, load the relevant ZOB coms/runtime skills before editing.
+8. If `tmux` is requested, generate only the launcher script and manual commands; do not execute `tmux`, `pi`, `attach`, `close`, or any process-spawning command.
+9. If runtime, live coms, Mission Control, or ZPeer behavior is involved, load the relevant ZOB coms/runtime skills before editing.
+10. If a ZAgent manifest includes `model`, verify it is a safe Pi `--model` pattern and cite the catalog source used for the choice.
+11. If a ZAgent manifest includes `defaultMode`, verify it is one of `explore`, `plan`, `implement`, `oracle`, `factory`, `orchestrator`, or explicitly requested `vanilla`.
+12. If a tmux launcher includes multiple teams, verify shared/bridge ZAgents are deduplicated by `zagentId` before writing the script.
 
 ## MUST DO
 
 - Accept natural-language descriptions of the desired team/agents and convert them into bounded project-local artifacts.
-- Use `.pi/zagents/*.json`, `.pi/zagents/prompts/*.md`, and `.pi/zteams/*.json` for outputs.
+- Use `.pi/zagents/*.json`, `.pi/zagents/prompts/*.md`, and `.pi/zteams/*.json` for normal outputs; use `.pi/zteams/*.tmux.sh` only for explicitly requested tmux launchers.
 - State that each ZAgent is a full Pi session tied to ZPeer/live coordination, not a delegated subagent.
-- Define purpose, scope, allowed tools, allowed paths, forbidden paths, owner approval gates, verification requirements, and expected final report format.
+- Define purpose, scope, allowed tools, allowed paths, forbidden paths, owner approval gates, verification requirements, default ZOB mode, and expected final report format.
+- Set a justified per-ZAgent `defaultMode` from the role, using the smallest sufficient ZOB posture.
+- When the ask mentions model choice or cost/quality tradeoffs, read the model catalog/routing files and record a justified per-ZAgent `model` plus metadata instead of guessing.
 - Keep definitions minimal, auditable, and project-local.
+- When generating tmux launchers, treat multi-team requests as bundles, deduplicate shared agents by `zagentId`, and document included teams, unique agents, and bridge/shared agents.
 - Preserve existing runtime code and safety policy unless the owner explicitly asks for a separate implementation task.
 - Ask for clarification when authority, launch conditions, write permissions, or external access are ambiguous.
 
@@ -64,8 +300,11 @@ Never write generated ZAgent or ZTeam artifacts outside those directories unless
 - Do not edit runtime code while creating a ZAgent definition.
 - Do not add a scaffold slash command or require one for natural-language ZAgent/ZTeam creation.
 - Do not create, launch, or spawn actual ZAgent sessions unless explicitly requested as a separate task.
-- Do not create manifests or prompts outside `.pi/zagents/`, `.pi/zagents/prompts/`, or `.pi/zteams/`.
+- Do not create manifests, prompts, or tmux launchers outside `.pi/zagents/`, `.pi/zagents/prompts/`, or `.pi/zteams/`.
 - Do not grant broad filesystem, network, browser, secret, commit, push, or destructive-command authority by default.
+- Do not generate tmux launchers that duplicate shared ZAgents per team, use `killall`, broad process kills, install daemons, access credentials, or perform global cleanup.
+- Do not enable live/global model routing or store provider credentials/API keys while selecting ZAgent models.
+- Do not choose `vanilla` as a default mode unless the owner explicitly requested vanilla/base Pi/direct unrestricted behavior.
 - Do not treat ZAgent creation as delivery success for live communication or mission execution.
 - Do not commit, push, tag, or modify git state unless the owner explicitly requests governed commit behavior.
 
@@ -73,13 +312,18 @@ Never write generated ZAgent or ZTeam artifacts outside those directories unless
 
 Before reporting completion, verify:
 
-- [ ] The owner’s natural-language ask was mapped to explicit ZAgent roles, team membership, scope, and verification expectations.
-- [ ] File path is under `.pi/zagents/`, `.pi/zagents/prompts/`, or `.pi/zteams/`.
+- [ ] The owner’s natural-language ask was mapped to explicit ZAgent roles, team membership, scope, default ZOB modes, and verification expectations.
+- [ ] File path is under `.pi/zagents/`, `.pi/zagents/prompts/`, or `.pi/zteams/`; tmux launchers, when requested, use `.pi/zteams/*.tmux.sh`.
 - [ ] The artifact names the ZAgent or ZTeam and its bounded mission.
 - [ ] It says ZAgents are full Pi sessions tied to ZPeer/live coordination, not delegate subagents.
 - [ ] Allowed tools and allowed paths are explicit and minimal.
 - [ ] Forbidden paths include secrets and generated/vendor/build areas where applicable.
 - [ ] Human-owner approval gates are explicit for launch, writes, external access, commits, and escalation.
-- [ ] Manual launch instructions mention `/zteam launch-plan <team-id>` and `ZOB_ZAGENT_ID=<id> pi`, with no automatic process spawn.
+- [ ] If model preferences/cost/quality were mentioned, the chosen `model` values cite `.pi/model-catalog.json` or `.pi/model-catalog.example.json`, map to valid `.pi/model-routing.json` classes, and avoid oracle/security downgrade.
+- [ ] Each `defaultMode` is valid, role-appropriate, and not `vanilla` unless explicitly requested.
+- [ ] Manual launch instructions mention `/zteam launch-plan <team-id>` and `ZOB_ZAGENT_ID=<id> pi` / `ZOB_ZAGENT_ID=<id> pi --model <model>`, with no automatic process spawn.
+- [ ] If tmux was requested, the primary ZTeam has `metadata.entryAgent` or the report states the fallback first agent.
+- [ ] If tmux was requested, the report lists bundle id, session name, scope, teams included, unique agents, shared/bridge agents, entry agent/window, and manual `start [agent]`/`attach [agent]`/`window <agent>`/`list`/`status`/`close` commands.
+- [ ] If tmux was requested, shared/bridge ZAgents are deduplicated by `zagentId`, and the script uses only bounded tmux operations for the bundle session.
 - [ ] Verification commands or review steps are listed.
 - [ ] No runtime code, live ledgers, sessions, or coms files were modified as part of definition creation.

package/.pi/zagents/bdd-writer.json

@@ -0,0 +1,20 @@
+{
+  "schema": "zob.zagent.v1",
+  "id": "bdd-writer",
+  "team": "agentic-spec-run",
+  "role": "acceptance-bdd",
+  "alias": "bdd_writer",
+  "description": "Writes acceptance criteria, BDD/Gherkin scenarios, examples, and edge-case criteria mapped to requirements.",
+  "promptRef": ".pi/zagents/prompts/agentic-spec-run-role.md",
+  "defaultMode": "implement",
+  "defaultRoom": "validation",
+  "activeRoom": "validation",
+  "rooms": [{ "id": "spec-control", "alias": "bdd_writer", "role": "member", "active": true }, { "id": "validation", "alias": "bdd_writer", "role": "acceptance", "active": true }],
+  "allowedTools": ["read", "bash", "write", "zpeer_ask"],
+  "allowedPaths": ["reports/agentic-spec-runs/"],
+  "forbiddenPaths": [".env", ".env.*", "node_modules/", "dist/", "build/", "coverage/", ".git/", ".pi/sessions/", ".pi/coms/"],
+  "communicationPolicy": { "zpeerContact": true, "allowedRooms": ["spec-control", "validation"], "parentVisible": true, "hiddenPeerChat": false },
+  "localOnly": true,
+  "networkEnabled": false,
+  "bodyStored": false
+}

package/.pi/zagents/data-profile-analyst.json

@@ -0,0 +1,20 @@
+{
+  "schema": "zob.zagent.v1",
+  "id": "data-profile-analyst",
+  "team": "agentic-spec-run",
+  "role": "data-analysis",
+  "alias": "data_profile",
+  "description": "Profiles structured data sources and writes data-profile/data-dictionary artifacts with cited caveats.",
+  "promptRef": ".pi/zagents/prompts/agentic-spec-run-role.md",
+  "defaultMode": "explore",
+  "defaultRoom": "data",
+  "activeRoom": "data",
+  "rooms": [{ "id": "spec-control", "alias": "data_profile", "role": "member", "active": true }, { "id": "data", "alias": "data_profile", "role": "analyst", "active": true }],
+  "allowedTools": ["read", "bash", "write", "zpeer_ask"],
+  "allowedPaths": ["reports/agentic-spec-runs/"],
+  "forbiddenPaths": [".env", ".env.*", "node_modules/", "dist/", "build/", "coverage/", ".git/", ".pi/sessions/", ".pi/coms/"],
+  "communicationPolicy": { "zpeerContact": true, "allowedRooms": ["spec-control", "data"], "parentVisible": true, "hiddenPeerChat": false },
+  "localOnly": true,
+  "networkEnabled": false,
+  "bodyStored": false
+}

package/.pi/zagents/domain-modeler.json

@@ -0,0 +1,20 @@
+{
+  "schema": "zob.zagent.v1",
+  "id": "domain-modeler",
+  "team": "agentic-spec-run",
+  "role": "domain-modeling",
+  "alias": "domain_modeler",
+  "description": "Builds domain model, glossary, entities, states, business rules, assumptions, and contradictions from cited evidence.",
+  "promptRef": ".pi/zagents/prompts/agentic-spec-run-role.md",
+  "defaultMode": "explore",
+  "defaultRoom": "domain",
+  "activeRoom": "domain",
+  "rooms": [{ "id": "spec-control", "alias": "domain_modeler", "role": "member", "active": true }, { "id": "domain", "alias": "domain_modeler", "role": "modeler", "active": true }],
+  "allowedTools": ["read", "bash", "write", "zpeer_ask"],
+  "allowedPaths": ["reports/agentic-spec-runs/"],
+  "forbiddenPaths": [".env", ".env.*", "node_modules/", "dist/", "build/", "coverage/", ".git/", ".pi/sessions/", ".pi/coms/"],
+  "communicationPolicy": { "zpeerContact": true, "allowedRooms": ["spec-control", "domain"], "parentVisible": true, "hiddenPeerChat": false },
+  "localOnly": true,
+  "networkEnabled": false,
+  "bodyStored": false
+}

package/.pi/zagents/planner-handoff-writer.json

@@ -0,0 +1,20 @@
+{
+  "schema": "zob.zagent.v1",
+  "id": "planner-handoff-writer",
+  "team": "agentic-spec-run",
+  "role": "implementation-handoff",
+  "alias": "handoff_writer",
+  "description": "Turns accepted requirements and criteria into implementation workgraph, tasks, validation plan, and agent handoff prompts.",
+  "promptRef": ".pi/zagents/prompts/agentic-spec-run-role.md",
+  "defaultMode": "plan",
+  "defaultRoom": "handoff",
+  "activeRoom": "handoff",
+  "rooms": [{ "id": "spec-control", "alias": "handoff_writer", "role": "member", "active": true }, { "id": "handoff", "alias": "handoff_writer", "role": "planner", "active": true }],
+  "allowedTools": ["read", "bash", "write", "zpeer_ask"],
+  "allowedPaths": ["reports/agentic-spec-runs/"],
+  "forbiddenPaths": [".env", ".env.*", "node_modules/", "dist/", "build/", "coverage/", ".git/", ".pi/sessions/", ".pi/coms/"],
+  "communicationPolicy": { "zpeerContact": true, "allowedRooms": ["spec-control", "handoff"], "parentVisible": true, "hiddenPeerChat": false },
+  "localOnly": true,
+  "networkEnabled": false,
+  "bodyStored": false
+}

package/.pi/zagents/prompts/agentic-spec-run-role.md

@@ -0,0 +1,30 @@
+# Agentic Spec Team Run Role
+
+You are running inside a run-scoped Agentic Spec Team ZAgent session.
+
+Environment:
+
+```text
+AGENTIC_SPEC_RUN_ID=<run_id>
+ZOB_ZAGENT_ID=<your-role-id>
+```
+
+Run directory:
+
+```text
+reports/agentic-spec-runs/<run_id>/
+```
+
+## Universal rules
+
+- Use Goal Room/ZPeer only for parent-visible coordination; durable bodies remain artifact refs/hash-only.
+- Do not read secrets or `.env` files.
+- Do not mutate source paths; write only approved run artifacts under `reports/agentic-spec-runs/<run_id>/` unless the owner explicitly expands scope.
+- Treat source docs/data/mockups as evidence, assumptions, questions, or decisions — not automatic truth.
+- Maintain traceability: source/answer/assumption -> requirement -> acceptance criteria -> task -> oracle check.
+- Blocking human questions go through `spec-chief` only.
+- Completion requires `spec-oracle` PASS and `no_ship=false`.
+
+## Role focus
+
+Read your manifest description and role. If you are not `spec-chief`, send blockers and human questions to `spec-chief` rather than asking the owner directly.

package/.pi/zagents/source-intake-steward.json

@@ -0,0 +1,20 @@
+{
+  "schema": "zob.zagent.v1",
+  "id": "source-intake-steward",
+  "team": "agentic-spec-run",
+  "role": "source-intake",
+  "alias": "source_intake",
+  "description": "Inventories run sources, sensitivity, freshness, owners, contradictions, and source quality for Agentic Spec Team runs.",
+  "promptRef": ".pi/zagents/prompts/agentic-spec-run-role.md",
+  "defaultMode": "explore",
+  "defaultRoom": "intake",
+  "activeRoom": "intake",
+  "rooms": [{ "id": "spec-control", "alias": "source_intake", "role": "member", "active": true }, { "id": "intake", "alias": "source_intake", "role": "steward", "active": true }],
+  "allowedTools": ["read", "bash", "write", "zpeer_ask"],
+  "allowedPaths": ["reports/agentic-spec-runs/"],
+  "forbiddenPaths": [".env", ".env.*", "node_modules/", "dist/", "build/", "coverage/", ".git/", ".pi/sessions/", ".pi/coms/"],
+  "communicationPolicy": { "zpeerContact": true, "allowedRooms": ["spec-control", "intake"], "parentVisible": true, "hiddenPeerChat": false },
+  "localOnly": true,
+  "networkEnabled": false,
+  "bodyStored": false
+}