SolidSpec: Stop Vibe-Coding, Start Building with AI — Try a new way

How a single CLI turns your AI coding agent from a code monkey into a disciplined software engineer

You open Claude Code. You type: “Build me a payment checkout flow with Stripe.” Thirty seconds later, you have 400 lines of code. It compiles. You’re thrilled.

Three weeks later, the feature is in production and the security team finds a PII exposure. The edge cases you forgot to mention are bugs. The tests that “will be added later” never were. The code that “works” doesn’t do what you actually needed.

Sound familiar?

This is the core problem with AI-assisted development as it’s practiced today: the gap between what you say and what you need. AI agents are incredibly capable at writing code — but they’re terrible at knowing what to write, why it should exist, and how to prove it’s correct.

SolidSpec is a Rust CLI that closes that gap. It doesn’t replace your AI agent. It gives it structure.

The Insight: AI Agents Need a Spec, Not Just a Prompt

Every experienced software engineer knows that the hardest part of a feature isn’t writing the code — it’s understanding the requirements well enough to write the right code. Senior engineers spend significant time on:

• Clarifying scope before touching a keyboard
• Designing interfaces before writing implementations
• Writing tests that fail for the right reason before adding any logic
• Validating that what was built matches what was intended

AI agents skip all of this. They jump straight to code because that’s what you asked for.

SolidSpec inserts the missing discipline layer. It generates structured artifacts — specs, plans, task lists, test reports — that drive your AI agent the way a senior tech lead would drive a junior developer. The agent doesn’t get to code until it knows what it’s building, why, and how success will be measured.

Seven Methodologies, One CLI

SolidSpec ships seven built-in workflows, each matching a different type of feature and risk profile. You pick the one that fits, and the CLI handles everything else.

SchemaArtifactsBest forminimal4Internal tools, spikes, known requirementsspec-driven9Standard team features (the default)security-first5Payment, auth, PII, regulated domainstdd-driven10Libraries, APIs, complex business logicintent-driven11Uncertain scope, compliance, long-lived featuresapex-driven9Complex features needing structured implementationintent-apex11Enterprise / maximum rigor

Let’s walk through the ones that matter most.

Workflow 1: spec-driven — The Standard

This is the default. Nine artifacts, full pipeline. It covers the vast majority of features.

spec → clarify → plan → tasks → tests → implement → analyze → review → ship

You run one command:

solidspec pipeline --new "User authentication with OAuth" --no-agent

SolidSpec creates specs/001-user-authentication/ with scaffolded templates for every artifact. Your AI agent gets structured slash commands registered in its native format — /solidspec-specify, /solidspec-plan, /solidspec-implement, and so on — with role-specific instructions at each phase.

The agent isn’t just told “write an auth system.” It’s told: You are a Spec Writer. Your job is to produce user stories in FR-### format, testable acceptance criteria using Given/When/Then, and a quality checklist. You are NOT writing code. Here is the anti-rationalization table of excuses you will not make…

The pipeline enforces order. The AI can’t implement until there’s a plan. It can’t generate a plan until there’s a spec. Each artifact is a dependency in a DAG, resolved by Kahn’s algorithm. You always know exactly what’s done and what’s next:

solidspec status 001

# Feature: 001-auth  |  Schema: spec-driven (built-in)
# 9 artifacts, 3 complete, 2 ready
#
# #   Artifact   Status       Depends On
# ───────────────────────────────────────
# 1   spec       ✓ done       —
# 2   clarify    ✓ done       spec
# 3   plan       ✓ done       spec
# 4   tasks      ▶ ready      spec, plan
# 5   tests      ▶ ready      spec
# 6   implement  ⏸ blocked    tasks

Workflow 2: tdd-driven — Real Test-Driven Development with AI

This one is my favorite, and the most recent addition. It brings genuine RED-GREEN-REFACTOR discipline to AI-assisted development.

Here’s the problem with how AI agents “do TDD” today: they don’t. They write tests after the fact, or they write tests and implementations simultaneously, which isn’t TDD — it’s test-decoration. The tests end up testing the implementation rather than the behavior.

tdd-driven fixes this at the structural level:

spec → clarify → plan → tasks
     → tdd-tests (RED)         ← agent writes ALL failing tests first
     → implement (GREEN)       ← agent implements ONE test at a time
     → tdd-refactor (REFACTOR) ← agent refactors, interface must not grow
     → analyze → review → ship

The RED Phase

When you run solidspec tdd-tests, SolidSpec generates a tdd-red-report.md that the agent must fill in before writing any test code. The scaffold forces the agent to:

1. Design interfaces first — what public APIs will the tests call? What gets injected vs. created internally?
2. Define mock boundaries — only external systems (HTTP, databases, file I/O) get mocked. Never your own modules.
3. Write the tracer bullet — the single most critical acceptance criterion becomes test #1. It must FAIL for the right reason before anything else is written.
4. Work through remaining criteria — one test per behavior, named after what it tests (user_can_log_in_with_email, not calls_verify_password).

The RED phase ends when every test compiles and fails because the implementation doesn’t exist yet. Not because of a wrong assertion. Not because of a missing import. Because the code isn’t there.

The GREEN Phase

The agent doesn’t get to write all the implementation at once. The tdd-red-report.md contains a cycle table — one row per acceptance criterion — and the agent works through it sequentially:

1. Run the full test suite. Find the next failing test.
2. Write the minimum code to make only that test GREEN.
3. Run the full suite again. The target must be GREEN. Nothing previously passing may go RED.
4. Mark the task complete. Move to the next test.

This is vertical slicing, not horizontal batching. It prevents the AI from writing speculative implementation for tests it hasn’t targeted yet.

The REFACTOR Phase

Once all tests are GREEN, solidspec tdd-refactor scaffolds a tdd-refactor-report.md. The agent looks for six named refactor candidates — Duplication, Long methods, Shallow modules, Feature envy, Primitive obsession, Interface creep — and applies changes one at a time. After every individual change, the full test suite must run GREEN. The interface must not grow.

Use tdd-driven when:

• You’re building a library or SDK that other services depend on
• You’re writing complex business logic (pricing engines, rule evaluators, state machines)
• You’re rewriting a working system where regressions are unacceptable
• The contractual definition of done is “all tests pass”

solidspec pipeline --new "JWT authentication library" --schema tdd-driven --no-agent

Workflow 3: security-first — OWASP Gates the Task List

Simple but powerful. The DAG won’t let you generate tasks until a security review exists:

spec → plan → security-review → tasks → implement

The AI agent audits the architecture plan against OWASP Top 10 before a single task is written. Every finding — Critical, High, Medium, Low — must have a corresponding mitigation task. You cannot implement around a Critical finding.

Use this for: payments, auth, PII storage, public API endpoints, healthcare, anything regulated.

solidspec pipeline --new "Stripe payment integration" --schema security-first --no-agent

Workflow 4: intent-driven — Proving WHY Something Was Built

This solves a problem that most teams don’t even realize they have: intent drift.

You spec a feature. You build it. Six months later, someone looks at the code and asks: “Why does this exist? What was it supposed to achieve?” Nobody remembers. The requirements technically pass, but the actual user need isn’t met. This is how you end up with features that are “done” but wrong.

intent-driven (IDSD — Intent-Driven Specification Development) adds a root anchor to the chain:

intent (WHY) → spec → clarify → plan → tasks → tests
             → implement → evidence → analyze → review → ship

The intent.md file captures three things before the first spec line is written:

• Goal — one sentence, no implementation details. “Users can authenticate securely without managing passwords.”
• Constraints — boundaries that must remain true. “No PII stored beyond hashed credentials. Must work offline.”
• Evidence — measurable criteria for success. “95% of login attempts complete in under 2 seconds. Zero stored plaintext credentials in penetration test.”

Every subsequent artifact traces back to this intent. solidspec analyze produces an intent drift score — the percentage of evidence criteria not yet covered by implemented tests. At 30% uncovered you get a High finding. At 70% you get Critical.

The full traceability chain looks like this:

INT-001 → FR-001 → T001 → test_auth.spec.ts

After implementation, solidspec evidence cross-references each evidence criterion against your implemented test scaffolds and produces a satisfaction report. solidspec evidence --update automatically rewrites intent.md status to active, satisfied, or drifted.

Use intent-driven when:

• The scope is uncertain or stakeholders disagree on what “done” means
• The feature will evolve over many iterations
• Compliance or audit requires a traceable, versioned record of requirements
• You suspect the team has drifted from the original vision

The Parallel Fan-Out Ship Gate

Every workflow that ends in ship runs four AI review lanes concurrently:

solidspec ship 001
                  │
      ┌───────────┼───────────┬───────────┐
      ▼           ▼           ▼           ▼
 Code Review  Security    Test        Performance
              Audit       Coverage
      │           │           │           │
      └───────────┴───────────┴───────────┘
                      │
              SHIP ✓  or  HOLD ✗

Each lane invokes a dedicated AI agent with a focused prompt. The security lane has an unconditional block on any CRITICAL finding — regardless of the overall score. The result is a machine-readable ship-report.md:

<!-- ship: true -->

Decision: SHIP

| Lane           | Score  | Status |
|----------------|--------|--------|
| Code Review    | 88/100 | ✓ Pass |
| Security Audit | 92/100 | ✓ Pass |
| Test Coverage  | 76/100 | ✓ Pass |
| Performance    | 65/100 | ✓ Pass |

Run it in CI with solidspec ship --fail-on-hold — exit 0 on SHIP, exit 1 on HOLD.

No AI agent? No problem. solidspec ship --no-agent runs heuristic-based scoring using the review artifacts already generated. A clean spec scores 100. A flawed one is penalized by finding severity.

20 AI Agents, One Interface

SolidSpec auto-detects which agents are present in your repository and registers slash commands in each agent’s native format:

• Claude Code → .claude/commands/solidspec-*.md
• Mistral Vibe → .vibe/skills/solidspec-*/SKILL.md
• GitHub Copilot → .github/agents/solidspec-*.agent.md
• Gemini CLI → .gemini/commands/solidspec-*.toml
• Cursor, Windsurf, Codex, Kiro, Qwen, opencode… (20 total)

If you have both Claude Code and Vibe installed:

mkdir .claude .vibe
solidspec init --here
# Registered commands for 2 agent(s): claude, vibe

Both get the same commands. The artifacts in specs/ are agent-agnostic. You can use Claude for specification and Vibe for implementation — they both read from the same tasks.md.

The automated pipeline can invoke agent CLIs directly:

# solidspec.toml
[pipeline]
specify   = "claude"
plan      = "claude"
tasks     = "claude"
implement = "vibe"     # different agent for implementation
analyze   = "claude"

solidspec pipeline --new "User auth with OAuth" --auto

Built-In Guardrails Against AI Shortcuts

Every agent prompt includes an anti-rationalization table — a list of the most common AI excuses and their rebuttals, injected automatically:

Agent excuseBuilt-in rebuttal”I’ll add tests after”Tests written after cover 30% fewer edge cases”This is too simple for a spec”Every section serves a purpose — empty = incomplete”I can infer the missing requirements”Inferred requirements diverge — make them explicit”It works — ship it””It works” is not a review

For TDD mode, there’s a dedicated set:

TDD excuseBuilt-in rebuttal”I’ll write all tests first, then all the code”That is horizontal slicing — DO NOT DO THIS”The test passes unexpectedly”STOP — investigate before proceeding”I’ll mock the internal service”Mock ONLY external systems — never your own modules”I’ll add a public method during refactor”Interface must not grow — FORBIDDEN

Getting Started in 3 Commands

# 1. Install
git clone https://github.com/jyjeanne/solidspec.git
cd solidspec && cargo build --release
# Copy solidspec.exe to your PATH

# 2. Initialize a project
mkdir my-app && cd my-app
mkdir .claude  # or .vibe, .github, etc.
solidspec init --here

# 3. Start your first feature
solidspec pipeline --new "My first feature" --no-agent

SolidSpec creates the project structure, registers slash commands for every detected agent, and generates the full artifact scaffold. From there, you can open your AI agent and follow the structured workflow — or let the automated pipeline drive the whole thing.

Choosing Your Workflow

Not sure which schema to pick? Here’s the decision table:

SituationUseQuick script, requirements fully knownminimalStandard team or solo featurespec-drivenPayment, auth, PII, regulated domainsecurity-firstLibrary, SDK, API with strict contractstdd-drivenBusiness logic refactored oftentdd-drivenUncertain scope, compliance requiredintent-drivenComplex implementation needing structureapex-drivenAll of the aboveintent-apex

The Bottom Line

AI coding agents are not going away. They’re getting faster, smarter, and more capable every month. But speed without structure produces technical debt at scale.

SolidSpec doesn’t slow down AI development — it makes it sustainable. You get the speed of AI generation with the correctness of structured engineering. Every artifact is versioned, every decision is traceable, every phase has a quality gate.

The code your AI writes when it has a spec, a plan, a task list, and a test report is categorically better than the code it writes from a one-line prompt.

Give your AI agent the structure it needs to do its best work.

SolidSpec is open source, MIT licensed, and built in Rust.

→ GitHub: https://github.com/jyjeanne/solidspec

solidspec --version
# solidspec 0.3.0

Built for engineers who want AI speed without sacrificing engineering discipline.