zob-agentic-spec-team

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. It is a specialized Agent Factory pattern:

Skill = rules and operating contract
Factory = repeatable checkpoints, sentinels, validators
ZTeam/ZAgents = run-scoped human-facing team
CLI = scriptable entrypoint and tmux automation
Coms = parent-visible async asks, blockers, evidence refs, and oracle/no-ship routing

Use the generic examples/agent-factory-tmux-comms/ pattern for a smaller teaching version of the same shape.

Entry points

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:

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

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:

source_ref | owner_answer | explicit_assumption | decision_ref

The traceability matrix must connect:

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:

{
  "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:

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:

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>