Speccify: npm für Spezifikationen statt Code

1. Das Problem

Heutige Komponenten-Ökosysteme sind pro Sprache und Framework fragmentiert. Eine React-Komponente lässt sich nicht in SwiftUI einsetzen, ein Angular-Service nicht in einer Flutter-App, ein Django-Validator nicht in einer Rust-Edge-Function. Bibliotheken werden N-mal neu geschrieben; jedes Team implementiert Login-Flows, Datentabellen und Onboarding-Wizards immer wieder neu.

Das eigentliche Wissen über eine Komponente – wie soll sie sich in welchem Zustand verhalten? – steckt implizit im Code eines konkreten Stacks. Es ist dort weder wiederverwendbar noch maschinenlesbar abstrahiert.

Mit AI-Agenten verschiebt sich der Engpass. Code zu generieren ist billig geworden. Der eigentliche Wert liegt in einer präzisen, deterministischen Beschreibung des Gewollten.

„The bottleneck in software is no longer typing code, it is specifying intent." — sinngemäß aus aktuellen Diskussionen zu Spec-Driven Development

2. Die Idee in einem Satz

npm für Spezifikationen statt für Code – Komponenten beschreiben, nicht implementieren. Der AI-Agent ist der Compiler in das Ziel-Framework.

Eine Komponente in Speccify ist eine abgeschlossene Spezifikation, die alles enthält, was ein Agent braucht, um sie in einem beliebigen Stack korrekt umzusetzen:

• Eindeutige, unveränderliche Identität (spec://login-with-otp@1.4.0, scope-fähig: @org/login-with-otp@1.4.0).
• Maschinenlesbares Spec-File (<name>.speccify.yaml, validiert per JSON-Schema).
• Menschen- und LLM-lesbare Beschreibung (strukturiertes Markdown).
• Akzeptanzkriterien als Given/When/Then und Test-Fixtures.
• Visuelle Referenzen (Screenshots, Wireframes, Figma-Embeds, Negativ-Beispiele).
• Sprachunabhängige Inputs/Outputs/Events (analog JSON Schema / Protobuf).
• Abhängigkeiten zu anderen Komponenten (uses: [spec://otp-input@^1, ...]).
• Constraints für Accessibility, Performance, Security, i18n.
• Optionale Referenzimplementierungen pro Framework als Conformance-Tests.

3. Drei Komponenten-Klassen

Workflows referenzieren andere Komponenten per ID. Komposition ersetzt Copy-Paste.

4. Was ein Agent damit macht

speccify pull --target react --out ./src/components

Oder im Editor:

„Bau mir einen Onboarding-Flow mit @org/login-with-otp und @org/profile-setup, Ziel: React 18, Style: Tailwind."

Der Agent

1. resolved die Specs inkl. transitiver Abhängigkeiten,
2. mappt sprachunabhängige Typen auf Ziel-Stack-Typen,
3. generiert idiomatischen Code im Ziel-Framework,
4. erzeugt Conformance-Tests aus den Akzeptanzkriterien,
5. meldet Lücken und Mehrdeutigkeiten in der Spec zurück (Refinement-Loop).

5. Spec-Format (Entwurf)

id: spec://login-with-otp
version: 1.4.0
kind: ui-workflow            # ui-component | logic | workflow
title: Login mit Einmal-Passwort
summary: >
  Login-Flow per E-Mail/Telefon und 6-stelligem OTP, inkl. Resend, Lockout
  nach 5 Fehlversuchen, Accessibility AA.

inputs:
  - name: identifier
    type: string
    constraints: [email | e164-phone]
outputs:
  - name: session
    type: ref://spec/session@^1
events:
  - name: otp_sent
  - name: login_failed
    payload: { reason: enum[invalid_otp, expired, locked] }

uses:
  - spec://otp-input@^1.0
  - spec://rate-limiter@^2

acceptance:
  - given: User gibt gültige E-Mail ein
    when: Submit gedrückt
    then: otp_sent emittiert, OTP-Eingabe erscheint binnen 300 ms
  - given: 5 falsche OTPs in Folge
    then: login_failed mit reason=locked, 15 min Sperre

ux:
  references:
    - figma://file/abc123?node=4:12
    - asset://screenshots/happy-path.png
    - asset://screenshots/error-locked.png
  a11y: WCAG-2.2-AA
  i18n: required (de, en)

non_functional:
  performance: "TTI < 2s auf 3G"
  security: ["keine OTPs im LocalStorage", "Rate-Limit serverseitig"]

conformance:
  fixtures: ./fixtures/*.json
  golden_renders:
    swiftui: ./golden/swiftui/
    react: ./golden/react/

6. Kernprinzipien

1. Spec-First, Code-Second – die Spec ist das Artefakt, Code ist Ausgabe.
2. Determinismus durch Präzision – je vollständiger die Spec, desto reproduzierbarer der Output verschiedener Agenten.
3. Stable Identity – <comp-id> ist unveränderlich; Änderungen erzeugen eine neue Version.
4. Composability – Komponenten referenzieren Komponenten, transitiv auflösbar.
5. Verifiability – jede Spec hat ausführbare Akzeptanzkriterien; Conformance-Tests laufen pro Ziel-Stack.
6. Human + AI Co-Authoring – Specs werden gemeinsam mit AI refined, mit klaren Diff- und Review-Workflows.
7. Open Core – Spec-Format und CLI Open Source; Hosting, Collaboration und Search als Service.

7. Differenzierung

8. Produkt-Oberfläche

Reihenfolge nach dem Refinement: CLI + MCP + Website/Playground zuerst, Desktop-App optional und nachgelagert. Frühe Adopter leben in Editor, Terminal und CI – genau dort soll der Workflow laufen.

✅ CLI (speccify) – primäre Oberfläche

MVP-Befehle: init, add, pull --target, lock, verify, publish, yank, search, lint. In CI prüft speccify verify, dass Spec- und Output-Hashes mit dem Lockfile übereinstimmen. Resolver- und Codegen-Logik teilt sich die CLI mit dem MCP-Server. Status (Stand Mai 2026): init, add, lock, pull --target react, verify, lint sind in Phase 1a/1b implementiert; publish, yank, search folgen mit dem Registry-MVP.

✅ Agent-API / MCP-Server – gleichberechtigt zur CLI

MCP-Server, der jeder Coding-Agent-Umgebung (Claude Code, Junie, Cursor, Aider) Zugriff auf das Registry gibt: resolve(id), search(query), render(id, target), validate(code, id), lock, verify. Macht „Agent ist der Compiler" erst erlebbar – derselbe Workflow für Menschen und Agenten.

✅ Website + Browser-Playground

• Discovery: Volltext + semantische Suche, Tags, Kategorien, Trending.
• Komponenten-Detailseite: Spec, Beispiele, Bildergalerie aus Asset-Refs, „Used by", Versionen, Forks.
• Browser-Playground: Spec eingeben → Live-Generierung in Ziel-Framework. Fast Abfallprodukt der Codegen-Pipeline und beste Demo-Oberfläche fürs Onboarding.
• Refinement-Diskussionen pro Spec: später, wenn echte Nutzung zeigt, wo sie gebraucht werden.

🅿️ Desktop-App (geparkt)

Tauri 2 + Rust + SvelteKit/Next.js bleibt als Stack-Entscheidung dokumentiert, die Umsetzung ist aber on-hold. Re-Aktivierungs-Kriterien: ≥ 30 aktive Spec-Autoren und dokumentierter UX-Bedarf aus echter CLI-/Web-Nutzung. Damit entkoppeln wir das Konzept-Risiko (taugen Specs überhaupt?) vom Tech-Risiko (Rust/Tauri/Code-Signing/WebKitGTK) und lernen das Wichtigste zuerst. Speccify selbst ist als Python-Implementierung gestartet (speccify_core + speccify_cli, Typer/Pydantic/PyYAML).

Visuelles Tooling – schrittweise

8a. So fühlt sich der Workflow an

# Initialisieren
speccify init my-app --target react

# Spec hinzufügen (schreibt speccify.yaml + speccify.lock)
speccify add @org/login-with-otp@1.4.0

# Code generieren
speccify pull --target react --out ./src/components

# Reproduzierbar prüfen (CI, offline möglich)
speccify verify --offline

# Eigene Spec publishen (immutable, signiert) — kommt mit Registry-MVP
speccify publish

Aus einem Coding-Agent heraus passiert dasselbe per MCP: resolve(@org/login-with-otp@^1) → render(target=react) → validate(code, id). Das Lockfile pinnt nicht nur Spec-Hashes, sondern auch den Generator (template oder llm mit Modell- und Prompt-Pin) plus optionalen Seed – damit ist nicht nur die Auflösung reproduzierbar, sondern auch der generierte Output. Für deterministische CI-Läufe ohne Live-LLM-Zugriff existiert ein Replay-Cache (speccify pull --offline).

Die Designentscheidungen für Identität, Versionierung, Resolver, Lockfile, Immutability, Trust und Distribution sind bewusst aus existierenden Package-Managern ausgewählt (npm-Scopes, Go-MVS, Cargo-/Maven-Immutability, sigstore-Signaturen) und in einem separaten Vergleichsdokument begründet. Wir übernehmen explizit nicht den Caret-Default von npm, kein Backtracking-Resolver, kein unpublish < 72h.

9. Technologie-Stack

10. Phasen-Roadmap (Kurzfassung)

1. Spec-Schema v0 + Lint ✅ – JSON-Schema (Draft 2020-12), Asset-Refs first-class, fünf Referenz-Specs, speccify lint. Tag v0.0.0-phase0.
2. CLI-MVP + MCP + erstes Codegen-Target + Browser-Playground – init/add/pull/lock/verify/publish/yank/search/lint, MCP-Server mit identischer Logik, React als erstes Target, Lockfile mit Generator-Pin (template oder llm mit Modell-/Prompt-Pin + Seed). End-to-End-Demo: Coding-Agent zieht Spec via MCP und baut Komponente.
3. 1a ✅ Manifest + Pseudo-Registry, MVS-Resolver, Lockfile, Stub-Codegen, pull/verify für React.
4. 1b 🟡 LLM-Codegen (Claude Sonnet 4.5) + Replay-Cache, minimaler init, TSX mit Props/Types; pull/verify werden gerade auf den Dispatcher umgestellt.
5. Registry-MVP – Django-Backend, Web-UI, Workspaces, sigstore-Vorbereitung, registry-gebundene Scopes.
6. Weitere Codegen-Targets – SwiftUI + Angular, Conformance-Runner pro Target.
7. 🅿️ Desktop-App (geparkt) – Re-Aktivierung erst bei ≥ 30 aktiven Autoren und echtem UX-Bedarf.
8. Visuelles Tooling + Refinement-Workflows – Galerie, Live-Preview, AI-Lückenfinder, Diff-Tool – nach 20–50 echten Specs.
9. Community & Discovery – Tags, „Used by", Forks, semantische Suche, 100 Saatgut-Specs, Figma-Integration.
10. Polish & Launch – Dokumentation, Quickstart-Videos, Beta-Programm.

11. Erfolgsmetriken

• Determinismus: strukturelle Diff-Distanz zwischen Outputs verschiedener Agenten für dieselbe Spec.
• Coverage: Anteil Specs, deren Conformance-Tests in ≥3 Targets grün laufen.
• Time-to-Component: Sekunden von speccify pull bis lauffähiger Code.
• Refinement-Loop-Länge: Iterationen, bis eine Spec „agent-ready" ist.
• Community-KPIs: aktive Autoren, neue Specs/Woche, Pulls/Woche.

12. Risiken & offene Fragen

• Determinismus zwischen LLM-Versionen: Wie wird sichergestellt, dass eine Spec auch in zwei Jahren zu konsistentem Code führt? → Conformance-Tests + gepinnte Modelle pro Spec-Version.
• Schreibhürde: Wird das Schreiben einer Spec aufwendiger als das Schreiben des Codes? → AI-Co-Author, Templates, Konzept der „minimal viable spec".
• Lizenzmodell: MIT/Apache für Specs, Dual-Lizenz für Marketplace?
• Forking-Modell: à la GitHub vs. zentrales Registry?
• Plattform-Strategie: SaaS-only oder self-hosted Edition?
• Rust-Lernkurve / WebKitGTK / Tauri-Plan-B: durch das Parken der Desktop-App aktuell entschärft, dokumentiert für die Re-Aktivierung.
• UI-lastige Komponenten ohne visuelle Refs: im CLI-/MCP-only-Workflow reichen Asset-Refs in der Spec eventuell nicht. Bewusst akzeptierter Trade-off; visuelles Tooling kommt in Phase 5.
• Modell-Drift: Wenn ein im Lockfile gepinntes Modell EOL geht, brauchen wir ein Migrations-Tool. → Offener Punkt im Package-Manager-Vergleich.

13. Spike-Status (was bereits gebaut ist)

Der ursprüngliche Spike-Vorschlag ist weitgehend umgesetzt:

1. ✅ Spec-Schema v0 (YAML + JSON-Schema), inkl. Asset-Refs.
2. ✅ Fünf handgeschriebene Referenz-Specs (button, contact-form, http-api-client, onboarding-wizard, login-screen) unter specs/.
3. 🟡 Eine Codegen-Pipeline: React/TSX (Phase 1b, statt ursprünglich SwiftUI – wegen breiterer Verifizierbarkeit und schnellerem Feedback). Live-Adapter über Anthropic Claude Sonnet 4.5; SwiftUI/Angular als nächste Targets vorgesehen.
4. ✅ CLI-MVP (init, add, lock, pull --target react, verify, lint) mit speccify.lock inkl. Generator-Pin (template oder llm).
5. ⏳ MCP-Bridge mit identischer Resolver-/Codegen-Logik – steht für Phase 1b/2 an.
6. ⏳ Conformance-Test-Runner für die React-Pipeline – nach Step 5b/5c.
7. ⏳ Demo: aus Junie/Claude Code per MCP resolve → render(target=react) → validate → lauffähige Komponente → interner Pitch.

Das Go/No-Go für Phase 2 (Registry) erfolgt nach erfolgreicher End-to-End-Demo aus Phase 1b.

14. Inspirationen

• OpenAPI / AsyncAPI – Spec-First für APIs mit etabliertem Codegen-Tooling.
• JSON Schema, Protobuf, GraphQL SDL – sprachunabhängige Typsysteme.
• Storybook – komponenten-zentriertes Authoring, aber framework-gebunden.
• Figma + Tokens Studio – visuelle Spezifikation, ohne Verhalten/Logik.
• Penpot, Plasmic – Design-zu-Code, framework-spezifisch.
• MCP (Model Context Protocol) – Standard, um Agenten Werkzeuge bereitzustellen.
• Spec-Driven Development (Cursor Rules, AGENTS.md, AGENT_SPEC) – wachsender Trend, bisher ohne zentrales Registry.

15. Status & nächste Schritte

• Rebrand abgeschlossen: Das Projekt heißt jetzt Speccify (vormals flowcation). Phase 1a-0 (Rename flowcation → speccify) ist umgesetzt.
• Phase 0 ✅ – Spec-Schema v0, speccify lint, fünf Referenz-Specs, CI grün, Tag v0.0.0-phase0.
• Phase 1a ✅ – Manifest, Pseudo-Registry, MVS-Resolver mit Diamond-Test, Lockfile-Format, speccify init/add/lock/pull/verify, Stub-Codegen für React.
• Phase 1b 🟡 – React-LLM-Adapter (Claude Sonnet 4.5), Replay-Cache und LlmClient-Protokoll fertig (Steps 1–5a). Offen: Step 5b (pull/verify auf den Codegen-Dispatcher umstellen, --offline/--cache-dir-Flags, Live-Cache-Aufnahme durch Maintainer), Step 5c (E2E-Smoke in CI), Step 6 (Tag v0.2.0-phase-1b).
• Markenrecherche / Domain: Im Zuge des Rebrands offen, in .agent/status.md zu pflegen.
• Package-Manager-Designentscheidungen sind geklärt (npm-Scopes, Go-MVS, Cargo-/Maven-Immutability, sigstore, registry-gebundene Scopes); Begründung im internen Vergleichsdokument.
• Nächste Schritte:
  • Phase 1b Steps 5b/5c/6 abschließen, Tag v0.2.0-phase-1b.
  • MCP-Bridge an render_for_target koppeln.
  • Phase 2 vorbereiten (Registry-MVP: Django-Backend, sigstore-Vorbereitung).
  • 3–5 Use-Cases als Saatgut definieren (Team / Kundenprojekte).
  • Pitch-Deck (8–10 Slides) auf Basis dieses Artikels aktualisieren.
  • 🅿️ Desktop-App geparkt: Tauri-Spike, Rust-Lernpfad, Plan B (SwiftUI-Shell).

→ Vollständiger Plan: Speccify-Repo, .agent/plans/speccify-plan.md (lokal: ~/Desktop/Work/Flowcation/.agent/plans/speccify-plan.md). Der ursprüngliche flowcation-plan.md ist im LambdaPy-Repo unter .agent/plans/archived/flowcation-plan.md archiviert.