Proposal: dogfood Spec-Driven Development on features that warrant it

[PascalThuet]

Context

Spec Kit ships templates (spec.md / plan.md / tasks.md) and a workflow, but the repository itself contains no public example of a non-trivial feature developed end-to-end with that workflow. The only spec.md files in main today live under tests/hooks/ (test fixtures) and templates/commands/ (the templates themselves).

I'm not suggesting every PR be specified — plumbing, refactors, and catalog updates clearly don't need it, and forcing the workflow on them would be theater. I'm also not proposing a fixed cadence ("one per release"): a quota would just push contributors to manufacture artifacts on features that don't need them, which is the worst of both worlds.

The proposal is simpler: when a feature meets the criteria where SDD pays off — non-trivial scope, ambiguous design space, cross-cutting impact, or security/correctness stakes — commit its specs/<feature>/{spec,plan,tasks}.md alongside the code. Sometimes that's two features in a release, sometimes zero. The trigger is the feature's shape, not the calendar.

Engineering benefits

• Real-world reference, not a fixture. Contributors and downstream users get to read a working example, not a toy.
• Surfaces workflow rough edges on actual product work. Bugs and friction points that templates alone can't reveal.
• Forces upstream design decisions. Threat models, contracts, and scope get pinned down before code, instead of being discovered in PR review or post-merge fixes.

Credibility benefits

• Closes the dogfooding gap. A toolkit advocating Spec-Driven Development that doesn't dogfood it is a fair line of criticism, and one that's difficult to rebut today. Even partial, deliberate dogfooding ("we use SDD where it pays off, here's the example, here's where it doesn't") is a stronger answer than no answer.
• Demonstrates honest scope. Dogfooding only where it pays off sends a more credible message than blanket advocacy: SDD is the right tool for features of a certain shape, here's the proof, here's where it stops being worth the cost. That selectivity is itself a credibility signal — it shows the maintainers know the workflow's limits.
• Gives reviewers and adopters a portable artifact. Enterprise teams evaluating SDD can point to a real spec.md from upstream when pitching internally, instead of relying on documentation examples.
• Improves trust signal for new contributors. A populated specs/ directory shows maintainers run on the workflow they ship, which lowers the perceived risk of investing time in learning it.
• Compounds over time. Each dogfooded feature adds a reference spec that doubles as regression evidence: this is how we shipped X, this is what the spec said, this is what shipped. After a handful of features the repo has a small library of real-world examples — a documentation asset competitors won't have.

Concrete candidate: PR #2393

PR #2393 (config-driven opt-in authentication registry) is a textbook fit. Looking at its commit log:

• The security model pivoted mid-PR: the initial implementation was try-each-provider (send credentials by default, fall back), later rewritten as opt-in only after security review ("Security-first redesign: no credentials are sent unless the user explicitly creates auth.json").
• The AuthProvider ABC was reshaped twice during the PR (api_base_url and hosts attributes added then removed).
• Roughly ten follow-up commits patched threat-model gaps that emerged in review: multi-hop redirect token preservation, header-override bypass, host pattern validation, unknown-provider rejection, OAuth2 body URL-encoding, etc.
• The PR also discovered in-flight that IntegrationCatalog and WorkflowCatalog made unauthenticated requests and needed to route through open_url.

A spec.md with explicit threat-model acceptance criteria, a plan.md enumerating call-sites and the AuthProvider contract upfront, and a tasks.md ordering the work — exactly the artifacts SDD is meant to produce — would have either prevented or pre-listed most of those follow-ups, and produced a much cleaner narrative for reviewers.

Proposal to maintainers

Would you be open to dogfooding the workflow on features where it materially helps, with their spec artifacts merged into specs/? Concretely this means agreeing on the rough criteria (non-trivial scope, ambiguous design, cross-cutting or security-sensitive) and letting contributors and maintainers flag candidates as they come up — no quota, no forced rhythm.