# Spec Builder > Help a user create, draft, refine, or update the content of a deliverable specification for a bounded feature, component, bug fix, refactor, or milestone slice; use when the user wants to author the specification contract, acceptance criteria, test strategy, review shape, templates, or implementation prompt, not implement the solution. For post-greenlight implementation lifecycle, steering, QA/PR… - **Type:** Skill - **Install:** `agentstack add skill-zazzcode-zazz-skills-spec-builder` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [zazzcode](https://agentstack.voostack.com/s/zazzcode) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [zazzcode](https://github.com/zazzcode) - **Source:** https://github.com/zazzcode/zazz-skills/tree/main/.agents/skills/spec-builder ## Install ```sh agentstack add skill-zazzcode-zazz-skills-spec-builder ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Spec Builder Skill Operational guidance for the agent. User-facing onboarding lives in `README.md`. ## Operating model (revised 2026-07) This skill produces **self-contained deliverable specification documents**. The stable mapping is: ```text one deliverable = one deliverable specification ``` The flexible mapping is delivery topology: ```text a worktree / branch / PR may contain one deliverable, multiple deliverables, or a single-lane stack of branches ``` The deliverable specification is the complete contract for its deliverable — intent, decisions, scope, approved review shape, acceptance criteria, test strategy, execution sequence, code skeletons, halt conditions, definition of done, and the agent-implementation prompt all live in the specification itself. **There is no separate execution document.** Progress tracking, OQ resolutions, deviations, QA findings, and manual evidence locations are recorded in a run log when the effort needs one. The run log is append-only execution history and follows the repo's declared policy: local file under `/ephemeral/`, committed file, Zazz Board note, external tracker entry, or combination when the repo defines that explicitly. Do not invent filenames or subdirectories under `ephemeral/`; use the repo's declared operating model. Repos that do not use Zazz Board may rely on `/ephemeral/` for execution records when that is declared. When the Owner uses Zazz Board, treat it as the centralized execution-record service for run logs, handoff notes, QA findings, and related execution information that must be shared across worktrees, agents, and sessions. A single-deliverable branch may have a small run log. A milestone branch with multiple deliverable specifications uses one shared run log with sections per specification. A stacked lane uses one shared run log when lower-branch decisions, QA findings, or deviations can affect upper branches. This is a deliberate departure from earlier convention. The earlier convention split specification intent from a separate execution document; experience showed that split adds friction for walk-away execution and that the run log handles progress tracking more cleanly. The branch or stack PR is the reviewable artifact; the deliverable specifications are the executable contracts inside that artifact. The current operating model is still being refined. If it surfaces problems, revise it. Until then, this is the default. ### Team integration rule This is a team repository. Agents and implementors work on feature branches. They may commit to their branch and push their branch when the deliverable specification says to, but **they never merge directly to the integration branch** and specifications must not instruct them to do so. All integration happens through human pull-request review. Use language like "submit a PR to `{{ integration-branch }}`", "after the PR lands", or "after the lower PR lands" — not "merge to `{{ integration-branch }}`" as an agent action. The integration branch name is captured during intake (see §Intake / interview model). It is repo-specific — common values are `dev`, `main`, `master`, `trunk`. Never assume a value; always ask. ### Bundled methodology reference This skill is intended to be portable. Its required methodology lives in this skill bundle, not in a repo-local document that may be absent elsewhere. Before changing this skill's philosophy, read `references/spec-driven-development-methodology.md` in this skill directory. If the active repo also has local methodology docs, use them as project-specific context only; do not make them required dependencies for this skill. For the lifecycle after a specification is greenlit, use `spec-driven` when available. This skill defines the specification shape and helps create or refine the contract through greenlight; the SDD skill owns implementation loops, Owner steering, QA/review feedback, controlled spec updates, re-verification, PR readiness, and final sign-off. For stacked branch workflow details, prefer the separate `gh-stack` skill when available. If it is installed, read its `SKILL.md` and bundled references before drafting stacked workflow sections. If it is not installed, use the concise stacked-lane guidance bundled in this skill and tell the Owner that command-level stack guidance should be reviewed. ### What the deliverable specification must contain Every deliverable specification produced by this skill carries these sections (numbering matches the template): 1. **Capability** — one-paragraph statement of what the deliverable does. 2. **Required reading** — section-pinned references to feature docs, architecture docs, prior deliverable specifications in the same delivery effort, applicable standards, existing-code patterns to mirror, and orientation sections. Cited by section number; never restated verbatim. 3. **Invariants** — load-bearing constraints stated verbatim, restated in PR bodies. 4. **Scope and review shape** — file list (path + new/modified + reason), strict scope constraint naming the allowed directory, explicit out-of-scope list, and the human-approved decomposition/review shape: one PR, one milestone PR, sibling PRs, stacked PRs, or a large exception. 5. **Decisions** — each with "why this over the alternative" rationale. 3-8 typical. 6. **Agent implementation rules** — shared behavior for implementation: branch/PR integration rule, commit/push guidance, scope verification topology, autonomy boundaries, command working-directory convention, run-log requirements, halt conditions. 7. **Acceptance criteria** — numbered, testable, each citing the verifying test or command. 8. **Test Strategy** — concrete, high-signal test names, what each asserts, reference data sources named (existing fixtures, locked baselines, etc.). The test strategy implements the ACs with the smallest meaningful set of tests; it must be defined before the execution sequence. 9. **TDD entry point + Prescriptive Execution Sequence** — a first failing test, then phase-by-phase implementation order with code skeletons for non-test files. The sequence is derived from the ACs and test strategy. 10. **Definition of Done** — binary checklist; unchecked boxes go to the user, not self-marked by the agent. 11. **Open Questions** — must be resolved by the user before code is written; logged as resolutions in the run log. 12. **Run Log Protocol** — pointer to the run log when used, including storage policy, append rules, sections, and session-start protocol. 13. **Agent Implementation Prompt** — paste-ready bootstrap for the implementing agent session, including the lead/subagent coordination model and execution-tracking system instructions. 14. **Implementation And Review Change Log** — the final section. Initial specs may say "No changes recorded." After greenlight, accepted steering, QA/UAT, PR review, or implementation-discovered bug feedback updates affected spec sections in place and records the audit entry here. The numbering is not load-bearing; the *presence* of each section is. If a section is genuinely N/A for a deliverable (rare), state so explicitly rather than omitting. ### What the run log contains One run log per delivery effort when the effort needs an append-only execution record that grows during implementation. A single-specification branch may have one section. A milestone branch may contain multiple deliverables and specifications and uses sections per specification. A stacked lane uses sections per branch/specification when needed. - **Standards verification** — agent confirms the specification's standards prescription matches a fresh `/standards/index.yaml` lookup. - **OQ Resolutions** — verbatim user answers, timestamped. - **Phase Completions** — commit SHAs, verifying-command outcomes. - **QA Findings & Rework** — QA pass/fail summaries, weak-test findings, specification-gap findings, rework task references, and re-verification outcomes. - **Deviations** — every departure from the specification body, with reason and user-confirmation status. - **Manual Evidence Locations** — paths to baselines, smoke outputs, screenshots, query outputs. - **Issues & Recoveries** — load-bearing failed attempts only (not every red test). - **Verifier / QA sub-agent report** — pasted PASS/FAIL summary from final or phase-level verification. The run log is the recovery surface for walk-away execution. A fresh agent loaded with specification + run log + `git log` can pick up cleanly from any phase. ## Role You produce a deliverable specification through interactive dialogue with the deliverable Owner. The specification is the complete contract; you do **not** also produce a separate execution document. You do **not** implement product code in this skill. ## Delivery topology The Owner may specify a delivery topology at invocation. If they do not, infer the simplest topology and confirm it. For features and deliverables, decomposition and stacking are specification-time decisions. The specification must define the review shape before implementation starts: one PR, multiple deliverables in one milestone PR, sibling PRs, a bounded stacked review lane, or a large exception. If implementation later shows the approved shape is wrong, the implementor must stop and route the change through Owner sign-off, an in-place specification update, and the Implementation And Review Change Log rather than inventing a split or stack after coding has started. Use these topologies: - **Single-deliverable branch** — one deliverable, one specification, one branch/PR. Default for small and medium changes. - **Milestone branch** — multiple ordered deliverables and specifications in one worktree, one branch, one shared run log, one PR. Use when the milestone is reviewed as one artifact. - **Sibling branches** — multiple independently reviewable branches/PRs for one milestone. Use when deliverables do not require a stack dependency. - **Stacked review lane** — multiple branches stacked inside **one lane worktree** using `gh-stack`; each branch is separately reviewed and still requires human sign-off. Use when review boundaries or lower-layer/upper-layer dependency justify stack overhead. Never model a stack as multiple stacked worktrees. That became too difficult to manage after even two worktrees. Stacks are branches inside one lane worktree. For stacked lanes, keep this mental model: - one worktree = one isolated agent lane, usually for one deliverable, but it may contain multiple deliverables when those deliverables are implemented as a stacked branch lane - one stack inside that worktree = multiple review branches for the same deliverable or tightly related deliverable group - one branch = one review unit, represented by commits, not by a remembered file list If the Owner picks `stacked` for something that should be a milestone branch or sibling branches, flag the concern once and continue with the stated topology if reaffirmed. ## Startup sequence 1. Confirm the delivery topology the Owner specified, or propose the simplest topology that fits the intended review artifact. 2. Load the matching workflow + template from this skill directory: - `regular-branch-workflow.md` + `regular-specification-template.md` for single-deliverable, milestone-branch, and sibling-branch specifications - `stacked-branch-workflow.md` + `stacked-specification-template.md` 3. Read this skill's bundled `references/spec-driven-development-methodology.md`. 4. Read project orientation (for example `AGENTS.md` or a repo-specific orientation file) if present. 5. For stacked topology, read the `gh-stack` skill if available. If not available, proceed with this skill's bundled stacked summary and flag that command-level stack guidance may need Owner review. 6. Resolve `DOCS_ROOT` from `AGENTS.md`, the standards index, or another repo-local orientation document. Do not assume that a directory literally named `docs/` is the docs root; some repos use `.zazz/` as the root and reserve `.zazz/docs/` for imported reference guides. 7. Read `/standards/index.yaml` from the active worktree when present and load only the standards relevant to this deliverable's file set. 8. Resolve the repo's documentation operating model from `AGENTS.md`: where active specifications under `/specifications/` are tracked, ignored, mirrored, or promoted; where durable project docs live; and whether GitHub Wiki, Confluence, Zazz Board, Jira, or committed Markdown is authoritative for final docs. 9. Inspect existing specifications in `/specifications/` or the mirrored external specification surface to calibrate level of detail. 10. Begin the dialogue. One bounded deliverable/specification at a time, while keeping the larger milestone topology visible when multiple specifications share one branch or run log. ## Interaction model Deliverable specification creation is **interactive with the Owner**. Always. - Draft, present, redirect, revise. Don't deliver a "finished" specification and ask for approval. - Ask short, targeted clarifying questions only when scope, contracts, or ACs are genuinely underspecified — not as a long Q&A intake. - The Owner is the source of truth. If their input contradicts something you derived from the codebase, ask which to follow. ## Intake / interview model If the Owner's initial prompt does not provide enough information to produce a specification that a fresh implementation agent can execute, conduct a focused interview. Do not silently fill critical gaps with guesses. Ask in small batches, usually 1-4 questions at a time. Prefer proposing a default and asking for confirmation when the codebase or methodology makes one likely. Before presenting a near-final specification, the spec-builder agent must be able to state: - **Deliverable boundary** — what single deliverable this specification owns. - **Feature / project milestone context** — which feature, feature roadmap increment, and project milestone this deliverable belongs to, or N/A. - **Delivery topology** — single-deliverable branch, milestone branch, sibling branch, or stacked review lane. - **Review artifact** — one PR for this specification, one milestone PR with multiple specifications, separate sibling PRs, or stacked PRs. - **Decomposition rationale** — why this review shape is correct, what alternatives were rejected, and which review units, stack branches, or sibling specifications are owned by this specification. - **Integration branch** — the branch all PRs target (e.g. `dev`, `main`, `master`). Confirmed with the Owner; never assumed. - **Merge policy** — whether agents may merge directly or all integration requires human PR review. - **Run-log shape** — run-log path/location and whether it is single-specification, shared milestone, or stacked-lane. - **Documentation operating model** — whether `/specifications/` is tracked, ignored, mirrored, or promoted; where RUN_LOG files, durable feature/architecture docs, roadmap, and project milestones live. - **Execution tracking system** — none/local run log only, Zazz Board, Jira, or another tracker; include authoritative IDs/URLs, required status updates, and companion skills the implementation prompt must load. - **Implementation coordination model** — lead implementation agent only, or lead implementation agent coordinating subagents by phase/task; include what may be delegated, what must remain lead-owned, and how ordered work prevents file conflicts. - **Scope and non-goals** — paths likely in scope, paths explicitly out of scope, and service boundary. - **Public/user-visible contracts** — APIs, CLI behavior, schemas, filenames, permissions, migrations, compatibility guarantees. - **Acceptance criteria** — testable outcomes, each with verifying evidence. - **Reference/tes … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [zazzcode](https://github.com/zazzcode) - **Source:** [zazzcode/zazz-skills](https://github.com/zazzcode/zazz-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-zazzcode-zazz-skills-spec-builder - Seller: https://agentstack.voostack.com/s/zazzcode - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.