What is Spec-first?
Spec-first is a repository-based workflow for using AI coding agents to plan, review, build, and deliver software changes from written specifications. It guides work through four stages: create a spec with code references and done criteria, have a fresh reviewer check it, build in an isolated branch and worktree, then commit through project checks and open a pull request. A Claude Code plugin runs the workflow, while other agents can follow the same files through AGENTS.md and a Git hook.
Spec-first Features:
Spec Creation: The create-spec skill records a goal, steps, code facts with file and line references, and criteria for when the work is done.
Evidence Review: A script checks cited files and lines, and a fresh reviewer returns a BUILD, BUILD WITH CUTS, or REFUSE verdict with findings tied to code locations.
Isolated Builds: The apply-spec skill builds each change on its own branch and worktree, following the spec and the project's stated rules.
Commit Gate: A commit gate runs the project's declared verification stages for spec commits, blocking the commit when a stage fails and returning its output to the agent.
Series Delivery: The deliver-series skill builds groups of specs that do not share files in parallel, verifies the merged tree, and opens one pull request.
Decision Records: The workflow logs choices made during implementation, including what alternatives they beat and why, in YAML files alongside the code.
Resumable Context: Project context and workflow state are stored in files such as context.yaml so an agent can resume after a restart.
Spec-first Benefits:
Fewer Late Changes: Reviewing assumptions against the code before implementation can catch gaps before they turn into changes on a build branch.
Clearer Handoffs: Specs, done criteria, and decision records give developers and agents a shared account of the intended change and its reasoning.
Safer Delivery: Running project checks before a commit helps keep changes that fail those checks from landing.
Recoverable Work: Recorded state makes it easier to pick up an active task after restarting the machine or agent.
Parallel Progress: Separate worktrees let independent specs move forward at the same time without sharing a working branch.
Use Cases:
Feature Planning: Turn a feature idea described in everyday language into a reviewed implementation plan before an agent writes code.
Ticket Delivery: Use GitHub or Jira tickets as inputs to a workflow that takes planned work through implementation and pull request delivery.
Multi-Part Changes: Break a larger software change into related specs, then build independent parts concurrently and deliver them together.
Repository Upgrades: Plan and carry out an upgrade with explicit code references, operator costs, and completion criteria in its spec.
Agent Restarts: Resume an interrupted coding task by checking the saved project context, active work, and next steps.

