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.

[mnriem]

Please refer to https://github.github.com/spec-kit/community/walkthroughs.html for publicly available examples of Spec Kit. Note we would love to be able to list more exmples!

[PascalThuet]

Thanks for the link, those community walkthroughs are great, and I can see why they came to mind. I think my proposal is actually adjacent rather than the same thing, so let me try again, more clearly this time.

What I had in mind is upstream artifacts specifically: when a non-trivial feature lands in spec-kit, its specs/<feature>/{spec,plan,tasks}.md lands with it in this repo. Whether maintainers or contributors write them matters less than the fact that they exist in main, where readers can point to them. The community walkthroughs show third parties adopting SDD on their projects, which is awesome, but they live in external repos and can't really demonstrate "the workflow runs on the project that ships it," which is the gap I was trying to close.

If it's useful, PR #2393 (opt-in auth registry) is a concrete example of where this would have paid off: the security model pivoted mid-PR (try-each-provider → opt-in after security review), the AuthProvider ABC was reshaped twice, and roughly ten follow-up commits patched threat-model gaps surfaced in review. None of that is criticism of the PR — it's a hard feature — just an illustration that an explicit threat-model spec and a plan.md listing call-sites upfront would likely have absorbed a lot of that churn.

One thought that might be a cleaner starting point than picking features one by one: adopt a project constitution for spec-kit itself, using the /constitution workflow the repo already ships. That document could codify when SDD applies here (non-trivial scope, ambiguous design, cross-cutting, security/correctness) versus when it doesn't (plumbing, refactors, catalog updates), so it's settled once rather than re-litigated per PR. It would also be the most natural form of dogfooding : the project using its own flagship artifact on itself.

To keep the cost to maintainers low, I'm happy to do the authorship and let review be the only ask on your side:

1. Draft a candidate memory/constitution.md as a PR for review, and/or
2. Draft retroactive specs/auth-registry/{spec,plan,tasks}.md for feat: Config-driven opt-in authentication registry with multi-platform support #2393 as a small proof-of-concept (separate PR, doesn't block anything).

No pressure on cadence or scope, happy to start with whichever feels easier to evaluate, or drop it entirely if it's not a direction you'd want. Just wanted to make sure the original idea was on the table clearly. Thanks again for engaging with this!

[mnriem]

I have no problem if you would try it out and see where it leads. Note that I do look at specs for this repository in a spec forward way. Aka the spec defines the unit of work and once it is done it is historical. I am opting for this perspective for the Spec Kit repository as it is rapidly evolving. Let me know your thoughts!

[PascalThuet]

Thanks ! the "spec-forward / historical-once-shipped" framing actually helps. It removes the main worry about merging specs upstream (maintenance debt against a fast-moving codebase).

That nudges me toward the constitution as the cleanest first step: /constitution is the most on-brand dogfooding artifact spec-kit ships, it's forward-looking by definition, and it settles the meta-question once instead of per-PR.

I'll open an issue to track it and follow up with a PR drafting memory/constitution.md via /constitution, codifying the criteria non-trivial scope, ambiguous design, cross-cutting, security/correctness) plus your spec-forward stance.