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 go
go 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-project
spektacular init claudeScaffold a new spec by passing a JSON payload with the feature name. The
command returns the normalised spec_name and spec_path — use those
for the follow-up steps rather than assuming the filename.
spektacular spec new --data '{"name":"auth-feature"}'
$EDITOR .spektacular/specs/<returned-spec-name>.mdPass the spec name returned by step 3. The plan workflow explores your
codebase, asks clarifying questions, and writes the plan to
.spektacular/plans/ when done.
spektacular plan new --data '{"name":"<returned-spec-name>"}'Pass the plan name returned by step 4. Spektacular drives the coding agent through each phase of the plan and validates the result against your acceptance criteria.
spektacular implement new --data '{"name":"<plan-name>"}'Specs are plain markdown files. No special syntax — just structured sections that give the planning agent what it needs.
# Feature: User Authentication
## Overview
Add OAuth2 login with Google and GitHub
providers 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 Approach
Use 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-Goals
Social 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.
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.
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 plan, plus supporting
research and context documents, are written to .spektacular/plans/.
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.
Install Spektacular and generate your first plan in minutes.
brew install jumppad-labs/homebrew-repo/spektacular