DEV Community: Alfredo Perez

Living Specs in SpecKit

Alfredo Perez — Sat, 17 Oct 2026 01:57:15 +0000

Nine months ago I started building a VS Code extension in the open, and I ran every change in it through spec-driven development. A few weeks ago I wrote about what that left behind: a specs folder I never opened again, and an agent that never opened it either.

That piece ended with a promise. I'd cut one feature from it to keep it readable, and I now think that feature, specs you can reuse, holds the whole method together.

In SpecKit Companion it's called a living spec. Instead of one spec per change that freezes the day it ships, you keep one spec per feature, like billing or auth, that says what the feature must do today. Every run that touches the feature loads it before drafting anything, and rewrites it when the work is done. The rest of this piece hangs off that loop:

The usual setup has no arrow back, so a spec is written once and every later run starts over from the code.

What a spec is, and where it usually dies

In most agents you can already ask for a plan before any code gets written. Spec-driven development slices that plan into phases: specify what the feature must do, plan how, break it into tasks, then implement. Each phase leaves a markdown file in the repo, and you read each one before the next runs. You get to see whether the implementation is going your way, step by step, with a little more control than letting it run.

That part works. It's why I ended up with ninety-four of those folders.

What nobody talks about is what happens to the files after the feature ships. In the usual setup, nothing. Spec-kit gives each feature its own numbered folder, and that folder is finished the day the feature is:

The code keeps changing after that, and nothing carries the change back, so each folder is only true for the week it was written. That's where three problems start, none of them dramatic, all of them normal.

Every spec starts from zero

Every time a spec touches something, say a dialog, the specify and plan phases go and investigate how that dialog works, and they write down what they learn: the data model, the pieces around it, the conventions. That's just normal. It's the phases doing their job.

The problem is that the next spec that touches the same dialog does the whole investigation again. Nothing from the last time is there to point at. The understanding was real, and it got written down, and then it got filed in a folder the next run doesn't read. So the agent re-derives it, every feature, from the code.

A living spec is a pointer to that previous understanding. When the next run starts, the agent has more guidance, faster, because the record of how the feature works is already there and already current.

You can't find how a feature works

The second problem is the one I felt as a person rather than as an agent. Once a spec exists, it's hard to find out what the feature is supposed to do today.

Take one thread in my repo: how a task gets marked complete. I iterated on that many times. Each iteration got its own spec, its own requirements, its own record of what I believed at the time. Ask the folder how task completion works today, and this is the shape of the answer:

Five specs touch it, four are superseded, and none of them says which. A living spec gives that question one place to land.

It isn't that I filed them badly. A spec is a snapshot of one moment's intent, and snapshots don't update. Stack ninety-four of them and you don't have documentation, you have an archive. There is a name for this in the writing about spec-driven development: most teams pay for a spec that stays and get the benefit of a spec written once and forgotten. That was me.

The agent reads what's nearby

The third problem is about where the agent looks. Ask Claude, or any provider, to work on a feature without a spec run, and it reads the code near the thing you named. That's fine. The code sitting right there is real information.

Two things make it less fine. The neighbor code isn't always what you would consider the standard, so the agent copies a convention nobody endorses. And the specs folder, the one place where the intended behavior is written down, is unfeasible to go through, because it accumulates fast and nothing in it says what is current. So the agent goes around it. It's right to.

This is the observation that shaped the whole design: a markdown file sitting next to the code it describes gets read, spec run or not, by any provider, in any prompt. The location is the feature. There is research on how models lose what they were told before the conversation ends, and a file that survives the session is what brings it back.

Specs that get a second life

Reading about how other workflows handle this, especially OpenSpec, is what inspired the feature. OpenSpec keeps one durable spec per capability and folds each change back into it when the change ships. The specs get a second life. I liked that a lot, because it meant a spec wasn't going to become a dead file in a dead folder. It was going to be documentation I could read later, modify, adjust.

I also looked at what that looks like in practice, across 788 public repositories using it. Two things stood out. The fold-back step is manual, and skipping it is how the record dies: code keeps moving, the specs sit still, and nobody notices for months. And nobody maintains prose nobody reads. Even mature repos leave the purpose line as a placeholder. Those two things decided what SpecKit Companion would do differently.

What a living spec looks like

In Companion, a living spec covers one capability, like checkout, auth or billing. The examples from here on come from Teamboard, the small demo app I use for the extension's screenshots: a team directory where members have profiles, photos and a search box.

Turning it on is one file at the root of the project, and the feature is off until that file exists. Each capability gets a name and the files that belong to it:

# 📃 living-specs.yml
enabled: true
capabilities:
  - name: member-profiles
    match: ['src/features/profile/**', 'src/api/members/**']
  - name: directory-search
    match: ['src/features/directory-search/**']
    spec: src/features/directory-search/directory-search.spec.md # 👈 lives next to the code

The match globs are how Companion knows which capability a change touches, so it's the part that matters most. The spec line decides where the file goes. Without it, the spec lives centrally at capabilities/member-profiles/member-profiles.spec.md, the way OpenSpec does it. With it, the spec sits in the folder of the code it describes. Side by side, the two options look like this:

The difference is who finds the spec without being told where it is. You can pick per capability, and /speckit.companion.living-move moves a spec between the two later, so nothing here is a commitment.

Inside, a living spec holds what the capability must do today, as requirements and scenarios, and nothing about how it was built. Here's the start of the one for member profiles:

<!-- 📃 capabilities/member-profiles/member-profiles.spec.md -->
# Member Profiles

## Purpose

Every Teamboard member has one profile: a name, a role, a team and a short bio.
This capability owns who may read a profile, who may change it, and what the
rest of the product is allowed to assume about its fields.

## Requirements

### A member edits only their own profile

A profile update MUST be accepted only from the member it belongs to or from a
workspace admin.

#### Scenario: a member opens another member's profile

- **WHEN** the viewer is neither the owner nor an admin
- **THEN** the profile renders read-only and the update endpoint refuses the change

There's no component name, no endpoint path, no data model in it. That's on purpose: the code can be refactored under it without the spec going stale, and the part that would go stale, how it's built, is the part the agent can always read from the code.

Next to the code, and in a tree

My hypothesis, or the reason I feel it's better this way, is navigation. I made a version of this argument once before, for an earlier tool, and living in a real repo for a few months has only made it stronger. If every spec lives in a capabilities/ folder, that's already a step forward, because the specs got extracted from the pile. But it also means that when I'm looking at the code, I have to go somewhere else to find out what it's supposed to do. If the spec sits beside the code, I'm already there. And so is the agent.

The thing that keeps this from turning your source tree into a mess is the sidebar. The Living Specs view shows every capability as a tree, grouped by where it lives:

Both kinds sit in the same tree, so putting a spec next to the code doesn't make it harder to find. Other tools don't do this part, and it's the part that made colocated specs practical for me: easy to find, easy to navigate, and opened in a viewer that renders the spec as a page rather than raw markdown.

Adopting one area at a time

Owning the location also lets you adopt one domain at a time. Maybe you use spec-driven development and you own a domain, and you don't want to force it on the whole team. You adopt that domain. From then on, everything that touches it uses living specs, and everyone else's workflow is untouched.

Adopting is one command pointed at one folder:

/speckit.companion.living-adopt src/features/directory-search

It reads that area's surface (the routes, the screens, what each one needs before it renders), proposes the capabilities for just that area, and stops to show you the names, the globs and where each spec will live. Once you confirm, it drafts the spec and adds the capability to living-specs.yml. The draft doesn't pretend to be more than it is:

<!-- 📃 src/features/directory-search/directory-search.spec.md -->
# Directory Search

> [DRAFT] Adopted from the code's surface and the project's conventions. Review before trusting.

## Purpose

The directory is how a Teamboard member finds a colleague. This capability owns
what a search matches, how results are ordered, and which members a searcher is
allowed to see.

## Requirements

### A search matches name, role and team
...

## Uncovered

Each requirement is marked as observed in the code or inferred, anything it couldn't settle carries a [NEEDS CLARIFICATION: …] that it walks you through one at a time, and rules nobody owns land under ## Uncovered. The banner goes away when the last marker does. On adoption day your job is reading and correcting a draft, and the markers show you which parts nobody has confirmed yet.

Written as a side effect of shipping

Here's the part that answers the objection I take most seriously, that spec-kit claims to keep specs alive and delivers specs that freeze. You don't keep a living spec current by hand. The pipeline does.

When a spec run starts, the specify phase has a step that finds the living specs for the area you're touching and loads them before it drafts anything. Not only the leaf you named: the parents in the hierarchy too, so the new feature spec starts from what is true across the whole area. Plan works from that. Tasks work from that.

The rewrite happens at the end. While it finishes the feature, the agent adds a short section to the feature's own spec for each capability the feature changed, saying what changed. For the profile photo feature in the demo, that section looks like this:

<!-- 📃 the feature spec for 041-profile-photo-upload -->
## ADDED Requirements
<!-- capability: member-profiles --> <!-- 👈 which living spec it goes to -->

### A member sets their own profile photo

#### Scenario: a member uploads a new photo
- WHEN a member picks a JPEG under 5 MB on their own profile
- THEN the photo replaces the previous one

When you mark the feature complete, that section folds into member-profiles.spec.md: an added requirement is appended, a modified one replaces the old text, a removed one is deleted. There are four kinds (ADDED, MODIFIED, REMOVED, RENAMED), and a feature that changed two capabilities sends each one only its own section. Because the section is written into the feature's spec, it shows up in the same PR diff as the code, so the change to the living spec gets reviewed instead of applied blindly. If a run loaded a living spec and wrote nothing for it, completion names it and says there was nothing to fold, so a skipped fold-back is visible rather than silent.

The first real feature I ran this way was a webview rendering change. The ticket said nothing about HTML safety. The living spec for that area did, and the rule traveled through every phase until it became something I could tick:

The rule reached the work because the spec was loaded, not because anyone remembered it.

What also made me trust this is that it shows its work. The Overview of a finished run lists the living specs it found, with a badge that says whether they folded back:

The badge tells me the run found all the relationships, not just the one I pointed at, and that the record is current as of this feature. Kent Beck's objection to spec-driven development was never that you write things down. It was that you write them down and they freeze while the code moves. Fold-back at completion is the thaw.

When you worked outside the pipeline

Sometimes, and this is really normal, I don't use spec-kit at all: big spikes, exploratory features, a quick fix on a Friday. Now imagine a team of dozens, where not everyone runs the same workflow with AI, and that's fine too. The code moves and the living spec sits still, which is exactly the way the records died in those 788 repos. So Companion watches for it, and this is the path back:

Nothing blocks the quick fix. Drift is information, not a gate: a flag never stops a run, it just means you know, and you sync when you're ready.

Each capability whose code changed since its spec was last committed carries a drift badge in the sidebar. From the terminal, it's two commands:

# 👇 what moved, uncommitted work included
/speckit.companion.living-drift --working

# 👇 update every affected spec
/speckit.companion.living-sync

Drift lists, per capability, the files that changed since its spec was last committed, and says how each one slipped. A tracked file went through the pipeline but its change never folded back, a missed sync. An unspeced file changed entirely outside the pipeline, so the living spec never saw it at all, which is the one to look at first.

Sync then groups your changes by capability, reads what actually changed, and updates each affected spec. It edits rather than regenerates: every requirement and scenario the change didn't touch stays word for word, so a sync never flattens what someone wrote by hand. And it leaves the edits uncommitted, so the code and the spec get reviewed together. The spec page has the same thing as an Update button:

The covered paths are what drift is measured against, so a spec only flags when its own code moved, not every time someone touches the repo.

What it asks of you

It asks for adopting the system: adding domains, organizing as a team, deciding where you want your living specs to live. And it asks for being conscious that you'll need to sync and get rid of drift, because it happens.

There is also something it doesn't do yet, and I'm still thinking about it. While specify and plan run, they gather a lot: data models, architecture, decisions. Right now the living spec keeps how the feature works and nothing else. I don't know yet whether those other artifacts should be persisted too, whether they add to the understanding of the feature or just add to the context, and whether they would stay maintainable. That's an open question, not a roadmap.

And to be fair to the other side: there is a good argument that an executable test is the more durable contract, because it survives a model upgrade unchanged where prose gets reinterpreted. I think that's right, and I think a living spec holds something a test cannot, which is why the feature exists at all.

Try it

Ninety-four specs nobody opened taught me less than the handful that get loaded every session.

If you want to try it, the steps below follow the order of this piece, and the guide has the rest.

Install the spec-kit extension: specify extension add companion --from https://github.com/alfredoperez/speckit-companion/releases/download/companion-latest/companion.zip
Create living-specs.yml at the root with enabled: true. Living specs are off until this file exists.
Run /speckit.companion.living-adopt src/<area> on the one area you explain most often, and read the draft.
Ship a feature through the pipeline and check the Overview for the folded-back badge.
When the sidebar shows drift, run /speckit.companion.living-sync and commit the spec edits with the code.

To see it move before you install anything, the SpecKit Companion website has a short video that walks through living specs.

This is the first of the three threads I cut from the 238-specs piece. Give Spec Kit Superpowers introduced the other two, fast mode and auto mode, in a line each. Next up is auto mode properly: planning several features at once and reviewing the whole batch from the sidebar.

Take Your AI's Questions Out of the Terminal

Alfredo Perez — Wed, 14 Oct 2026 20:33:35 +0000

This is a decision page. Claude Code wrote it after reading a project's notes, and it shows the detail a chat question leaves out. I answer it in Obsidian.

When an AI asks me to choose, what I get is the question and the options, one line each. The detail that would help me choose is still inside its context, and I can't see it. On this page it's all there: what Claude found while reading the project, a picture of the problem, a table of what could break, and only then the options, with one marked as recommended. I tick a box, type a line if I have one, and tell Claude I'm done.

The page is plain markdown. Two things make it look like this: a skill that knows which parts a decision page can use, and the vault stylesheet from Make Your Vault Look and Read the Way You Want, which draws them so I can read the page instead of parsing it. If you haven't set up that stylesheet, start there, because this article builds on it.

How it started

For most choices, the grid Claude Code shows in the chat is all I need. The bigger ones were the problem. One line per option can't hold a picture of the problem or what might break, and once I answer, the question scrolls away, so a month later I can't find what I picked or why.

Matt Pocock's grill-me got me most of the way, and I want to give it proper credit. It's a skill that interviews you about a plan until you and the agent understand it the same way: a round of numbered questions, each with a recommended answer under it. Here's the first round it gave me on the question I use as the example below.

I used it for weeks and kept running out of space, because a terminal gives every question the same few lines, whatever the question needs. So I moved the questions into a document, where a question can carry a picture, a table, or a folded block of code. I ask for a page when the questions need background I haven't read, when there are more than three and they affect each other, or when I've already said "let me think about it". Most choices don't pass that test, and for those the chat grid is still the right shape.

Ask for the page

For the examples I'll use Worky, a made-up company that schedules painter crews. It has three screens: a Client Portal where homeowners book and track a job, a Crew App where painters see today's jobs on a phone, and a Dispatch Console where the office moves crews between jobs. The open question was whether the calendar gets built once and shared, or whether each screen builds its own view of the same schedule.

Here's the kind of thing I said to Claude:

I need to decide whether Worky's three apps share one calendar
or each build their own. Read the Worky notes first, then write
me a decision page I can answer tomorrow. Recommend an answer for
each question, but don't tick anything for me.

Claude read the project notes and wrote one page into the project's decisions folder. Follow-up rounds go into the same page, so there's one place to look.

Put what Claude found beside the question

This is the part a chat round has no room for. Each question on the page carries what Claude found while reading the project, open, right under the heading:

A row of small tags. One says how sure the finding is, for example "seen in all three apps", and one says how big the change would be.
A one-line summary of the question.
A picture, when a picture says it faster.
A short "What I found" list, two or three plain sentences.

The heading carries a tag too, for how heavy the question is: "quick call", "trade-off" or "the debate". The quick calls come first, so I get a few answers down before the hard one.

This is the second question on the Worky page, about where the shared words live so that "moved" means the same thing on every screen.

A sentence can say the three screens use three different words. The picture shows it, and a chat round has nowhere to put one.

See what could break before you choose

Under the finding sits a short "what could break" table: the change, what breaks, and how we'd find out. Rows where nothing fails and you only find out late are tinted, so I can spot the dangerous ones without reading every cell.

The tinted row is the reason the recommendation is a typed package: with the other two options, a wrong word on one screen fails silently.

Answer right next to the question

Under the table come the options as checkboxes, with a green Recommended tag on one of them, an empty slot to type in, and a folded block called "Dev details".

The recommendation is marked but never ticked, because a ticked box should always mean I decided. If Claude ticked it for me, I couldn't tell my agreement from my not reading.

"Dev details" holds the code and the file names: what the package would export, and where each screen keeps its words today. I don't need it to choose, so it stays closed, and whoever wants to check Claude's reading opens it. The rule I ended up with is that what I need to decide is open, and what I'd only need to check is folded.

There's no plugin and no form to export. The page is the form, so my answers stay as text beside the question they answer.

When I say I'm done, Claude reads the page in a set order:

The "Talk to me" box at the top first, because that's where I'd say it's asking the wrong question.
The assumptions it listed, to see if I struck one out.
Which options I ticked.
Anything I typed beside a question.
Questions I left blank, which usually means the question was wrong.

Then it tells me what it understood, in one short block, before doing anything. A ticked box with "but only for the Crew App" typed beside it isn't the same answer as a ticked box, and that block is where a misreading gets caught.

The skill that writes it and the styles that draw it

I don't build these pages by hand, and Claude doesn't make them up each time either. Two pieces do the work, and they were built together.

The first is a skill called create-decision. It knows the parts a decision page can use and when to use each one: the tags, the one-line summary, the "What I found" list, the picture, the "what could break" table, the options, the typing slot and the folded "Dev details". Not every question gets every part. A quick call has no table and no picture, and the debate has all of them. The skill writes each part as plain markdown: a short span with a class name for a tag, a normal table for what could break, a checkbox list for the options, a callout that starts folded for the code. It also holds the rules from this article: the finding above the options, the code folded below them, never ticking for you, and the read-back order.

The second is the vault's stylesheet, vault.css, the one from the first article. A few lines in it draw each part: the span becomes a pill, a flag in one table cell tints the whole row, each checkbox becomes a card, and ==Recommended== becomes the green tag. The decision page is the same stylesheet put to work on one kind of note.

Here are the parts in one picture.

The two pieces know about each other through the obsidian skill from that first article. It lists the components the vault can draw, with the markdown for each one. create-decision picks from that list, so when I added the tinted row, I added it in both places: one rule in vault.css, one line in the component list, and the decision skill could use it the next time.

That split is why the page survives outside Obsidian. Open it in any editor and the questions, the options and my answers are all still there as text. Only the cards and the colors are gone.

The parts are the ones I wanted. If you don't want the tags, or you want the code open, or you'd rather have a "what we tried before" list than a table, you say that to Claude and it changes the skill, so every page after that has the parts you chose.

Both pieces are in the obsidian-claude-vault repo: the skill under .claude/skills/create-decision, the styles in .obsidian/snippets/vault.css, and the Worky page at Projects/Worky/decisions/One calendar or three.md.

Watch answered questions fold into phases

Once I answer a question, it becomes a numbered decision, and the decision moves into the phase of work it led to. Here's the whole loop.

On the Worky page I answered the first question in round one: three views over one schedule. That's now D1. It sits inside the phase that's in progress, folded, with my reason, the options I didn't pick, and what would make me reopen it.

As the project moves, finished phases collapse to a single line with a colored status. The page gets shorter as more gets decided. What's left open is at the top, and the history is one click away, filed under the work it produced instead of the order I was asked. The numbers never get reused, because people say "D1" long after the round that made it.

My first version let these pages expire after a few weeks. I changed my mind, because the answered page turned out to be the most useful note in the project folder. When something changes, I open the decision, read the "revisit if" line, and decide again with the old reasoning in front of me. And before Claude writes a new decision page, it reads the project's decisions folder, so it doesn't ask me something I already settled.

Try it, then make your own

Pick a decision you've been putting off, the kind where you've said "let me think about it" at least once. Ask Claude to read the notes around it and write you a decision page with a recommendation for each question, then answer it tomorrow with coffee. If you want a working example first, clone obsidian-claude-vault and open the Worky calendar decision. One call is already filed in its phase, and two questions are waiting for you.

Decisions are only my example. The same two pieces work for any page you answer or read often: a skill that knows which parts the page can use, and a few styles that draw them. It could be a weekly review you tick through, or a bug list with a tag on each item saying how sure the finding is. Tell Claude what you want to see when you open the page and how you want to answer it, then ask it to write the skill and the styles. Mine took a few rounds of "this part looks off" before it settled, and yours will too.

Make Your Vault Look and Read the Way You Want

Alfredo Perez — Mon, 05 Oct 2026 13:26:37 +0000

I wanted my vault to look right. Not a theme someone else picked, and not the default gray, but a place I'd actually want to open every morning, with notes that tell me where things stand before I read a paragraph. You can get both now by showing Claude a picture of what you like, saying what you want in a sentence, and telling it what's off until it matches.

For years I had two options: live with the default look, or spend an evening hunting for a theme and then in forum threads guessing which of a hundred settings controlled the sidebar. I never learned the styling side of Obsidian, and I still haven't. What changed is that I stopped trying to write it and started describing the result. Claude does the reading that used to cost the evening.

This post belongs to a series on keeping your notes in markdown and letting Claude do the parts that used to be expensive. The argument going around is that documentation should move to HTML because it looks better and can do the layout. I'd rather keep the plain files and make them look right, and this post covers both halves of that: how the vault looks, and how the notes inside it read.

My taste is only the example

What I liked was Bear. Its dark sidebar, the calm light page next to it, the way nothing competes with the text. So my example is a Bear-style vault with a dark blue rail in the Tokyo Night palette.

That's Bear's picture of itself, from bear.app.

You'll want something else, and that's the point. Maybe it's Craft, or a notebook you used in school, or a screenshot of an app you saw on someone's desk. The method below doesn't care what the target is. It cares that you can point at it and say what's wrong with the first try.

Show it, say it, repeat

The whole thing is three moves. I give Claude a screenshot of the look I want, tell it which part of the vault I'm talking about, and ask it to make my vault look like that. Then I switch the change on, compare, and say what's off.

The arrow back to the screenshot is the part that matters. Claude reads how Obsidian draws each part of the screen and writes a small add-on file for the one piece I named, so I never have to learn what any of it is called. Obsidian lets you switch each of those add-ons on or off in its Appearance settings, which means every change is one toggle away from undone.

The sidebar, start to finish

The sidebar was the hardest part, so I started there. In the example vault it's drawn by a plugin called Notebook Navigator, which ignores most of Obsidian's usual styling. I didn't know that. Claude found it out by reading the plugin's own files, and it found the settings the plugin exposes for its colors.

My request was close to this:

Look at the attached Bear screenshot. I want a dark left rail in the
Tokyo Night blue, and everything else should stay light. Only change
the navigation pane. Put it in its own file I can switch off, and
explain the colors in a comment at the top.

I named one surface, the dark rail and nothing else, because "make it look like Bear" is too loose. A change that restyles the sidebar and the editor together ends up repainting the whole app. One surface kept the result small and easy to undo.

What came back was one small file, and a choice I wouldn't have made on my own. It used two shades of the same blue: a bright one on the dark rail, and a darker twin for links and buttons on the light side. The reason was in the comment it wrote at the top of the file: the bright blue washes out against a white page, so it's hard to read there, and the darker one would disappear on the dark rail. I'd have picked one blue, found half of it unreadable, and blamed the theme.

The picture shows what's touched and what isn't.

Only the rail went dark, which is what makes it feel like Bear rather than a dark mode. After that it was a few one-sentence fixes: the selected row is too bright, the counts are hard to read, the icons need to match the blue.

Here's a note before and after, with every change switched off and then on. I didn't change a word of the note itself.

Nothing in the note moved, only what draws it. That's why I'm comfortable letting Claude change how the vault looks at all: the notes stay plain text any editor can open, and switching the look off puts you back exactly where you started.

The smaller asks worked the same way, one sentence each. "Make the reading column wider" took it from Obsidian's default of 700 pixels to 1,000, and Claude's note at the top said it only works with the "Readable line length" option on, which saved me ten confused minutes. "Show me each heading's level in the margin while I edit" added a small muted marker that hides on the line your cursor is on. And "make the Calendar start weeks on Monday" was one change to that plugin's settings. None of them was hard. The value was not having to find where Obsidian keeps those knobs.

The same method, inside the notes

A vault that looks right still holds notes that read like a wall of bullets. Every time I liked a widget in an HTML doc, I rebuilt it by hand: a two-column compare here, a green, amber and red matrix there, a pipeline with little arrows between the steps. Each one lived in the page that used it, so the next page got a slightly different copy.

Worse, I couldn't find anything I'd written in them. At one point about 140,000 words of my notes, roughly a tenth of the whole vault, sat inside HTML pages that search couldn't see. A page can look exactly right and still be a dead end: you can't search it, link to it, or stumble on it from another note. Markdown notes stay searchable and linkable, which is why I want the good look inside the notes and not in a separate page.

So I gave the shapes I kept rebuilding a name, and taught Claude the names. Here's the same weekly update written twice with the same facts. On the left it's what I used to write. On the right it's what I get now when I ask for it.

The right-hand version answers "where are we?" before you read a sentence, and it's still the same plain file underneath. My set is cards, phases, a matrix and a handful of others. If you're always writing pros and cons, meeting agendas or reading lists, those are your components.

Ask for a comparison, get cards

When two things are being compared, I ask for cards.

Compare the MVP with the full vision as two cards.

What comes back is two boxes side by side, each with a title and a line or two.

The two colors do the comparing before you read a word. That's on purpose: two matching gray boxes make the reader work out which is which, which defeats the layout. If you'd rather have them in your own colors, or three across instead of two, that's one sentence to Claude.

Ask for a plan, get phases

When the work has an order, I ask for phases.

Turn this plan into phases. Phase 1 is in flight, keep only that one open.

Every phase is folded except the one being worked on, so the rail reads as a column of status chips with one open block. The states are a small closed set: done, now, next, queued and parked. "Later" is missing on purpose, because it hides why something isn't next. Queued means ready but not prioritized, and parked means blocked by something outside the work.

Ask for a matrix, see the shape

This is the demo I use to explain why names matter. The example vault gives Claude a short guide to every component: its name, what it's for, and how to write it. Claude reads that guide before it writes any note, and that's how a plain request becomes a finished shape.

Take a comparison in plain prose: Companion has an in-editor interface and spec-kit doesn't, and for auto-mode it's the reverse, with spec-kit only partial. Read that twice and you have the facts. Now ask for it as a matrix.

Turn this comparison into a capability matrix with a legend.

The matrix isn't prettier so much as faster. You see the shape of the data instead of holding three clauses in your head. Two rows are a toy, and at ten rows the difference is the whole point.

The rules that keep them safe

I cared about three things. Each component is one of Obsidian's built-in boxes for notes and warnings, called callouts, with a name I chose, so nothing has to be installed for the text to make sense. If the look is missing, a set of cards shows up as a plain gray box labelled "Cards", ugly but readable. And a matrix cell says "partial" in words, colored amber, instead of a yellow circle, because you can't search for a circle.

There's one more rule, and it's the first line of the components page in the example vault: don't decorate. Most notes are prose and a callout or two. A component is for content that has a shape, like a comparison, a sequence or a status.

The rest of the shelf is smaller: a box for terminal output, a frame for a diagram, a story map, a folder tree, a row of numbers when the numbers are the finding, and a few inline tags.

Eight shapes cover most of what I used to build by hand in HTML, and they share one look, so a note from March matches a note from today. The guide also carries my mistakes, which is what makes the corrections stick. The one I remember is a story map that borrowed the matrix's legend and showed colors that appeared nowhere in the map. Nothing errors to tell you a key is lying. Now "the legend uses the same colors as the cells" is written where Claude reads it, so I'm not correcting it in every note.

Build your own views: a dashboard, a board and a canvas

Components change how one note reads. Sometimes what I want is a page that looks across many notes: what's in progress, what's stuck, what changed this week. Obsidian has three ways to build that, and I ask Claude for each of them the way I ask for everything else.

A dashboard that keeps itself current

The Dataview plugin builds a page from what your notes say about themselves, like a status or a date. Nothing on the page is typed by hand, so it can't go stale. In the example vault it powers a Worky dashboard with the crew-scheduling stories counted by status, the open decisions, and the latest updates and meetings.

Make a dashboard page for the Worky project. Show its stories grouped by
status, the decisions that are still open, and the latest updates and meetings.

Then I adjust. "Make the status a colored chip." "Only show this week." "Put the blocked ones at the top." Each one is a sentence, and the page rebuilds itself when the notes change.

The same page with one snippet switched on. Nothing about the data changed. The statuses became chips, the headers got quieter, and the dates now stay on one line:

The latest-updates list only works because each note carries a date at the top. I hadn't written one, so I asked Claude to add it to the three notes and to sort the list by it. That's the pattern with a dashboard: if a table can't show something, the notes don't say it yet, and you ask Claude to make them say it.

The dashboard is a question the vault answers every time you open it, which is why I stopped keeping status lists by hand.

A board where cards are notes

Obsidian's Bases feature can show notes as a Kanban board. Each column is one value of a property, like status, and each card is a note. Drag a card to another column and Claude isn't involved at all: Obsidian changes that property in the note for you.

Show the crew-scheduling stories as a Kanban board, one column per status.

That gave me the board.

It has limits, and a good review of it at Practical PKM lays them out. A board groups by one property only, every card has to be its own note, and you can't reorder cards inside a column. As of this writing it's also an early-access feature in Obsidian, so it may not be in your version yet. It isn't the older Kanban plugin, which keeps its cards inside a single file. If you need a plain checklist board in one note, that's a different tool.

A canvas for arranging things

A canvas is an open board of cards and arrows, which suits a story map better than a list does. The example vault has one for crew scheduling, with the stories laid out in lanes. I asked for softer cards, and the look came from a snippet, the same as the sidebar. What came back is plain white cards with quiet borders inside tinted lanes, with a yellow card marking the one thing that blocks the rest.

Make the cards on the story map softer: rounded, a pale tint per lane,
and no heavy borders.

The lanes and arrows say where a story sits in the whole plan, which a list of the same stories can't.

One idea behind all three

All three read your notes as they are. Nothing about the notes changes to make them show up: they stay plain markdown, with a line at the top saying what they are. You style the view, not the data. So I ask Claude for the view, look at it, and say what to change, and if I ever drop the plugin, the notes are exactly what they were.

Good plugins to start with

The example vault switches on six community plugins. Each one is something you can set up by saying what you want, the same way as the sidebar.

Notebook Navigator replaces the file list with a two-pane browser, folders on the left and notes with a short preview on the right. It's the Bear feel. Try: "Show two lines of preview under each note and hide the note that shares its folder's name."
Calendar puts a month view in the right sidebar and opens the note for any day you click. Try: "Add a week column to the Calendar so I can open a note for the whole week."
Dataview turns a question into a list that keeps itself up to date, like every open decision in a project. The example vault's Worky dashboard is built with it, so you can see one at work. Try: "Add a list to this project note of every note tagged decision that isn't done."
Excalidraw lets you draw diagrams that live in the vault and stay editable. The skills that write a product spec or a roadmap save their diagrams this way. Try: "Draw this flow as an Excalidraw diagram I can move things around in."
Callout menu adds a right-click menu to any box in a note, to change its kind, fold it or copy what's inside. Try: "Add my component names to Callout menu so I can turn a box into cards or phases with a right-click."
Admonition is switched on too, but honestly nothing in the example vault needs it, because Obsidian's built-in callouts draw every component. You can skip it.

One plugin was removed on purpose: Code Styler restyles the small code-looking tags that the phase and story chips are drawn from, so it breaks them.

The loop for plugin settings is the same as for the look: you say what you want, Claude changes the plugin's settings, and you reload the plugin.

The coral note is the catch worth knowing before you start. Obsidian keeps some settings in memory and writes them back when it closes, so a change made while it's open can get quietly overwritten. If a change doesn't stick, quit Obsidian, ask again, and reopen.

Claude will also tell you when you're asking the wrong plugin. I assumed I could point Calendar at a folder for daily notes, and Claude came back and said Calendar has no such option: in the example vault, Notebook Navigator decides where daily notes go. I'd never have found that by clicking through settings panes.

Keeping it tidy

I asked Claude to keep each change separate: one for the sidebar, one for the reading width, one for the heading markers, one for the components. When an Obsidian update breaks one thing, I switch off one piece instead of hunting through everything. I also kept the comment Claude writes at the top of each change. It's the only record of why the sidebar uses two blues, and six months from now I won't remember. Because all of this lives inside the vault folder, it travels with the notes to any machine they sync to.

Try it

Open your vault, take a screenshot of an app whose look you like, and ask Claude for one thing: "make my sidebar look like this, and only the sidebar." Switch it on, say what's off, and go again. Then pick one comparison paragraph you already have and ask Claude to "turn this into two cards." When you catch yourself asking for the same shape twice, ask Claude to give it a name and add it to the guide. The example vault at github.com/alfredoperez/obsidian-claude-vault has my Bear version and my set of components if you'd rather start from something and take it somewhere else.

Under the hood

Each change to the look is a CSS snippet, a small file in the vault's .obsidian/snippets folder that Obsidian lists under Settings, Appearance, CSS snippets: bear-sidebar.css, line-width.css and heading-levels.css. One stylesheet, vault.css, draws every component, keyed off each callout's name so plugins don't break it. The guide Claude reads is the obsidian skill in .claude/skills, and Reference/Components.md shows every component. A small stylesheet, views.css, gives the dashboard and the canvas their look, and the board is a .base file next to the stories it shows. Plugin settings live in each plugin's own folder, and .obsidian/README.md lists the six plugins and why each is there. All of it is in the example vault.

Build Log 4: Your Pipeline, as Nodes

Alfredo Perez — Mon, 05 Oct 2026 13:26:06 +0000

How many settings should it take to answer one question?

The question was simple: how much ceremony do you want for this change? But SpecKit Companion had grown three different knobs to answer it. There was Template Profile (standard / turbo / off). There was a Turbo Workflow Picker. There was a Complexity Fast Path toggle. Each one earned its place honestly, shipped for a real reason in its own build log. That is the part worth saying out loud: none of them was a mistake on its own.

But stacked together, they were a maze. I built them, and even I had to stop and think about which combination did what.

That is the smell of a design problem. When the controls for one decision multiply, the decision is the thing that needs fixing, not the controls.

So this wave replaced all three with one idea: your pipeline is now a plain list of steps you can read, reorder, and add to, instead of a fixed sequence buried in code. Three toggles collapse into one picker, and when the list finishes it marks the spec done on its own.

The knobs were patches on something deeper

Here's the thing the toggles were quietly admitting: the pipeline underneath was hardcoded. It was always the same fixed sequence, specify then plan then tasks then implement, baked into the code. The settings couldn't reshape that sequence. All they could do was nudge it from the outside, trimming a template here, skipping a step there. Three knobs, all working around the same limitation.

You can see the cost up close in one file. The specify command was 142 lines doing seven different jobs back to back, and three of those jobs were copy-pasted to live somewhere else too. The logic that sizes a change as small or large sat inside specify, and inside a standalone classify command, and described a third time in the workflow file. So "change how we decide a change is small" meant editing the same idea in three places and hoping they stayed in sync. There was even a parity checker whose entire job was to catch them drifting apart. When you need a robot to babysit your copies, the copies are the problem.

On the left: one file doing seven jobs, the sizing logic tagged in all three places it got copied. On the right: that same idea collapsed into a single node. Everything in this wave is the move from left to right.

So the real fix was never "remove a setting." It was to change what the pipeline is.

Your pipeline is now a list of nodes

Stop treating the pipeline as code. Treat it as data. A workflow is just an ordered list of nodes, and now it literally is one:

# 📃 speckit-companion.workflow.yml
steps:
  - id: specify # 👇 writes the spec
  - id: classify # 👇 sizes the change: small | normal | oversized
  - id: route # 👇 the fork: less ceremony for small, full pipeline otherwise
  - id: mark-complete # 👇 the last node: writes status: completed

So what is a node? It's just a named step with a job, and there are only four jobs it can have. Here they are, side by side:

A node either investigates (reads the request and the code, gathers understanding, writes no document), authors (writes one specific file or section, like specify producing the spec), gates (a check or review pause), or controls (routes or finishes, like route and mark-complete). Notice there's no fifth kind. That constraint is the trick: because a node can only do one of four things, the workflow reads like a sentence instead of a program. Write the spec, size it, fork on the size, finish. That's all a pipeline is now.

(Today these are whole commands lined up. The next step is finer grained, letting the sections inside a command be nodes too, so you could pick exactly which parts of a spec get written. That's still being built; the grammar above is what it'll be built on.)

This is the whole point of the wave, so it is worth sitting on. Once the pipeline is a list, the things the old toggles fought for stop being toggles and become nodes in the list.

"Less ceremony for a small change" used to be the Complexity Fast Path setting. Now it is the route node. It reads the size from classify and picks a path: a small change runs plan and tasks without the review-gate pauses, anything normal runs the full gated pipeline, and an oversized change warns out loud and then runs the full pipeline anyway. The safe default is always the full path, so an unclear size never silently drops a step.

"Mark the spec done when it's actually done" used to be a manual click. Now it is the terminal node. When the list finishes, the spec lands at completed on its own.

Put it together and the fork you used to toggle is right there in the list:

The diamond is route, reading the size and picking a path. The mint check is the terminal node closing the spec. What used to be two hidden toggles is now two visible nodes you can point at.

Nothing here is a new setting. The behavior moved into the workflow, where you can see it and reshape it, instead of living in a pile of checkboxes that hide it.

What you actually see today: one picker

The structural change is large. The visible change is small, and that's fine. The three Beta toggles are gone, replaced by one setting with exactly two values:

// 📃 settings.json
"speckit.defaultWorkflow": "companion"  // 👈 or "speckit". That's the whole menu.

The Create Spec picker pre-selects your choice. Pick SpecKit and you get the stock pipeline, untouched. Pick SpecKit Companion and you get the leaner one, right-sizing built in.

One dropdown, two values. That is the entire visible surface of everything above: all the node machinery, reduced to a single choice at the top of the page.

And because deleting settings is its own kind of risk, the extension migrates on activation. It drops the three retired keys at every scope and coerces the old values, so a leftover entry in someone's settings.json does not break activation. That bug bit me once with a renamed provider. Not again.

Now the honest part, because build-in-public is worthless if it only shows the wins. Since the draft, the commands learned to read the list and walk it themselves. In an agentic CLI like Claude Code, you run specify and it advances to the next node on its own, with the terminal node wired to mark the spec complete. That self-advance is real and shipped.

The finish line used to be the catch. A panel run would get most of the way and then stick at implementing, because two writers raced on the same status file. That one is fixed now: status only ever moves forward, so a late or duplicate write can't drag a spec backward, and the terminal node lands it at completed on its own.

What's left is cosmetic. One of the close paths can still write a duplicate "done" line into the history, and there's a ticket open for it. The completion itself is solid.

Two ways to walk the same list, stacked:

Same nodes, same commands underneath. The only thing that changes between the lanes is who presses next: you, clicking through in a one-shot chat, or the agent walking the list on its own in a CLI that keeps going.

The receipt: I shipped this wave's own ticket through it

The right-sizing is already real, and I have the receipt. I built one of this wave's own tickets through the Companion workflow: the Create Spec polish, the very page that picker lives on. It's a small change, a few CSS tweaks and some placeholder copy, so the workflow sized it small and folded the plan and tasks steps. Those two steps, which on a real feature take minutes of generation, finished in about 80 milliseconds each. For a small change there's nothing heavy to write. The plan file came out 204 bytes. Seven tasks, the full suite green (998 tests), and the spec closed out completed. The fold isn't a someday promise. It already runs.

When the plan met reality

The best part of this wave was the part that went wrong on paper first.

My ticket confidently described how to build the workflow, and it was wrong in three specific ways. I only found out because I checked against the actually-installed spec-kit before writing a line of YAML. The routing step I planned didn't exist under that name. Workflows turned out not to register through the extension manifest at all; they live in their own catalog. And my version floor quietly excluded the exact pre-release builds the install produces.

Three assumptions, three corrections, zero wasted implementation. That is the whole argument for a pre-flight pass. An hour reading the tool you actually have beats a day building against the tool you imagined.

The engine I almost rode

The tempting version of this is to write my own runner: a loop that walks the nodes, handles the gates, manages pause and resume. That's a lot of code, so my first instinct was to dodge it entirely. Spec-kit ships its own workflow engine, and on paper it does everything: steps, gates, conditional routing, pause and resume from the exact node you stopped on. Ride that, I figured, and Companion gets a real runner for free.

Then I actually checked. That engine is genuinely capable, but in this project nothing had wired it up yet: the Companion workflow wasn't registered with it, and every spec I'd shipped, mine and the demos, had run the way people actually run them, one command at a time. Hanging the whole roadmap on a runner that nothing here had ever connected to meant building for a tool I imagined instead of the one in front of me. So I asked a smaller question: where does the self-advance actually need to live?

The picture is the answer: the gears live inside the command you already run, not in a separate box you have to start first. Instead of a standalone runner, the command does its own node, then reads the list, finds the next node, and keeps going. Nothing extra to invoke. Running specify is running the first node of the engine. The decision that changed this wave was where the engine goes, and the answer turned out to be "the thing you already run."

Two honest limits, because this is the part that bites if you don't say it out loud. First, "keep going on your own" needs an agent that keeps acting after a step. So ask one question before you lean on self-advance: does your tool keep acting after a reply, or stop dead after one? Claude Code and the agentic CLIs keep going. Some one-shot IDE chats stop, and there the fallback is you, or the GUI button, firing the next step. The rule the commands carry is "continue if you can." Second, "read the list and run the next node" is the model following instructions, not a bulletproof loop. The bulletproof version is exactly specify workflow run from a terminal, and that's the command nobody wants to type. So this is a deliberate trade: self-advance that works in your everyday flow with zero special commands, leaning on the agent instead of a hard engine, with the terminal runner still there for anyone who wants the guaranteed version.

What this wave taught me

When one decision needs three toggles, fix the decision, not the toggles. Multiplying controls is the smell; the rigid thing underneath is the real bug.
Make the pipeline data, not code. A workflow you can read as a list is one you can reorder and extend without editing a command.
Check the tool you actually have before you build against it. An hour reading the installed spec-kit caught three wrong assumptions and saved a day of rework.
Put the engine in the thing you already run. Self-advance lives in the command, so there's no separate runner to wire up.

What's next

Here is the part this was all for, and it is no longer a someday promise. The pipeline being a list means you grow it by adding to the list, and the first real addition already runs. A Companion run now ends reviewed and PR'd instead of as raw code: right before it marks the spec complete, it reviews its own diff against the project's conventions, runs a simplifier pass, and opens a pull request, stopping before merge. None of that is new code in the extension. It is a handful of lines in a .specify/companion.yml file that the command reads at run time and slots in at the right moment.

Notice what does not change in that picture. The new node (marigold) drops in one slot before the finish, and every command around it stays exactly as it was. That is what "grow it by adding to the list" actually looks like.

That is the whole shape of it: because it's just entries in a list, you add your own without rewriting any command. Drop in a security review, pick the exact author steps your team wants, skip the rest. None of it is a new toggle.

What's genuinely still ahead is making it effortless: a hands-off auto mode that runs the whole list start to finish without anyone pressing next. That has since shipped too, so the next build log is its story.

Same pipeline. Next time, it drives itself.

Build Log 3: Turbo Mode and the Fast Path

Alfredo Perez — Mon, 05 Oct 2026 13:25:48 +0000

spec-kit treats a typo fix and a brand new auth system exactly the same way. Same eight files in the spec folder. Same user-story scaffolding. Same heavy pipeline, whether the change earns it or not.

For most of what I ship, that is ceremony I never read. A User Scenarios block, a separate checklists/requirements.md gate, a quickstart.md, a dual-option Project Structure tree. All of it generated, none of it touched.

I had already built a leaner shape into SDD: about three files instead of eight, a short Overview instead of user stories. So this step had two goals. Give spec-kit that same shape without forking it. Then go one further and stop making a one-line change walk the whole pipeline at all.

That turned into two features, and a week of churn before they settled into a shape I would actually ship.

What I shipped

Two features came out of this, and they solve the same problem from two different angles: a typo fix and a new auth system should not cost the same ceremony.

Turbo mode changes the shape of a spec. Same seven commands, but leaner output: no user stories, tasks grouped by the files they touch, side documents written only when they help. A smaller spec folder.

The Fast Path changes the flow. When a change is genuinely small, it short-circuits the pipeline. No separate plan and tasks stages. It goes straight from specify to implement, in a single run.

Turbo stands on its own. The Fast Path builds on it, because skipping plan and tasks only makes sense once the shape is already lean, so it fires only when turbo is on. In settings they are two independent switches: speckit.companion.templateProfile for turbo, speckit.companion.complexityFastPath for the Fast Path. Both ship opt-in beta. The next two sections take each one in turn: what it is, how to turn it on, and exactly how it compares.

Turbo mode

What it is. A second shape for the same seven spec-kit commands. companion-standard is the stock commands, unchanged, with honest timing added. companion-turbo keeps those same commands but trims the heavy parts: the user stories collapse into a three-line Overview, tasks group by files and dependencies, and the side documents get written only when they actually help. A third value, off, means plain upstream spec-kit with no overrides at all.

A quick honesty note on the name. This shipped as lean first. I renamed it to turbo before any release, with no alias and no migration. "Lean" sold the wrong thing. The point is not fewer files. The point is that it is faster.

How to enable it. Set the project default speckit.companion.templateProfile to turbo. It defaults to off, so this is opt-in.

# 📃 .specify/companion.yml  (machine-local, gitignored)
templateProfile: turbo

Each spec then carries its own profile pin in .spec-context.json, so the choice holds all the way through plan, tasks, and implement. Why that pin matters is its own story, below.

How it differs from standard. Here is the full per-file breakdown:

	`standard`	`turbo`
`spec.md`	User Scenarios / user stories	a 1-3 line Overview, no user stories
`tasks.md` axis	grouped by user story, `[US#]` labels, MVP framing	grouped by files and dependencies, strict `[Tn] [P?] + path`
`plan.md`	dual-option Project Structure + Complexity Tracking	a turbo Approach and Structure (files/deps) + Out of Scope
`requirements.md`	full checklist, including acceptance scenarios	lean self-check, no user-story items
`research` / `data-model` / `contracts/` / `quickstart`	written by default	on demand only, when they help that change
Net spec folder	about 8 files	`spec.md` + `plan.md` + `tasks.md` + `requirements.md`, side files on demand
Timing fidelity	honest finish-only	honest finish-only (identical)

The same split is easier to see stacked side by side.

Turbo keeps four files where standard keeps eight, and the user stories are the one block it drops outright.

The Fast Path

What it is. The Fast Path lets a small change skip the middle of the pipeline. Under the hood it is a classify step at the end of turbo's specify command: it reads the spec you just drafted, returns one of two verdicts, simple or normal, and then either short-circuits straight to implement or runs the full pipeline. It is best-effort, and it deliberately errs toward normal. A change never gets under-planned by accident.

It decides on four inputs:

Input	What it reads	Pushes toward
`fastPathEnabled`	the `complexityFastPath` flag	`simple` only if `true`
`projectedFiles`	files the change will touch, vs a 5-file ceiling	`normal` if over
`projectedTasks`	tasks projected, vs a 10-task ceiling	`normal` if over
`scopeSignal`	scope phrases (`rewrite`/`overhaul`/`new system` vs `one-line`/`rename`/`typo`)	`larger` forces `normal`

A spec is simple only when the flag is on, both projections sit at or under the ceiling, and the scope signal is not larger. Anything else is normal.

How to enable it. Set speckit.companion.complexityFastPath to true. Like turbo, it defaults to false, and it only does anything in turbo mode.

# 📃 .specify/companion.yml
templateProfile: turbo
complexityFastPath: true # 👇 small changes now fast-track to implement

If both the project file and the editor setting are present, the project file wins, and the resolved value is mirrored back so the command body reads a single source of truth.

How it compares. The two branches:

	`simple` (Fast Path)	`normal` (full pipeline)
When	flag on, 5 or fewer files, 10 or fewer tasks, no "rewrite" scope	anything larger, or flag off
Artifacts	one combined `spec.md` (Approach + Implementation Tasks inline) + `requirements.md`	`spec.md`, then `plan.md`, then `tasks.md`
Stages	`specify` straight to `implement` (plan/tasks folded)	`specify`, `plan`, `tasks`, `implement`
Lands at	`ready-to-implement` in one run	each step run on its own
Over the guardrail	warns, never a silent fast-track	not applicable

When the change crosses the guardrail (more than 5 files or 10 tasks, or a "rewrite"-class scope word), the body prints a warning and runs the full pipeline instead. It never silently fast-tracks something big.

The fold is real, not cosmetic. After specify self-closes, the command writes the folded plan and tasks entries itself, the last one marking the spec ready-to-implement. So the Companion viewer reads plan and tasks as satisfied, not missing, and the spec lands ready for implement in a single run. The final completed gate stays a human action.

The whole routing decision reads more clearly as one picture.

A simple change takes the short express arrow to implement, while anything past the guardrail drops back onto the full four-stage line.

Does it work?

I ran the same feature, on the same codebase, through both shapes. Turbo finished the full pipeline in 12.4 minutes against standard's 21.3, a 42% drop, and produced 3 spec artifacts instead of 8.

Metric	Standard	Turbo
Total pipeline	21.3m	12.4m (42% faster)
specify / plan / tasks / implement	5.2 / 5.9 / 2.5 / 5.2m	1.3 / 2.6 / 1.0 / 6.2m
Spec artifacts	8	3
Source files touched	6	3
Tasks	9	6

Now the honest part. Turbo's implement step was actually slower, 6.2 minutes against 5.2, despite having fewer tasks. That is one run, so it is noise, not evidence that scaffolding speeds up implementation. The lever here is choosing the right profile, not bloating turbo to chase a number. I am calling it out because the tempting conclusion, that more upfront design makes implementation faster, is exactly the one this data does not support.

The Fast Path got its own proof on a real spec. A small install-URL fix, run in turbo with the Fast Path on, emitted one combined spec.md, an Overview plus an inline Approach, and landed at implement in a single shot. After specify self-closed, the command wrote the folded plan and tasks entries itself, with real timestamps:

// 📃 specs/159-inline-install-stable-url/.spec-context.json
// history[]: the two folded entries (abridged)
{ "step": "plan",  "substep": "fast-path",
  "kind": "complete", "by": "ai", "at": "2026-06-13T01:31:19.217Z" },
{ "step": "tasks", "substep": "fast-path",
  "kind": "complete", "by": "ai", "at": "2026-06-13T01:31:19.425Z" }

The eval asserts those folds carry real timestamps and that the spec reaches ready-to-implement, and it stays silent on a normal spec.

Underneath all of it, the timing finally stayed honest. Back in Build Log 2, the eval caught the timing lying. Finish-only journaling is the fix that stuck: it logs one complete event per task and derives every duration from the gaps between finishes. Lap times, not stopwatches. The zero-second ticks, the phantom gaps between tasks, the bursts where a dozen substeps share one timestamp: all gone. The eval runs 13 pass, 0 fail.

Why the shape lives in commands, not templates

The obvious way to reshape a spec is to override the document template, spec-template.md, with a lean one. I built it that way first. It silently did nothing.

The reason is mechanical, not stylistic. A spec-kit preset can override two kinds of file: the command (the prompt the agent runs) and the template (the document scaffold). Template overrides only resolve when a setup script walks the override stack.

plan and tasks go through setup-plan.sh and setup-tasks.sh, which do walk the stack. A template override there takes effect.
specify copies templates/spec-template.md by literal path and never runs the resolver. A lean spec-template.md is simply never read.

So template overrides are mixed: they work for plan and tasks, and no-op for specify. Command overrides apply uniformly to all seven commands. The only reliable single mechanism is to carry the shape in the command bodies, so that is where it lives. The accepted tradeoff: in turbo mode the on-disk spec-template.md still shows the stock shape. Turbo just does not read it.

The two code paths make the mismatch obvious.

Plan and tasks honor a template override, specify copies the file by literal path and walks right past the resolver, so the shape has to live in the command body to reach all seven commands.

Why modes route, not swap

Once the shape lives in command bodies, the next obvious move is to swap them. Switch to turbo, uninstall the standard commands, install the turbo ones. My first cut did exactly that. The moment you switched mid-pipeline, /speckit-plan failed with "Unknown command."

The fix was to stop deleting things. Keep both command sets installed, and route each command to its /speckit.companion.* twin based on the spec's pinned profile. Nothing gets removed, so switching modes can never strand you. An add-only "ensure standard" runs on activation to re-materialize the stock family on a fresh checkout, and it never removes anything.

The pin also has to be durable. Turbo used to run for specify and then quietly revert to stock for everything after it. The capture script writes .spec-context.json with no profile, and the extension only pinned the profile when it created that file itself. The command always got there first, so the pin was never written. The fix back-fills the pin from the project default on the first lifecycle write:

// 📃 specs/159-inline-install-stable-url/.spec-context.json
{
  "workflow": "speckit",
  "profile": "turbo", // pinned at specify, carried to completed
  "currentStep": "implement",
  "status": "completed"
}

Now the shape carries the whole way through, and existing un-pinned specs heal themselves on their next write.

Where it landed

This is the part a clean changelog hides.

The rename. It shipped as lean, then became turbo before release. No alias, no migration, the old value just gone.

The reversal. I planned all of this to ship on by default, opt-out. It landed opt-in, grouped under a "Beta Features" settings section, both toggles defaulting to off. A half-proven feature does not get to reshape everyone's pipeline by default. Capture and status/resume, the parts that just track your work, stay always-on. They are the v1 core, not a beta.

Here is where the two switches actually surface.

Both live under Beta Features, defaulting to off, so nothing changes until you opt in.

Two housekeeping wins that say more than they look. The published .vsix had bloated to 66.6 MB because it was shipping my entire dev workspace: example sandboxes, caches, spec fixtures. Trimming it to 1.17 MB, roughly 60 times smaller, is just the principle that installing the extension should ship the extension, not my workspace. And .specify/companion.yml is now machine-local and gitignored, so one developer's profile default no longer leaks into everyone else's checkout.

What's next

The Fast Path just merged, so everything this log describes is shipped, opt-in beta for now. Both graduate to on-by-default only after they have proven themselves on enough real specs to earn the trust that capture and resume already have.

Then Build Log 4: giving the pipeline an ending. Today it stops at implement, and the review, the commit, the PR, the mark-complete all still live in my head. Next I make them part of the workflow itself, recorded and on screen. That is also what finally makes auto mode worth having.

The public backlog tracks every step as it merges. Star the repo to follow along, and I will see you at Build Log 4.

Build Your Own SDD Workflow

Alfredo Perez — Mon, 05 Oct 2026 13:25:08 +0000

Spec-driven development works. Planning before you code catches bad assumptions early, keeps scope honest, and gives the AI enough context to write code you'd actually ship. That's not the problem.

The problem is ceremony. GitHub spec-kit gives you seven steps, multiple checkpoints, and templates designed for large teams coordinating across repos. When you're adding a component or fixing a bug, that's a lot of overhead for a Tuesday afternoon.

And it's not like there's a shortage of alternatives. New AI workflow repos show up weekly. Everyone's got an opinion on the "right" way to structure AI-assisted development.

Here's the thing. What if you just built the one that fits how you think?

That's what this article is. We'll build a 4-step SDD workflow from scratch and wire it into SpecKit Companion so you can see and run each phase visually. Four commands, four files, zero ceremony.

What We Kept

GitHub spec-kit gives you seven steps: constitution, clarify, specification, plan, tasks, implement, review. I only needed four.

Dropped:

Constitution: coding rules belong in CLAUDE.md once, not re-checked per feature
Clarify: draft first, iterate. Stop asking questions before you've seen anything
Review: add it back as an enhancement when you need it

Kept:

Specify: defines what you're building
Plan: designs how to build it
Tasks: breaks the plan into executable steps
Implement: executes the work

So the pipeline looks like this: specify → plan → tasks → implement

Specify → sdd.specify → spec.md. Explores the codebase, defines what and why
Plan → sdd.plan → plan.md. Reads the spec, designs how to build it
Tasks → sdd.tasks → tasks.md. Breaks the plan into ordered, verifiable tasks
Implement → sdd.implement → Code + PR. Executes tasks one by one, commits, opens a PR

All four map to SpecKit Companion phases. The first three produce markdown files. Implement runs the sdd.implement command. It doesn't produce a file, it executes the work.

Get the Files

Here's what goes into your project. Seven files: four commands that tell the AI what to do, three templates that define what the output looks like.

Commands (.claude/commands/):

sdd.specify.md
sdd.plan.md
sdd.tasks.md
sdd.implement.md

Templates (.claude/templates/):

sdd-spec.md
sdd-plan.md
sdd-tasks.md

Grab the SDD Starter Files (Gist). Drop them in the folders above and you're ready.

Why SpecKit Companion

You could run these commands from the terminal and call it a day. But SpecKit Companion gives you something the terminal doesn't: you can see where you are. Each phase shows up in the sidebar, you click to advance, and you always know what's done and what's next. It turns a set of markdown commands into an actual workflow you can follow.

Here's the config. Add this to .vscode/settings.json:

{
  "speckit.customWorkflows": [
    {
      "name": "sdd",
      "displayName": "SDD",
      "description": "Lean 4-step SDD workflow: specify, plan, tasks, implement",
      "steps": [
        {
          "name": "specify",
          "label": "Specify",
          "command": "sdd.specify",
          "file": "spec.md"
        },
        {
          "name": "plan",
          "label": "Plan",
          "command": "sdd.plan",
          "file": "plan.md"
        },
        {
          "name": "tasks",
          "label": "Tasks",
          "command": "sdd.tasks",
          "file": "tasks.md"
        },
        {
          "name": "implement",
          "label": "Implement",
          "command": "sdd.implement",
          "actionOnly": true
        }
      ]
    }
  ],
  "speckit.defaultWorkflow": "sdd"
}

Four steps. The first three produce markdown files. Implement runs the command but doesn't produce a file; it executes the work.

Walking Through a Feature

Let me walk you through a real feature. We're adding a home page and navigation bar to an empty application, enough to see every phase in action.

Specify

Click "+" in the SpecKit Companion sidebar, describe what you want ("Add a home page with a navigation bar"), and select the SDD workflow.

Once the specification finishes, the new spec appears in the sidebar. Open it and you'll see what we're building. Under the hood, the AI explored two or three relevant files, figured out the scope of the change, and wrote spec.md: summary, requirements with Given/When/Then scenarios, and what's out of scope.

Plan

Hit Plan at the bottom of the Specify phase. The command reads spec.md, researches existing patterns in your repo, and writes plan.md: the approach, files to create or modify, and risks.

Here's the part I like: it stops and shows you the plan before anything moves forward. You approve, edit, or reject. No guessing, no "let me just refactor this real quick" surprises.

Tasks

Click Tasks. The command reads both spec.md and plan.md, then breaks the plan into phased, verifiable tasks. Each task gets a Do/Verify pair: what to build and how to confirm it works. Phase 1 runs in order. Phase 2 tasks are tagged for parallel execution (tests, docs, cleanup that can run as separate agents).

Implement

Drop to the terminal, run /sdd.implement. This is where the AI actually writes code. It reads all three files, executes Phase 1 tasks sequentially, auto-fixes small issues like import errors, but stops for anything architectural. Phase 2 agents launch in parallel. It commits and optionally opens a PR.

Implement lives in the terminal because that's where code belongs. SpecKit Companion handles planning. The terminal handles execution.

Enhance Your Workflow

That worked great for a full feature. But now imagine you need to add a title to the nav bar, a one-line change. The same four steps still run: the AI explores the codebase, researches architecture, writes a multi-file plan, breaks it into phased tasks. That's a lot of machinery for something you could describe in a sentence. Since this is your workflow, you can fix that.

Fast Mode

Open sdd.specify.md. After the AI explores the codebase, add a step that classifies the change:

📃 .claude/commands/sdd.specify.md

### 4. Detect Complexity

Based on what you found in Explore, classify the change:

| Signal                                            | Mode        |
| ------------------------------------------------- | ----------- |
| Touches 1 existing file, change is <10 lines      | **minimal** |
| Pure style or config tweak                        | **minimal** |
| Touches 2+ files, or adds a new component/service | **normal**  |

If unclear, default to **normal**.

Then add a step that only runs in minimal mode. Instead of handing off to /sdd.plan and /sdd.tasks, it generates all three files in one pass:

📃 .claude/commands/sdd.specify.md

### 6. Minimal Mode — Write `plan.md` + `tasks.md`

Skip this step if mode is **normal**.

Write `specs/{NNN}-{slug}/plan.md`:

- Approach (1-2 sentences)
- Files to change
- Phase 1 tasks with Do/Verify pairs

Write `specs/{NNN}-{slug}/tasks.md`:

- Single phase task list matching the plan

Try it: run /sdd.specify add a title to the nav bar. The command sees it's a single-file fix and collapses three steps into one. All the artifacts, none of the ceremony.

One command, and you're ready to implement.

The Checkpoint

Open sdd.implement.md. After the AI executes all tasks, add a checkpoint that presents the results for review before pushing:

📃 .claude/commands/sdd.implement.md

### 5. Checkpoint — Commit + PR

Display exactly this format, then use **AskUserQuestion**:

--- CP: Commit & PR ---
Commit: {type}({scope}): {short description}

PR title: {type}({scope}): {short description}
PR body: ## What - [bullet from spec]

    ## Why
    [one sentence from spec]

    ## Testing
    - [verify step from tasks]

Options:

- **Approve** — proceed to commit and PR
- **Edit** — user provides notes; apply changes, redisplay

Run /sdd.implement. The AI creates a branch, executes the task, and then stops. Before anything gets pushed, it shows you exactly what changed, the commit message, and the PR body. You approve, edit, or reject. Nothing leaves your machine without your sign-off.

Two interactions total. Full traceability. And if you don't like the PR title, you fix it right there.

Make It Yours

You just saw two customizations in action: a complexity check in sdd.specify.md and a checkpoint in sdd.implement.md. Both are just markdown rules you can tune or remove.

Every step works the same way. Want "Security Considerations" in every spec? Add one line to sdd.specify.md. Want conventional commits? Add a rule to sdd.implement.md. Want TDD enforced? Add "write tests before implementation" to sdd.tasks.md.

And the workflow commands are just the first layer. Add rules in CLAUDE.md, build a pattern library, wire in specialized agents. Each layer makes the next one better.

Layer 1: Workflow commands. sdd.specify.md, sdd.plan.md, sdd.tasks.md, sdd.implement.md. The structure.
Layer 2: Rules. CLAUDE.md / AGENTS.md. Naming, testing, commit standards. Written once, applied to every feature.
Layer 3: Pattern library. "Here's how we do X." Component templates, API patterns. The AI matches your codebase instead of guessing.
Layer 4: Skills and agents. Specialized tools called during steps. Route TypeScript to a code reviewer, HTML to an accessibility expert.

It's all markdown. Improving it is trivial.

Get Started

Grab the SDD Starter Files (Gist): 4 commands + 3 templates
Configure SpecKit Companion: copy the settings.json snippet above
Demo repo: the project from this walkthrough, with all commands and config ready to clone
Evolving version: I'm building on this at alfredoperez/sdd, a Claude Code plugin incorporating the best patterns from 8+ open-source AI workflows

Install SpecKit Companion from the VS Code Marketplace, drop the files, and start shipping. Next up: how to scale this across a team with shared specs and conventions.

Custom Workflows in SpecKit Companion

Alfredo Perez — Mon, 05 Oct 2026 13:24:57 +0000

You might think SpecKit Companion only works with GitHub's spec-kit. It doesn't. Spec-driven development is exploding right now — there are dozens of workflows and methodologies emerging across the community — and SpecKit Companion can work with any of them.

One that caught my attention is Gentle AI by Gentleman Programming. It's an ecosystem configurator that transforms AI coding agents into comprehensive development systems. It takes a different approach to SDD: instead of one AI doing everything, it delegates to specialized sub-agents for each phase — explore, specify, design, implement, verify. One command sets up the entire workflow, and it pairs perfectly with SpecKit Companion's visual interface.

Let me show you how to set it up and run through a quick feature build.

What Are Custom Workflows?

By default, SpecKit Companion uses GitHub spec-kit's commands — speckit.specify, speckit.plan, speckit.tasks, speckit.implement. A custom workflow lets you swap those out for commands from a different SDD methodology.

You define the steps, the commands they run, and the files they produce. SpecKit Companion handles the rest — sidebar navigation, phase tracking, progress indicators — all working with your workflow instead of the default.

Setting Up Gentle AI

Before configuring the custom workflow, you need to install Gentle AI. Run gentle-ai install in the terminal — the interactive TUI lets you select your agent (Claude Code, Cursor, etc.) and components (SDD, Engram memory, skills). This bootstraps the SDD commands and file structure in your project.

Once initialized, you need to add the SpecKit Companion configuration to .vscode/settings.json — Gentle AI doesn't do this for you. Here's what the workflow configuration looks like:

// 📃 .vscode/settings.json
{
  "speckit.customWorkflows": [
    {
      "name": "gentle-ai",
      "displayName": "Gentle AI (SDD)",
      "description": "Multi-agent SDD workflow using gentle-ai",
      "steps": [
        {
          "name": "specify",
          "label": "Spec",
          "command": "sdd-spec",
          "file": "spec.md",
          "subDir": "specs"
        },
        {
          "name": "plan",
          "label": "Design",
          "command": "sdd-design",
          "file": "design.md",
          "includeRelatedDocs": true
        },
        {
          "name": "tasks",
          "label": "Tasks",
          "command": "sdd-tasks",
          "file": "tasks.md"
        }
      ]
    }
  ],
  "speckit.defaultWorkflow": "gentle-ai",
  "speckit.specDirectories": ["specs", "openspec/changes/*", "openspec/changes/archive/*"],
  "speckit.customCommands": [
    {
      "name": "verify",
      "title": "Verify",
      "command": "/sdd-verify",
      "step": "tasks",
      "tooltip": "Validate implementation matches specs"
    },
    {
      "name": "archive",
      "title": "Archive",
      "command": "/sdd-archive",
      "step": "tasks",
      "tooltip": "Archive completed change"
    }
  ]
}

The customCommands section adds Verify and Archive buttons to the Tasks phase — these aren't workflow steps, but actions you can trigger once implementation is done. Verify validates that the code matches the specs, and Archive moves the completed change to the archive directory.

Notice the labels are different from the default workflow — Spec, Design, Tasks instead of Specify, Plan, Tasks. SpecKit Companion adapts to whatever naming your workflow uses.

Running Through the Workflow

To test this out, I'll add a header navigation bar to an empty Angular app — a quick demo to show the full cycle.

Creating the Spec

Click the "+" button in the SpecKit Companion sidebar and you'll see a workflow selector — the default GitHub spec-kit workflow and Gentle AI are both available. Select Gentle AI (SDD).

Describe what you want to build, select the workflow that we just added, add any images that can give more context and hit submit. The sdd-spec command runs and generates the specification.

Once you click submit, the terminal opens with a command like:

/sdd-spec Add a navigation bar and a home page

Gentle AI creates two specs — one for each feature (the navbar and the home page). You can see both listed in the SpecKit Companion sidebar.

Spec → Design → Tasks

From here, the experience is the same visual flow you're used to — but with Gentle AI's three phases:

Spec — The specification defines what we're building. In Gentle AI, this follows their Given/When/Then scenario format with one spec per feature. The sidebar shows all the specs created under this change.

Notice the subDir setting in the config — this tells SpecKit Companion that specs live in their own subfolder, which is how both specs get grouped under the same change:

// 👇 Specs get their own subfolder
{
  "name": "specify",
  "label": "Spec",
  "command": "sdd-spec",
  "file": "spec.md",
  "subDir": "specs"
}

Click the Design button at the bottom to move to the next phase. This executes a command like /sdd-design <change-path> in the terminal.

Design — Instead of a single plan file, Gentle AI generates a design document with architecture decisions and rationale. The includeRelatedDocs flag tells SpecKit Companion to display related files (like the spec files from the previous step) in an expandable sub-tree, giving you context without leaving the Design phase:

// 👇 Shows spec files as context in a sub-tree
{
  "name": "plan",
  "label": "Design",
  "command": "sdd-design",
  "file": "design.md",
  "includeRelatedDocs": true
}

Click the Tasks button at the bottom to move to the final phase. This runs /sdd-tasks <change-path> and creates the implementation tasks for both specifications.

Tasks — The implementation breakdown. Each task is phased and ordered. You'll also see Verify and Archive buttons — these are custom commands, not workflow steps. Once you implement the tasks with sdd-apply, use them to validate and archive the completed spec.

Once all tasks are done, the top navigation bar shows an indicator that the spec is completed. From here you can either verify or archive. In our case, we'll go directly to archive.

The progress bar at the top tracks you through all three phases, and when the last one completes, the spec is marked as done — same visual feedback, different workflow underneath.

Archiving with Custom Commands

Let's try the Archive button — this is a custom command we defined in settings.json, not a workflow step. Clicking it runs /sdd-archive and moves the completed change to the openspec/changes/archive/ directory.

Two settings work together here. The custom command adds the button to the Tasks phase:

// 👇 Adds Archive button to the Tasks step
{
  "name": "archive",
  "title": "Archive",
  "command": "/sdd-archive",
  "step": "tasks",
  "tooltip": "Archive completed change"
}

And the specDirectories setting keeps archived specs visible in the sidebar:

// 👇 Archive folder included so past specs stay browsable
"speckit.specDirectories": [
  "specs",
  "openspec/changes/*",
  "openspec/changes/archive/*"
]

The archived spec doesn't disappear — you can browse past changes without digging through folders.

When to Use Custom Workflows

Two main use cases:

1. Try another existing SDD workflow. Gentle AI is just one example. Any methodology that uses commands and produces markdown files can be plugged into SpecKit Companion. Found a workflow you like on GitHub? Configure it in settings.json and you have a visual interface for it immediately.

2. Create your own workflow for your team. Maybe you don't like how speckit.plan works — you want something leaner. Or more sophisticated. Or you want to add a review step between plan and tasks. Custom workflows let you define exactly the phases and commands your team needs.

We'll dig deep into option 2 in the next article.

What's Next

Now that you know SpecKit Companion works with any SDD workflow, the next question is: what if none of the existing ones are exactly what you need? In the next article, we'll walk through stripping spec-driven development down to a lean 3-step pipeline tailored to your project.

Give it a try — install SpecKit Companion from the VS Code Marketplace and plug in the SDD workflow that fits your team.

SpecKit Companion

Alfredo Perez — Mon, 05 Oct 2026 13:24:36 +0000

GitHub's spec-kit has been gaining serious traction — 46.7k stars and counting — and for good reason. It brings a solid methodology for using spec-driven development with the AI coding tool of your choice.

But you might be asking: what is spec-driven development? It's the practice of defining what you want to build and why before asking AI to write code. Instead of vague prompts and hoping for the best, you write explicit specifications that become the AI's roadmap. Fewer misunderstandings, fewer iterations, better results. (If you want the full breakdown, check out Spec-Driven Development: Stop Vibe Coding.)

Here's where SpecKit Companion enters. It's a VS Code extension that gives you a visual interface for spec-driven development — browse specs, track workflow progress, and manage your AI configuration, all without leaving your editor.

Why a Visual Interface?

When Kiro launched their IDE built around spec-driven development, something clicked for me. Seeing your specs, plans, and tasks laid out visually — not buried in markdown files — changes how you interact with them. It's easier to navigate. Easier to spot what's wrong. Easier to give feedback.

Think about it: once you're working with specifications and plans, you want to see them. You want to add a comment on line 12 of a spec where the requirement is unclear. You want to look at the plan and say "this part doesn't match what I had in mind" and regenerate just that section. You want to view diagrams inline instead of switching to a markdown preview.
That feedback loop — review, comment, regenerate — is what turns spec-driven development from a process into a conversation.

Even creating a spec is better with a visual interface. You can write a detailed description, point to existing files for context, and attach screenshots — all in one place.

But Kiro is a full IDE. I wanted that same visual experience for any AI coding assistant — Claude Code, GitHub Copilot, Gemini CLI — without leaving VS Code. SpecKit Companion was born from that gap: a lightweight extension that adds the visual layer Kiro pioneered, but works with the tools you already use.

Installation

Three steps:

Open VS Code Extensions (Cmd+Shift+X)
Search for "SpecKit Companion"
Click Install

Or go directly to the VS Code Marketplace. Supports macOS, Linux, and WSL.

The Sidebar

The sidebar has two main areas:

Specs — Your Workflow Hub

This is where you spend most of your time. Every specification you create shows up here with its current phase: Specify → Plan → Tasks → Done. Click any spec to open it in the Workflow Editor.

At a glance, you can see how far along each spec is — which ones are still being defined, which have plans ready, and which are fully tasked out and ready for implementation.

Configuration — Steering, Agents, Skills & Hooks

The rest of the sidebar is about context and configuration — everything that shapes how the AI works during your spec-driven workflow:

Steering — Your project rules, constitution, and shared scripts. The guardrails that keep the AI aligned with your codebase conventions.
Agents — Personal and project-level AI personas for specific tasks.
Skills — MCP Servers that extend what the AI can do.
Hooks — Automations triggered by events (Claude Code only).

Think of this area as the control panel. The specs are what you're building. The configuration is how the AI should behave while building it.

The Workflow Editor

The Workflow Editor is where specs come to life. A progress bar at the top shows exactly where you are in the workflow — and a special indicator lets you know when a spec is complete.

Creating a Spec

Hit the "+" button in the sidebar and you're in. Write a detailed description, point to existing files for context, attach screenshots or mockups — whatever helps the AI understand what you're building.

Reviewing with Inline Comments

Here's where the visual interface really pays off. Once a spec or plan is generated, you can add review comments on individual lines — just like a code review. Disagree with a requirement? Comment on it. Think the plan missed something? Flag that specific line.

Based on your comments, you can regenerate the file — the AI uses your feedback to improve that specific section. It's a much faster feedback loop than re-prompting from scratch.

Navigating the Phases

Each phase has its own view. The progress bar at the top highlights where you are, and you advance by clicking the action button at the bottom of each step.

Specify — Your requirements. The what and why. This is the first phase — it activates when you create a new spec. When you're happy with your requirements, click "Generate Plan" to move forward.

Plan — The technical strategy. In spec-kit, this isn't a single file — you get the plan itself, plus research, data models, and a quickstart reference. The editor gives you tabs to navigate between them and can even show you diagrams. When the plan looks right, click "Generate Tasks" to advance.

Tasks — The implementation breakdown. Each task is tracked, and you can see exactly how far along the implementation is. When you're ready, click "Implement Tasks" to kick off implementation.

Done — All phases complete. The progress bar shows four filled circles and the spec is marked as finished.

Beyond the Defaults: Custom Commands & Workflows

SpecKit Companion works great with GitHub spec-kit's built-in workflow. But you're not limited to it.

You can add custom commands that run in any phase of the spec-driven workflow — extending what the defaults offer. And you can create entirely custom workflows for spec-driven development that aren't tied to GitHub spec-kit at all.

This is a deep topic, so I'm covering it separately in other articles:

Custom Workflows in SpecKit Companion — We'll demonstrate how to use another SDD AI workflow with Agent Teams Lite by Gentleman Programming
Build Your Own SDD Workflow — We'll create and customize our own workflow that adapts to our needs.

Getting Started

New to spec-driven development? Stop Vibe Coding, Start Shipping covers the full workflow from zero.

Already using spec-kit? Install SpecKit Companion and open the sidebar — your existing .specify/ specs will show up automatically.

Links:

Build Log 2: Capturing the Whole Lifecycle, and Shipping v1

Alfredo Perez — Mon, 05 Oct 2026 13:24:10 +0000

Build Log 1 proved one link in the chain: a spec-kit after_specify hook writes my state file, and the SpecKit Companion GUI lights up from it. One write. That's a spike, not a product.

The problem shows up the second you do anything past specify. Plan, tasks, implement, none of them are captured, so the moment you move forward, the GUI is showing a half-truth. And it gets worse: spec-kit hooks are agent-mediated. They fire only if the agent runs them. Skip a command, run one out of band, open an old project that never had the extension, and the hook never fires at all. The GUI doesn't just go stale. It goes blind.

So this log has one job: capture the whole lifecycle, and never lie about state, even when a hook didn't fire. When that holds, v1 ships, tracking and resume on any spec-kit project, with zero template changes.

What I built

Three things stacked on each other: the rest of the capture chain, a safety net for when a hook doesn't fire, and the two commands that finally make the captured state useful.

The lifecycle hooks. Build Log 1 had one hook. Now there are four, each backed by a per-step capture command that reuses the same write-context.py writer.

# 📃 speckit-extension/extension.yml
hooks:
  after_specify: { command: speckit.companion.capture, optional: false }
  after_plan: { command: speckit.companion.capture-plan, optional: false } # 👈 new
  after_tasks: { command: speckit.companion.capture-tasks, optional: false } # 👈 new
  after_implement: { command: speckit.companion.capture-implement, optional: false } # 👈 new

Each one appends an entry to history[], the canonical event journal, and advances currentStep and status. (The old name transitions[] is gone. One journal, one name.) Inside implement, each completed - [x] **T###** task gets its own entry, recorded as a substep so the viewer never mistakes a single task for the whole step finishing.

The derive-from-files fallback. This is the part that earns "never lie." derive-from-files.py is a stdlib reader that reconstructs history[] from the artifacts already on disk, spec.md, plan.md, tasks.md, and which task markers are checked, plus git history, when no hook ever fired. Same no-backward-clobber guard as the live path, tagged by: "derive" so you can tell reconstructed state from captured state. Delete the state file, or run on a project that never touched the extension, and the GUI still reflects reality.

Status and resume. Two commands turn all that captured state into something you actually use:

/speckit.companion.status reads the canonical file (or derives it on a miss) and prints the current step, status, recorded decisions, and the next action.
/speckit.companion.resume picks up at the next unchecked task, carries the recorded decisions[] back into scope, and dispatches the next /speckit.* command.

The Companion sidebar surfaces the same data: the SPECS tree lists every active spec with its current step, refreshed live by the watcher that was already there.

Here's that tree in the sidebar:

Spec 131 sits expanded to its three finished steps, updated by the watcher without a manual refresh.

That's v1. Tracking plus resume on any spec-kit project, no template change. Open a tracked spec and the whole journal renders: each phase with its real duration, every task with the one-line summary it wrote as it landed.

Here's that full render for spec 131:

Four phases with their real durations up top, then the T001 through T004 substeps below, each carrying the one-line summary it wrote as it finished.

Does it actually work?

Start with the easy half: the deterministic tests. The capture layer ships 12 stdlib tests, append-only history, no-backward-clobber, unknown-key preservation, per-task idempotency, a full derive round-trip. Status and resume add 25 more Python resolver tests and 354 green Jest tests on the GUI side. All passing.

The interesting part is that I wrote an eval, and the eval caught capture lying.

eval-speckit-extension is a re-runnable checker: it asserts the journal is well-formed, the timestamps are monotonic and not backfilled, and the per-task substeps line up with tasks.md. It also prints a timing breakdown, and that breakdown is what blew the whistle. Here's one of my own specs after a full implement run:

# 👇 spec 130 — every task stamped at the same instant, by the hook
implement T001 … T024   by: extension   at: 2026-06-07T23:27:31.648Z
  cadence: BURST — 24 task substeps, 0ms span   ✗

Twenty-four tasks, one timestamp, all written by: extension. The capture said all 24 ran, but with zero time between them. The journal looked complete and was quietly meaningless. The root cause is structural: the after_implement hook fires once, at the end of the step. A hook physically cannot produce cadence inside a step it only sees the end of.

So the fix moves the cadence source out of the hook and into the implement preamble. The idea: have the AI journal each task the moment it finishes, authored by: "ai" with a real timestamp, instead of letting one hook stamp them all at the end.

// 📃 .spec-context.json — a live per-task entry, now written by the AI (spec 131)
{
  "step": "implement",
  "substep": "T004",
  "task": "T004",
  "kind": "start",
  "by": "ai",
  "at": "2026-06-08T11:29:35Z"
}

Because each live entry carries its task id, the old hook's task-sync dedupes against them and degrades to a no-op backstop. If the AI skips the journaling, the hook still records everything. Strictly better, never worse.

Here's the honest part: it isn't fixed yet. I re-ran the eval on the next spec, and it refused to sign off:

✗ [FAIL] timestamps-real: 10/16 look hand-typed (round ms) — capture may be backfilled, not live
✓ [PASS] per-task-substeps: 4 task events; substep==task: True
· [INFO] task-cadence: 4 tasks; gaps 0ms, 0ms, 39.0s
→ 12 pass / 1 fail / 4 info

The entries are by: "ai" now, which is the structural win. But on a small, fast spec the AI still batched three of them at one timestamp, and those round-second stamps look backfilled, not live. The burst isn't gone. It's smaller.

And that's the actual point of this beat. I shipped the capture, the fallback, and an eval whose entire job is to refuse the story I want to tell. It caught the original 24-task 0ms burst, and it's still catching the residual one. The cadence quality is a known bug, tracked in the backlog, not hand-waved away in the journal. A state engine that lies confidently is worse than one that admits it isn't done.

Here's what the eval saw before and after the fix:

On the left, all 24 tasks pile onto one instant; on the right the AI-authored entries spread out, but three still stack up, and the eval circles exactly those.

The other two proofs are quieter but matter just as much. Delete .spec-context.json on a real spec and derive-from-files.py rebuilds the right step and status from the artifacts and git alone. And /speckit.companion.status reads that journal, or the derived one, and tells you exactly where a spec sits:

$ /speckit.companion.status
Spec: Fix Opencode Prompt Flag   (source: state)
Step: implement   Status: implemented
Decisions: (none recorded)
Next: Pipeline complete  →  —

Its sibling, /speckit.companion.resume, reads that same resolved state, carries the recorded decisions[] into scope, and dispatches the next /speckit.* command, or refuses to invent one when the pipeline is already done. I pointed it at the spec above, which had finished every step:

$ /speckit.companion.resume
The resolution is complete: true.
Pipeline complete — nothing to resume.

That's the terminal branch doing exactly the right thing: read the journal, resolve complete: true, dispatch nothing. It's the unglamorous half of resume, but it's the half that keeps the command from running a finished spec off a cliff. The interesting half, resume re-entering a half-done pipeline and firing the next command, is covered by the 25 resolver tests today, and it earns a proper walkthrough rather than a footnote here. So that gets its own log.

And the final proof is the one I'd been putting off: installing it the way a stranger would. Not the dev symlink I'd been dogfooding all along, but the real thing, specify extension add companion --from <release.zip> off a public GitHub release. Then I ran /speckit.specify on a fresh feature and watched the release-installed hook write the file itself:

// 📃 specs/131-fix-opencode-prompt-flag/.spec-context.json — written by the release-installed extension
{
  "step": "specify",
  "kind": "start",
  "from": { "step": null },
  "by": "extension",
  "at": "2026-06-08T02:09:08.437Z"
}

by: "extension" means the hook fired, not a manual write; the ms-precision timestamp means it fired live, at the moment specify ran, not backfilled later. The same canonical history[], the same writer, but emitted by a copy of the extension that came down the wire from a release archive. That's the line between "works on my machine" and "works." v1 ships.

Why I built it this way

A few choices I'd defend to anyone copying this:

Reuse the hook mechanism for every lifecycle event. No daemon, no file watcher polling for changes. It rides spec-kit's own prompt-driven execution, the same machinery Build Log 1 already proved.
Derive-from-files is a first-class capture path, not a gap-filler. Hooks are best-effort by design. The fallback means the GUI reflects reality even on a project that never ran the extension. State you can't trust is worse than no state.
Status and resume are thin readers over the one canonical file. No second source of truth to drift out of sync.
Resume dispatches the already-installed /speckit.* commands, not a specify workflow resume CLI. The backlog assumed a >=0.8.5 subcommand, but my workspace runs 0.7.4.dev0. Binding resume to a subcommand that might not exist would break on exactly the stock installs v1 is supposed to support. Dispatching what's already there works everywhere.
Capture and status/resume stay always-on. They're the v1 core the GUI reads from. The differentiator features, the lean preset, complexity, drift, auto mode, agent teams, all come later and ship opt-out. The thing that tracks your work shouldn't be a setting.

What's next

v1 is the boundary this log climbs to: install the Companion on any spec-kit project and get tracking plus resume on your existing flow, no template change. From here the posts stop being plumbing and start being the SDD opinion.

Two things I'm deliberately carrying forward. The cadence still bursts on fast specs, and the eval won't let me forget it. And resume deserves to be shown re-entering a live pipeline, not described. Both get their own treatment next, alongside Build Log 3: the SDD shape, the sdd-lean preset that overrides the templates, and a complexity fast-path that right-sizes the ceremony so a one-line change doesn't drag the full pipeline behind it.

The public backlog tracks every step as it merges. Watch the repo, and I'll see you at the next one.

Angular Best Practices for AI

Alfredo Perez — Mon, 05 Oct 2026 13:23:38 +0000

If you've been using AI to write Angular code, you've probably noticed a pattern. Your agent keeps making the same mistakes. It writes sequential async calls that create request waterfalls. It eagerly loads routes that should be lazy. It misuses signals in ways that thrash change detection. The code compiles, it runs, but it's not how you'd write it.

AI agents are great at Angular syntax, but they don't have the context of what "good" Angular looks like in production. They're missing the best practices that experienced developers carry around in their heads.

When I saw Vercel's react-best-practices announcement, I realized this is exactly what Angular needs. A curated set of rules you can share with your AI agent and with other developers. But I also wanted something the community could contribute to and make better over time, not just a static list that one person maintains.

So I built Angular Best Practices, a curated rules package that teaches your AI coding agent how to write better Angular code. It works with Claude Code, Cursor, Codex, VS Code Copilot, and 30+ more agents.

npx skills add alfredoperez/angular-best-practices

What Is It?

Angular Best Practices is a skills package built on the Agent Skills specification. You install it, and your AI agent immediately gets access to curated Angular rules covering everything from eliminating request waterfalls and bundle optimization to signals, RxJS patterns, change detection, SSR, testing, and architecture.

One thing I noticed when rules are AI-generated: they tend to include long code examples with poor context. That wastes tokens and bloats your agent's context window. Every rule in this package is human-reviewed for accuracy and token efficiency. Each rule is under 50 lines with one to three line code examples. Every rule shows a clear incorrect vs correct pattern so the AI knows exactly what to change, not just what to aim for. They're tagged by impact (CRITICAL, HIGH, MEDIUM, or LOW) so the most important ones get applied first.

Pick What You Need

I didn't want to split every little aspect of Angular into its own package. If you look at the rules/ folder in the repo, you'll see every rule divided by topic: signals, components, RxJS, change detection, and so on. But when you install the core package, it all comes together as a single file. If you use Angular, this is the one you want:

npx skills add alfredoperez/angular-best-practices

Where it does make sense to split is at the library level. State management libraries, component libraries, testing libraries—these are different for every project. My plan is to have best practices for each one as a separate package, so you just pick whatever you actually have installed:

npx skills add alfredoperez/angular-best-practices-ngrx
npx skills add alfredoperez/angular-best-practices-signalstore
npx skills add alfredoperez/angular-best-practices-tanstack

If you prefer manual installation, copy the AGENTS.md file directly into your project: .claude/AGENTS.md for Claude Code, .cursor/rules/angular.md for Cursor, or .github/copilot-instructions.md for VS Code Copilot.

Explore the Rules

Before installing anything, browse all the rules on the web app at angular-best-practices-web.vercel.app. Check out the categories, read through the code examples, and see if there's something you'd want to use right away—or if there's a rule you think is missing.

Want a Rule Added?

This is an open source project. If you want a rule added, create a request on GitHub—that's it. Rules follow a simple template: a short description, an incorrect pattern, and the correct one, all under 50 lines. Every submission gets human-reviewed for accuracy and token efficiency before it's merged.

Get Started

npx skills add alfredoperez/angular-best-practices

Check out the GitHub repo, browse the rules at angular-best-practices-web.vercel.app, and let me know what you think. Next time your AI agent tries to nest three subscriptions deep, it'll know better.

Give Spec Kit Superpowers

Alfredo Perez — Mon, 05 Oct 2026 13:23:13 +0000

Spec-driven development is the habit of making the AI agent write down what it's going to build before it builds it. GitHub's Spec Kit is the tool a lot of people use for that: one command per phase, specify, plan, tasks, implement, and each phase lands as a markdown file in your repo.

If you've run a feature or two through it, you know the part that's hard to hold in your head. Here's what a single run leaves behind, phase by phase, with the side commands you can call in between.

When it finishes, you're the one who has to work out which of those files says what actually happened. The files are all there, but nothing puts them together for you.

Kiro showed that putting the specs in a panel beside the code, instead of in a folder you open by hand, makes the whole thing easier to follow.

Image: Kiro's launch post.

Spec Kit deserves the same, and that's what SpecKit Companion is. It's a VS Code extension that reads what Spec Kit writes and turns it into one page per spec: what the run was for, what it checked, what it decided, and what's left. It also changes the run itself, with a shorter pipeline for small changes, specs that stay current after a feature ships, and a pipeline you can rearrange.

The files never stop being markdown, and that's what makes this work: the agent creates and edits them fast because they're plain text, and Companion is a better way to read the same files.

Install both halves

Companion comes in two parts, and it helps to know which is which before you install. The VS Code extension is the part you look at. The spec-kit extension installs into Spec Kit itself and runs on the command line: it records the run, sizes the pipeline to the change, and keeps living specs up to date. The VS Code side reads what the command-line side writes to a plain .spec-context.json in each spec folder. Neither needs the other, but the tour below assumes both.

The VS Code extension comes from the Marketplace: search for SpecKit Companion in VS Code and install it. The spec-kit extension is a separate step, and it's the one that turns on traceability, fast mode, auto mode, living specs, and custom workflows.

specify extension add companion --from https://github.com/alfredoperez/speckit-companion/releases/download/companion-latest/companion.zip --force

Spec Kit asks you to confirm before it installs from a URL instead of its catalog, so answer y at the prompt. Here's what both halves look like once they're in.

Open a repo that already has a .specify folder and the sidebar fills in.

Start on the Overview

The first thing Companion gives you is the Overview. Every spec with recorded activity gets one page that says what the run was for and what it actually did, and that's where the spec opens.

Here's why it matters. A run in stock Spec Kit produces seven artifacts across four phases. To know whether any of it happened the way you intended, you read all of them, and in practice nobody does.

I'll use one finished spec, a profile photo upload, for every screenshot below, so you're never decoding a new feature between sections. Here is what the page holds, top to bottom, and why each part earned its place.

Why the spec exists, and how the run went

The first thing you read is the reason the spec exists, written as a sentence rather than a feature name. Under it sits the run rail with the four phases, how long each took, and the total, and then a card with the approach in two lines, the area of the codebase it worked in, the size verdict that decided how much pipeline it got, and the living specs it loaded and folded back into.

This block is the answer to "what is this spec and is it relevant to me". When I come back months later, that's the whole question, and it takes a few seconds here instead of four files.

The fence around the work

This part is two lists: what must stay true no matter how the feature is built, and what was deliberately put out of scope. The second list is the one that saves arguments later. When someone asks why the uploader doesn't crop, the answer is on the page, dated, and it was a choice.

What was checked, and what happened

This is every check the run made, split in two. On top are the checks the pipeline ran itself: the command, the exit code, and how long it took. Below them is anything the run only reported, like a manual pass on a phone, shown quieter so it can't pass for proof. If a check failed, it sits here with its exit code, not buried in a terminal scrollback that closed with the session.

This is the part I trust most. A spec can describe anything, and so can an agent summarizing its own work. A row with an exit code is harder to be wrong about.

Choices future work should not have to rediscover

The rejected alternatives are more important than they sound. A decision alone tells you what was decided. A decision with what it rejected tells you the consequences were considered, and it stops the next person, or the next agent, from proposing the rejected option as if it were new.

Requirement to task to test

A requirement with no test shows up as a gap, which is the cheapest moment to notice. The run log and the per-task records fold away under it for when you want the blow-by-blow.

And while it runs

The same spec is what I watch while a run is going. The pipeline across the top unlocks phase by phase, tasks tick over while implement runs, and one button always offers the next step. When it settles, the Overview above is what's left behind.

Read the spec, not the markdown

Click into any artifact and the viewer takes the plain markdown the agent wrote and renders it as something you can scan: user stories become cards, requirements become labeled rows, acceptance scenarios read as Given, When, Then lines, tasks sit under their phase with a badge for their state, and Mermaid diagrams render inline. The file underneath doesn't change. What changes is that you can find the one requirement you care about without reading the ones around it.

Two things make this more than pretty markdown. The first is that any file the spec mentions is a link. When the plan says the route lives in avatar.ts, you click it and the file opens beside the plan.

The second is that you're in VS Code, so the spec sits beside the code it describes and the git changes the run produced. With the diff next to it, you read the plan against what actually changed instead of on its own, and that's where a plan that says one thing while the code does another shows up.

Review the spec where it is written

The part I use most is that you can review the artifacts and talk to the spec right there, without going back to the chat to prompt each correction. Every rendered row takes a comment, the way a line in a pull request does.

Here's what those comments usually catch. The agent reads the code near where it's working, picks up a pattern that lives there, and treats it as the house style, when it's often a shortcut someone took in March. The plan proposes a component that's fine for this feature and not reusable for the next one. Or it read a requirement wrong. In the raw markdown those lines look like every other line. In the viewer they're rows you can point at.

The alternative is what I did first: type the correction into the chat. "The service in the plan, around the middle, should use the shared client, and the component should not be one-off." Then hope the model finds the lines you meant, and fixes both without touching anything else. Two corrections in one prompt is already a coin flip.

I comment on each thing, exactly like a pull request review, then hit Refine once. Here's what the agent receives when I do.

Each comment arrives with the exact line it's about, and the instruction is to edit the file in place rather than regenerate it. The spec comes back corrected, and often with tasks added: a step that applies the pattern I actually want, or a check that keeps the mistake from coming back. The model decides the extent. A one-word comment reworks a sentence, and a paragraph reconsiders the section.

Comments are saved as you type and committed with the repo, so a review you abandon on Friday is still there on Monday, or on the other machine. Some comments never go to the agent at all. They stay as notes for whoever reads the spec next.

Work from the sidebar

The sidebar has three areas, and each one answers a different question.

Specs are grouped by lifecycle, with live status per document. You can sort, filter by status, and mark specs complete or archived so only the open ones show.

I don't like working several features at once, so most days that filter shows one or two. What it's built for is the other mode: plan several features, let them run in auto mode, and come back to review all of them from one list. Hover a spec and it offers to resume where it left off.

See what stays true

Feature specs describe one change and then go quiet. Living specs are one per capability, like checkout, auth, or billing. They're loaded into the agent's context when a feature touches that area and brought up to date when the feature ships. I wrote up why in I Wrote 238 Specs and Never Read One Again.

The sidebar's Living Specs area opens each one as a list of requirements.

A living spec holds what the capability must do, as requirements with scenarios, plus the paths it covers. When a feature run touches that area, the spec is loaded before the agent reads code, and when the feature ships, what changed is folded back into it. The feature spec stays as the record of the run, and the living spec is the record of what is true.

Each requirement is a card, and its left edge tells you where it stands: confirmed, adopted and waiting for you to confirm it, or drifted because the code changed. Each capability shows its test coverage, and the drift flag appears the moment its source files change without the spec following. Comments and Refine work here the same way they do on a feature spec. Open any source file and the status bar says how many living specs describe it, one click from the requirement. That's the answer to the question a folder of feature specs can't answer: is this still true?

See the pipeline your project runs

Spec-driven development only works for a team if the workflow fits the team. Yours might want a security review after the plan, a different task template, or no checklist at all. When the pipeline can't bend, people route around it, and then the specs stop meaning anything. So Companion lets you change the pipeline, and the Pipeline Builder is where you see what you changed.

The steps are columns in run order. Inside each step you see its phases, the nodes in them, and the hooks your project attached before or after.

Anything your project changed carries the same color: a hook you added, a node you rewrote, a template section you replaced. Nothing else gets that color, so when someone asks what your team does differently, you can answer by looking. You can build from the same panel too, and if companion.yml is newer than the commands built from it, the header tells you.

What changes in the run itself

Companion isn't only a better way to look at the files. It also adds new ways to run Spec Kit, so the workflow fits how you actually work. Each of these gets its own piece:

Fast mode reads the size of a change and folds the pipeline for small ones, so a renamed button doesn't get the full ceremony.
Auto mode runs specify to implement without stopping, which is how I plan several features and review them together.
Living specs, adopted on a repo you already have, with drift detection and sync.
Custom workflows: your own steps, hooks, and node order, from one file. The earlier versions of that idea are in Build Your Own SDD Workflow and Custom Workflows in SpecKit Companion.

Try it

Install the VS Code extension from the Marketplace, and the spec-kit extension with the command above.
Open a repo with a .specify folder.
Read the Overview before anything else.

Docs and install links are at speckit-companion.dev.

Next up: how I plan several features at once, run them in auto mode, and review the whole batch from the sidebar.

I Wrote 238 Specs and Never Read One Again

Alfredo Perez — Fri, 11 Sep 2026 15:02:05 +0000

Nine months ago I started building a VS Code extension in the open, and I ran every change in it through spec-driven development.

The tool underneath is GitHub's spec-kit. The idea is simple: before the AI agent writes any code, you make it write down what it's building. A feature moves through four phases, specify, plan, tasks, and implement, and each one lands as a markdown file committed to the repo. You review the spec instead of reviewing the two hundred lines of code that would have come out of misreading it.

My project is SpecKit Companion. It sits on top of spec-kit and shows you those specs while they're being written, so you can catch a wrong requirement before it becomes a wrong implementation.

The repo now contains 94 spec folders, 238 markdown files, and 15,225 lines of specification.

I haven't reopened a single one since it was marked complete.

That's not laziness. It's the honest result of doing spec-driven development on something real for long enough. I stopped believing the folder had answers in it somewhere around spec forty, and I never went back. The specs folder had become a write-only place: somewhere things go, not somewhere anyone reads.

Spec-driven development is what created that problem. It shouldn't be that way.

What spec-kit gets right

Give GitHub's spec-kit its due, because the part it owns is the hard part.

It forces the decision onto paper before the code exists. I wrote up that whole loop in Stop Vibe Coding, Start Shipping. Specify, plan, tasks, implement, and each phase pulls something out of your head that you would otherwise leave implicit and find it later, usually while debugging. A vague requirement dies at the specify step, rather than becoming two hundred lines of wrong implementation.

That worked. That is why there are 94 of them.

What no one talks about is what 94 completed specs do to a repository.

Specs don't just accumulate. They start to lie.

Developing SpecKit Companion was not a straightforward series of new features. It was rewrites, refactors, and reversals: decisions I made in March and undid in June.

Let's take one concrete thread, how a task gets marked complete, how the time it took gets tracked. I've iterated that many many times. Each iteration had its own spec, its own acceptance criteria, its own functional requirements, its own record of what I believed at the time.

So when I go looking for "how does task completion actually work", there's no answer in that folder. Five specs touch it. Four are superseded. None of them says which.

That's the piece that is lost when people talk about spec-driven development. A spec is a moment's snapshot of intent. Snapshots don't update. Put 94 of them in a folder and you don't have documentation, you have an archaeological site, and every layer contradicts the one above it.

The first fix was the obvious one: pull out the durable parts into docs/. That worked for a month or so. Then the docs drifted too, because a hand-maintained abstraction has exactly the same problem plus a second place to look. Now I'm moving away from that.

The part I got wrong

I figured the problem of all this was mine. I couldn't find things, so I stopped looking, and I treated that as a personal organization issue.

Then I looked at what my agent was doing.

Before living specs, when I asked Claude to work on a feature, it read the codebase. Not the specs. The code, plus whatever scattered documents it could find, reconstructing intent from implementation every single session. 94 specs sat right there in the repo, describing exactly what it was working out from scratch, and it went around them.

Of course it did. I would have done the same. Faced with 238 files, which ones are current? You don't know. The rational move is to read the code.

So the folder wasn't just unread by me. It was unread by the machine that wrote it.

Here's the line I'd put on a wall: a spec that nothing reads isn't documentation, it's exhaust.

Once I saw it that way, the question had a different shape. It moved from "how do I organize my specs" to "what does the agent load before it starts."

There are two extensions, and only one of them is a GUI

Before we get to the mechanism, a clarification is needed, as this is the single most common misunderstanding about SpecKit Companion, and it matters for everything below.

It reads as a VS Code thing. It isn't.

The VS Code extension is the GUI. The sidebar, per-spec status, the pipeline rail, the Resume button, inline review. It's the half you look at.

The spec-kit extension installs into spec-kit itself and runs on the command line. It records the lifecycle, right-sizes the pipeline, assembles commands from nodes, and extracts living specs. There's no editor involved.

Neither half depends on the other. The command-line half writes a plain .spec-context.json into each spec directory, and the GUI reads that. That file is the entire handoff, and it's an ordinary JSON, so anything else can read it too.

Which means: the command-line part generates living specs, drift detection, and the run record. And if you never open VS Code, you get all of them.

I'll take the blame for the confusion. I started with the GUI and the product outgrew it, and the naming is still a reflection of that history. While we are here, one asymmetry is worth stating plainly: the GUI doesn't support every AI provider yet. The spec-kit extension does, matching stock spec-kit's set.

Living specs invert the read order

A living spec is one spec per capability, not one spec per change. Checkout. Auth. Billing. In this repo: core, spec viewer, AI providers, and eleven more. 238 files and 15,225 lines of feature specs become 14 files and 3,112 lines.

The feature specs went nowhere. They got relegated. They're the artifacts of the work now, the record of what happened during a run, not the record of what's true. That distinction is the whole point.

The extraction step is what makes it work, and it isn't a copy. When a feature ships, the extraction compares the living spec to the code and reconciles both, so what lands is what the code actually does, not what the feature spec hoped it would do.

Then the read order reverses. The agent loads the living spec first, and reads code only to discover where the capability lives, not to discover what it does.

Here's the portable version of that: when I build the next feature without any spec-kit, in a plain prompt, the living specs still answer what the capability needs. They are not tied to the workflow that created them.

You can store them centrally in a capabilities folder, or colocated with the code they describe. One reversible command lets you flip between them.

Four questions that follow

Once specs are readable again, four things you couldn't ask before become askable.

Are they still true?

Companion commands update living specs. Work done outside Companion, a quick fix in a plain prompt on a Friday, leaves requirements that nothing recorded.

That's where drift detection comes in. It flags which capability's source files have been changed since its spec was last committed. Then the repair command rereads the actual code changes, compares them to the living spec and adjusts it.

You turn it on repo by repo, it just adds to a spec, and a flag never stops a run. Drift is information, not a gate.

Can I verify one run?

The intent, approach, decisions and requirements are distributed across seven artifacts and four phases. You have to read all of them to know if any of it was ever fulfilled. Nobody does.

The Overview is a single page that answers why the spec exists, its constraints, the decisions made and alternatives rejected, each verified check and the command that proves it, and a requirement-to-test coverage table.

The rejected alternatives are more important than they sound. A decision tells you only what was decided. A decision with its rejected alternatives tells you the consequences were considered.

Months later, this is the page that tells you in about ten seconds if a spec is even relevant to what you're looking for.

How do I correct one?

The old way was to type out the correction: "Remember that new service to use, at about line forty, that should be different". Then hope the model gets the line you meant and good luck trying to fix multiple things at the same time.

Inline review comments are the pull request review you already know. Read the artifact, comment on the specific line, hit refine, and the pending comments go to AI as an in-place edit of the source. The model determines the extent: reword the artifact or reconsider that one line.

There is a second use which I did not design, which came from a user. Some comments aren't even directed at the AI. These are notes of why a decision was taken, left for the next person reading the spec. They never leave.

I am more likely to give up on reviews halfway than to finish them. Comments are saved as you type and committed with the repo. Next session, the half-done one is still there or on the other machine.

Does a renamed button need all of this?

Here's stock spec-kit's honest failure. Every change goes through the full pipeline, so every change is a decision to use spec-kit or not. You touch two files, and go for a simple prompt.

I run into this all the time with little things. Moving a button in the sidebar. Adding a context menu item. Renaming something.

Fast mode detects the change and folds the pipeline for the small ones. But the reason I'm still running the pipeline for a renamed button isn't what you'd think. My workflow is already review, open the PR, wait for it, merge. Not doing the pipeline means hand-prompting all four of those over and over.

It composes with auto mode. For a small change I don't need to review the spec, the plan, and the design. It goes from issue link to PR without stopping, and fast mode makes it quick, not ceremonial.

The measured version, from a benchmark across both workflows: Companion specs are approximately 60 to 68% leaner and write no throw-away side files at any size. Correctness was tied, with every cell in both workflows shipping a passing build against an all-green regression suite and scored 5.0 out of 5 on an independent-judge rubric. Ceremony is the variable, not whether the feature works.

Where it still loses

The two-extension confusion above is the real adoption cost, and I haven't solved it, only explained it.

Living specs adoption on an existing codebase is the part I'm least sure of. There's a brownfield adoption path, but it needs more feedback than it's had. Usage is nowhere near OpenSpec's, and I don't have enough signal yet to know which parts of it are wrong.

The customization claim needs an honest edge too. Every part of the process is configurable: the steps, the templates, the artifacts, the hooks, which skills attach where. I built that deliberately, because every SDD framework I tried boxed me into its own commands, and I walked through building one from scratch in Build Your Own SDD Workflow and Custom Workflows. But everything being configurable means there's more to configure, and the default path has to be good enough that most people never touch it. I'm not certain it is yet.

What I'd take from this

The useful question in spec-driven development is not how much spec you write. It's what gets read later, and by whom.

94 specs nobody opened taught me less than 14 that get loaded every session.

Both halves are useful, and they work better together, and the docs are at speckit-companion.dev, if you want to try them out in your own repo.

I cut three threads to keep this one readable: adopting living specs on an existing codebase, what the fast-mode short circuit actually decides, and running auto mode end to end. Each is a separate piece and I'll write them up next.