| name | super-spec |
| description | Create product, technical, PRD, RFC, agent-build, and handoff specs from rough context. |
Super Spec
Super Spec turns rough operator context into an executable spec that a builder, reviewer, or agent fleet can act on after context compaction.
Use it when a task needs more than a plan: product requirements, technical design, proof gates, rollout, rollback, builder prompt, and reviewer prompt in one durable artifact.
What it produces
- Source map: evidence, constraints, assumptions, ignored context, and open questions.
- Goals and non-goals strong enough to stop scope creep.
- Requirements with acceptance criteria and validation method.
- Technical design, data/API surfaces, permissions, dependencies, and failure modes.
- Tests, evals, proof requirements, production QA gate, rollout, observability, and rollback.
- Traceability matrix from requirement to proof.
- Atomic build plan.
- Builder prompt and reviewer prompt.
- Route receipt showing whether the run used Pro or an explicit fallback.
Why it exists
Agent work often fails because the handoff is mushy: unclear requirements, hidden assumptions, no proof gate, and no way for another agent to resume after context compaction. Super Spec is the antidote. It compiles messy context into a document that can be built, reviewed, and audited.
Runner behavior
The included runner prefers a Pro/Oracle route when configured. It is fail-closed by default: if Pro is expected and the Pro route fails, it stops instead of silently writing a fallback spec. Use --no-pro for an intentional non-Pro run, or set SUPER_SPEC_ALLOW_CODEX_FALLBACK=on only when a fallback spec is acceptable.
For long Pro jobs, use background Responses mode and enough time:
export SUPER_SPEC_ORACLE_BACKGROUND_MODE=on
export SUPER_SPEC_PRO_TIMEOUT=3600
export SUPER_SPEC_PRO_HTTP_TIMEOUT=60m
export SUPER_SPEC_ORACLE_WALL_TIMEOUT=3700s
Install
curl -sSf https://superada.ai/install/super-spec | sh
Run
super-spec --title "Enterprise Local Model Orchestrator" --input context.md
Or directly:
skills/super-spec/scripts/run-super-spec.sh --title "<title>" --input <context-file>
Configuration
Set these when using a Pro route:
export SUPER_SPEC_PRO_MODEL=gpt-5.4-pro
export SUPER_SPEC_PRO_BASE_URL=http://127.0.0.1:4000/v1
export SUPER_SPEC_PRO_API_KEY=...
For Azure Responses via Oracle, set your own deployment values:
export SUPER_SPEC_AZURE_ENDPOINT=https://your-resource.openai.azure.com
export SUPER_SPEC_AZURE_DEPLOYMENT=gpt-5.4-pro
export SUPER_SPEC_AZURE_API_VERSION=2025-04-01-preview
Do not paste API keys into specs, prompts, or public docs.
Quality bar
- The spec must reduce degrees of freedom for the builder.
- Requirements must be testable or explicitly unresolved.
- Non-goals must block obvious scope creep.
- Every risky assumption needs a validation path.
- Tasks must be small enough for review and proof.
- The final spec must be resumable by another agent after context compaction.
