SuperSpecs: The Discipline Framework That Stops Your AI Agent From Going Rogue

How spec-driven planning, enforced TDD, and a wiki that never forgets finally tame the chaos of AI-assisted software development

https://github.com/fokkerone/superspecs

The Problem No One Talks About

You’ve been there. You spend a Tuesday afternoon pairing with Claude or Cursor. You make great progress — authentication logic sketched out, a clean data model emerging, three clever architectural decisions negotiated with your AI co-pilot. You close the laptop feeling good.

Wednesday morning: the agent knows nothing. The conversation is gone. You start explaining JWT refresh tokens from scratch. The agent confidently builds something that contradicts a decision you made yesterday. You catch it halfway through. You backtrack.

https://github.com/fokkerone/superspecs

By the third week, your codebase is a graveyard of half-baked patterns. The agent keeps re-solving the same problems. Tests are absent or tacked on afterward. Technical debt compounds faster than you can track it.

This isn’t a model capability problem. It’s a structural one. AI coding agents have no memory between sessions, no enforced process, and no accountability to a shared source of truth. Without discipline around how you use them, they’re a very fast way to dig yourself into a deep hole.

***SuperSpecs fixes this.***

What SuperSpecs Actually Is

SuperSpecs is a discipline framework for AI-driven software development built entirely on Markdown files. No runtime, no custom integrations, no vendor lock-in. It works by injecting structured, opinionated workflow instructions into your AI agent’s context at the start of every session.

Its design rests on three interlocking pillars:

1. Spec — Before any code is written, intent is captured as testable, machine-readable requirements: SHALL statements and GIVEN/WHEN/THEN scenarios. The spec is deliberately sized to fit inside a fresh 200,000-token context window. Any executor — any agent, any session, any model vendor — can pick it up tomorrow and start fully informed. No prior chat history required. No tribal knowledge needed.

2. TDD — RED before GREEN, without exception. Tests are written first. Code written without a failing test gets deleted and restarted. The test suite is the ground truth, not the agent’s self-assessed confidence level.

3. Wiki — After every shipped feature, knowledge is distilled into structured wiki pages: architecture decisions, patterns, trade-offs, gotchas, interface contracts. The next session opens the wiki and starts informed, not blind. Knowledge compounds. Problems stay solved.

The result: multiple AI agents can run in parallel, each with a fresh context window, each working from the same spec, each contributing to the same growing knowledge base — with nothing lost between sessions.

The Four-Phase Lifecycle

SuperSpecs divides every feature into four distinct phases. Skip a phase and the framework won’t let you proceed. This is not optional — it is the discipline.

Phase 0 — Setup (/techstack)

Run once per project. The agent acts as a senior tech lead running a guided discovery session. It asks about your stack: frontend framework, backend language, deployment target, CI/CD pipeline, quality tooling, team constraints.

From your answers it produces three things: a recommended list of installable skills mapped to your specific technology choices, concrete versioned library recommendations per domain, and a stack-specific production-readiness checklist tailored to what you’re actually building.

It writes the result to superspec/wiki/techstack/profile.md. Every future session can check this file and immediately understand the project’s technical context — without you having to explain it again.

Phase 1 — Plan (/discuss + /spec)

This is where most AI-assisted projects fail. The agent starts coding before anyone agrees on what is being built. SuperSpecs makes this structurally impossible.

/discuss captures intent before any spec is written. The agent reads your existing wiki, then asks you to describe the feature conversationally — but it asks one question at a time, covering what you’re building, why it matters now, what the constraints are, what success looks like, and what the risks are. The output is DISCUSS.md: goals, non-goals, constraints, key decisions with explicit rationale, rejected alternatives, open questions, success criteria, and identified risks.

/spec then transforms that discussion doc into a formal, testable spec. Each SHALL requirement must have at least one happy-path scenario and one edge-case or error scenario in GIVEN/WHEN/THEN format. Implementation details are explicitly forbidden inside the spec — no code, no file paths, no library choices. The spec describes behavior, not implementation. It also produces tasks.md: concrete implementation tasks organized into waves (Wave 1 Foundation → Wave 2 Core Logic → Wave 3 Integration), each with a precise description, the files to touch, a test requirement, and a “done when” definition.

The context window check is a hard constraint: if the spec is more than 150,000 tokens, the workflow stops and forces decomposition into sub-specs. This keeps every single executor — human or agent — fully oriented without hitting a token cliff.

Phase 2 — Execute (/pick-spec → /branch → /subagent → /tdd → /code-review)

Execution is where SuperSpecs earns its reputation. It is a tightly controlled assembly line.

/pick-spec is the gate between planning and execution. It validates the spec for completeness (every requirement has a scenario, every scenario is testable), clarity (no ambiguous SHALLs, no under-specified tasks), and context budget. If validation fails, you get a specific list of what to fix. Nothing is dispatched until the spec is clean.

/branch creates an isolated execution environment: one branch per spec, no exceptions. For truly parallel execution — multiple specs running simultaneously — git worktrees are the recommended path. Each spec lives in its own directory with its own working tree, avoiding the file-system conflicts that come from running multiple agents on the same checkout.

/subagent orchestrates wave-based execution. Each task gets assembled into a precise context package: the full spec, the single task block, and the current codebase state — and nothing else. No chat history. No accumulated context drift. A fresh 200k window per task, every time.

Between tasks, two reviews always run in sequence.

/tdd enforces the RED → GREEN → REFACTOR cycle with no loopholes. The agent reads the task’s test requirement first. It writes a test for the behavior — not implementation details. It runs only the new test and confirms it fails for the right reason: because the feature doesn’t exist yet. If the test passes immediately, the test is wrong and must be fixed before anything else happens. Then the agent writes the minimum implementation to make the test pass (YAGNI strictly enforced — no “I might need this later” additions). Full suite runs. Then REFACTOR: clean up without changing behavior, verify tests stay green, commit with a structured message.

If code was written before a test, the agent deletes the implementation and restarts from RED. This is not a suggestion.

/code-review runs two passes between every task. Pass 1 is spec compliance: for each requirement in scope, find the test coverage, verify the behavior matches the spec. Any Critical finding in Pass 1 stops everything — Pass 2 doesn’t run. Pass 2 is code quality: logic correctness, test quality, structure (DRY, YAGNI, clarity), consistency with existing patterns. A blocked review requires a clean re-review to clear. There is no “approve with outstanding criticals.”

The severity model is explicit:

| Severity | Meaning | Action |
| - -| - -| - -|
| **Critical** | Spec violation, security issue, data loss risk, test circumvented | Hard stop |
| **High** | Logic error, wrong behavior, missing error handling | Must resolve before wave ends |
| **Medium** | Code quality, missed edge case | Logged, addressed |
| **Low** | Style, naming, minor improvement | Logged, optional |

After each wave completes, execution pauses for a human checkpoint. You review the wave results, the review log, and the test output before the next wave begins. This is the moment to catch drift before it compounds.

Phase 3 — Verify (/check-tests + /wiki)

/check-tests runs the full test suite and then does something most CI pipelines skip: it walks every GIVEN/WHEN/THEN scenario in spec.md and verifies each one has a corresponding test. Uncovered scenarios are Critical gaps that block shipping. Code coverage metrics are informational — scenario coverage is the actual requirement.

/wiki distills the completed feature into the living project knowledge base. It reads the discussion doc, spec, review log, and key implementation files. It writes structured wiki pages with YAML frontmatter (title, tags, spec reference, dates, sources) organized by domain folder (auth/, api/, data/, ui/, infra/, patterns/, decisions/). Every page captures: summary, context, key decisions with rationale and trade-offs, patterns with short code examples, gotchas, interface contracts, open questions. It cross-links to related wiki pages bidirectionally.

This is what makes the whole system compound. Each new feature doesn’t just add code — it adds knowledge. The next planning session starts by reading the wiki and immediately understands the patterns, the decisions, and the pitfalls that came before.

Phase 4 — Ship (/ship)

Precondition checks before a PR is created: all tests passing, wiki imported, no open Critical review findings, branch is superspec/<slug>. The agent writes a structured PR description (what, why, how it works, test summary, spec link, wiki links), creates the PR, writes a CHANGELOG entry, archives the phase directory, and marks the spec as shipped. Then it surfaces what’s ready to execute next, or prompts you to start a new feature.

The Four Rules That Make It Work

SuperSpecs is opinionated. It has four hard rules and it enforces them structurally:

1. No implementation code before a failing test. Not “try to write tests first.” Not “tests are encouraged.” Write a test. Watch it fail. Then write code. If you violate this, delete the code and restart.

2. Critical code-review findings block all progress. One uncovered scenario, one spec violation, one security issue — everything stops. There is no “we’ll address it in the next sprint.”

3. Spec must fit a fresh 200k-token context window. If it doesn’t fit, decompose it. This isn’t a best practice — it’s a structural requirement. An executor that can’t read the whole spec in one shot is flying blind.

4. Every shipped feature produces a wiki page. The knowledge doesn’t live in chat history. It doesn’t live in your head. It lives in a structured, searchable, cross-linked wiki page that any agent or developer can read on day one.

These rules aren’t suggestions to help things go slightly better. They’re the mechanisms that prevent the specific failure modes that make AI-assisted development go wrong: context amnesia, spec drift, test debt, and knowledge evaporation.

The Wiki: What Actually Compounds Over Time

The wiki deserves its own attention because it’s the part of SuperSpecs that most fundamentally changes the AI development experience at scale.

Andrej Karpathy observed that AI agents have ephemeral context windows — they start each session with no memory of what came before. Most teams try to solve this with long system prompts, chat history pasting, or just accepting the redundancy and re-explaining the same things over and over.

SuperSpecs takes the opposite approach: treat the wiki as the persistent layer of the system, and design every session to read from it first. The wiki is not documentation for humans. It’s an information substrate for agents.

When you run **/discuss** for a new feature, the agent reads the wiki before asking you anything. It knows what patterns you’ve already established. It knows what decisions you’ve already made and why. It knows what you tried and abandoned. It doesn’t ask you to explain your JWT strategy because you already wrote a wiki page about it.

When you run **/techstack**, the profile lives in the wiki. When you run /**wiki**, you’re not writing docs for posterity — you’re pre-loading next session’s context with everything worth knowing about the code you just shipped.

The wiki grows. Its value compounds. A project six months in has a wiki that makes every new feature cheaper and more coherent than the last. This is the flywheel that traditional AI-assisted development completely lacks.

— -

Works With Every Major Agent

SuperSpecs is installed once and works across every major AI coding tool. No custom integration code. No vendor-specific logic. It works by creating symlinked Markdown files that each agent reads at startup.

Bootstrap files exist for: Claude Code, OpenCode, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Aider, Codex, and Kiro. When the agent reads its bootstrap file at session start, it gets the lifecycle summary and the available slash commands. When you invoke a skill, it reads the full step-by-step instructions from the corresponding SKILL.md file.

The architecture is deliberately minimal: twelve Markdown files, one install script, zero runtime dependencies. The entire framework is a behavior injected into your agent’s context — not a service to maintain, not an API to integrate, not a plugin to keep updated.

— -

Installing in Three Minutes

Option 1 — Global clone (recommended):

git clone https://github.com/your-org/superspecs.git ~/.superspecs
bash ~/.superspecs/setup.sh

Option 2 — npm:

npm install -g superspecs && superspecs install
# or: npx superspecs install

Option 3 — Per-project embed:**

git clone https://github.com/your-org/superspecs.git .superspecs
bash .superspecs/setup.sh

After installation, open your agent and say: ”Tell me about your superspecs.” A correctly installed agent describes the four-phase lifecycle, all available commands, and the four hard rules.

Your first feature workflow:

/techstack → define stack, get library and skill recommendations /discuss → capture decisions before planning /spec → write the testable spec /pick-spec → validate + prepare execution /branch → create isolated branch or worktree /subagent → execute wave by wave with TDD /check-tests → verify every scenario is covered /wiki → distill to knowledge base /ship → PR, archive, next cycle

# Who This Is For

SuperSpecs is for teams who have already experienced the failure modes of unstructured AI-assisted development and want a systematic fix. It is **not** for exploratory hacking, throwaway prototypes, or one-off scripts. It is for software you intend to maintain, extend, and hand to other developers — or other agents.

It is particularly powerful in these scenarios:

- **Multiple AI agents working in parallel** on the same codebase. Each agent works from the same spec, in its own worktree, with a fresh context window. Parallel execution with no shared state and no context contamination.

- **Long-running projects** where context amnesia compounds. The wiki grows with every shipped feature. Three months in, every new session starts with a rich, accurate knowledge base instead of a blank slate.

- **Teams with multiple developers** where architectural consistency matters. Decisions made by one developer — or one agent session — are recorded in the wiki with their rationale. No one contradicts yesterday’s decision because they didn’t know it existed.

- **Onboarding** new developers or switching AI agents. The spec is fully self-contained. The wiki covers the key decisions. A new contributor can get oriented in minutes.

# The Bigger Picture

There is a version of AI-assisted development that actually gets better over time — where each feature builds on the last, where knowledge accumulates instead of evaporating, where parallel agents amplify rather than contaminate each other, where tests exist not because someone remembered to write them but because the process makes it impossible to skip them.

That version requires discipline. Not the discipline of trying harder, but the discipline of having a framework that makes the right thing the easy thing.

SuperSpecs is that framework. It is not magic. It is a set of opinionated conventions, enforced at the process level, that take the specific failure modes of AI coding agents and make them structurally impossible. It does not make your agents smarter. It makes your development process rigorous — and rigor is what compounds.

The context window resets every session. The wiki doesn’t. The spec persists. The tests accumulate. The wiki grows. Every session inherits the sum of every session before it.

That’s the system. That’s SuperSpecs.

*SuperSpecs is open source and works with Claude Code, Cursor, OpenCode, Copilot, Gemini CLI, Windsurf, Aider, Codex, and Kiro. Install it in three minutes with a single shell command.
Superspecs is under heavy development, things might change*