RFC: Specification domains — discipline-appropriate planning vocabulary without forking core templates

[dovich]

Summary

This RFC introduces Specification Domains — a mechanism to decouple spec-kit's planning engine from its default software-centric vocabulary. A domain is a named planning context declared by an extension, establishing a clean upgrade boundary: core spec-kit improvements flow to all users, while domain-specific planning vocabulary evolves where it belongs — in the hands of the practitioners who understand it.

Background / evolution

As spec-kit matures, it is being adopted by multi-disciplinary teams whose deliverables extend beyond the default software delivery model. The embedded software-centric vocabulary — well-suited to the default case — becomes a ceiling for those teams: the planning vocabulary (clarify taxonomy, spec section structure) does not match their discipline's concepts, and any adaptations they make to core templates are overwritten on upgrade. There is currently no mechanism to declare domain-specific customizations in a way that survives a spec-kit core update.

Crucially, the affected teams are not only those working in wholly non-software disciplines. The pattern arises within software teams whose projects include non-software deliverables — design assets, brand collateral, hardware components — where some features belong naturally to the default templates and others do not. This is a consequence of embedding planning vocabulary in core template text rather than in extension-owned files, and it is the natural next problem to solve as the tool reaches broader adoption.

Motivation from practice

Two recent development efforts, each applying spec-kit to work that included non-software deliverables, surface the same category of problem from different directions. They are offered as concrete data points, not as authoritative statements about what any domain requires — the appropriate vocabulary for a given domain is properly the concern of the extension authors and practitioners who build and use it.

Example 1 — Hardware: RISC-V processor implementation

Experience using spec-kit to drive a RISC-V processor implementation from specification through FPGA validation illustrates the mismatch that arises when a non-software discipline uses spec-kit without modification.

Hardware implementation demands high-fidelity planning at every stage — compliance scope, interface contracts, verification coverage, physical constraints — organized around concepts that have no direct analog in a software product taxonomy. The core clarify taxonomy is organized around software product concepts: Functional Scope, Domain & Data Model, Interaction & UX Flow, Integration & External Dependencies. These are well-chosen for software. For a hardware implementation project, the planning questions that arise in practice tend to organize around different axes, and the specific vocabulary varies by subdomain and team; the point is that the structure of what needs to be clarified differs, not just the terminology.

When the taxonomy does not match the discipline, one of two outcomes tends to occur: engineers translate their concerns into the nearest available software category (introducing noise and suppressing domain-specific questions that have no natural home), or they skip the clarify step entirely. The second outcome is the more costly one — the clarify command is among the highest-value steps spec-kit provides, and losing it to vocabulary friction is a meaningful regression.

Template structure presents a similar issue. The spec and plan templates reflect a software delivery lifecycle. A hardware verification workflow has stages whose planning concerns differ from a software release pipeline in ways that affect what sections belong in a plan and what "done" means at each stage — the structural shape of the work differs, not just the labels.

Example 2 — Design system and brand identity

A more recent effort involved developing a design system alongside a brand identity. This project is notable because it is not a non-software project — it is a project a software team owns and delivers, with software and non-software deliverables running in parallel: component libraries, design tokens, and Storybook stories alongside brand mark, typography system, color palette, marketing collateral, and print materials.

The software components map reasonably well to the default spec-kit templates. The non-software components expose the vocabulary mismatch in a different form than hardware does. The clarify taxonomy's categories have meaning in a design context but the relevant questions tend to organize differently. Concerns that arose in practice included things like: what output formats and color profiles are required for each delivery context, how stakeholder approval is structured for brand assets, how production handoff works for print collateral, and what usage constraints apply to brand elements. These are not exotic concerns — they are routine planning questions for design work — but they do not fit comfortably into a software taxonomy.

More significantly, what "done" means differs by deliverable type within the same project. A software component is done when it passes tests and an accessibility audit. A brand asset is done when it is approved by stakeholders and exported in the required formats for each use context. These are not different phases of the same lifecycle; they are parallel workstreams that deserve tracked specifications with structure appropriate to each.

This example adds an important dimension: the problem is not confined to teams doing non-software work. It arises within broadly software-adjacent projects — design systems, branded developer tooling, marketing engineering — that software teams routinely own. When a design-system domain exists alongside a software domain, the entire project stays within the same git-backed planning ecosystem, preventing the fragmentation of intent that results when design work migrates to other tools while software planning remains in spec-kit.

The common structural problem

Both examples surface the same underlying issue. Spec-kit's planning vocabulary — especially the clarify taxonomy, but also template section headings and terminology — is embedded directly in core command template text. When a team adapts these for their domain, their changes live in files that spec-kit owns. A core upgrade overwrites them.

The resulting situation is familiar: teams either freeze their spec-kit version and fall behind on improvements, or upgrade and re-apply their customizations manually each time, or maintain a diverged fork. None of these are sustainable at organizational scale.

Domains address this structurally. A domain extension owns its vocabulary files. Core spec-kit owns its files. The two evolve independently. A core upgrade that does not change a file a domain extension overrides requires no action from the domain extension author. An upgrade that does change such a file produces a known, explicit dependency — the extension's manifest declares which files it overrides, making the surface area visible.

User story / use case

As a team lead adopting spec-kit for a discipline outside the default software delivery context,
I want to install a domain extension maintained by specialists in my discipline that adapts spec-kit's vocabulary to our planning needs,
So that my team gets structured, constitution-backed planning discipline without bending our domain's concepts to fit a software vocabulary — and without giving up spec-kit core improvements as they release.

Design constraints and trade-offs

"Teams can fork the templates directly — no core change needed."

Forking templates is exactly the current practice, and it is the problem being addressed. Forked templates live in files that spec-kit owns and overwrites on upgrade. The upgrade-dependency partition that domains provide is precisely what a fork cannot offer. Domains move the vocabulary into extension-owned files, making the upgrade surface area explicit and manageable.

"The existing extension system handles customization already."

Extensions can add new commands and register hooks, but they cannot intercept or redirect template loading in any core command. specify.md, plan.md, tasks.md, and clarify.md hardcode their template paths in prompt text; there is no interception point. Domains require a small amount of core support — a template resolver called from each command — precisely because the current extension mechanism does not reach template loading. The rest — vocabulary files, domain-specific templates, taxonomy additions — lives entirely in extensions.

"This adds complexity to core spec-kit."

The core-side change is small: a template resolver that maps (domain_id, template_name) to a file path, and a domain selection step at specify entry. For the software domain (the default), the resolver returns the existing core path — no behavioral change for current users. The domain vocabulary itself lives in extensions, not in core. The complexity of supporting any given domain is owned by the domain extension, not by spec-kit core.

"The clarify taxonomy is general enough — teams can adapt mentally."

This is partly true for experienced practitioners. The cost is borne by new team members, by the clarify step's value as a structured prompt (it surfaces questions the team hasn't thought of yet), and by teams in disciplines where the conceptual distance from software vocabulary is large. The taxonomy's value is precisely that it is systematic and complete for its domain. A domain extension that provides a taxonomy appropriate to another discipline extends that value rather than diluting it.

"These use cases are too niche to warrant a core change."

The teams pushing spec-kit into new domains are, by nature, the ones who have adopted it deeply enough to feel its current limits. The two motivating examples span different distances from the software default deliberately: hardware is a discipline-crossing case where the conceptual distance is large, while a design system project is one a software team already owns — the mismatch is narrower but present across a significant portion of the deliverables. Supporting both is not a distraction from spec-kit's core value; it is an investment in the teams most committed to structured planning discipline.

The mechanism is designed to be general. What makes it tractable is that domain vocabulary lives in extensions, not in core — the cost of adding a new domain falls on the extension author, not on spec-kit core.

A secondary observation from the design system example: a single project may naturally call for different domains across different feature types — software domain for component API specs, design-system domain for brand asset specs. That points toward a possible future direction for the mechanism, but is not part of this proposal.

UX sketch

Domain selection is a one-time prompt at the start of /speckit.specify, suppressed when only the default domain is available:

Available planning domains:
  1. software (default)
  2. design-system
  3. hardware

Select domain [1]: _

The selection is recorded in the spec frontmatter and consumed by all downstream commands (plan, tasks, clarify) without further prompting:

**Domain**: hardware

Backward compatibility

Domain support is opt-in by extension installation. A project with no domain extensions installed behaves identically to spec-kit today. The domain: frontmatter key is additive — existing specs without it default to the software domain transparently. Removing a domain extension reverts all commands to the software path with no configuration change.