speccen
/ˈspɛkŋ/noun - West-Vlaams, means candy
Makes spec-driven software development a little sweeter.

specification-driven lean by design autonomous by choice

speccen takes a request through six phases, from deep analysis to an agreed specification to implementation and close-out. A Software Architect decides. The AI assists, in Claude Code or Copilot CLI.

Install speccen Read the README

The speccen workflow

  1. 01Feature analysisAn interview that pins down the request.
  2. 02Code analysisEvidence from the code, not guesses.
  3. 03Compliance and reviewOpen decisions become ADRs.
  4. 04SpecificationThe plan, frozen when the phase closes.
  5. 05ImplementationCode against the spec. Accept or revert.
  6. 06Close-outDocuments for each audience. Knowledge to the store.

Every phase ends with a stop. The next phase starts when you say go.

Optional after close-out, started by the Architect:
  • 07Retrospective
  • 08Reference

Agree the understanding before any code exists

Fixing a wrong assumption in a document costs almost nothing. Fixing it in shipped code does not. So speccen builds the understanding first, and you review it while changing it is still cheap.

The Architect is the only decision authority. The AI never changes code before the implementation phase, and it never calls itself the author of an artifact. In gated mode it never starts a phase on its own.

Decide yourself, or delegate on the record

Gated, the default

Every phase ends with a stop. Nothing advances without your go.

Autonomous

An agent acts as your delegate. It decides only from what you recorded: your ADRs, your prompts, the project conventions and frozen artifacts.

The delegate tests itself at every phase end, with cited evidence, and stops when your recorded intent does not decide a material choice. Every choice it makes goes into delegated-decisions.md for you to adopt or override.

Some things stay yours: deciding ADRs, promoting knowledge to the durable store, waiving a test, skipping a phase and changing the mode. Set the mode per project, per bundle or per phase in a small YAML file.

Decisions that outlive the feature

Each run produces a bundle: a folder of markdown files that is scaffolding and perishes after merge. The decisions and lessons it produced graduate into a store in your repository.

.speccen/
  decisions/    ADRs, the deliberate forks
  lessons/      what bit us
  notes/        small decisions and hiccup fixes
  features/     one node per feature
  extensions/   your project rules, per phase
  bundles/      one folder per run, gone after merge
  index.md      regenerable root index

The store keeps the sign on every fence. Code that contradicts an expectation, with its reason unrecorded, gets cleaned up, and the bug it fixed comes back.

See what comes out

Phase 08 produces a layered reference page: it starts at the system context and zooms in, one level at a time, so a reader can stop at any depth and still hold a true picture. Changed parts stand out in every diagram, and the rejected alternatives sit next to each decision.

This example documents an invented refactor of a pump safety rule engine. The subject is made up. The structure and depth are the point.

Open the example reference

Install

Claude Code

/plugin marketplace add speccen/speccen-ai-toolkit
/plugin install speccen@speccen-ai-toolkit

GitHub Copilot CLI

copilot plugin marketplace add speccen/speccen-ai-toolkit
copilot plugin install speccen@speccen-ai-toolkit

Start a run

/speccen:speccen-start

The workflow asks for an id prefix, the feature name, the work kind and the mode. VS Code users and local installs are covered in the README.