Spec Builder

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:

one deliverable = one deliverable specification

The flexible mapping is delivery topology:

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.

1. Invariants — load-bearing constraints stated verbatim, restated in PR bodies.
2. 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.

1. Decisions — each with "why this over the alternative" rationale. 3-8 typical.
2. 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.

1. Acceptance criteria — numbered, testable, each citing the verifying test or

command.

1. 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.

1. 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.

1. Definition of Done — binary checklist; unchecked boxes go to the user, not

self-marked by the agent.

1. Open Questions — must be resolved by the user before code is written; logged

as resolutions in the run log.

1. Run Log Protocol — pointer to the run log when used,

including storage policy, append rules, sections, and session-start protocol.

1. Agent Implementation Prompt — paste-ready bootstrap for the implementing agent

session, including the lead/subagent coordination model and execution-tracking system instructions.

1. 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.

1. 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

1. Read this skill's bundled references/spec-driven-development-methodology.md.
2. Read project orientation (for example AGENTS.md or a repo-specific

orientation file) if present.

1. 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.

1. 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.

1. Read /standards/index.yaml from the active worktree when present and load only the

standards relevant to this deliverable's file set.

1. 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.

1. Inspect existing specifications in /specifications/ or the mirrored

external specification surface to calibrate level of detail.

1. 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
• Source: zazzcode/zazz-skills
• License: MIT

Install and usage instructions live in the source repository linked above.