Blueprint

> Blueprint Skill · v1.0 · Author: Motodigitalguru · License: [MIT](./LICENSE)

/blueprint — Konzept-Skill

Du erstellst einen modulorientierten Bauplan in ./docs/konzept/, bevor irgendetwas implementiert wird. Ziel: beim späteren Coden muss nichts mehr improvisiert werden — Schnittstellen, Datenmodell, Sicherheit, Tests, Risiken, Hosting, Kosten und Bau-Reihenfolge stehen vorher fest.

Kernprinzipien:

• Adaptiv, nicht starr — frage nur, was du brauchst und nicht aus Input/Repo ableiten kannst.
• Vorschau vor Schreiben — keine Datei wird ohne explizite Bestätigung geschrieben.
• Phasen sind Tore, keine Etiketten — Draft darf Lücken haben, Locked darf es nicht.
• Modul-Verträge sind Pflicht — jedes Modul beschreibt was es nach außen gibt und was es von außen erwartet.
• Keine generischen Best-Practices — alles modulbezogen oder konkret. Wenn es generisch wäre, weglassen.

---

0. Aufruf-Erkennung

Beim Aufruf prüfe in dieser Reihenfolge:

1. Args parsen. /blueprint (kein Arg) → Erstlauf-oder-Refresh-Modus. /blueprint update → expliziter Update-Modus. /blueprint → behandle Freitext als Initial-Input.
2. ./docs/konzept/ existiert?

• Nein → Erstlauf (siehe §2).
• Ja, und Aufruf war /blueprint update oder enthält Update-Sprache ("ändere", "update", "im Konzept", "im Blueprint") → Update-Modus (siehe §6).
• Ja, und Aufruf ist nacktes /blueprint → frage: "Konzept existiert. Update-Dialog starten oder neu aufsetzen (alt überschreiben)?". Default = Update.

1. Phase aus konzept.json lesen (Feld phase: draft | locked). Wenn Datei fehlt aber ./docs/konzept/ existiert → behandle als draft und warne den User.

---

1. Begriffe und Phasen

| Phase | Strenge | Was darf | Was muss | |-------|---------|----------|----------| | draft | mittel | TBD in Feldern, lückenhafte Module, fehlende Tests/Risiken | Vision, Stack, Modul-Liste, grobe Abhängigkeiten | | locked | streng | nichts Lückenhaftes | jede Sektion vollständig, keine TBD, jedes Modul hat Schnittstellen-Vertrag, alle Pflicht-Dateien existieren, konzept.json validiert gegen Schema |

Übergang draft → locked ist nur erlaubt, wenn die Locked-Checkliste (checklists/locked-checks.md) lückenlos durchläuft. Sonst Refusal mit konkreter Mängelliste.

Phase wird im Header jeder generierten Markdown-Datei sichtbar gemacht:

> **Phase:** draft · **Stand:** 2026-05-06

---

2. Erstlauf-Flow

2.0 Plattform-Klärung (Pflicht, vor allem anderen)

Bevor irgendein Stack, Modul oder Template angefasst wird, muss die Plattform feststehen. Sie ist die folgenreichste Einzel-Entscheidung im Konzept und definiert den Rest.

Mögliche Werte für plattform.primary:

| Wert | Bedeutung | Was es ändert | |------|-----------|---------------| | web | klassische Web-App, responsive, Browser-only | Server-rendered möglich, Cookies, kein App-Store | | web-pwa | Web + Progressive Web App (Installierbar, Offline-Cache) | Service-Worker, Manifest, Icons in vielen Größen | | mobile-native | iOS + Android nativ (Swift + Kotlin) | API-first Backend, zwei Code-Bases, App-Store-Submission, Apple Dev Account 99 €/Jahr, Play 25 $ einmalig | | mobile-cross | React Native / Expo / Flutter | API-first Backend, OTA-Updates möglich, eine Code-Base, Native-Module bei Bedarf | | mobile-hybrid | Capacitor / Ionic (Web in WebView) | Web-Code-Base, App-Store-Submission, Native-Bridge für Hardware | | desktop | Electron / Tauri | Auto-Update-Channel, Code-Signing (macOS Notarization, Windows Authenticode) | | cli | Kommandozeilen-Tool | Keine UI-Sektion, Distribution via npm/brew/cargo | | browser-ext | Browser-Erweiterung | Manifest v3, Store-Submission (Chrome / Firefox / Edge separat) | | bot | Chat-/Service-Bot (Discord, Slack, Telegram, …) | Plattform-API als zentraler Zwang, Webhook/Long-Polling | | library | Bibliothek/SDK | Keine Hosting-/Auth-Sektion, dafür API-Stabilität, Versionierung, Doku-Pflicht |

Zusätzlich plattform.secondary (Array, optional): Liste weiterer Targets, falls gemischt (z. B. primary: mobile-cross, secondary: ["web-pwa"]).

Frage stellen, sobald die Plattform nicht aus Input/Repo eindeutig ist. Bei Mobile/Desktop/Bot/Ext immer explizit nachfragen, auch wenn der User "App" sagt — "App" ist mehrdeutig.

Folge-Konsequenzen, die der Skill ab hier automatisch zieht:

• mobile-* / desktop / browser-ext → Backend wird API-first modelliert, kein server-rendered HTML als Default. Auth via Token (JWT/Session-Token), nicht Cookie-only.
• mobile-* / desktop / browser-ext → betrieb.md bekommt Sektion "Distribution & Store-Submission" (App-Stores, Code-Signing, Review-Prozess, OTA-Updates).
• mobile-* → kosten-und-zeit.md listet Apple Dev (99 €/Jahr), Google Play (25 $ einmalig), ggf. TestFlight, App-Store-Connect-Setup-Aufwand.
• mobile-* / desktop → tests-und-qualitaet.md bekommt Geräte-/OS-Matrix.
• mobile-* / web-pwa → Push-Notifications-Architektur (APNs, FCM, Web-Push) explizit modellieren.
• bot → Plattform-Limits (Rate-Limits, Message-Größe, Slash-Command-Format) als eigene Sektion in architektur.md.
• library → keine betrieb.md als Deployment-Sektion, stattdessen Release-/Versionierungs-Strategie. Keine Auth, keine Hosting-Sektion.

Die Plattform wandert in konzept.json unter plattform (siehe Schema).

2.1 Input einsammeln

Genau ein Einstiegsfeld. Skill akzeptiert:

1. Idee (1–2 Sätze)
2. Groben Markdown-Entwurf
3. Bestehenden Code → Repo-Scan (max. 3 Tool-Calls: Verzeichnis-Listing, README, package.json/pyproject/etc.)

Wenn der initiale Aufruf zu wenig liefert: eine offene Frage zurückgeben ("Was soll dieses Projekt tun? 1–2 Sätze reichen."). Niemals Fragebogen-Stil.

2.2 Awareness-Trigger prüfen

Bevor du weiterfragst: lies awareness/adult-keywords.txt und prüfe Input + ggf. README/package.json gegen die Liste. Bei Treffer oder Unklarheit eine Ja/Nein-Frage stellen: "Berührt das Projekt Adult-/NSFW-Content?". Antwort wird in konzept.json als awareness.adult (boolean) festgehalten und zieht die Spezial-Sektionen in §5.

2.3 Lücken-Analyse

Nach Input-Einsammlung gehe die folgenden Sektionen einmal durch und identifiziere, was bereits aus Input/Repo ableitbar ist und was fehlt:

| Sektion | Minimum für draft | Zusätzlich für locked | |---------|---------------------|--------------------------| | Vision | Idee, Problem, Zielgruppe | Out-of-Scope, Erfolgs-Kriterium | | Architektur | Stack-Vorschlag, High-Level-Struktur | Performance-Budgets, A11y-Level, Browser-Support | | Datenbank | Entities + Felder | Indizes, Relationen vollständig, Constraints | | Module | Liste mit Zweck und grober Komplexität | Schnittstellen-Verträge je Modul, interne Funktionen, Tests, Logging | | Modulgraph | grobe Abhängigkeiten | Bau-Reihenfolge mit Begründung, Zyklen-Check | | Aufgaben | — | Checklisten pro Modul mit Vorbedingungen | | Risiken | externe Abhängigkeiten genannt | Kopplungs-Warnungen, regulatorische Themen | | Sicherheit | Auth-Methode | OWASP-Checkliste pro Modul, DSGVO-Daten, Rate Limiting, Secrets | | Tests | — | pro Modul Pflicht-Tests, Coverage-Erwartung, Fehlerbehandlungs-Konvention | | Betrieb | — | CI/CD, Logging, Error-Tracking, Health-Checks, Backup, Audit-Log | | Hosting/Tools | Hosting-Empfehlung | Zusatz-Tools, externe Services | | Kosten/Zeit | grober Score | Aufschlüsselung pro Modul |

Frage nur das, was zum aktuellen Phasen-Ziel fehlt. Wenn der User draft will, frage nicht nach locked-Feldern.

2.4 Adaptive Fragerunde

Stelle gesammelte Fragen in einer Runde (gebündelt, nummeriert), nicht einzeln. Wenn User mit "weiß nicht" / "schlag vor" antwortet, schlage selbst vor und kennzeichne im konzept als proposed: true. User kann später überschreiben.

2.5 Vorschau vor Schreiben

Bevor du Dateien anlegst, zeige eine kompakte Übersicht (maximal ~20 Zeilen):

Module:           Auth (M), Profile (S), Marketplace (L), Payment (XL), Admin (M)
Stack:            Next.js 15 + Drizzle + Postgres + Clerk
Hosting:          Vercel (Frontend) + Neon (DB) + Stripe (Payment)
Adult-Awareness:  Nein
Komplexität:      L · ca. 6–8 Wochen Vollzeit
Pflicht-Dateien:  vision, architektur, datenbankstruktur, module/*, module-graph,
                  aufgaben, risiken, sicherheit, tests-und-qualitaet, betrieb,
                  hosting-und-tools, kosten-und-zeit, konzept.json
Bedingt:          compliance.md (User-Daten), migrationen-und-seeds.md (DB)

Frage: "Schreiben mit diesen Annahmen? (ja / ändere X / abbrechen)". Erst nach ja Dateien schreiben.

2.6 Schreiben

• Lege ./docs/konzept/ an (mit module/ Unterordner).
• Befülle Templates aus templates/. Platzhalter {{...}} ersetzen, keine Platzhalter zurücklassen außer als bewusste TBD: -Marker im draft.
• Schreibe konzept.json zuletzt, nachdem alle MD-Dateien stehen.
• Validiere konzept.json gegen schema/konzept.schema.json (siehe §4). Bei Validierungsfehler: User informieren, Phase auf draft setzen, Fehler als TBD in MD spiegeln.

2.7 Abschluss

Gib dem User:

1. Liste der geschriebenen Dateien mit Pfad
2. Aktuelle Phase (draft oder locked)
3. Empfehlung für nächsten Schritt: "Lock starten mit /blueprint lock?" oder "Module bearbeiten mit /blueprint update?"

---

3. Modul-Format

Jedes Modul liegt unter ./docs/konzept/module/.md und folgt dem Template templates/module/_template.md. Pflicht-Sektionen:

1. Zweck — was macht das Modul, warum existiert es (2–4 Sätze)
2. Schnittstellen-Vertrag

• Gibt nach außen: Funktionen mit Signaturen, Events, DB-Tabellen, API-Endpoints
• Erwartet von außen: welche Funktionen / Daten / Events anderer Module gebraucht werden

1. Interne Funktionen — Liste mit kurzer Beschreibung
2. Komplexität — S / M / L / XL mit 1-Satz-Begründung
3. Abhängigkeiten — Liste anderer Module (Pflicht / optional)
4. Sicherheits-Aspekte — was an OWASP/DSGVO berührt wird
5. Pflicht-Tests — was zwingend getestet werden muss
6. Logging/Audit — welche Events das Modul erzeugt

Slug-Regel: kleinbuchstaben, Bindestriche, ASCII (payment-refunds.md statt Payment Refunds.md).

Vertrag = isolierbares Bauen. Wenn du das Modul später baust, soll dessen Datei + die Verträge der Dependencies reichen.

---

4. JSON-Schema und Validierung

konzept.json ist das maschinenlesbare Spiegelbild der MD-Dateien. Source of Truth ist Markdown, konzept.json wird beim Schreiben/Updaten daraus synthetisiert. Beim Locken validiert der Skill konzept.json gegen schema/konzept.schema.json.

Ablauf beim Locken:

1. Locked-Checkliste durchlaufen (checklists/locked-checks.md).
2. konzept.json mit aktuellem Stand neu generieren.
3. Schema-Validierung. Bei Fehlern: konkret nennen, Phase bleibt draft.
4. Erfolg: phase: locked, Header in allen MDs aktualisieren, lockedAt: in JSON.

Zwei Validierungs-Skripte, beide werden beim Lock-Versuch ausgeführt:

# 1. Schema-Validation (Pflicht-Felder, Typen, Phase-Anforderungen)
node skill/blueprint/scripts/validate.mjs ./docs/konzept/konzept.json

# 2. Kreuz-Konsistenz (module/-Files ↔ konzept.json ↔ bauReihenfolge ↔ Kanten)
node skill/blueprint/scripts/cross-check.mjs ./docs/konzept

Beide müssen Exit-Code 0 zurückgeben. Bei Fehler in einem der beiden bleibt Phase auf draft, Mängelliste an User.

Wenn Node nicht verfügbar: manuelle Prüfung gegen Schema und manuelle Kreuz-Konsistenz aus der Locked-Checkliste.

---

5. Adult-/NSFW-Spezialfall

Wenn awareness.adult: true, automatisch zusätzlich:

• risiken.md — Sektion "Content-Klassifikation und regulatorische Risiken" (UK OSA, DE JuSchG/JMStV, US 2257, DSGVO)
• hosting-und-tools.md — explizite Warnung zu Vercel / Cloudflare / großer Teil AWS; adult-friendly Anbieter empfehlen (Hetzner, OVHcloud Bare-Metal, MojoHost)
• compliance.md (Pflicht, nicht bedingt) — Altersverifikation, 2257-Records (falls US-Bezug), Content-Moderation-Prozess
• Werbung-Sektion in vision.md oder betrieb.md — Hinweis: Google Ads / Meta gesperrt, Alternativen (TrafficJunky, ExoClick, JuicyAds) listen
• Payment-Sektion in architektur.md — Stripe / PayPal / Klarna ausgeschlossen, Alternativen (CCBill, Segpay, Verotel, SegPay-Alternativen, Crypto)

Nichts in Watte packen. Wenn der Skill sieht, dass der User Stripe für Adult plant, hart benennen: "Stripe lehnt Adult ab, dein Konzept würde an dem Punkt scheitern".

---

6. Update-Modus

Drei Eingangswege:

6.1 Geführter Update-Dialog (/blueprint update)

Zeige Sektions-Übersicht mit aktuellem Stand:

1. Vision (Stand: 2026-05-03)
2. Architektur (Stand: 2026-05-03)
3. Datenbankstruktur (Stand: 2026-05-04, 5 Entities)
4. Module (12 Stück) → einzeln auswählbar
...

User wählt Nummer(n). Skill stellt nur die Fragen, die für diese Sektion relevant sind. Schreibt nur die betroffenen Dateien neu.

6.2 Kontextuelles Update (natürliche Sprache)

Beispiele: "ändere im Blueprint Modul Habit, das braucht jetzt Tags", "im Konzept Stack auf Bun statt Node umstellen".

Skill:

1. Identifiziert betroffene Sektion(en) und Datei(en).
2. Zeigt Diff der geplanten Änderung (kein Voll-Rewrite).
3. Wartet auf Bestätigung.
4. Schreibt nur das Geänderte. Phase fällt auf draft zurück, falls die Änderung Locked-Bedingungen verletzt — User informieren.

6.3 Lock-Aufruf (/blueprint lock)

Direkt zum Lock-Tor. Locked-Checkliste durchlaufen, validieren, melden.

---

7. Stack-Empfehlung

Wenn User keinen Stack vorgibt, schlage einen passenden vor und begründe in architektur.md: was gewählt, warum, welche Alternativen verworfen.

Heuristik (nicht starr):

• Web-App mit DB, Auth, kommerziell: Next.js / Astro + Postgres (Neon/Supabase) + Drizzle/Prisma + Clerk/Auth.js.
• Performance-kritisch / Realtime: SvelteKit oder Next.js mit eigenem WS, Redis.
• Adult-Content: kein Vercel / kein Cloudflare-Workers in der ersten Reihe — Hetzner/OVH + eigenes Deployment (Coolify, Dokku) oder Railway als Mittelweg.
• Klein, eine Person, schnell live: Astro statisch + Pocketbase / SQLite + Backblaze B2 für Files.

Stack-Wahl darf nie ohne Begründung passieren.

---

8. Was bewusst NICHT in den Output gehört

• Code-Style-Details (Prettier, EditorConfig) — gehört ins Lint-Setup, nicht ins Konzept.
• Generische Best-Practices ohne Modul-Bezug.
• Implementierungs-Code. Der Skill schreibt kein Implementations-Code — nur Konzept-Dateien.
• Ausführliche Doku-Strategie. README + JSDoc reicht.

---

9. Output-Pfade (Referenz)

./docs/konzept/
├── vision.md
├── architektur.md
├── datenbankstruktur.md
├── module/
│   ├── _template.md          (Kopie aus skill/, optional zur Referenz)
│   └── .md             (eine Datei pro Modul)
├── module-graph.md
├── aufgaben.md
├── risiken.md
├── hosting-und-tools.md
├── kosten-und-zeit.md
├── sicherheit.md
├── tests-und-qualitaet.md
├── betrieb.md
├── konzept.json
├── compliance.md             (bedingt: User-Daten / Adult)
└── migrationen-und-seeds.md  (bedingt: DB)

---

10. Fail-Modes (was tun wenn etwas schiefläuft)

| Situation | Verhalten | |-----------|-----------| | User will sofort locked, aber Sektionen fehlen | Refusal mit konkreter Liste, biete draft an | | User pusht Stack, der mit Awareness kollidiert (Stripe + Adult) | Hart benennen, Vorschlag mit Alternative, frage explizit ob trotzdem | | Schema-Validation fällt durch | Phase = draft, Fehler als TBD in MDs spiegeln, User-Liste mit konkreten Pfaden | | ./docs/konzept/ existiert aber konzept.json fehlt | Synthetisiere konzept.json aus MDs (best effort), markiere als phase: draft | | Repo-Scan trifft auf riesiges Repo | Beschränke auf Top-Level + README + manifest-Datei. Frage User nach Schwerpunkt. |

---

11. Templates

Templates liegen in templates/. Verwende **

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: motodigitalguru-beep
• Source: motodigitalguru-beep/blueprint
• License: MIT
• Homepage: https://www.flow-code-labs.io

Install and usage instructions live in the source repository linked above.