Introducing Specnaut: a structured workflow for AI coding agents

Why another scaffolding tool?

Most coding-agent workflows fall apart at the boundary between "the human writes a prompt" and "the agent writes code." There's no shared structure — every team improvises a folder, a checklist, a commit-message convention. The result is that switching agents (or teammates) means re-learning local custom every time.

GitHub Spec Kit was the first serious attempt at fixing this: a small CLI that scaffolds a spec → plan → tasks → implement pipeline an agent can follow. The idea is right. The execution requires Python, depends on cloud calls, and stops at every phase to ask the human what to do next.

Specnaut is what we built when we wanted that pipeline to actually run end-to-end without babysitting. It is a single native binary — no Python, no LLM calls of its own, no cloud — that scaffolds files an AI coding harness consumes. You point it at any project, pick a harness (Claude Code, Cursor, Codex, Gemini, Copilot, Windsurf, OpenCode, Antigravity), and it drops in the slash-commands, agent definitions, templates, and backlog wiring needed to drive a structured workflow.

The CLI emits files. The harness drives them. Specnaut itself never talks to a model.

What you get out of specnaut init

A scaffolded project ships with:

• The auto-chain pipeline — /specnaut specify "<feature>" runs clarify → plan → tasks → analyze → implement → review → merge in a single session. It only stops twice: once if a clarification is genuinely required, and once before the final merge.
• A real review phase — after implementation, a review-coordinator dispatches code/security/test reviewers in parallel, aggregates findings, and loops back into the implementer until the gates pass. No "looks good to me" rubber-stamp.
• A backlog with a Product Owner agent — every mutation (create, clarify, move status, close) goes through a product-owner subagent that enforces issue conventions. Three backends supported: a local Markdown file, GitHub Issues + Project V2, or GitLab Issues.
• Eight harness adapters — same source-of-truth content under templates/core/, mapped per harness to its expected layout (.claude/, .cursor/, .gemini/, etc.).
• A constitution — specnaut constitution lets you encode the project's non-negotiables (testing requirements, security posture, IaC mandate). Every plan checks itself against the constitution before tasks are generated.

Mid-chain re-entry

One ergonomic problem comes up more than any other: what happens if your agent's context fills up halfway through a run?

Early on, you'd manually re-run each remaining phase. The chain knew nothing about resuming.

Now: invoke any phase from a fresh session — /specnaut plan 042, /specnaut implement 042 — and the skill inspects the artefacts on disk. If downstream files (tasks.md, data-model.md, etc.) are missing, it infers "the user wants to resume" and chains forward. If they're present, it infers "the user wants to re-run just this phase" and exits cleanly. Two opt-out flags, --continue and --once, let you force either behaviour explicitly.

Auto-chaining is the default, so there is no separate command to remember. If you have an older project wired to /specnaut-auto, that alias still resolves but is deprecated and goes away in the next major version.

Where to start

The fastest path is Homebrew:

brew tap specnaut/tap && brew install specnaut
specnaut init --here --ai claude --backlog github

Or a single curl, if you'd rather not tap:

curl -fsSL https://raw.githubusercontent.com/specnaut/specnaut-cli/main/install.sh | bash

That gives you the full Claude Code wiring with a GitHub-backed backlog. Switch the harness flag for any of the other seven, or --backlog local to keep everything in a single Markdown file.

The full docs live at https://specnaut.com. The source — and the issue tracker, where the mid-chain re-entry behaviour was filed by a real user three days before it shipped — is at https://github.com/specnaut/specnaut-cli.

If you've been hand-rolling spec/plan/tasks templates per project, give it a spin. The whole point is that the structure stops being your problem.