Introducing speq-skill: a workflow that guides your coding agent

Everybody agrees: AI makes code cheap. The question is: how do you get the AI to produce working and tested software?

In the past months I have worked intensively with coding agents. My favorite agent so far is Claude Code, and since the release of Opus 4.6 it has become my go-to tool for writing software.

Here’s what I’ve learned:

The bottleneck is no longer writing code.
It’s telling the agent what to build. Precisely enough that the result actually works.

Today, most people deal with this in one of two ways:

Vibe coding — just prompt and iterate. It’s fast for prototypes, but it doesn’t scale.
Copy-paste prompting — collect snippets and prompt templates, paste them in before each task. Better than vibe coding, but it doesn’t build a lasting knowledge base.

What both approaches are missing is a system.

What’s missing is a system#

I’ve written about this on the blog: spec-driven development as a methodology, why vibe coding doesn’t scale, and how to write effective specs. For me, spec-driven development is the missing system for coding agents.

There are many spec-driven development tools out there, but none of them gave me:

A straightforward, repeatable workflow
No lock-in to a single language or framework
A permanent spec library that grows with the project
Specs that stay small, so the context window stays clean
A system that asks me instead of making assumptions
A system that works in brownfield projects, too

Introducing speq-skill#

So I built speq-skill. It’s a free plugin for Claude Code and Codex. It is a set of skills that guide the agent through one workflow: plan → implement → record.

The core idea: your specs live permanently in your project. The skills tell the agent what to do in each phase, what to ask you, and which rules to follow. A small CLI, speq, lets the agent list and read the spec library, so it only reads the specs that matter for the task.

The workflow#

/speq:mission → specs/mission.md + specs/architecture.md (once per project)
                       │
      ┌────────────────┼────────────────┐
      ▼                ▼                ▼
/speq:plan  →  /speq:implement  →  /speq:record  (repeat)

Mission#

Run /speq:mission once per project. In a brownfield project, the agent explores your codebase. In a greenfield project, it interviews you. The result is specs/mission.md and specs/architecture.md: the purpose, users, tech stack, and architecture that every future session needs.

Plan#

When you’re ready to build a feature, run /speq:plan. The agent reads the existing specs that relate to your request and asks clarifying questions. You discuss gaps and vague parts of your prompt before any code exists.

The result is a plan with spec deltas. The deltas are markdown files with requirements written as BDD-style scenarios using RFC 2119 keywords. A reviewer agent challenges the plan before you see it. Each plan stays in specs/_plans/ until implementation is complete.

Implement#

Run /speq:implement <plan-name>. The agent splits the plan into tasks and hands them to sub-agents. The sub-agents work test-first and must show evidence that the feature works, instead of claiming success. Hard tasks go to a stronger sub-agent. When the work is done, a code reviewer checks the changed files, and you get a verification report.

Record#

Run /speq:record once the implementation is verified. The agent merges the spec deltas into the permanent library and archives the plan. Your specs accumulate over time into a record of what the software does and why.

Guardrails that guide the agent#

Each phase comes with rules the agent follows without being prompted:

Code quality and TDD. Failing test first, integration tests as proof, no unchecked claims of success.
Design principles. Prefer deep modules, hide information, keep dependencies pointing the right way.
Git discipline. The agent reads git state but does not write history.
Writing rules. Conclusion first, one idea per sentence, no filler.
Semantic anchors. Skills name established methods, such as London School TDD or ADR, to steer the agent toward well-documented practice.

The skills also teach the agent to use Serena for code navigation and Context7 for library docs. Both are optional.

The spec library#

Specs live in your project as plain markdown files, organized by domain and feature:

specs/
  mission.md
  architecture.md
  _plans/          # staging area for in-progress work
  _recorded/       # completed plans, kept for reference
  auth/
    login/
      spec.md
    signup/
      spec.md

_plans/ holds plans while a feature is being planned and implemented. _recorded/ holds completed plans after their deltas are merged, so you can trace how your project evolved.

Each spec uses Given/When/Then scenarios with RFC 2119 keywords (SHALL, SHOULD, MAY):

### Scenario: expired token

- Given a user with an expired authentication token
- When the user requests a protected resource
- Then the system SHALL return a 401 status code
- And the system SHALL include a `WWW-Authenticate` header

See writing specs for AI coding agents for the full guide on this format.

Get started#

speq-skill is a personal side project of mine. It is open source and free to use. Installation instructions and full documentation are on GitHub.

If you’re new to spec-driven development, the three-part blog series provides the foundation: