A deep dive into spec-driven development — from writing your first spec to shipping working code.
Zero to code in under 5 minutes.
Requires Go 1.21+ and a supported coding agent CLI (Claude Code, Bob, or Codex) installed and configured.
# install with gogo install github.com/jumppad-labs/spektacular@latest
# or download a pre-built binary from the releases page# https://github.com/jumppad-labs/spektacular/releasesRun this from the root of your codebase, naming the coding agent you want
to use (claude, bob, or codex). Creates a .spektacular/ directory
with config, knowledge base, and template files.
cd my-projectspektacular init claudeAll interaction with Spektacular 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-newSpektacular will then guide you through the process of gathering the required information to create a new 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 start generating code. This is also acheived by using a skill in your agents terminal.
/clear/spek-implementSpecs are plain markdown files. No special syntax — just structured sections that give the planning agent what it needs.
# 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 spec, generate a plan, then implement and validate — with the agent checking its own work against the spec at each handoff.
Run spektacular spec new to scaffold a spec from the template, then
fill in your requirements, constraints, and acceptance criteria. The
spec is plain markdown — no special syntax, just structured sections.
Specs don’t only start this way — during any open-ended discussion,
the agent watches for the moment it produces something spec-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.
Plan turns the spec 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 offers to walk through the
plan conversationally — the approach and reasoning, how the work
breaks into phases, and what was deliberately left out — before you
commit to it. You can interrupt with questions or changes at any
point; edits land directly in plan.md. Reading the documents
yourself remains just as valid — the walkthrough is optional.
Implement drives the coding agent through each phase of the plan and verifies the output against your acceptance criteria — so you know the implementation matches the spec.
Before it starts, Spektacular checks the plan’s phases against the
spec’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 spec’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/.
Install Spektacular and generate your first plan in minutes.
brew install jumppad-labs/homebrew-repo/spektacular