Speckit: making greenfield and feature work actually interesting

At work someone posted a tool called Spec-Kit for a hackathon project. I immediately saw value in it and started using it across about a dozen personal projects now - everything from a custom Go API to a solo RPG engine to an EPUB/PDF analysis pipeline. The core idea is simple: every project gets a constitution, and every feature gets a spec before any code is written. What surprised me is how much more interesting that makes the actual building.

The problem it solves

Most of my personal projects start the same way. I have an idea, I open a terminal and scaffold whatever it is, then I open VSCode and start writing things and testing. Three hours later maybe I’ve built something that sort of works but doesn’t quite match what I had in mind. Refactor and re-do the table model, increment the version, rinse and repeat.

I think the gap between “vague idea” and “concrete code” is where all the interesting decisions live and I like using spec-kit to nail this down.

Under the hood

Speckit is two things:

1. A constitution generator - a Python CLI that scans your repo (package.json, go.mod, pyproject.toml, whatever) and walks you through creating a project constitution. The constitution defines your non-negotiable principles, architecture constraints, and development workflow.

2. A specification framework - a .specify/ directory with templates and Claude commands that guide you from feature idea to implementation plan to task list.

The constitution is the interesting part. It’s not documentation for documentation’s sake. It’s a set of gates that every feature has to pass through. When I defined “Hexagonal Architecture” as a principle in josh.bot’s constitution, every subsequent feature spec had to show how it maintained port/adapter separation. That’s not bureaucracy - that’s the kind of constraint that makes design decisions faster because half the options are already eliminated.

Greenfield: starting a project right

When I start something new, the first thing I do is run the constitution generator. It auto-detects the stack, reads the README, and asks a series of questions about principles, testing strategy, and architecture. The output is a YAML document that becomes the project’s source of truth.

For Elegy Campaign Player, the constitution established things like:

• All game mechanics must be deterministic given a seed
• AI narration is optional, never gating
• 19 engine modules with clear domain boundaries
• Development must be test-driven (a whole other can of worms for a large codebase)

Those three constraints shaped every decision that followed. When I was building the combat system and had to choose between a stateful class hierarchy and a pure function pipeline, the constitution already answered it. Deterministic means pure functions. Done.

The constitution also includes an amendment process. When you learn something mid-project that changes your assumptions, you amend the constitution rather than just quietly drifting. The history of amendments is often more useful than the current document.

Feature work: the spec pipeline

For existing projects, speckit shines when adding features. The workflow looks like this:

/speckit.specify "add lift tracking API endpoints"
  -> writes specs/001-lifts-api/spec.md (user stories, acceptance criteria)

/speckit.plan
  -> writes specs/001-lifts-api/plan.md (technical approach, constitution check)

/speckit.tasks
  -> writes specs/001-lifts-api/tasks.md (granular implementation steps)

Each step produces a document that the next step consumes. The plan includes a constitution check - a table showing how each project principle is satisfied or violated by the proposed approach. If something doesn’t pass, you know before writing any code.

Here’s a real example from josh.bot. When I added the lifts API, the constitution check looked like:

Principle	Status	Notes
Hexagonal Architecture	PASS	New LiftService interface in domain/
Single-Table DynamoDB	PASS	Separate table for lift data
Test-Driven Development	PASS	Mock DynamoDB adapter for unit tests

That took thirty seconds to review and saved me from at least one wrong turn (I was initially going to query the main table with a GSI, but the constitution reminded me that lift data has different access patterns and deserves its own table).

Why it makes things interesting

The counterintuitive thing is that adding structure to personal projects makes them more fun, not less. Here’s why:

The interesting decisions get surfaced. When you write a spec, you’re forced to articulate what you actually want. Half the time, the spec reveals that what you thought was one feature is actually three, or that the real value is in a different place than you assumed. That’s the interesting part of engineering, and speckit makes sure you don’t skip it.

Constitutional constraints accelerate decisions. Instead of spending twenty minutes debating with yourself about whether to use a class or a function, the constitution tells you. The mental energy goes to the genuinely novel parts of the problem.

The spec becomes a conversation partner. When using Claude with speckit’s commands, the AI has enough context (constitution + spec + plan) to give useful feedback rather than generic advice. “Your plan violates principle III” is more useful than “have you considered error handling?”

Traceability is satisfying. Being able to trace from a user story in the spec to a task in the plan to a test in the code to a commit in the history - that’s a level of coherence that most personal projects never achieve. It feels like building something solid rather than hacking something together.

Where I’ve used it

At this point speckit is running in josh.bot (Go API), Elegy Campaign Player (TypeScript game engine), cartograph (Python code analysis), bookalysis (EPUB pipeline), autonotes (Obsidian vault analysis), and several others. Across all of them, there are probably 50+ completed feature specs.

The projects that benefit most are the ones with the most constraints. Elegy has 22 feature specs because a 124-page game manual creates a lot of bounded design problems. Each one is a small puzzle: how do I implement this rule while maintaining determinism, test coverage, and module isolation? The spec pipeline turns that from overwhelming into tractable.

The tooling

The constitution generator is a Python CLI built with Rich for the interactive prompts and PyYAML for output. It has a zero-prompt autogen mode that scans your repo and generates a reasonable constitution without asking any questions - useful for bootstrapping existing projects.

The specification framework is a set of markdown templates and Claude slash commands that live in each project’s .specify/ and .claude/commands/ directories. Nothing proprietary, nothing locked in. It’s just structured markdown and a convention for how to use it.

If, like me, you’re the kind of person who starts projects constantly and finishes them sometimes, speckit might be worth trying. Not because it makes you more disciplined, but because it makes the planning phase as interesting as the coding phase. And once planning is interesting, you do more of it, and the code that follows is better for it.