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.