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 the Claude Code CLI 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. Creates a .spektacular/ directory with config, knowledge base, and template files.
cd my-project
spektacular initScaffold a new spec file from the template, then fill in your requirements and constraints.
spektacular new auth-feature --title "User Authentication"
$EDITOR .spektacular/specs/auth-feature.mdThe TUI launches, streams agent output in real time, asks clarifying questions, and writes the plan when done.
spektacular plan .spektacular/specs/auth-feature.mdHand the plan to a coding agent. Spektacular executes each task, then validates the result against your acceptance criteria.
spektacular implement .spektacular/plans/auth-feature/plan.mdSpecs 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 scaled to complexity, then implement and validate.
Run spektacular 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.
Analyse uses a cheap, fast model to score the spec on a 0.0–1.0 complexity scale — examining requirement count, constraint density, technical keywords, and spec length. The score is returned in under a second.
Plan
uses that score to select a model tier. It loads your project
knowledge base, explores the codebase, and runs interactively
in the TUI — streaming markdown output and surfacing
clarifying questions you answer by pressing a key. The result
is written to .spektacular/plans/.
Implement hands the plan to a coding agent as a subprocess. The agent executes each task from the plan, and a validation step verifies the output against your acceptance criteria — so you know the implementation matches the spec.
Model routing and complexity thresholds are controlled by .spektacular/config.yaml.
models:
default: anthropic/claude-3-5-sonnet-20241022
tiers:
simple: anthropic/claude-3-5-haiku-20241022 # score 0.0–0.3
medium: anthropic/claude-3-5-sonnet-20241022 # score 0.3–0.6
complex: anthropic/claude-3-opus-20240229 # score 0.6+
complexity:
thresholds:
simple: 0.3
medium: 0.6
complex: 0.8
Model selection is automatic. Raise or lower the thresholds to tune how aggressively Spektacular routes to more capable (and more expensive) models. Environment variables are expanded — set ANTHROPIC_API_KEY and the default agent will use it automatically.
Spektacular is v0.1.0 — early development. The core spec → plan pipeline works. Here's what's coming next.
Contributions welcome — fork the repo and open a pull request.