maxgfr/construct

construct – eine Produktidee, fundiert in ein baubares SRD

construct verwandelt eine Produktidee in ein Software Requirements Document (SRD) Paket, dessen Anforderungen und Entscheidungen auf echter Recherche basieren, nicht auf dem Gedächtnis des Modells. Die deterministische Engine (scripts/construct.mjs, Zero-Dep Node) erledigt die Suche, Zusammenstellung der Dossiers, SRD-Rendering und -Validierung mit Code; Ihre Aufgabe ist es, das Interview zu führen, die Recherche zu steuern und das gerenderte Grundgerüst zu einem präzisen, fundierten SRD anzureichern.

Die Kernregel: Bevorzuge eine fundierte Anforderung gegenüber einer geratenen. Nutzen Sie die von der Engine abgerufenen Recherchen (Wettbewerber, OSS-Vorarbeiten, technische Dokumentationen, StackOverflow), um Umfang, nichtfunktionale Anforderungen (NFRs) und Architekturentscheidungen zu rechtfertigen, und zitieren Sie die Belege mit [E#]. Die Fundierung ist hier empfehlend – construct check meldet die Abdeckung, scheitert aber nie daran –, also liegt der Grad der Genauigkeit bei Ihnen.

Das Skript

Ein eingebundenes, abhängigkeitsfreies Bündel: node scripts/construct.mjs <command>. Kein npm install, keine API-Schlüssel. Führen Sie --help für die vollständige Oberfläche aus. Wichtige Befehle:

• init --idea "<Einzeiler>" --out <run> – Erstellt einen Run-Ordner + brief.json.
• research --out <run> [--angles market,oss,tech,semantic] [--q "<fokus>"] [--semantic] – Sammelt Belege aus verschiedenen Perspektiven im Verzeichnis <run>/evidence/ (ein EVIDENCE.md + evidence.json Dossier mit [E#] IDs). Standard-Perspektiven: market,oss,tech.
• analyze --out <run> [--json] – Der "Was ist dünn?"-Bericht: Benennt jedes Feature/jeden Wettbewerber/jede Technologie/jeden Seed, der aktuell als UNGEFUNDERT gerendert wird, und gibt den Drill-Befehl aus, der die jeweilige Lücke schließt. Informativ, nie blockierend.
• web|oss|tech|so --out <run> [--q "<fokus>"] [--url ...] [--seeds ...] [--docs-url <u,...>] – Führt EINE Perspektive auf der Standardausgabe aus (kein Dossier). Verwenden Sie diese, um tiefer in einen dünnen Faden einzusteigen; --docs-url bindet bekannte Dokumentationsseiten direkt ein.
• render --out <run> [--level light|complex] [--merge] – Rendert den SRD-Baum + SRD.json aus brief.json + dem Dossier.
• check --out <run> [--min-grounding <0-100>] [--semantic] [--json] – Die HARTE strukturelle Prüfung (Exit ≠ 0 bei unvollständigem SRD) plus der EMPFEHLENDE Fundierungsabdeckungsbericht. --min-grounding N aktiviert ein zweites Gate, das unter N% fundierten Behauptungen fehlschlägt; --semantic bezieht VERIFY.json mit ein (siehe review) und schlägt bei jeder widerlegten/nicht belegbaren Behauptung fehl. (Abweichend von research --semantic, das nur Belege nach Embedding-Relevanz neu sortiert.)
• review --out <run> [--apply <verdicts.json>] [--max-review N] [--json] – Das Behauptungs-Unterstützungs-Tool. Ohne --apply schreibt es eine Behauptung↔Beleg-Arbeitsliste (VERIFY.todo.json + VERIFY.md): jede fundierte Behauptung, gepaart mit jedem zitierten [E#]-Auszug zur Beurteilung. --apply <verdicts.json> reduziert Ihre Urteile (supported|partial|refuted|unsupported) in VERIFY.json, auf das check --semantic prüft. Verteilen Sie es gemäß references/orchestration.md.
• verify --out <run> [--app <dir>] [--run-tests] [--strict] [--json] – Der Bau-Schiedsrichter: BUILD-PLAN.json ist wohldefiniert und azyklisch, jede Aufgabenreferenz löst sich in SRD.json auf, Dateien erledigter Aufgaben existieren, jede Anforderung wird von einem Test referenziert. --run-tests führt auch die deklarierten Testbefehle aus; --strict lässt eine gebaute Muss-Anforderung ohne referenzierenden Test fehlschlagen.
• status --out <run> [--json] – Zeigt, was im Run bisher existiert; --json fügt die Bau-Frontier hinzu (welche BUILD-PLAN-Aufgaben jetzt baubar sind vs. blockiert).
• semantic up|down|status – Optionaler lokaler Docker-Stack (Qdrant + Ollama + SearXNG).

Arbeitsablauf

Sie werden einmal aufgerufen und müssen ein vollständiges, fundiertes SRD zurückgeben. Treiben Sie die Schleife bis zum Abschluss voran; halten Sie nur inne, um den Benutzer nach einer echten Entscheidung zu fragen.

1. Führen Sie ein Interview mit dem Benutzer – eine Frage nach der anderen. Legen Sie das Produkt fest, bevor Sie recherchieren. Befolgen Sie references/interview-playbook.md: Problem, Zielbenutzer, Kernwert, Muss/Sollte/Kann-Funktionen, Einschränkungen (Budget, Zeitplan, Team, Compliance), in Frage kommende Technologien sowie etwaige Wettbewerber / OSS-Seeds. Empfehlen Sie bei jeder Frage eine Antwort; werfen Sie keinen Fragenkatalog hin. Schreiben Sie die Antworten in brief.json (starten Sie es mit construct init).

2. Recherche – fundieren Sie die Idee. Führen Sie aus:

   node scripts/construct.mjs research --out <run> --angles market,oss,tech
   

   Dies entdeckt Wettbewerber im Web, durchsucht vergleichbare OSS-Projekte (und deren Issues/PRs nach echten Fallstricken) und zieht Kandidaten-Tech-Dokumentationen + StackOverflow heran. Lesen Sie <run>/evidence/EVIDENCE.md.

3. Tiefer graben – bis analyze sauber ist oder der Benutzer Sie stoppt. Führen Sie aus:

   node scripts/construct.mjs analyze --out <run>
   

   Es nennt genau, was dünn ist – Funktionen, Wettbewerber, Kandidaten-Technologien und OSS-Seeds ohne zuordenbare Belege – und gibt den Drill-Befehl aus, der die jeweilige Lücke schließt. Verteilen (Fan-out): Wenn Sie parallele Unteragenten einsetzen können, entsenden Sie einen pro Lücke; jeder erhält den Brief-Einzeiler, die Lücke, seinen Drill-Befehl und eine eigene Websuche, und gibt eine Zusammenfassung von ≤5 Zeilen sowie URLs zurück, die eine Fundierung wert sind. Unteragenten DÜRFEN NICHT in den Run-Ordner schreiben – Drills geben auf der Standardausgabe aus; nur construct research schreibt das Dossier, und NUR SIE führen es aus. Führen Sie die Ergebnisse seriell zusammen: construct web --url <u,...> --out <run> → research erneut ausführen → analyze erneut ausführen. (Keine Unteragenten? Arbeiten Sie die Lücken selbst ab, einen Drill nach dem anderen.) Teilen Sie dem Benutzer mit, was Sie gefunden haben, und lassen Sie ihn lenken – priorisieren Sie Muss-Funktionen und tragende Entscheidungen, hören Sie auf, wenn er sagt, es reicht. Siehe references/orchestration.md und references/research-playbook.md.

4. Rendern Sie das SRD. Wenn der Brief solide und das Dossier reichhaltig ist:

   node scripts/construct.mjs render --out <run> --level complex
   

   Wählen Sie complex, wann immer ein Bau überhaupt möglich ist; ein späterer Wechsel der Stufe nummeriert FR-IDs neu (siehe references/srd-authoring.md). Dies schreibt den SRD-Baum (siehe unten). Das Datenmodell und die Schnittstellen werden durch Inferenz aus dem Brief vorab eingesät – überprüfen Sie sie, vertrauen Sie ihnen nicht. Reichern Sie es dann an: Lösen Sie jeden 🧠 Entscheide:-Aufruf auf, schärfen Sie die vorlagenbasierten Abnahmekriterien und NFR-Metriken zu testbaren, begrenzten Aussagen (befolgen Sie references/acceptance-criteria.md – check warnt, solange welche vorlagenbasiert bleiben), korrigieren/erweitern Sie das Datenmodell und die Schnittstellen und fügen Sie [E#]-Zitate aus dem Dossier an die Anforderungen und Entscheidungen an, auf denen sie beruhen. Siehe references/srd-authoring.md und references/citation-format.md. Erweitern Sie bei complex auch das Designsystem (design/): Ersetzen Sie die eingesäten Design-Tokens durch die echten Markenwerte des Produkts, überprüfen Sie die Komponenten- und Bildschirm-/Flow-Inventare und schärfen Sie die Barrierefreiheitskriterien auf den Zielstandard (abgeleitet aus dem Brief, Standard WCAG 2.2 AA). Siehe references/design-system-authoring.md.

5. Adversarielle Überprüfung – lassen Sie frische Augen es brechen. Entsenden Sie einen Unteragenten als Prüfer OHNE weiteren Kontext als den Run-Ordner-Pfad und references/adversarial-review.md (keine Unteragenten? Führen Sie den Durchgang selbst durch, folgen Sie strikt dieser Checkliste als feindseliger Leser.). Er muss versuchen, das SRD zu brechen – Mehrdeutigkeit, nicht testbare Kriterien, fehlende Fehlerpfade, Zitatenwäsche, Widersprüche – und getaggte Ergebnisse zurückgeben. Beheben Sie jeden [blocker], verwenden Sie Ihr Urteilsvermögen bei [advisory], führen Sie dann check erneut aus. Wiederholen Sie die Schleife, solange neue Blocker auftauchen (maximal 3 Runden, legen Sie dann dem Benutzer offen, was übrig bleibt). Führen Sie für eine wirklich umstrittene, schwer umkehrbare ADR auf complex-Ebene auch das 3-Richter-Gremium aus references/orchestration.md durch.

6. Validieren (drei Ebenen).

   • Strukturell (hart): node scripts/construct.mjs check --out <run>. Es schlägt fehl bei ungelösten 🧠, keinen funktionalen Anforderungen, einer FR ohne Abnahmekriterien, einer baumelnden Entitäts-/Schnittstellen-/NFR-Referenz, einer fehlenden erforderlichen NFR-Kategorie oder einer fehlerhaften ADR. Korrigieren Sie, bis es bestanden wird.
   • Fundierung (empfehlend): Derselbe Befehl gibt die Abdeckung aus – welcher Anteil der Anforderungen/Entscheidungen Belege zitiert. Erhöhen Sie sie dort, wo es darauf ankommt (die tragenden Entscheidungen); siehe references/grounding-coverage.md. Standardmäßig lässt es den Bau nie fehlschlagen, also verwenden Sie Ihr Urteilsvermögen. Wenn der Benutzer die Fundierung erzwingen möchte, fügen Sie das Opt-in-Gate hinzu: check --out <run> --min-grounding 70.
   • Behauptungsunterstützung (empfehlend → Opt-in-Gate): Die Abdeckung zählt Zitate; sie prüft nicht, ob sie halten. construct review --out <run> erstellt eine Behauptung↔Beleg-Arbeitsliste; beurteilen Sie jedes Paar (Verteilung gemäß references/orchestration.md Muster 4), erstellen Sie verdicts.json, review --apply verdicts.json, dann check --out <run> --semantic, um widerlegte/nicht belegbare Behauptungen abzuweisen. Ein Durchgang über die tragenden FRs/ADRs vor der Präsentation lohnt sich. Wiederholen Sie die Schritte 3–6, bis check strukturell bestanden ist, der Prüfer keine neuen Blocker findet und die Fundierung ehrlich ist.

7. Präsentieren. Geben Sie dem Benutzer das SRD-Paket: die Vision, die Wettbewerbslandschaft, die fundierten Anforderungen und die wichtigsten Entscheidungen (mit ihren [E#]-Belegen und Links). Weisen Sie explizit auf Unbekanntes hin, anstatt zu raten.

8. Bauen (wenn der Benutzer die App möchte, nicht nur das SRD). Der Render hat auch BUILD-PLAN.json ausgegeben – einen maschinenlesbaren Aufgaben-DAG (T-000 Gerüst + eine Aufgabe pro FR, Muss → Sollte → Kann, entitätsbewusste Abhängigkeiten), dessen acceptance-Einträge IN SRD.json zeigen. Sie schreiben den gesamten App-Code; die Engine fungiert als Schiedsrichter. Befolgen Sie references/build-playbook.md:

   • Führen Sie T-000 aus (Gerüst, Test-Harness, CI); setzen Sie conventions.appDir und conventions.testCommand in BUILD-PLAN.json.
   • Pro Aufgabe, in topologischer Reihenfolge: Lesen Sie die Abnahmekriterien aus SRD.json; testen Sie sie testgetrieben – jeder Test nennt seine FR-ID (z.B. describe("FR-001 …"); das ist es, wonach verify sucht); protokollieren Sie artifacts + tests; setzen Sie status: "done"; führen Sie node scripts/construct.mjs verify --out <run> aus und beheben Sie jeden Fehler vor der nächsten Aufgabe.
   • Gleichzeitige Aufgaben innerhalb eines Meilensteins haben keine Kanten zueinander, daher kann ihre bereite Frontier (status --out <run> --json) parallel gebaut werden – ein isolierter Git-Worktree pro Aufgabe; Sie allein führen die Ergebnisse in BUILD-PLAN.json zusammen (Muster 5 in references/orchestration.md).
   • Pro Meilenstein: verify --out <run> --run-tests --strict, dann eine Meilenstein-Adversarial-Review – frische Augen auf der Jagd nach einem Abnahmekriterium, das kein Test tatsächlich abdeckt (siehe das Playbook; references/verify.md erklärt, was verify beweisen kann und was nicht).
   • Wenn sich eine FR beim Bau als falsch erweist, ändern Sie den Brief, rendern Sie neu (Fortschritt wird nach Feature-Titel zusammengeführt), taggen Sie verschobene FR-IDs neu, führen Sie check erneut aus.

Was erzeugt wird (der SRD-Baum, unter --out)

00-overview/   VISION.md · SCOPE.md (+ 🧠 offene Entscheidungen)
requirements/  FUNCTIONAL.md (FR-NNN · Priorität · Gegeben/Wenn/Dann · [E#])
               NON-FUNCTIONAL.md (NFR-NNN nach Kategorie · Metrik · [E#])
architecture/  SYSTEM-CONTEXT.md · DATA-MODEL.md · INTERFACES.md
               decisions/NNNN-*.md  (ADRs)
design/        PRINCIPLES.md · DESIGN-TOKENS.md (+ design-tokens.json) · COMPONENTS.md
               SCREENS.md · ACCESSIBILITY.md      (nur complex; --no-design zum Überspringen)
competitive/   LANDSCAPE.md (Wettbewerber + OSS-Vorarbeiten)
BUILD-PLAN.md · BUILD-PLAN.json (Aufgaben-DAG für die Bauphase)
TRACEABILITY.md (FR ↔ NFR ↔ ADR ↔ Entität ↔ Schnittstelle ↔ Komponente ↔ Bildschirm)
evidence/      EVIDENCE.md · evidence.json · meta.json   ·   brief.json · SRD.json

light hält es schlank; complex fügt den vollständigen NFR-Satz, eine zweite ADR, Abnahmekriterien für Fehlerpfade, die vollständige Rückverfolgbarkeitsmatrix und einen Designsystem-Unterbaum (design/: Prinzipien, Tokens, Komponenten, Bildschirme/Flows, eine Barrierefreiheits-Vereinbarung – --no-design verzichtet darauf). Fügen Sie --merge für eine einzige Datei SRD.md hinzu.

Optionaler semantischer Modus (vollständig lokal, kein API-Schlüssel)

Die Perspektiven Markt/OSS/Technologie benötigen nichts weiter als Netzwerkzugriff. Für einen Relevanzdurchlauf über die gesammelten Belege können Sie ein lokales Embedding-Modell aktivieren:

node scripts/construct.mjs semantic up        # docker: Qdrant + Ollama + SearXNG
node scripts/construct.mjs research --out <run> --angles market,oss,tech,semantic --semantic

Alles läuft in lokalen Docker-Containern – kein Schlüssel, keine Daten verlassen die Maschine. Wenn der Stack nicht aktiv ist, protokolliert --semantic einen Hinweis und behält das lexikalische Ranking bei. Siehe references/semantic-setup.md.

Referenzen

• references/interview-playbook.md – Wie Sie den Brief erfragen, eine Frage nach der anderen.
• references/research-playbook.md – Auswahl von Perspektiven und tieferes Graben bis "gut genug".
• references/orchestration.md – Das dreistufige dynamische Arbeitsablaufmodell und die Unteragenten-Muster: Forschungs-Fan-out, Red Team, Richtergremium, Behauptungsunterstützungs-Fan-out, Bau-Fan-out (und die Ein-Schreiber-Regel).
• references/adversarial-review.md – Die Red-Team-Checkliste und ihr Ergebnisvertrag.
• references/srd-authoring.md – Auflösen von 🧠-Aufrufen, Schreiben testbarer Anforderungen und ADRs.
• references/design-system-authoring.md – Anreicherung des complex-Designsystems: Tokens, Komponenten, Bildschirme/Flows und die Barrierefreiheits-Vereinbarung.
• references/acceptance-criteria.md – Schlechte→gute Gegeben/Wenn/Dann-Umschreibungen und messbare NFR-Metrikmuster.
• references/citation-format.md – Die [E#]-Fundierungskonvention.
• references/grounding-coverage.md – Was der empfehlende Abdeckungsbericht bedeutet und wie man ihn verbessert.
• references/build-playbook.md – Die Bau-Schleife: Aufgaben-TDD, FR-Tag-Konvention, Meilenstein-Gates, die Meilenstein-Überprüfung.
• references/verify.md – Was jeder verify-Check beweist und was noch einer Überprüfung bedarf.
• references/provider-apis.md – Wie OSS-Issues/PRs pro Host ohne Schlüssel abgerufen werden.
• references/web-discovery.md – Die geschichtete schlüssellose Websuche.
• references/semantic-setup.md – Der optionale lokale Docker-Stack.