A deep dive into spec-driven development, from writing your first spek to shipping working code.
Zero to code in under 5 minutes.
Requires Go 1.21+ and a supported coding agent CLI (Claude Code, Bob, Codex, or oh-my-pi) installed and configured.
# install with gogo install github.com/hivecommons/spektacular@latest
# or download a pre-built binary from the releases page# https://github.com/hivecommons/spektacular/releasesRun this from the root of your codebase, naming the coding agent you want
to use (claude, bob, codex, or omp). Creates a .spektacular/ directory
with config, knowledge base, and template files.
cd my-projectspektacular init claudeFor oh-my-pi, use spektacular init omp, start omp here in the project’s
top folder, then enter /spek-new your feature (or /skill:spek-new).
Spektacular’s commands only work from that folder, and omp only discovers
the plain commands there. Once root AGENTS.md exists, omp does not read
root CLAUDE.md; put instructions omp should see in AGENTS.md instead.
See the omp integration for installed files and shared-project
upgrade behaviour.
All interaction with Spek is through your agent, spektacular provides the agent skills that instruct it how to perform various capabilies like creating a new specification.
To create a new specification using the agent Claude Code you can run the following command in the agents terminal:
/spek-newSpek will then interview you first, adaptive questions about what you’re building, before guiding you through drafting and confirming each section of the specification.
Once the specification has been created, next you move on to generate a detailed technical plan for the implementation of the specification. This is also achieved by using a skill in your agents terminal.
Note: The aim of spektacular is to make conservative use of tokens for your coding agent. It has been designed that no agent context is required from the previous steps. For this reason you should clear your agents context before running the next command to generate a plan.
/clear # Clear the agents context before generating a plan/spek-planFinally, once the plan is complete and you are happy with it, it is time to implement the spek and start generating code. You implement a spek, and its plan (which shares the spek’s name) is how the implement workflow carries it out. This is also acheived by using a skill in your agents terminal.
/clear/spek-implementFour words do most of the work in this documentation. They nest, and the nesting is the whole model.
A workflow is the full journey of one feature, from an idea to merged code. It runs in three stages — Spec, Plan, Implement — and each stage is broken into steps, driven by a state machine.
Workflow├── Stage: Spec│ └── Steps: overview → requirements → acceptance_criteria → ...├── Stage: Plan│ └── Steps: discovery → architecture → milestones → tasks → ...└── Stage: Implement └── Steps: read_plan → implement → test → verify → ...A stage is one of Spec, Plan, or Implement. Each produces an artifact
the next one consumes: the spek says what to build, the plan says how, and
implement carries it out and records what happened. A stage is entered with
spektacular <stage> new and runs to completion before the next begins.
A step is a single unit of work within a stage — one question to answer,
one section to draft, one file to write. Steps are not suggestions the agent
may reorder or skip: the state machine decides which step is current, what
it needs, and when the stage may advance. Run spektacular plan steps to
list the steps of a stage, or spektacular status to see where a
running one has got to.
A task is one unit of work in a plan: it sits under a milestone, targets
one repository, and is carried out by an agent or by a person. When the Plan
stage reaches its tasks step it breaks the work into tasks, each with its
own id, the tasks it depends on, and its own acceptance criteria. The
Implement stage then carries them out, either the whole plan in one run or one
task at a time. So a stage is one third of a workflow, while a task is one
unit of work described by a plan. They are not the same unit, and the docs
keep them distinct. See Plan tasks for the task format and
how to see where a plan’s tasks stand.
Spek implements StateFlow, which separates driving the process from doing the work.
The steps within a stage are not a prompt asking an agent to remember a checklist. They are a state machine, following the approach set out in StateFlow: Enhancing LLM Task-Solving through State-Driven Workflows (Wu, Yue, Zhang, Wang and Wu, arXiv:2403.11322).
StateFlow’s central claim is that a complex task goes better when you separate process grounding from sub-task solving. A state represents the status of a running process; entering it triggers actions, such as prompting a model or calling a tool; and transitions out of it are governed by explicit rules rather than by the model’s own sense of having finished.
Spek maps onto that directly. The state machine owns the process: it
knows the current step, what that step requires, and what must be true
before the stage advances. The agent owns the work inside a step, and only
that. This is why progress survives a context window ending, a crashed
session, or a switch between agents — the state lives in state.json rather
than in a conversation, so spektacular status can always answer
where things stand.
The paper reports the practical effect of this split: on InterCode SQL, a 13% higher success rate at a fifth of the cost compared with a ReAct-style baseline, and on ALFWorld, 28% higher at a third of the cost. Constraining when a model acts turns out to matter as much as prompting how.
Speks are plain markdown files. No special syntax, just structured sections
that give the planning agent what it needs. The Requirements and Constraints
sections follow ISO/IEC/IEEE 29148:2018,
the international standard for requirements engineering in systems and
software; the rest of the sections are ours. A spek started from existing
material records where its content came from in a sources list, and a
spek that belongs to an epic names it in epic.
# Feature: User Authentication
## OverviewAdd OAuth2 login with Google and GitHubproviders to the existing Express app.
## Requirements- [ ] Users can sign in with Google OAuth2- [ ] Users can sign in with GitHub OAuth2- [ ] Session persists across browser refreshes- [ ] Logout clears session and redirects
## Constraints- Must use existing Express backend- No new dependencies over 50KB gzipped- Cannot change the /api/users schema
## Acceptance Criteria- [ ] Login redirects to provider, returns with valid session- [ ] Session cookie is httpOnly, secure, sameSite=strict- [ ] Logout flow works end-to-end
## Technical ApproachUse passport.js for OAuth2 strategy.Integrate with existing session middleware.
## Success Metrics- OAuth2 login completes in under 2 seconds- Zero increase in /api/users error rate
## Non-GoalsSocial login with Apple or Microsoft.A concise 2–3 sentence summary answering: what is being built, what problem does it solve, and who benefits? Grounds the agent before it reads anything else.
A checklist of discrete behaviours. Use active voice (“Users can…”). Each item should be independently verifiable and focus on what, not how.
Non-negotiable boundaries: existing APIs, dependency limits, performance budgets. Violations are plan failures. Leave blank if none.
Binary pass/fail conditions, each traceable to a requirement and testable by someone who didn’t write the code. These become the verification steps in the output plan.
High-level technical direction: key architectural decisions, preferred patterns, integration points, and known risks. Leave blank to let the planner propose an approach.
How you’ll know it works well after delivery. Quantitative (“p99 latency < 200ms”) or behavioural (“users complete the flow without support”). Leave blank if not applicable.
Explicitly out of scope, prevents scope creep and over-engineering. Leave blank if there are no exclusions to call out.
Three stages: write the spek, generate a plan, then implement and validate, with the agent checking its own work against the spek at each handoff.
Before Spek drafts a single section, it interviews you. Rather than working through a fixed script, the agent asks open questions about what you’re building, adapting each one to what you’ve already said, a technique called Flipped Interaction, drawn from prompt-engineering research on shifting conversational control to the agent.
Agent: What are you building, and who runs into the problem it solves?You: A CLI users can point at a local repo to check for outdated dependencies.Agent: Should it just report outdated packages, or offer to upgrade them too?You: Report only, for now, upgrading is a separate feature.Agent: Got it, I have enough to draft an Overview. One more thing: does this touch the docs site too, or is it CLI-only for now?The interview stops once no further question would change the draft, not once every possible detail has been asked about.
In a project with more than one registered repo, the interview already knows the full roster, so a feature that reads as focused on one repo still gets asked about impact on the others, shaped by what each one actually is:
Agent: This project also has a "docs" repo registered (role: documentation). Does exposing this as a new CLI flag mean the docs site needs a new page or section too?You: Yes, it should get its own reference page.From there, each section, Requirements, Constraints, Acceptance Criteria, and the rest, is drafted from what the interview established and presented back for you to confirm or correct, rather than asked from a blank prompt. Rejecting a draft opens a short follow-up conversation to understand why before anything changes, since a single correction can turn out to need more than one change. The spek itself stays plain markdown, no special syntax, just structured sections.
Speks don’t only start this way: during any open-ended discussion,
the agent watches for the moment it produces something spek-worthy (a
scoped decision, a multi-requirement feature) and proactively offers
to capture it, calibrated by the spec_trigger_threshold
config key. It always proposes before starting,
never begins unilaterally.
Starting from existing material. Speks don’t only start from a
conversation. Point Spek at an issue, a tracker epic, a design
document, a file, a web page or pasted text (“spec from #45”), and it
fetches the material with your agent’s own tools, drafts every section
it can, lists what the material leaves out, and asks only about those
gaps. Each section step then presents its pre-filled draft for you to
confirm or refine, rather than asking from scratch. If the agent has no
tool that can reach the source, it says so and asks you to paste the
content. The spek records where its content came from in sources,
with the date each one was retrieved:
sources: - uri: https://github.com/hivecommons/spektacular/issues/70 retrieved_date: "2026-09-28"Spektacular itself never fetches anything: the agent does, and the CLI only records the provenance. A source that already lists child items, such as a tracker epic with sub-issues, leads to an offer to set up an epic with one spek per child instead of a single spek.
Plan turns the spek into a detailed implementation plan. It loads
your project knowledge base, explores the codebase,
and surfaces clarifying questions before writing anything. The
conventions, gotchas, decisions, and architecture it draws from the
knowledge base are woven directly into the plan, so the output reflects
how your project works rather than a generic approach. The plan, plus
supporting research and context documents, are written to
.spektacular/plans/.
Once the documents are written, the agent walks you through the plan
conversationally before you sign it off: the approach and reasoning,
how the work breaks into tasks (naming every task that needs a person,
and why), and what was deliberately left out. You can interrupt with
questions or changes at any point; edits land directly in plan.md.
The walkthrough is part of every plan and ends only when you confirm
the plan is right.
Implement carries out a spek: you name the spek to implement, and Spek drives the coding agent through each phase of its plan and verifies the output against your acceptance criteria, so you know the implementation matches the spek. A spek that belongs to an epic is first checked against the speks it depends on, so you know before the first task if one of them is not implemented yet.
Before it starts, Spek checks the plan’s phases against the
spek’s Requirements and Acceptance Criteria checklist: any gap must
be either filled in or explicitly accepted as a descope. After
implementation finishes, it checks the spek’s checklist against what
was actually built, and writes a changelog record of what shipped,
why, and how it differed from the plan to .spektacular/changelog/.
Once written, the spek and plan become a historical, archaeological record, not a live description of current behavior.
A coding agent asked how the system works today reads the code, not the spec: a spek and plan are a process document, not a product document, capturing the intent and scope at the time they were written, while the codebase keeps moving. Ask why something was built a particular way, though, and the agent will still open and cite the relevant spek, plan, or changelog record to explain the original reasoning.
The knowledge base is the exception. Entries there are current and binding rather than historical: they state how the project works and how work in it must be done. Where an entry and the code disagree, the entry states the target and the code is what has yet to meet it.
Every spek, plan, and changelog record Spek writes carries the same lifecycle metadata, tracked automatically without any extra configuration.
draft, final, superseded or archived).This metadata is what makes the archaeology model workable at scale: as speks, plans, and changelog records pile up across a project’s history, document status and dates are how you and your agent tell a still-active record from a closed one, or find the handful of records that matter out of hundreds. Every record supports filtering by this metadata from the CLI.
Install Spektacular (Spek) and generate your first plan in minutes.
brew install hivecommons/homebrew-repo/spektacular