feat: Add Spec-Driven Development semantic anchor

[Copilot]

Adds Spec-Driven Development as a new semantic anchor — an approach where software is defined, constrained, and validated through explicit specifications, with specs (not code) as the source of truth.

Changes

• docs/anchors/spec-driven-development.adoc — English anchor covering all core concepts: formalized intent, separation of concerns, traceable capabilities, deterministic execution, continuous verification, contract-first APIs, living specifications
• docs/anchors/spec-driven-development.de.adoc — German translation
• website/public/data/anchors.json — New entry; categories: requirements-engineering + development-workflow; related: bdd-given-when-then, tdd-london-school, domain-driven-design, ears-requirements, property-based-testing
• skill/semantic-anchor-translator/references/catalog.md — Entry added under Requirements Engineering so AI agents can surface this anchor

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Anchor Proposal]: Spec Driven Development</issue_title>
<issue_description>### Proposed Term

Spec Driven Development

Context (Optional)

Spec-Driven Development

An approach where software is defined, constrained, and validated through explicit specifications before and during implementation, with code treated as a direct realization of those specs rather than the source of truth.

Core elements:

Formalized intent: domain concepts, boundaries, invariants, and behaviors are written as structured specifications

Separation of concerns: domain, application, and contracts are defined independently of implementation details

Traceable capabilities: every feature is expressed as a discrete capability with clear inputs, outputs, and rules

Deterministic execution: implementation follows specs without introducing implicit behavior or assumptions

Continuous verification: tests validate conformance to specs, not just code correctness

Outcome: A system where understanding, evolution, and validation are anchored in shared, explicit definitions instead of inferred behavior from code.

Pre-submission Checklist

• I have searched existing anchors and this term is not already included
• This term refers to a well-established concept (not something I invented)</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Anchor Proposal]: Spec Driven Development #348

---

⚡ Quickly spin up Copilot coding agent tasks from anywhere on your macOS or Windows machine with Raycast.

[raifdmueller]

Analysis of Proposed Anchors

Evaluated against the quality criteria: Precise, Rich, Consistent, Attributable.

Summary

PR	Anchor	Tier	Recommendation	Rationale
#354	P.A.R.A. Method	3	⚠️ Discuss	Rich and attributable (Tiago Forte), but knowledge management — not SE methodology. Extends catalog scope.
#355	PERT	2	✅ Accept	Classic estimation technique (1958), precise formula, well-established. Tier 2 is correct — useful but niche.
#356	Spec-Driven Development	3	⚠️ Discuss	Relevant to our workflow doc, but is it an established anchor or an emerging practice? Proponents listed (Swagger, Thoughtworks) are not the originators of the term.
#357	Explicit Contract Surface	3	❌ Reject	Not an established term — it's a combination of existing patterns (ACL, DTOs, contract-first). Proponents listed (Evans, Martin, Fowler) didn't coin this term. Fails "Attributable" criterion.
#358	Vertical Slice Architecture	3	✅ Accept	Well-established (Jimmy Bogard), precise, rich. Tier 3 is justified — complements Clean/Hexagonal Architecture.
#359	GRASP	3	✅ Accept	Classic OO patterns (Craig Larman), 9 well-defined patterns. Tier 3 justified — foundational, widely taught.
#360	KISS	1	⚠️ Discuss	Tier 1 is correctly assigned by Copilot! KISS lacks definition depth — "keep it simple" is a directive, not a methodology. Same problem as YAGNI (also Tier 1). But it's so widely referenced that excluding it feels wrong.

Detailed Analysis

#354 P.A.R.A. Method — ⚠️ Discuss

• Precise: Yes — four clear categories (Projects, Areas, Resources, Archive)
• Rich: Moderate — primarily an organizational framework, less rich than Diataxis
• Consistent: Yes — well-defined by Forte
• Attributable: Yes — Tiago Forte, "Building a Second Brain"
• Concern: Extends catalog beyond SE into personal productivity. Is that in scope?

#355 PERT — ✅ Accept

• Precise: Very — concrete formula (O+4M+P)/6, network diagrams, critical path
• Rich: Yes — connects estimation, scheduling, probability, risk
• Consistent: Yes — 65+ years of established usage
• Attributable: Yes — Malcolm, Roseboom, Clark, Fazar (1958)
• Tier 2 correct: Useful but specialized (project planning, not daily coding)

#356 Spec-Driven Development — ⚠️ Discuss

• Precise: Moderate — the term is used differently by different people (API-first vs. formal specs vs. our workflow doc)
• Rich: Yes — connects to BDD, TDD, contract-first, verification
• Consistent: Weak — no single canonical definition
• Attributable: Weak — Swagger/Thoughtworks are not the originators; the term is emergent
• Concern: We have a whole workflow document about this. Making it an anchor could create circular references. Also, our evaluation showed EARS (similar domain) scores poorly.

#357 Explicit Contract Surface — ❌ Reject

• Precise: Moderate — describes a pattern but the name is not established
• Rich: Yes — connects ACL, DTOs, mapping, DIP
• Consistent: No — this is not a recognized term in the literature
• Attributable: No — Evans/Martin/Fowler did not coin this term
• This is a design practice, not a semantic anchor. It combines existing anchors (Clean Architecture, DDD, SOLID DIP) but doesn't add a new activation.

#358 Vertical Slice Architecture — ✅ Accept

• Precise: Yes — clear distinction from layered architecture
• Rich: Yes — connects to CQRS, feature cohesion, screaming architecture
• Consistent: Yes — Jimmy Bogard's talks and blog posts are canonical
• Attributable: Yes — Jimmy Bogard
• Tier 3 justified: A well-known alternative to Clean/Hexagonal that LLMs should know

#359 GRASP — ✅ Accept

• Precise: Very — 9 named patterns with clear definitions
• Rich: Yes — foundational OO design patterns, connects to SOLID, GoF
• Consistent: Yes — Craig Larman's "Applying UML and Patterns" is canonical
• Attributable: Yes — Craig Larman
• Tier 3 justified: Standard curriculum material, widely taught

#360 KISS — ⚠️ Discuss

• Precise: Low — "keep it simple" is a directive, not a methodology
• Rich: Low — doesn't activate multiple interconnected concepts
• Consistent: Mixed — everyone agrees on the principle but not on what "simple" means
• Attributable: Yes — Kelly Johnson (Lockheed Skunk Works)
• Tier 1 correctly assigned: Same tier as YAGNI and TIMTOWTDI. Copilot got this right!
• Question: We reference KISS in the workflow doc (AGENTS.md conventions). Rejecting it would be inconsistent.

[raifdmueller]

Thanks for this proposal! Spec-Driven Development is clearly relevant to our project — we have an entire workflow document dedicated to it.

Recommendation: don't merge as a separate anchor.

Here's our reasoning:

1. No single canonical definition. "Spec-Driven Development" means different things to different people — API-first design (Swagger), formal specifications, or our broader workflow approach. The proponents listed (Swagger/OpenAPI Initiative, Thoughtworks) didn't coin the term as a unified methodology.

2. Our workflow document is the better reference. The workflow doc describes a complete spec-driven process using existing anchors (Gherkin, arc42, ADR, TDD, etc.). A separate "Spec-Driven Development" anchor would create a circular reference — the anchor points to our workflow, and our workflow uses other anchors.

3. "Attributable" criterion is weak. Unlike TDD (Kent Beck), arc42 (Starke/Hruschka), or SOLID (Robert Martin), there's no single authority behind "Spec-Driven Development" as a coherent methodology.

The evaluation scores 100% on L1 Recognition — but that's because the concept is well-known, not because the term activates a specific methodology. Many well-described concepts score 100% without being semantic anchors (see our quality criteria).

We appreciate the contribution! The individual anchors that make up spec-driven workflows (Gherkin, BDD, TDD, arc42, ADR) are already in the catalog and work well.

[raifdmueller]

Follow-up: Testing related terms

We also tested whether more specific variants would work as semantic anchors:

Term	Claude Sonnet	GPT-4o
"Spec-Driven Development"	✅ Describes SDD generically	✅ Generic but reasonable
"AI Unified Process according to Simon Martinelli"	❌ "I don't have specific information"	⚠️ Halluzinates plausible-sounding content
"BMAD Method"	❌ Associates with EPA chemical risk assessment	⚠️ Invents "Blueprint, Model, Automate, Deploy"

Findings:

• "AI Unified Process" (Martinelli) is too new — not yet in the training data. Claude honestly says it doesn't know it; GPT-4o makes something up.
• "BMAD" activates the wrong domain entirely (chemistry, not software). GPT-4o invents a plausible-sounding but fabricated acronym expansion.
• "Spec-Driven Development" works generically but doesn't activate a specific, attributable methodology.

This confirms our recommendation: none of these terms currently qualify as semantic anchors. They may in the future as the concepts gain wider adoption and enter LLM training data.

For now, the best approach is to use the established anchors that make up a spec-driven workflow: Gherkin, BDD, TDD London/Chicago School, arc42, ADR according to Nygard — as described in our workflow document.

[rdmueller]

@raifdmueller we also have the concept of Semantic Contracts. So suggest to use other anchors instead of "spec driven dev". What if we create a new category for Semantic Contracts. We could even create a file which contains all of them.

What would be a good semantic contract in this case?

When we talk about a specification or "spec", we mean a specification with use cases, activity diagrams (not only the happy path) and acceptance criteria written in Gherkin.

? Please advice

[raifdmueller]

Great idea! A "Semantic Contract" defines what we mean when we use a term — it's a meta-level anchor that sharpens existing anchors.

For the spec example, I'd suggest keeping it as an AGENTS.md convention rather than a catalog anchor:

## Semantic Contracts
- "Specification" means: Use Cases with Activity Diagrams (all paths, not just happy path) 
  and acceptance criteria in Gherkin format. See: Gherkin, arc42 Section 10.

This works because:

1. It's project-specific — different teams may define "spec" differently
2. It composes existing anchors (Gherkin, Activity Diagrams) rather than creating a new one
3. The LLM reads AGENTS.md at session start and applies the contract automatically

A catalog anchor would need to be universal — but "what a spec means" varies by team. Semantic Contracts live best in AGENTS.md where they can be customized.

That said, we could add a meta-anchor like "Semantic Contracts" to the catalog that explains the concept of defining team-specific term definitions in AGENTS.md. That would be genuinely useful as a semantic anchor — it teaches the LLM the pattern of looking for and respecting project-level term definitions.

What do you think — a meta-anchor "Semantic Contracts" that teaches the pattern, with project-specific contracts in AGENTS.md?

[rdmueller]

I think we should add a new top-level menu item and collect semantic contracts there. Spec-Driven would be the first.

Why do you reference arc42 Section 10?

I think it makes sense to use this information to create a detailled issue and close this PR and the corresponding issue (with comment and reference from the new issue)

[raifdmueller]

Created #364 for the Semantic Contracts feature. This replaces the need for a standalone Spec-Driven Development anchor — the concept becomes a selectable Semantic Contract that users can download and add to their AGENTS.md.

(Regarding the arc42 Section 10 reference — that was a mistake, removed.)

[raifdmueller]

Replaced by #364 (Semantic Contracts)