Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
<div align="center">
<img src="assets/speq-skill-logo.svg" alt="speq-skill Logo" width="200">
speq-skill
A light-weight and straightforward workflow for spec-driven development with Claude Code or Codex
Getting Started • Why • How It Works • Documentation • Installation </div>
Getting Started
curl -fsSL https://raw.githubusercontent.com/marconae/speq-skill/main/install.sh | bashThen open Claude Code or Codex and start with the matching trigger: /speq:mission in Claude Code, or $speq:mission in Codex.
<details> <summary>What does the installer do?</summary>
- Downloads a pre-built
speqbinary for your platform (Linux x86_64/ARM64, macOS Apple Silicon). On other platforms it stops and points to the source build - Installs the CLI to
~/.local/bin/speq - Installs plugin files to
~/.speq-skill/ - Registers
/speq:*skills for Claude Code and$-triggered skill suggestions for Codex when available - Registers the local Codex marketplace when the Codex CLI is available
To uninstall, see Installation — Uninstall.
</details>
Why I Built It
I want to leverage AI coding agents such as Claude Code and Codex as effective tools for software engineering.
There are many other spec-driven development tools out there...
...but I wanted the following:
- A workflow that is not primped on one language or framework (e.g., Python or TypeScript)
- A straightforward repeatable workflow (
plan → implement → record) - A permanent and growing spec-library
- A workflow that keeps the specs small to avoid context cluttering
- A workflow that keeps asking me instead of making assumptions
- Semantic anchors that ground AI behavior in established methodologies
So I built speq-skill.
It combines skills with a simple CLI called speq that lists and reads the permanent spec library. The coding agent lists the features, then reads only the relevant ones during planning and during the implementation. This avoids reading unnecessary specs into the context window.
New to spec-driven development? Read "Spec-driven development: an introduction" and "Writing specs for AI coding agents" on my blog.
Each skill is grounded in semantic anchors — named references to established methodologies (like London School TDD, BLUF, ADR) that steer AI behavior toward well-documented practices.
Who should use it?
Vibe Coding does not scale. speq-skill adds the missing workflow and guardrails.
It introduces a lightweight workflow for spec-driven development. It adds a CLI to enable the coding agent to list and read the permanent spec library.
How Does it Work?
/speq:mission → specs/mission.md + specs/architecture.md (once per project)
│
┌────────────────┼────────────────┐
▼ ▼ ▼
/speq:plan → /speq:implement → /speq:record (repeat)- Mission — Do it once. The coding agent explores your codebase (or interviews you for a greenfield project) and generates
specs/mission.mdandspecs/architecture.md. - Plan — Describe what you want. The coding agent reads the existing specs, asks clarifying questions, and creates a plan with spec deltas.
- Implement — The coding agent implements the plan, guided by guardrails for code quality, testing and more.
- Record — The coding agent merges implemented spec deltas, and the architecture delta if the plan has one, into the permanent spec library.
Specs live in specs/<domain>/<feature>/spec.md. specs/architecture.md holds the current architecture. Plans stage in specs/_plans/<plan-name>/. The separation keeps your spec library clean while work is in progress.
Building Blocks for Agentic Workflows
/speq:plan-pr and /speq:implement-pr are two building blocks for agentic workflows centered on pull requests. Each one orchestrates the planning, implementing, and recording skills: /speq:plan-pr runs planning and opens a draft PR on a feat/<plan-name> branch, and /speq:implement-pr runs implementing and recording on that branch. You stay in the loop by commenting on the pull request. See PR Pipeline.
Documentation
| Guide | Description |
|---|---|
| Installation | Setup CLI and plugin |
| Workflow | One-time mission setup, then Plan → Implement → Record cycle |
| FAQ | Add features, fix bugs, start greenfield or brownfield |
| PR Workflow | Plan and implement via a feat/ branch + Pull Request |
| Decision Log | Design decisions, ADR fragment format, validation, and show |
| CLI Reference | All CLI commands |
| MCP Servers | Optional Serena and Context7 setup |
| Semantic Anchors | Named methodologies grounding each skill |
| Model Routing | How workflow skills and sub-agents are routed across models |
| Hooks | Repo-local .speq/<name>-hook.md customizations |
Important
speq-skill is a plugin for Claude Code, Codex, and other compatible AI coding agents. This project provides workflow structure and spec management only—the coding agent generates all code, specs, other artifacts, and tool calls.
Companions
speq-skill works well with Serena for code navigation and Context7 for library documentation. Both are optional. The skills use each one when it is installed and skip it when it is not. See MCP Servers.
[!NOTE] Serena and Context7 are separate open-source projects with their own licenses and terms available in the linked repositories. Context7 sends your documentation queries to a hosted service and offers a free-tier.
Acknowledgments
- The
code-revieweragent's YAGNI / Over-Engineering review category was inspired by the tag taxonomy of ponytail. - The semantic anchor approach — naming established methodologies (e.g. London School TDD) directly in skill instructions — draws on the LLM-Coding/Semantic-Anchors catalog.
License
This project is licensed under the MIT License.
<div align="center">
Build with Rust 🦀 and made with ❤️ by marconae.
</div>