spec-first CLI
A CLI that guides AI coding from idea to review through requirements, plan, code and checks and keeps traces in the repo.
- 110 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- `spec-first init` writes managed agent files into the repository and `spec-work` changes source code according to the plan.
- The commit and PR entry points act only with your authorisation.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/spec-firstDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- `spec-first init` writes managed agent files into the repository and `spec-work` changes source code according to the plan.
- The commit and PR entry points act only with your authorisation.
This is third-party code. Review the repository files before installing.
What it does
spec-first turns AI coding sessions into verifiable changes inside the repository. The `spec-first init` command generates `spec-*` entry points for the chosen agent, and the workflows themselves run in the agent session: `spec-brainstorm` gathers requirements, `spec-plan` prepares an implementation plan, `spec-work` carries it out and `spec-code-review` checks the changes. Plans, tasks, checks and knowledge stay in the project `docs/`. `docs/plans/` holds requirements and plans, `docs/solutions/` holds verified solutions and `docs/validation/` holds check evidence. The agent does not declare a task done on its word: commands, exit codes and logs confirm completion.
Who it is for. Teams that write code with Claude Code, Codex or Cursor and want to keep intent, plans and check evidence across sessions and agents.
Good fit when
- An idea is rough and must become requirements through `spec-brainstorm`.
- Plans and decisions get lost between sessions or when moving from Codex to Claude Code.
- Code is reviewed by diff or PR and findings with check gaps are needed.
- Tests fail, the cause is unclear and `spec-debug` runs with fix evidence.
- Verified solutions are accumulated in `docs/solutions/` for later reuse.
Not a fit when
- A one-off prompt without repository artifacts is enough.
- Policy forbids keeping workflow files in the repository.
- A standalone IDE or a central process engine is required.
- Product priorities and architecture are meant to be decided by the tool.
Example request
Run `spec-brainstorm "Add configuration import to the CLI"` and show the requirements before writing a plan.Limitations
Node.js 20 or newer, npm, Git and at least one supported agent are required. Claude Code and Codex have primary support while the other agents run in preview mode. The `spec-*` entry points are commands inside an agent session and cannot be run from a shell; `spec-first` only prepares files for them. After `init` the agent must be restarted or it will not see the new entry points. The main documentation is in Chinese; an English version lives in `README.en.md`.
How to disable. Run `spec-first clean` to remove the generated files of the chosen agent, then `npm uninstall -g spec-first`. The `docs/` directory with plans and knowledge remains yours.
FAQ
How do I get started with spec-first?
Run `npm install -g spec-first`, then `spec-first quickstart` in the Git repository root. The wizard checks Node.js, Git and installed agents. After picking an agent, restart it so it sees the entry points.
Which agents are supported?
Claude Code and Codex have primary support. Kiro, Qoder, ZCode and Pi are preview, while Cursor and OpenCode are marked `generated_runtime_preview`.
How does `spec-brainstorm` differ from `spec-plan`?
`spec-brainstorm` turns a rough idea into a requirements document. `spec-plan` prepares an implementation plan once requirements are clear, and then `spec-brainstorm` can be skipped.
What if the agent does not see the `spec-*` entry points?
Run `spec-first doctor --verbose`: it shows environment and generation facts. Then compare with the agent capability catalog in `docs/catalog/runtime-capabilities.md`.
Does `init` make commits?
No. `spec-first init` previews managed files before writing, does not stage files in git and commits nothing.
Discussion
No questions or reviews yet.
Related
CLI toolsGitHub toolkit for spec-driven development: the specify CLI adds agent commands and skills to a project, from principles to implementation
A CLI for spec-driven development: the agent carries a task through files in the repository from plan to verification and archive
Orchestrator skill: from an idea the agent writes requirements and a spec, splits work into tasks, builds the project, checks it
Spec-driven development for coding agents: proposal, requirements, design and tasks come before any code
A skill that interviews you and writes requirements.md, design.md and tasks.md so Claude Code and Cursor work from one plan
Two skills for spec-driven development: /spec asks questions and saves a document to specs/, /spec-impl implements an approved spec step by step
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| spec-first (this card) | no | 110 | |
| spec-superflow | no | 879 | a plugin that drives one task from agreed scope to verification; spec-first keeps the chain from idea to knowledge in `docs/` and works across eight agents |
| LeanSpec | no | 300 | short markdown specs and a task board; spec-first adds plans, review and check evidence |
README in short
The chain runs: idea, requirements, plan, tasks, code, review, knowledge. The trust principle is one sentence: scripts prepare facts, the model judges meaning and the project owner authorises side effects.