Customization — Make the Workflow Your Own

Learning objectives

By the end of this module, you will be able to:

1. Pick the right building block — extension, preset, project-local override, workflow, or bundle — for a customization.
2. Predict which layer supplies a template, and confirm it with specify preset resolve.
3. Explain why a template change applies on the next run but a command change only on install.
4. Evaluate a component before installing it, using specify bundle info and each catalog’s install policy.
5. Reshape SPECTRA’s documents with a template override and move them with the Artifact root: line — without touching .specify/extensions/.
6. Avoid shadowed templates, processes with no templates, and preset stacks nobody can explain.

1.Why customize at all

Everything you have run so far — the SDD loop, idea assessment, the bug workflow — is one of Spec Kit’s first-party processes, and Spec Kit calls them starting points, not limits. Your team has standards the defaults know nothing about: an accessibility bar, a security review, a house format for decision records, a rule about where documents live.

Two tempting ways to get those standards into the agent’s output both fail. Asking every time works until the person who cares goes on holiday. Editing the installed files works until the next update replaces them.

The supported path is to encode the standard once, in a layer the tools already read, and commit it. The constitution says what must be true of the work; a template says what every document must contain. Neither removes a human gate: a customization changes what the agent drafts, and people still decide whether the draft is right.

2.Five building blocks, and when to use each

Spec Kit gives you five ways to change the workflow, and each answers a different kind of goal.

A quick way to hold it: a new verb is an extension; a different shape is a preset (many repositories) or an override (this one); a sequence is a workflow; the whole kit is a bundle.

3.How Spec Kit decides which template wins

When a command needs a template, Spec Kit looks through four layers, top to bottom, and uses the first match:

3.1 Each file is resolved on its own

Your specs can come from a project override while your plans come from core and your ADRs from SPECTRA. To see which layer supplies a file, ask:

specify preset resolve spec-template

It prints the winning path and its layer — (top layer from: core) in a fresh project, (top layer from: project override) once you add your own copy. Despite its name, it traces the whole stack, extensions included.

3.2 Templates resolve when used; commands are written at install time

/speckit-specify reads whichever spec template the stack resolves at that moment, so a template override applies on the very next run — no reinstall, no restart.

Commands are different. Installing or removing an extension or preset writes the effective command files into your agent’s directory (for Claude Code, .claude/skills/), and the agent runs those files without walking the stack again. So a command override takes effect when components are installed or reconciled, not live. If you changed a command and nothing happened, check that first.

3.3 Removing a layer restores the one below

There is nothing to reset. Delete your override, or remove a preset, and the next layer down supplies the file again.

4.Presets, workflows, bundles — and whom to trust

4.1 Presets: priority and composition

A preset overrides templates and commands supplied by core and by installed extensions. Browse with specify preset search, inspect with specify preset info <id>, install with specify preset add <id>.

Presets stack by priority — 10 by default, and the lower number wins. Install a compliance preset with --priority 5 and a style preset at the default, and compliance wins for any file both provide. specify preset list prints presets winner first; set-priority reorders them.

By default a preset’s file replaces the lower layer’s. A preset can instead prepend or append its content to the lower layer’s, or wrap it, using a {CORE_TEMPLATE} placeholder where the lower layer’s content goes. Those three let a preset add to a template without forking it, so upstream improvements still reach you.

4.2 Workflows and overlays, in brief

A workflow chains commands, prompts, shell steps, and human gates into a run that can pause and resume. specify workflow list shows what is installed — typically Spec Kit’s built-in speckit workflow — and run, status, and resume drive one. To change an installed workflow without editing it, add an overlay: a small YAML file that edits its steps (replace a gate, insert a lint step), registered with specify workflow overlay add <file> --priority <n>. Overlays live under .specify/workflows/overlays/, so they survive workflow updates.

4.3 Bundles: read before you install

A bundle is a versioned bundle.yml that pins extensions, presets, and workflows for a role or team and installs them in one step. It adds no behaviour of its own. Spec Kit ships two first-party bundles, bugfix and assess — orchestrated versions of what you ran in Modules 6 and 5.

specify bundle search           # what exists, with a trust indicator
specify bundle info <id>        # the full expanded component set — read this first
specify bundle install <id>     # only after you have read it

info shows exactly what install would add — every component with its pinned version — plus a verified or community marker. remove takes out only what that bundle contributed. Installing from a catalog needs network access.

4.4 Catalogs and trust

Catalogs are where search and add look. Each is install-allowed or discovery-only: out of the box, Spec Kit’s official catalog allows installs, while its community catalog lets you find components but not install them.

SPECTRA arrives the same way: spectra install registers SPECTRA’s public catalog with --install-allowed and installs the extension from it. That registration in .specify/extension-catalogs.yml takes the place of the built-in list, which is why specify extension search in a SPECTRA project offers only SPECTRA. (Extensions shipped inside Spec Kit, such as bug and assess, still install normally.)

• Community components are maintained independently and not reviewed by Spec Kit’s maintainers. Read the source before installing.
• Never flip a discovery-only catalog to install-allowed to get past the guard — that flag is the vetting boundary.
• In an unfamiliar repository, run specify extension catalog list first. A committed catalog file is not evidence anyone reviewed what it points at.

5.SPECTRA’s customization points

SPECTRA is not a special case. It is an extension, installed from a catalog into .specify/extensions/spectra/, and its document templates sit in layer 3 of the stack. Every SPECTRA document agent resolves its template through that stack, so you customize SPECTRA exactly as you customize Spec Kit.

5.1 Override, commit, and leave the extension alone

Copy the shipped template to .specify/templates/overrides/<name>.md, edit it, and commit it. Every later document of that kind follows your structure, for the whole team, and the override survives specify extension update because it lives outside the extension’s folder. Never edit files under .specify/extensions/: an update replaces them wholesale, and your change goes with them.

5.2 It tells you which template it used — and follows it

Every SPECTRA command reports the template it resolved, by path, because an override that silently failed looks exactly like one that worked. It then follows that template’s sections exactly — same sections, order, and headings. A section you removed stays removed (the command mentions the omission once); a section you added gets filled from what the agent gathered, or says plainly that it has nothing, rather than inventing content.

A template controls shape, not the rules that make a document trustworthy: some invariants stay with each command, such as the impact agent’s citation rule.

5.3 Artifact root: where SPECTRA writes

SPECTRA’s document agents write under docs/ by default (docs/adr/, docs/brd/, …). One line in .specify/memory/constitution.md moves all of them at once:

Artifact root: documents/

The path must be project-relative; a value starting with / or containing .. is rejected. SPECTRA offers this line — the ADR agent does when docs/ looks like a published site source, where an internal decision record would go public — but never writes it into your constitution. You add it; it is your standard. Shape and location are independent: overrides decide one, the artifact root the other.

6.Pitfalls

6.1 One flat overrides folder

Core templates, extension templates, and SPECTRA’s per-category kb-vault templates are all overridden from .specify/templates/overrides/, by file name alone. A kb-vault category named spec, plan, tasks, checklist, or constitution would be shaped by spec-template.md (and so on) — the very file that overrides a core template. Keep category names clear of those five words.

6.2 bug and assess ship no templates

Look inside .specify/extensions/bug/: a README, a manifest, and commands/ — no templates/. The report formats live in the command files, so restyling assessment.md or decision.md takes a command override or a preset, which applies at install time, not on the next run.

6.3 A stack nobody can reason about

Every preset is another layer that might win for some file. With three presets and a few overrides, your spec may come from one layer and your plan from another. Before you debug the agent, ask the stack: specify preset resolve <name> for the file, specify preset list for the order.

6.4 An override is a fork — and only yours until committed

With the default replace behaviour your copy wins outright, including over later improvements to the shipped template. After updating, diff your override against its source:

diff .specify/extensions/spectra/templates/adr-template.md .specify/templates/overrides/adr-template.md

And an override works locally the moment you save it, which makes it easy to forget that nobody else has it until it is committed.

Lab — make your Module 4 project your own

You will override Spec Kit’s spec template, reshape SPECTRA’s ADRs, move where SPECTRA writes, and inspect a bundle without installing it (about 45 minutes). Start from a clean tree so every change shows up as a reviewable diff:

cd ~/sdd-brownfield-lab/lab-codebase    # or wherever your Module 4 project lives
git status                              # commit or stash anything left from Module 4

7.See the layers (3 min)

specify preset resolve spec-template
specify preset resolve adr-template

You should see something like this (long paths wrap):

  spec-template:
…/lab-codebase/.specify/templates/spec-template.md
    (top layer from: core)
  adr-template:
…/lab-codebase/.specify/extensions/spectra/templates/adr-template.md
    (top layer from: extension:spectra v<version>)

• The spec template comes from Spec Kit core (layer 4).
• The ADR template comes from the SPECTRA extension (layer 3) — the same stack, one layer up.

8.Add a project override for specs (10 min)

Your team has decided every UI change to the to-do app must state its accessibility behaviour up front. It is a standard for this one project, so a project-local override is the right tool.

8.1 Copy the core template into the override slot

mkdir -p .specify/templates/overrides
cp .specify/templates/spec-template.md .specify/templates/overrides/spec-template.md

8.2 Add a mandatory section

Open the copy and insert this between Success Criteria and Assumptions:

## Accessibility *(mandatory)*

<!--
  ACTION REQUIRED: State how keyboard, screen-reader, and zoom users get the same
  outcome as a mouse user. Each item is a testable behaviour, not implementation.
  No user interface? Write "No user-facing interface" and why.
-->

- **A11Y-001**: [Keyboard: every new control works with the keyboard alone]
- **A11Y-002**: [Screen readers: changes the user needs to know about are announced]
- **A11Y-003**: [Colour: no information is conveyed by colour alone]
- **A11Y-004**: [Readability: WCAG 2.2 AA contrast; layout works at 200% zoom]

The guidance comment is written for the agent: it is the instruction every future spec will be drafted against.

8.3 Confirm the stack sees it

specify preset resolve spec-template

• The path now ends in .specify/templates/overrides/spec-template.md.
• The layer reads (top layer from: project override).

8.4 Specify a tiny change

No reinstall, no restart — /speckit-specify resolves the template when it runs. Keep the change tiny, so the new section is the interesting part:

/speckit-specify Show a count of open (not yet completed) tasks above the list,
for example "3 open". The count updates when a task is added, completed, or deleted.

This creates a new feature folder under specs/ and makes it the active feature. You will not plan or build it; it exists to prove the template.

8.5 Human gate — review the spec

You are the product owner at the Plan gate: approve intent and scope, and check the new section earned its place.

• An Accessibility section sits between Success Criteria and Assumptions, where you put it.
• Each item is a testable statement about the count — not your placeholder echoed back, not “N/A”.
• No implementation crept in: “screen-reader users hear the new count” belongs in the spec; aria-live="polite" belongs in the plan.
• No scope crept in: no filters, no per-day counts.

## Accessibility *(mandatory)*

- **A11Y-001**: The count is information, not a control: it adds no stop to
  the keyboard tab order.
- **A11Y-002**: When the count changes, screen-reader users are told the new
  count without navigating back to it.
- **A11Y-003**: The count is given in words and numbers ("3 open"), never by
  colour or an icon alone.
- **A11Y-004**: The count stays readable at 200% zoom and meets AA contrast.

9.Override a SPECTRA template (10 min)

Your architects want every decision record to say how the decision could be undone. Same mechanism, different layer: this time you shadow an extension’s template.

9.1 Copy SPECTRA’s ADR template

cp .specify/extensions/spectra/templates/adr-template.md .specify/templates/overrides/adr-template.md

9.2 Add a Rollback Plan section

The shipped template has Context, Decision, and Consequences. Add this after Consequences:

## Rollback Plan

<!--
  How would we reverse this decision if it proves wrong? State the signal that
  would trigger reversal, the steps in order, and what happens to data written
  under this decision meanwhile. If reversal is impractical, say so and why.
-->

[Rollback plan]

Guidance comments never reach a finished ADR, so you can leave the copy’s header comment or trim it.

9.3 Record a real decision from Module 4

In Module 4 you settled how due dates are stored and compared — exactly what a later maintainer will want explained. Check that the stack now reports (top layer from: project override), then run the agent:

specify preset resolve adr-template

/speckit-spectra-adr Store each to-do's due date as a date-only ISO string (YYYY-MM-DD)
on the existing Todo record, and compare dates as strings rather than Date objects.

The agent reads the constitution, your specs, and lib/storage.ts, then asks up to five clarifying questions — expect one about rollback, which the codebase cannot answer. It writes docs/adr/ADR-001-<title>.md (a higher number if ADRs already exist) and checks the decision against your constitution.

9.4 Human gate — approve the decision record

This is the Design gate, where architects approve decisions. Today that is you.

• The report names the template it used: .specify/templates/overrides/adr-template.md.
• A Rollback Plan section follows Consequences, and no guidance comment or [placeholder] survived.
• The rollback plan is grounded (the storage format, older tasks saved without a due date) or says plainly what it does not know. Invented detail is a reason to send it back.
• The status is Proposed.
• If the agent recommended a constitution change, you decided on purpose. It edits the constitution only if you agree.

10.Redirect SPECTRA’s output (7 min)

Suppose your organization keeps internal documents in documents/ and reserves docs/ for published material.

10.1 Declare the artifact root

Open .specify/memory/constitution.md and add this line yourself — under a short “Documentation” heading, for example:

Artifact root: documents/

10.2 Record a second decision

/speckit-spectra-adr Keep every to-do in the single existing "todos" localStorage entry;
new features add fields to the Todo record instead of introducing new storage keys.

10.3 What to expect

The ADR command’s own instructions define what happens, so check the run against them:

• It writes to the new root: documents/adr/ADR-002-<title>.md (or your next number).
• The numbering continues across both folders: it still reads docs/adr/ for context and numbering.
• The earlier folder is read-only. Nothing in docs/adr/ is moved or edited. If the new decision supersedes an old one there, the new ADR’s Context says so, and you are told which file to update after you move it.
• It says so once: where ADRs live now, that the earlier folder was left untouched, and a command you can run to consolidate, along the lines of git mv docs/adr/*.md documents/adr/ && rmdir docs/adr. It does not run it.
• Your override still applies — the same template path as in step 9.

Human gate: review this ADR against the step 9.4 checklist.

11.Remove an override and watch the next layer return (2 min)

Park the spec override outside the stack rather than deleting it; you will decide in step 13 whether to keep it:

mv .specify/templates/overrides/spec-template.md spec-template.parked.md
specify preset resolve spec-template

• The spec template is back to (top layer from: core). No reinstall, no reset — the next layer down simply wins again. A command override, by contrast, would change nothing until components were reinstalled or reconciled.

12.Explore the ecosystem without installing (8 min)

These commands need network access. None of them changes your project.

specify extension catalog list
specify extension search
specify preset catalog list
specify preset search
specify bundle search
specify bundle info bugfix

• Extension catalogs: most likely just spectra, install allowed — so extension search here shows SPECTRA alone. Your project decides where discovery looks.
• Preset catalogs are configured separately: Spec Kit’s official (install allowed) and community (discovery only). Some community presets do at organization scale what you did by hand in step 8; specify preset info <id> names the repository to read first.
• Bundles: search marks each entry verified or community; info bugfix expands the first-party bug-fix bundle.

Before opening the answer, note for bugfix: what it adds, who maintains it, whether it is verified, and what it touches that you already have. That is the review you owe any component.

13.Decide what to keep, then commit it (5 min)

git status

You should see the ADR override, the constitution change, two ADRs, the count spec, and the parked spec template. Decide each one:

Check your branch (git branch --show-current) — with the git extension, step 8 may have created a feature branch. Then stage what you kept, by path. If you kept everything and consolidated the ADRs:

git add .specify/templates/overrides/ .specify/memory/constitution.md documents/
git commit -m "Add team template overrides and record due-date storage decisions"

The commit is the point: an override on your machine is a preference; an override in the repository is a team standard every teammate’s agent follows.

Knowledge check

What's next

Module 8 — Best Practices & Pitfalls steps back from the tools to the practice: the habits that consistently make spec-driven development work, the failure modes that sink it, and a critique exercise on deliberately flawed specs. Take one question with you: which of your team’s standards belong in the constitution, and which in a template?