Proposal: publish an sdd-with-anchors Responsible Vibe MCP workflow

[rdmueller]

Context

The Semantic Anchors site already endorses Responsible Vibe MCP as a tool that "enforces agentic workflows with phase gates and review checkpoints" (source). The 5-phase / 12-step workflow itself, though, lives only in human-readable prose. The agent re-derives the phase model from AGENTS.md and the website every session.

This issue proposes publishing a Responsible Vibe MCP workflow file (sdd-with-anchors) that encodes the workflow as a formal state machine. Any RVMCP-capable agent could then call whats_next() and proceed_to_phase() and receive deterministic step guidance — without burning context window on re-deriving the phase structure each time.

Why this fits the framework's own logic

Eichhorst's Principle frames the LLM as a noisy channel and prescribes closed-loop error correction. The current workflow does this for content (compiler, tests, reviews) but not for workflow state. When the agent compacts mid-session, the phase position is part of what gets lost. A workflow file moves phase state out of the channel and into a server — exactly the redundancy Shannon's theorem recommends for noisy channels.

Phrased in the framework's own slogan style: better state beats better prompts is the same principle as better tests beat better prompts, applied to workflow position instead of code correctness.

Deliverable sketch

A workflow file (location TBD — see open questions) that encodes:

• Phase 0 (Brownfield, optional): Scope Bounded Context (DDD)
• Phase 0.5 (Brownfield, optional): Socratic Code Theory Recovery, three sub-phases — Question Tree → Team Q&A → Synthesis
• Phase 1: Requirements Discovery (Steps 1, 2, 3, 4a, 4b, 4c, 4d)
• Phase 2: Architecture (Steps 5, 6)
• Phase 3: Implementation Planning (Step 7)
• Phase 4: Implementation Loop (Step 8, with TDD sub-loop)
• Phase 5: Quality Assurance (Steps 9, 10, 11, 12)

Each step reuses the verbatim prompts from the existing 13-row Prompt Cheat Sheet (greenfield) and 7-row Cheat Sheet (brownfield). Each phase declares an exit criterion (artifact presence) so transitions are verifiable rather than aspirational.

Illustrative shape (final schema aligned to RVMCP's existing workflows):

name: sdd-with-anchors
description: |
  Spec-driven development workflow following the Semantic Anchors
  methodology (5 phases / 12 steps). Greenfield by default;
  Phase 0 and 0.5 enable brownfield onboarding via
  Socratic Code Theory Recovery.
phases:
  - id: phase-1-requirements-discovery
    steps:
      - id: step-2-socratic
        instructions: |
          Use the Socratic Method combined with MECE to clarify
          requirements. Max 3 questions at a time. Challenge
          assumptions.
        anchors: [socratic-method, mece]
        exit_criteria:
          - artifact: src/docs/specs/clarified-requirements.adoc
      # ...
  - id: phase-2-architecture
    steps:
      - id: step-5-arc42
        instructions: |
          Fill the arc42 template in src/docs/arc42/ based on the
          specification. Use PlantUML C4 diagrams. For each
          architecture decision: ADR nach Nygard with Pugh Matrix
          (-1, 0, +1). Create a GitHub issue first.
        anchors: [arc42, c4-diagrams, adr-nygard, pugh-matrix]

Acceptance criteria

• Workflow file is installable via npx responsible-vibe-mcp setup or equivalent
• All 12 numbered steps and the four sub-steps of Step 4 are represented
• Brownfield Phase 0 and 0.5 are available either as a separate workflow or via a config flag
• Each phase's instruction text reuses anchor names from the catalogue verbatim
• Each phase has at least one verifiable exit criterion (artifact, marker file, or content predicate)
• An end-to-end smoke test exists that runs through all 12 steps on one of the existing OSS example projects (dacli is the obvious candidate)

Non-goals

• Not changing the methodology. The 5 phases and 12 steps stay as published.
• Not replacing the Prompt Cheat Sheets. They remain the human-readable reference; the workflow file is the machine-readable equivalent.
• Not requiring website prose changes (except one tooling-section link once the workflow exists).

Open questions

1. Repo placement — LLM-Coding/Semantic-Anchors, mrsimpson/responsible-vibe-mcp, or a new LLM-Coding/sdd-with-anchors repo? Trade-off between discoverability and ownership.
2. Anchor references — embed anchor descriptions inline (self-contained) or reference by URL (shorter, requires the catalogue to be online)?
3. Brownfield variant — separate workflow sdd-with-anchors-brownfield, or a brownfield: true flag on the same workflow?
4. Smoke-test corpus — which of the four OSS examples (dacli, Bausteinsicht, Vibe Coding Risk Radar, Semantic Anchors site) is the right reference?

References

• Greenfield workflow: https://llm-coding.github.io/Semantic-Anchors/spec-driven-development
• Brownfield workflow: https://llm-coding.github.io/Semantic-Anchors/brownfield
• Responsible Vibe MCP: https://github.com/mrsimpson/responsible-vibe-mcp
• Eichhorst's Principle, cited on the greenfield page

---

Happy to take a first cut at the YAML once the four open questions above have a direction. Comments welcome before any implementation work.

[JensGrote]

Issue #466 – Proposal: publish an sdd-with-anchors Responsible Vibe MCP workflow

Kommentar (GitHub-ready)

---

Assessment: RVMCP Workflow File for Spec-Driven Development

(German version below)

---

Context alignment

This proposal applies the project's own logic consistently: if anchors are "compressed pointers to methodology" for LLMs, then a workflow file is a "compressed pointer to process" for agents. The argument from Eichhorst's Principle is compelling — moving workflow state out of the noisy channel (context window) into a server is exactly the Shannon-redundancy pattern the framework already endorses for code correctness (tests) and architecture (specs).

The deliverable sketch is well-structured. Here's my assessment of the four open questions, plus implementation observations.

---

Open Questions — Recommendations

1. Repo placement

Recommendation: LLM-Coding/Semantic-Anchors (subdirectory workflows/sdd-with-anchors.yaml)

Option	Pro	Con
Same repo (LLM-Coding/Semantic-Anchors)	Co-located with anchor catalog, single source of truth for IDs, PR reviews cover both methodology + machine encoding	Larger repo scope
Separate repo (LLM-Coding/sdd-with-anchors)	Clean separation, independent versioning	Sync problem when anchors are renamed/added. Two PRs for one change.
RVMCP repo (mrsimpson/responsible-vibe-mcp)	Discovery via RVMCP ecosystem	Wrong ownership — methodology belongs to Semantic Anchors, not to the runtime

The tight coupling (workflow references anchor IDs verbatim) makes co-location the obvious choice. Independent versioning is a YAGNI concern at this stage — if it becomes necessary later, extraction is trivial.

2. Anchor references

Recommendation: Reference by ID, resolve at runtime.

anchors: [arc42, c4-diagrams, adr-nygard, pugh-matrix]

• The workflow file stays short and readable
• RVMCP resolves descriptions from the catalogue (via llms.txt or anchors.json) at whats_next() time
• Works offline if the agent has the catalogue cached (the website already publishes a JSON data file)
• Avoids content duplication that would drift

This follows the same principle as anchor cross-references in .adoc files — reference by ID, render at build/serve time.

3. Brownfield variant

Recommendation: Single workflow with a brownfield: true config flag.

config:
  brownfield: false  # default: skip Phase 0 + 0.5

phases:
  - id: phase-0-scope-bounded-context
    condition: "config.brownfield == true"
    # ...
  - id: phase-0.5-socratic-recovery
    condition: "config.brownfield == true"
    # ...
  - id: phase-1-requirements-discovery
    # always runs

Rationale:

• The brownfield phases are purely additive (prepended), not alternative — no branching logic needed
• One file to maintain when steps change
• Agent logic: if (config.brownfield) startAt('phase-0') else startAt('phase-1')
• Matches the website's presentation: both workflows share the same Steps 1–12, brownfield just adds Phase 0 + 0.5

4. Smoke-test corpus

Recommendation: dacli.

• Small, well-scoped (CLI tool with clear bounded context)
• Both greenfield and brownfield paths are documented against it
• Quick iteration cycle (minutes, not hours)
• Already used as the reference project in the workflow documentation

If a second corpus is needed later for variety, "Semantic Anchors website" itself would be the obvious brownfield candidate (larger, multiple bounded contexts, well-documented existing architecture).

---

Additional observations

Exit criteria as evaluation hooks:

The proposal's exit criteria ("artifact presence") can be extended to connect with the Contract Evaluation framework (#370). If a phase's exit criterion is "arc42 template filled", a contract eval spec could verify the LLM applied arc42 correctly — not just that the file exists. This creates a quality gradient:

Level	Exit criterion	Confidence
L0	File exists	Low (agent may create empty template)
L1	File non-empty with expected sections	Medium
L2	Content passes contract eval (specificity check)	High

Phase gate enforcement:

One RVMCP design question: should proceed_to_phase() enforce exit criteria (block transition if artifact missing), or merely warn? The "Meaningful Human Control" anchor (from the EA evaluation set) suggests: enforce for reversible phases (generating a spec), warn for irreversible ones (deploying). The user can override, but the default should be gated.

Step 4 sub-loop (TDD):

The TDD sub-loop in Phase 4 needs special handling. Unlike other phases that produce one artifact, Step 8 is an iteration:

- id: step-8-implement
  type: loop
  loop_condition: "all issues in sprint are done"
  per_iteration:
    - write failing test (Red)
    - implement minimal code (Green)
    - refactor (Refactor)
    - commit (Conventional Commits)
  exit_criteria:
    - all_tests_pass: true
    - no_open_issues_in_sprint: true

This maps to the "Walking Skeleton" anchor from the catalog — the first iteration should be a thin end-to-end slice, then subsequent iterations add depth.

TDD school selection:

The workflow currently assumes London/Chicago as the two TDD options. Once #557 (TDD Hamburg Style) lands as a contract and #556 (IOSP) as an anchor, the workflow should offer Hamburg Style as a third option for complex problems where micro-step TDD doesn't scale. The selection heuristic could be encoded as a decision point:

Complexity	TDD School	Rationale
Simple transformations	Chicago (classicist)	Pure input → output, no collaborators
Complex interactions with existing services	London (mockist)	Isolate from dependencies via mocks
Too complex for micro-steps, needs upfront design	Hamburg (Westphal)	ACD cycle: Analyze → Design → Code at service boundary

---

Recommendation

✅ Strong proposal — proceed. Start with:

1. Define the YAML schema (align with RVMCP's existing workflow format)
2. Encode the greenfield path (Phase 1–5, Steps 1–12)
3. Add brownfield flag + Phase 0/0.5
4. Smoke test against dacli
5. PR to this repo (workflows/sdd-with-anchors.yaml)

Happy to contribute the brownfield Phase 0.5 encoding (Socratic Recovery sub-phases) since we've implemented that pattern in our own AGENTS.md.

---

---

Bewertung: RVMCP-Workflow-Datei für Spec-Driven Development

(Deutsche Version)

---

Kontext-Einordnung

Dieser Vorschlag wendet die eigene Logik des Projekts konsistent an: wenn Anker „komprimierte Zeiger auf Methodik" für LLMs sind, dann ist eine Workflow-Datei ein „komprimierter Zeiger auf Prozess" für Agenten. Das Argument aus Eichhorsts Prinzip ist überzeugend — Workflow-State aus dem verrauschten Kanal (Context Window) in einen Server zu verschieben ist exakt das Shannon-Redundanz-Pattern, das das Framework bereits für Code-Korrektheit (Tests) und Architektur (Specs) empfiehlt.

---

Offene Fragen — Empfehlungen

1. Repo-Platzierung

Empfehlung: LLM-Coding/Semantic-Anchors (Unterverzeichnis workflows/sdd-with-anchors.yaml)

Option	Pro	Contra
Selbes Repo (LLM-Coding/Semantic-Anchors)	Co-located mit Anchor-Katalog, Single Source of Truth für IDs, PR-Reviews decken Methodik + Machine-Encoding ab	Größerer Repo-Scope
Separates Repo (LLM-Coding/sdd-with-anchors)	Saubere Trennung, unabhängige Versionierung	Sync-Problem wenn Anker umbenannt/hinzugefügt werden. Zwei PRs für eine Änderung.
RVMCP-Repo (mrsimpson/responsible-vibe-mcp)	Discovery via RVMCP-Ökosystem	Falsche Ownership — Methodik gehört zu Semantic Anchors, nicht zur Runtime

Die enge Kopplung (Workflow referenziert Anchor-IDs wortwörtlich) macht Co-Location zur offensichtlichen Wahl. Unabhängige Versionierung ist ein YAGNI-Concern in diesem Stadium — falls nötig, ist Extraktion später trivial.

2. Anchor-Referenzen

Empfehlung: Referenz per ID, Auflösung zur Laufzeit.

anchors: [arc42, c4-diagrams, adr-nygard, pugh-matrix]

• Workflow-Datei bleibt kurz und lesbar
• RVMCP löst Beschreibungen aus dem Katalog (via llms.txt oder anchors.json) bei whats_next() auf
• Funktioniert offline wenn der Agent den Katalog gecacht hat (die Website publiziert bereits eine JSON-Datendatei)
• Vermeidet Content-Duplikation die driften würde

Folgt demselben Prinzip wie Anchor-Querverweise in .adoc-Dateien — Referenz per ID, Rendering zur Build/Serve-Zeit.

3. Brownfield-Variante

Empfehlung: Einzelner Workflow mit brownfield: true Config-Flag.

config:
  brownfield: false  # default: überspringe Phase 0 + 0.5

phases:
  - id: phase-0-scope-bounded-context
    condition: "config.brownfield == true"
    # ...
  - id: phase-0.5-socratic-recovery
    condition: "config.brownfield == true"
    # ...
  - id: phase-1-requirements-discovery
    # läuft immer

Begründung:

• Die Brownfield-Phasen sind rein additiv (vorangestellt), nicht alternativ — keine Verzweigungslogik nötig
• Eine Datei zu pflegen wenn sich Schritte ändern
• Agent-Logik: if (config.brownfield) startAt('phase-0') else startAt('phase-1')
• Matcht die Website-Darstellung: beide Workflows teilen dieselben Steps 1–12, Brownfield fügt nur Phase 0 + 0.5 hinzu

4. Smoke-Test-Korpus

Empfehlung: dacli.

• Klein, klar abgegrenzt (CLI-Tool mit klarem Bounded Context)
• Beide Pfade (Greenfield + Brownfield) sind dagegen dokumentiert
• Schneller Iterationszyklus (Minuten, nicht Stunden)
• Bereits als Referenzprojekt in der Workflow-Dokumentation verwendet

Falls ein zweiter Korpus für Variety gebraucht wird, wäre die „Semantic Anchors Website" selbst der naheliegende Brownfield-Kandidat (größer, mehrere Bounded Contexts, gut dokumentierte bestehende Architektur).

---

Zusätzliche Beobachtungen

Exit-Kriterien als Evaluierungs-Hooks:

Die Exit-Kriterien des Proposals („Artefakt-Präsenz") können erweitert werden um sich mit dem Contract-Evaluation-Framework (#370) zu verbinden. Wenn das Exit-Kriterium einer Phase „arc42-Template gefüllt" ist, könnte eine Contract-Eval-Spec verifizieren dass das LLM arc42 korrekt angewandt hat — nicht nur dass die Datei existiert. Das erzeugt einen Qualitätsgradienten:

Level	Exit-Kriterium	Confidence
L0	Datei existiert	Niedrig (Agent kann leeres Template erstellen)
L1	Datei nicht-leer mit erwarteten Sektionen	Mittel
L2	Inhalt besteht Contract Eval (Specificity-Check)	Hoch

Phase-Gate-Enforcement:

RVMCP-Designfrage: soll proceed_to_phase() Exit-Kriterien erzwingen (Transition blockieren wenn Artefakt fehlt) oder nur warnen? Der „Meaningful Human Control"-Anker (aus dem EA-Evaluierungs-Set) empfiehlt: erzwingen für reversible Phasen (Spec generieren), warnen für irreversible (Deployment). Der User kann überschreiben, aber der Default sollte gegated sein.

Step-4-Sub-Loop (TDD):

Der TDD-Sub-Loop in Phase 4 braucht besondere Behandlung. Anders als andere Phasen die ein Artefakt produzieren, ist Step 8 eine Iteration:

- id: step-8-implement
  type: loop
  loop_condition: "all issues in sprint are done"
  per_iteration:
    - Fehlschlagenden Test schreiben (Red)
    - Minimalen Code implementieren (Green)
    - Refactoring (Refactor)
    - Commit (Conventional Commits)
  exit_criteria:
    - all_tests_pass: true
    - no_open_issues_in_sprint: true

Das mappt auf den „Walking Skeleton"-Anker aus dem Katalog — die erste Iteration sollte ein dünner End-to-End-Schnitt sein, dann fügen nachfolgende Iterationen Tiefe hinzu.

TDD-School-Auswahl:

Der Workflow geht derzeit von London/Chicago als den zwei TDD-Optionen aus. Sobald #557 (TDD Hamburg Style) als Contract und #556 (IOSP) als Anker landen, sollte der Workflow Hamburg Style als dritte Option für komplexe Probleme anbieten, bei denen Micro-Step-TDD nicht skaliert. Die Auswahl-Heuristik könnte als Decision Point kodiert werden:

Komplexität	TDD School	Begründung
Einfache Transformationen	Chicago (classicist)	Pure input → output, keine Kollaborateure
Komplexe Interaktionen mit bestehenden Services	London (mockist)	Isolation von Abhängigkeiten via Mocks
Zu komplex für Micro-Steps, braucht Upfront-Design	Hamburg (Westphal)	ACD-Zyklus: Analyze → Design → Code an Service-Grenze

---

Empfehlung

✅ Starker Vorschlag — fortfahren. Start mit:

1. YAML-Schema definieren (aligned mit RVMCPs existierendem Workflow-Format)
2. Greenfield-Pfad kodieren (Phase 1–5, Steps 1–12)
3. Brownfield-Flag + Phase 0/0.5 hinzufügen
4. Smoke-Test gegen dacli
5. PR in dieses Repo (workflows/sdd-with-anchors.yaml)

Bereit, die Brownfield-Phase-0.5-Kodierung (Socratic Recovery Sub-Phasen) beizusteuern, da wir dieses Pattern in unserer eigenen AGENTS.md implementiert haben.

[raifdmueller]

Review (automated triage) — 👍 Endorse, large; needs placement decision (not implemented here)

Encoding the published 5-phase/12-step SDD workflow as a formal Responsible Vibe MCP state-machine (so agents call whats_next()/proceed_to_phase() instead of re-deriving phases each session) is a solid, well-motivated proposal, and the thread already answers the main open questions (same-repo placement, anchor refs by ID resolved at runtime, brownfield as a single workflow with a flag, smoke-test via dacli).

Not implemented here because it's a new artifact plus runner integration with an external MCP (Responsible Vibe), which needs a maintainer to (a) confirm the dependency is one the project wants to take on, and (b) decide where the workflow file lives and how it's versioned against the anchors it references.

Recommendation: accept; start with a walking-skeleton — one phase wired end-to-end through RVMCP with a dacli smoke test — before encoding all 12 steps, so the integration risk is retired first (a spike, per the repo's own vertical-slicing contract). Per-phase exit-criteria quality levels and the TDD-school decision table from the thread are good content for that skeleton.

---

Generated by Claude Code