storybloq

Das Problem

KI-Programmierassistenten sind zustandslos. Jede neue Sitzung beginnt bei null. Das Modell weiß nicht, was gestern gebaut wurde, was defekt ist, welche Entscheidungen getroffen wurden oder woran als Nächstes gearbeitet werden soll. Entwickler kompensieren das mit CLAUDE.md-Dateien und verstreuten Notizen, aber es gibt keine Standardstruktur, keine Sitzungskontinuität und keine Werkzeuge.

Die wahren Kosten sind nicht die verschwendete Einrichtungszeit. Es sind wiederholte Fehler, erneut aufgerollte Designentscheidungen, halluzinierter Kontext und lineare statt sich akkumulierender Arbeit.

Related MCP server: AI Conversation Logger

Die Idee

Jedes Projekt erhält ein .story/-Verzeichnis mit JSON- und Markdown-Dateien. Tickets, Issues, Roadmap-Phasen, Sitzungsübergaben und gewonnene Erkenntnisse leben dort, werden von git verfolgt und sind für jede KI lesbar.

• CLI: storybloq – .story/ vom Terminal aus inspizieren und verändern.

• MCP-Server: strukturierte Werkzeuge, die Claude Code und Codex direkt aufrufen können, mit fünf zusätzlichen Werkzeugen, wenn der lokale Bus aktiviert ist. Kein Spawning von Unterprozessen.

• Skill: /story in Claude Code oder $story in Codex lädt den Projektstatus zu Beginn jeder Sitzung.

• Mac-App: native Seitenleiste, die .story/ überwacht und live aktualisiert, während Ihr KI-Client arbeitet (separates Produkt, kostenlos im App Store).

Installation

npm install -g @storybloq/storybloq@latest
storybloq setup --client all

Erfordert Node.js 20+ und mindestens einen KI-Client: Claude Code oder Codex CLI 0.130.0+. Das Paket liegt auf npm unter @storybloq/storybloq; Releases sind auf diesem Repository unter github.com/Storybloq/storybloq/releases getaggt.

setup --client all installiert den Storybloq-Skill für Claude und Codex, registriert dieses Paket als MCP-Server und konfiguriert verfügbare Client-Hooks. Eine erneute Ausführung ist sicher. Codex meldet installierte Hooks mit Vertrauensstatus unknown; öffnen Sie /hooks in Codex, um sie zu prüfen und zu bestätigen. setup-skill bleibt als Kompatibilitätsalias für die Claude-only-Einrichtung erhalten.

Upgrade

npm install -g @storybloq/storybloq@latest
storybloq setup --client all

Dieselben zwei Befehle wie bei einer Neuinstallation: @latest zieht die neueste Version, und die erneute Ausführung von setup aktualisiert die Storybloq-Skill-Dateien, registriert den MCP-Server neu und entfernt veraltete Hook-Einträge aus früheren Installationen.

Normalerweise sehen Sie beim nächsten storybloq-Aufruf ein einzeiliges Banner, sobald eine neuere Version auf npm verfügbar ist:

storybloq v1.2.0 is available (you have v1.1.6).
Update: npm install -g @storybloq/storybloq@latest

Das CLI aktualisiert außerdem still das Skill-Verzeichnis und migriert beim ersten Lauf nach einem Upgrade alle veralteten Hook-Einträge (z. B. vom vor der Umbenennung stammenden Paket @anthropologies/claudestory) – keine manuelle Bereinigung nötig.

Alternative Installation über das Claude-Code-Plugin-System: siehe Storybloq/plugin-archive (Legacy-Pfad; storybloq setup --client all ist die empfohlene Installation).

Ein Projekt bootstrappen

cd your-project
storybloq init --name "your-project"

Für Multi-Repo-Projekte siehe Föderation unten.

Das erzeugt:

.story/
├── config.json         project config + recipe overrides
├── roadmap.json        phase ordering + metadata
├── tickets/            T-001.json, T-002.json, ...
├── issues/             ISS-001.json, ISS-002.json, ...
├── notes/              N-001.json, N-002.json, ...
├── lessons/            L-001.json, ...
├── handovers/          YYYY-MM-DD-<slug>.md
└── snapshots/          state snapshots (gitignored)

Committen Sie alles außer .story/snapshots/.

Tägliche Nutzung

In Claude Code oder Codex:

• /story in Claude Code oder $story in Codex – lädt den Projektstatus, liest die neueste Übergabe, zeigt offene Tickets und Issues, listet blockierte Arbeit auf und fasst aktuelle Änderungen zusammen. Wenn der Client Hintergrund-Agenten ausführen kann und der bearbeitbare Backlog groß ist, schlägt es außerdem proaktiv den Orchestrierungs-Arbeitsstil vor (eine Empfehlung, die weiterhin durch explizites Opt-in abgesichert ist).

• /story auto T-001 T-002 ISS-013 / $story auto T-001 T-002 ISS-013 – autonomer Modus, begrenzt auf diese Einträge. Treibt ein Ticket durch Plan → Plan-Review → Implementierung → Tests → Code-Review → Commit mit Übergaben an jedem Kontrollpunkt.

• /story review T-001 / $story review T-001 – führt das Multi-Linsen-Review (siehe Storybloq/lenses) gegen den Diff eines Tickets aus.

• /story orchestrate / $story orchestrate – treibt einen Multi-Repo- (oder großen Single-Repo-) Backlog voran, wenn der Client exakt aufrufbare Workflow-/Subagenten-Werkzeuge bereitstellt. Codex verwendet multi_agent_v1.spawn_agent, seine normalisierte Kennung multi_agent_v1__spawn_agent oder ein exaktes spawn_agent-Werkzeug. Der auf Claude Agent View basierende Befehl storybloq dispatch wird mitgeliefert; ein produktverwaltetes Codex-Dispatch-Backend gibt es nicht.

• /story triage / $story triage – schreibgeschützte Triage des offenen Issue-Backlogs: verifiziert jeden Befund gegen den fixierten aktuellen HEAD, markiert bereits behobene und doppelte Issues, gruppiert Issues, die eine gemeinsame verifizierte Ursache haben, und empfiehlt einen priorisierten Ticketplan. Verändert weder Issues noch Tickets.

• /story bus / $story bus – pollt einen aufgabenbezogenen lokalen Bus-Endpunkt, damit ein Implementierer und ein unabhängiger Reviewer Befunde ohne Kopieren und Einfügen austauschen können.

• /story handover / $story handover – schreibt eine Sitzungsübergabe mit Entscheidungen, Blockern und nächsten Schritten.

Beide Clients unterstützen Kontextladen, autonomen Modus, MCP und Kompaktierungs-/Status-Hooks. Codex Desktop kann die zugehörige Aufgabe einer autonomen Sitzung öffnen und eine exakte Owner-Antwort an sie weiterleiten; Codex CLI fällt sicher auf einen manuellen Aufgabenwechsel zurück. Das autonome Code-Review hat standardmäßig ein 12-Runden-Landing-Limit (nach oben begrenzt durch das Ticketrisiko): ungelöste kritische Befunde und Ablehnungen blockieren weiterhin, während nicht blockierende Befunde am Limit zu Folge-Issues werden. Setzen Sie recipeOverrides.stages.CODE_REVIEW.maxReviewRounds auf 0, um das Limit explizit zu deaktivieren.

recipeOverrides.compactThreshold akzeptiert medium, high (Standard) oder critical. Der Wert bestimmt sowohl die Druckgrenzen als auch den Rotationsauslöser: medium verwendet niedrigere Grenzen und rotiert bei mittlerem Druck, während critical höhere Grenzen verwendet und auf kritischen Druck wartet. An einer sauberen COMPLETE-Grenze beendet Schwellendruck die begrenzte Sitzung über HANDOVER, weil Storybloq keinen Client-Kompaktierungsbefehl aufrufen kann. Wenn der Client selbst kompaktiert, bewahren die PreCompact- und SessionStart-Hooks dieselbe Sitzung; der Druck setzt sich erst zurück, nachdem SessionStart source: compact bestätigt.

Außerhalb des KI-Clients ist derselbe Zustand nur einen storybloq-Aufruf entfernt.

Automatische Fortsetzung bei Nutzungslimits

Claude-Code-Sitzungen stoppen bei Nutzungslimits („You've hit your usage limit"), und nächtliche autonome Arbeit stirbt still mit ihnen. Storybloq erkennt den Stopp über den StopFailure-Hook von Claude Code, parst die Reset-Zeit aus dem Sitzungstranskript, protokolliert den Stopp in einem globalen Ledger (~/.claude/storybloq/limit-ledger.json) und setzt die Sitzung fort, wenn das Limit zurückgesetzt wird. Standardmäßig aktiv, sobald Hooks installiert sind.

• Autonome Sitzungen werden auf derselben Wiederherstellungsspur wie die Kompaktierung geparkt und headless durch die vollständige Zustandsmaschine geweckt – Besitz-Neubindung, git-HEAD-Validierung und Wiederherstellungszuordnung gelten alle, sodass ein Aufwachen nach einer Arbeitsbereichsänderung validiert und nicht blind wiederholt wird. Sitzungen, die mitten in FINALIZE gestoppt wurden, werden nie automatisch fortgesetzt (Commit-Wiederholung ist nicht nachweislich sicher); stattdessen erhalten Sie eine Benachrichtigung mit manuellen Wiederherstellungsschritten.

• Normale Sitzungen erhalten bei Reset eine Desktop-Benachrichtigung mit dem exakten Befehl claude --resume. Projektweites Opt-in (limitResume.plainMode: "headless") weckt sie stattdessen headless.

• Die Berechtigungshaltung wird nie eskaliert. Eine Sitzung, die mit --dangerously-skip-permissions lief, wird nur dann mit diesem Flag geweckt, wenn das Projekt explizit zustimmt (limitResume.inheritBypass: true); andernfalls erfolgt eine Benachrichtigung.

Das Aufwachen wird von einem transienten, losgelösten Waker-Prozess gesteuert, nicht von einem Daemon: Er pollt das Ledger alle 30 Sekunden, setzt fort, was fällig ist (versuchsbegrenzt, gestaffelt, nebenläufigkeitsbegrenzt), und beendet sich, wenn nichts ansteht. Er überlebt Laptop-Schlaf, aber keinen Neustart oder Logout – nach einem Neustart startet ihn der nächste storybloq-Aufruf oder Hook-Fire in einem beliebigen Projekt neu, sodass wochenlange Wartezeiten bei Ihrer nächsten Aktivität wiederhergestellt werden. Dieser Kompromiss ist der Preis für „kein Daemon".

Inspizieren und verwalten Sie die Warteschlange mit storybloq limit-status (--cancel <key> zerstört eine ausstehende automatische Fortsetzung, --requeue <key> wiederholt einen zurückgestellten Datensatz). Global deaktivieren mit {"limitResume": {"enabled": false}} in ~/.claude/storybloq/config.json oder pro Projekt über limitResume in .story/config.json (auch maxAttempts, staggerMs, maxConcurrent, notify und mehr).

Vorarbeit: Der Erkennungs- und Neuparsing-Ansatz ist an unsnooze (MIT) angelehnt, das die transkriptbasierte Limiterkennung und Reset-Zeit-Analyse für tmux-gehostete Sitzungen Pionierarbeit leistete. Die Storybloq-Version lässt die tmux-Schicht zugunsten der dokumentierten Hook-Oberfläche weg und setzt autonome Sitzungen über ihre eigene Zustandsmaschine fort statt über Tastendrücke.

Storybloq Bus

Storybloq Bus ist ein optionales lokales Koordinationsprotokoll für eine Implementierer-Aufgabe und eine Reviewer-Aufgabe. Laufzeitstatus liegt unter gitignoriertem .story/bus/; bestätigte Befunde werden dennoch zu kanonischen Storybloq-Issues mit dauerhafter Quellenherkunft, bevor sie als Issue-Benachrichtigungen gesendet werden.

storybloq bus init
storybloq bus join implementer --client codex
storybloq bus join reviewer --client claude
storybloq bus hooks enable --client codex
storybloq bus hooks enable --client claude

Die Bus-Laufzeit ist lokal und gitignoriert, führen Sie also storybloq bus init einmal in jedem Checkout aus, das teilnehmen soll. Status und Doctor melden ein frisches Checkout als aktiviert, aber nicht initialisiert; dieser gesunde inaktive Zustand blockiert weder Commits noch autonomes FINALIZE. Andere Bus-Befehle und MCP-Werkzeuge initialisieren die Laufzeit nie implizit. Die Initialisierung lehnt symbolische Ignore-Dateien und Negationsmuster ab, weil sie nicht sicher beweisen kann, dass Git andernfalls die vollständige Laufzeit ausschließt.

Das Vordergrundprotokoll umfasst Senden, Pollen, Bestätigen, Thread-Zustand, Status, Doctor, Export und Ship-Prüfungen. Nachrichten sind hash-verkettet, idempotent, begrenzt, aufgabenbezogen, geheimnisgefiltert und werden über absturzwiederherstellbare Empfänger-Mailboxen zugestellt. Kritische Nachrichten erfordern standardmäßig ein passendes ungelöstes kritisches Issue. Bus-Text ist immer Peer-Agent-Beratung: Er gewährt niemals Owner-Genehmigung oder autorisiert Merge, Push, Signierung, Bereitstellung, Anmeldedaten, Ausgaben oder destruktive Aktionen.

V1 enthält keinen Daemon, kein Prozess-Spawning, keine headless Fortsetzung und kein automatisches Offline-Aufwachen als Bus-Zustellpfade. Natürliche SessionStart/Stop-Hooks und explizites Polling sind die Zustellpfade. Codex Desktop bleibt nicht aufweckbar. (Die automatische Fortsetzung bei Nutzungslimits oben ist eine begrenzte Ausnahme außerhalb des Busses: Ihr transienter Waker stellt limitgestoppte Sitzungen wieder her und ist kein Nachrichtenzustellpfad.)

Föderation

Föderation koordiniert die Arbeit von KI-Agenten über mehrere Repos hinweg. Ein Projekt wird zum Orchestrator. Es deklariert, welche Repos (Knoten) Teil des Systems sind, wie sie voneinander abhängen und wie sie zur Laufzeit kommunizieren. Jeder Knoten führt sein eigenes .story/ mit eigenen Tickets, Issues und Übergaben. Der Orchestrator liest über alle hinweg.

# Create an orchestrator
storybloq init --type orchestrator --name "my-platform"

# Register nodes
storybloq node add api --path ../api --stack typescript --role "REST backend"
storybloq node add web --path ../web --stack nextjs --depends-on api
storybloq node add sdk --path ../sdk --stack typescript

Drei Beziehungstypen verbinden Knoten:

• dependsOn in der Knotenkonfiguration: Kanten für die Build-Reihenfolge. Die Web-App hängt von der API ab.

• links in der Knotenkonfiguration: Laufzeitintegration. Die Web-App ruft die API über HTTP auf.

• crossNodeBlockedBy bei Tickets: Ein Ticket in einem Repo ist blockiert, bis ein Ticket in einem anderen Repo abgeschlossen ist. Beispiel: "crossNodeBlockedBy": ["api:T-012"].

Vom Orchestrator-Verzeichnis aus:

storybloq status              # aggregated view across all nodes
storybloq recommend           # federation-aware suggestions (bottlenecks, stale nodes, blockers)
storybloq ticket list --node api   # list tickets in the api node without cd-ing

Die Empfehlungs-Engine erzeugt föderationsspezifische Vorschläge: Knoten, die nachgelagerte Arbeit blockieren, Engpass-Knoten, von denen viele andere abhängen, Knoten ohne Übergabe seit zwei Wochen. Tickets mit crossNodeBlockedBy-Referenzen tauchen in Empfehlungen erst auf, wenn das blockierende Ticket abgeschlossen ist.

CLI-Referenz

Alle Befehle akzeptieren --format json|md (Standard: md). Für Skriptzwecke JSON durch jq leiten, die Markdown-Variante direkt lesen.

Projekt

Phasen

Tickets

Issues

Notizen und Lektionen

Übergaben, Blocker, Snapshots

Storybloq Bus (Opt-in)

Föderation (Orchestrator-Projekte)

Team (Team-Modus-Projekte)

Siehe Team-Modus für das Merge-Modell, auf dem diese Befehle basieren.

MCP-Server-Referenz

Bei Claude Code oder Codex registrieren (wird vom Setup automatisch erledigt):

claude mcp add storybloq -s user -- storybloq --mcp
codex mcp add storybloq --env STORYBLOQ_CLIENT=codex -- storybloq --mcp

Der Server importiert dieselben TypeScript-Module wie die CLI direkt, sodass kein Subprozess-Overhead entsteht. Er erkennt das Projektstammverzeichnis automatisch, indem er vom Arbeitsverzeichnis aus zum nächstgelegenen .story/-Übergeordneten aufsteigt.

Die Basistools sind nach Verantwortlichkeit gruppiert. Bus-fähige Projekte registrieren beim MCP-Prozessstart fünf zusätzliche Tools; starten Sie verbundene Clients nach storybloq bus init neu.

Lesen (keine Seiteneffekte)

storybloq_status · storybloq_phase_list · storybloq_phase_current · storybloq_phase_tickets · storybloq_ticket_list · storybloq_ticket_get · storybloq_ticket_meta_get · storybloq_ticket_next · storybloq_ticket_blocked · storybloq_issue_list · storybloq_issue_get · storybloq_issue_meta_get · storybloq_note_list · storybloq_note_get · storybloq_lesson_list · storybloq_lesson_get · storybloq_lesson_digest · storybloq_handover_list · storybloq_handover_latest · storybloq_handover_get · storybloq_blocker_list · storybloq_validate · storybloq_recap · storybloq_recommend · storybloq_export · storybloq_selftest

Schreiben (verändert .story/)

storybloq_snapshot · storybloq_handover_create · storybloq_ticket_create · storybloq_ticket_update · storybloq_ticket_meta_set · storybloq_ticket_meta_unset · storybloq_issue_create · storybloq_issue_update · storybloq_issue_meta_set · storybloq_issue_meta_unset · storybloq_note_create · storybloq_note_update · storybloq_lesson_create · storybloq_lesson_update · storybloq_lesson_reinforce · storybloq_phase_create

Autonomer Modus + Review + Beobachtbarkeit

storybloq_autonomous_guide steuert die autonome Zustandsmaschine (PICK_TICKET -> PLAN -> PLAN_REVIEW -> WRITE_TESTS -> IMPLEMENT -> TEST -> CODE_REVIEW -> FINALIZE -> COMPLETE).

storybloq_review_lenses_prepare · storybloq_review_lenses_judge · storybloq_review_lenses_synthesize orchestrieren die Multi-Lens-Review-Schleife (erfordert @storybloq/lenses).

storybloq_session_report · storybloq_register_subprocess · storybloq_unregister_subprocess zeigen den Session-Status in der Mac-App an.

Storybloq Bus (feature-gesteuert)

storybloq_bus_send · storybloq_bus_poll · storybloq_bus_ack · storybloq_bus_thread_get · storybloq_bus_thread_update

Jeder Aufruf erfordert eine stabile Endpunkt-ID und die aktuelle validierte Client-Task-ID. Poll- und Thread-Ausgaben kennzeichnen Peer-Inhalte als beratende Autorität. storybloq_bus_poll und storybloq_bus_thread_get sind in Bezug auf den kanonischen, verfolgten Projektzustand schreibgeschützt; Poll kann gitignorierte .story/bus/-Laufzeitmetadaten abgleichen. Die anderen drei behalten normale MCP-Schreibfreigaben.

Federation (Orchestrator-Projekte)

storybloq_node_init bootet .story/ in einem Node-Repository aus dem Orchestrator-Kontext.

storybloq_node_add · storybloq_node_list · storybloq_node_update verwalten die Node-Registry des Orchestrators.

Hooks

PreCompact (Kompaktierungsvorbereitung, vom Setup eingerichtet)

Führt storybloq session compact-prepare vor der Kontextkompaktierung aus, damit Snapshots und Resume-Breadcrumbs aktuell bleiben, wo der Client PreCompact-Hooks unterstützt. Das Codex-Setup verwendet storybloq session compact-prepare --client codex mit einem manual|auto-Matcher, sodass ein Codex-Hook keine Claude-gehörige Session kompaktieren kann; das Claude-Code-Setup lässt den Matcher leer.

{
  "hooks": {
    "PreCompact": [{
      "matcher": "manual|auto",
      "hooks": [{ "type": "command", "command": "storybloq session compact-prepare" }]
    }]
  }
}

Überspringen mit storybloq setup --client all --skip-hooks.

SessionStart (Resume-Prompt-Injektion)

Injiziert einen kompaktierungsbewussten Resume-Prompt. Das Codex-Setup verwendet denselben Befehl mit --codex-hook-json und dem Matcher startup|resume|clear|compact; sein Hook-JSON enthält auch die aktuelle Task-ID, sodass eine COMPACT-Wiederherstellung derselben Task ohne kopiertes/eingefügtes Resume-Token fortgesetzt werden kann. Die Hook-Vertrauenswürdigkeit kann vom Setup nicht überprüft werden; prüfen Sie nach der Installation /hooks in Codex.

{
  "hooks": {
    "SessionStart": [{
      "matcher": "compact",
      "hooks": [{ "type": "command", "command": "storybloq session resume-prompt" }]
    }]
  }
}

storybloq bus hooks enable ist ein separates projektweites Opt-in. Es fügt SessionStart Endpunktmetadaten und die Anzahl ausstehender Nachrichten hinzu und erlaubt dem synchronen Stop-Hook, einmal pro neuem Mailbox-Cursor zu blockieren. Peer-Payload-Bytes erscheinen nie in der Hook-Ausgabe. Claudes gemeinsame Hook-Struktur wird einmal aktualisiert und bleibt durch projektlokale Richtlinien geschützt; Codex verwendet storybloq hook-status --client codex.

Stop (Live-Status für die Mac-App)

Führt am Ende jedes Turns storybloq hook-status aus und aktualisiert die gitignorierte .story/status.json, die die Mac-App und die iOS-Begleit-App für den Live-Session-Status lesen.

Der Schreibvorgang ist inhaltsgesteuert: Wenn die Payload identisch mit dem ist, was die Datei bereits enthält (unter Ignorierung des Beobachtungszeitstempels und des erzeugenden Schreibers), wird nichts geschrieben und die Zeitstempel und der Inode der Datei bleiben unverändert. Leerlauf-Turns lassen den Arbeitsbaum daher völlig unberührt. Echte Änderungen – ein Workflow-Übergang, ein neuer MCP-Aufruf, eine Health- oder Lease-Änderung – werden weiterhin sofort geschrieben.

Projekte, deren Test-Harness jeden Schreibvorgang während eines Laufs als Fehler behandelt, können den Schreiber am Turn-Ende vollständig deaktivieren:

{ "statusWriter": { "stopHook": false } }

in .story/config.json. Der Hook führt dann überhaupt keine Statusarbeit aus: kein Session-Scan, kein Payload-Aufbau, keine Gitignore-Selbstheilung, kein Schreiben. Autonome Sessions aktualisieren den Status weiterhin bei ihren eigenen MCP-Übergängen, sodass die Mac-App während einer laufenden Session weiterhin den Live-Status anzeigt – sie aktualisiert nur nicht mehr zwischen Turns normaler interaktiver Arbeit. Das Flag ist standardmäßig aktiviert, und jede unlesbare oder fehlerhafte Konfiguration lässt es aktiviert.

StopFailure (Nutzungslimit-Erkennung)

Führt storybloq session limit-stop aus, wenn eine Claude-Code-Session aufgrund eines Ratenlimits stoppt, und zeichnet den Stopp für die Auto-Fortsetzung auf (siehe Nutzungslimit-Auto-Fortsetzung oben). Das Setup fügt außerdem eine zweite SessionStart-Matchergruppe ("resume") mit demselben Befehl session resume-prompt hinzu, sodass ein manuelles Wiederöffnen einer limitgestoppten Session limitbewusste Anleitung erhält. Beide Einträge sind nur für Claude, werden bei jedem Upgrade abgeglichen und automatisch entfernt, wenn der globale Kill-Switch gesetzt ist.

{
  "hooks": {
    "StopFailure": [{
      "matcher": "rate_limit",
      "hooks": [{ "type": "command", "command": "storybloq session limit-stop" }]
    }]
  }
}

Bibliotheksnutzung

import { loadProject } from "@storybloq/storybloq";

const { state, warnings } = await loadProject("/path/to/project");
console.log(state.tickets.length);           // all tickets
console.log(state.phaseTickets("p1"));       // leaf tickets in phase p1
console.log(state.umbrellaChildren("T-014")); // children of an umbrella

Vollständige Typdefinitionen werden mit dem Paket geliefert (exports.types).

Beispiele für Dateiformate

Ticket (.story/tickets/T-001.json):

{
  "id": "T-001",
  "title": "Add search to sidebar",
  "type": "task",
  "status": "inprogress",
  "phase": "p2",
  "order": 10,
  "description": "Fuzzy match over ticket title + description.",
  "createdDate": "2026-04-12",
  "completedDate": null,
  "blockedBy": [],
  "parentTicket": null,
  "crossNodeBlockedBy": []
}

Issue (.story/issues/ISS-001.json):

{
  "id": "ISS-001",
  "title": "Drag handle hit target too small on trackpad",
  "status": "open",
  "severity": "medium",
  "components": ["mac-app"],
  "impact": "Dragging tickets on trackpad requires multiple tries.",
  "location": ["macos/Views/KanbanCard.swift:42"],
  "sourceRefs": [{
    "path": "macos/Views/KanbanCard.swift",
    "startLine": 42,
    "revision": "5ac37f94f7023b18f72d8e3fcf43dd64f54c11d7",
    "contentHash": "f5b1b1b65dca3d9d86adf7c5d49082aa4dc09e7903ab46ce50e8cc6b4812e4cf",
    "reviewId": "review-2026-04-15"
  }],
  "dedupeKey": "review-2026-04-15:finding-3",
  "createdBy": "external-reviewer",
  "discoveredDate": "2026-04-15",
  "resolvedDate": null,
  "relatedTickets": []
}

Jeder Datensatz ist eine eigene Datei. IDs sind innerhalb eines Typs sequenziell (T-001, T-002, ...). Beziehungen haben einen einzigen kanonischen Eigentümer: Das blockedBy-Feld eines Tickets zeigt auf blockierende Tickets, und die Umkehrung (wer blockiert mich) wird durch Scannen abgeleitet.

Erstellungsvorgänge können sicher parallel ausgeführt werden. ID-Vergabe und der Erstellungsschreibvorgang erfolgen gemeinsam unter einer Projektsperre, sodass gleichzeitige Ersteller serialisiert werden und jeweils eine eindeutige sequenzielle ID erhalten. Eine Erstellung kann niemals stillschweigend einen vorhandenen Datensatz überschreiben; bei starker gleichzeitiger Konkurrenz schlägt ein Ersteller laut mit einem Fehler fehl, anstatt zu kollidieren.

Die sourceRefs eines Issues bewahren Review-Nachweise unabhängig von veränderlichen path:line-Anzeigezeichenfolgen. Storybloq hasht nur den normalisierten referenzierten Zeilenbereich und speichert niemals Quellauszüge. Eine gelieferte Revision wird zu einem Git-Commit aufgelöst; andernfalls erfasst Storybloq den Arbeitsbaumbereich und zeichnet HEAD nur auf, wenn diese Bytes übereinstimmen. storybloq validate meldet einen Fehler, wenn der ursprüngliche Nachweis nicht aufgelöst werden kann, eine Warnung, wenn gültiger historischer Nachweis bei HEAD verschoben oder geändert wurde, und keinen Befund, wenn er noch übereinstimmt.

Verwenden Sie storybloq validate --integrity-only, wenn beschädigtes config.json oder roadmap.json das normale Laden verhindert. Dieser schreibgeschützte Preflight scannt in einem Durchgang jede .story/**/*.json-Datei, meldet verfügbare Parserpositionen und trennt kritische Singleton-Fehler von überspringbaren Item- und Hilfsdateifehlern. Er schreibt beschädigte Dateien nie neu.

Bestätigte manuelle oder externe Review-Befunde sollten direkt als offene Issues erfasst werden. Suchen Sie zuerst, geben Sie die Reviewer-Zuordnung in createdBy an, hängen Sie Review-ID und Revision über sourceRefs an und verwenden Sie einen stabilen dedupeKey wie <review-id>:<finding-id>, damit Wiederholungen idempotent sind. Behalten Sie unsichere Designfragen als Notizen oder Owner-Fragen; der implementierende Agent ist für Status und Auflösung des Issues verantwortlich.

Ticket- und Issue-Datensätze bewahren unbekannte JSON-Felder. Verwenden Sie storybloq ticket meta und storybloq issue meta, um diese benutzerdefinierten Passthrough-Felder zu lesen oder zu ändern, ohne die zentralen Storybloq-Felder anzutasten. Werte sind JSON, und Punktpfade adressieren verschachtelte Objekte, zum Beispiel storybloq ticket meta set T-001 integration.linear '"ABC-123"'.

Die Tiefe der autonomen Plan-Review kann pro Ticket über die Metadaten reviewRisk (low, medium oder high) festgelegt werden. Beispielsweise erfordert storybloq ticket meta set T-001 reviewRisk '"high"' mindestens drei Plan-Review-Runden. Die älteren Metadaten risk werden ebenfalls erkannt, aber reviewRisk ist der kanonische Schlüssel. Diese Einstellung ändert nur die Review-Tiefe; sie überspringt niemals eine Review-Stufe.

Beispiel-Workflow

# Initialize
storybloq init --name "my-app"

# Add the first phase
storybloq phase create --id bootstrap --name "Bootstrap" --label "PHASE 1" \
  --description "Get the app running end-to-end"

# Add a ticket
storybloq ticket create --title "Scaffold Next.js" --type task --phase bootstrap

# Start Claude Code and type /story, or invoke $story in Codex, then work on it
# (or go autonomous: /story auto T-001 / $story auto T-001)

# At the end of a session, commit your changes including .story/
git add .
git commit -m "T-001: scaffold Next.js"

# Session ends. Next session starts with /story or $story and picks up with full context.

Team-Modus

.story/ ist einfaches, von git verwaltetes JSON. Ein Team, das es gemeinsam nutzt, stößt daher auf dieselben zwei Probleme wie bei jedem gemeinsamen Zustand: gleichzeitige Änderungen an demselben Datensatz und gleichzeitige Erstellung neuer Datensätze. Der Team-Modus adressiert beides.

storybloq team init     # once per project; commit the result
storybloq team setup    # once per clone, by every teammate

team init konfiguriert das Projekt für Teamarbeit (Schema-Version, Anspruchs-Verfall, ID-Allokator, erforderliche Client-Funktionen) und führt die Einrichtung für deinen eigenen Klon aus. team setup installiert den storybloq-json-Git-Merge-Treiber in die lokale Git-Konfiguration des Klons und schreibt .story/.gitattributes, sodass .story/-JSON-Dateien darüber verarbeitet werden. Die Git-Konfiguration ist pro Klon, daher führt jeder Teammitglied setup einmal pro Checkout aus. storybloq team doctor prüft die gesamte Einrichtung (doppelte Anzeige-IDs, ungelöste Konflikte, veraltete Ansprüche, installierter Merge-Treiber) und beendet sich mit --ci bei Fehlern mit einem Nicht-Null-Exit-Code; siehe Team-CI unten für den Merge-Gate-Workflow.

Gleichzeitige Änderungen: das Merge-Modell

Wenn git zwei Branches zusammenführt, die beide denselben .story/-Datensatz verändert haben, führt der Merge-Treiber einen strukturierten Drei-Wege-Merge pro Datensatz durch, statt eines zeilenbasierten Text-Merges. Felder werden unabhängig zusammengeführt: Wenn ein Teammitglied den status eines Tickets ändert, während ein anderes die description bearbeitet, landen beide Änderungen. Wenn dasselbe Feld auf beiden Seiten divergiert, wählt der Treiber keines von beiden. Er zeichnet die Divergenz als strukturierten _conflicts-Block innerhalb des Datensatzes auf, sodass die Datei gültiges JSON ohne Konfliktmarker bleibt; git meldet den Pfad trotzdem als konflikthaft, also git add die Datei und committe, um den Merge abzuschließen, und löse dann die aufgezeichneten Konflikte in deinem eigenen Tempo (sie werden über spätere Merges hinweg mitgeführt, bis sie gelöst sind). Ein Projekt mit ungelösten _conflicts ist schreibgesperrt, bis jeder Konflikt gelöst ist:

storybloq conflicts list                     # every item with unresolved conflicts
storybloq conflicts show T-042               # field-level detail: base, ours, theirs
storybloq resolve T-042 --field status --use theirs
storybloq resolve T-042 --field title --value '"Merged title"'
storybloq resolve config                     # config.json merges the same way
storybloq resolve roadmap                    # so does roadmap.json

Gleichzeitige Erstellung: Anzeige-ID-Kollisionen

Zwei Teammitglieder, die auf parallelen Branches Elemente erstellen, sind ein anderer Fehlermodus. Neue Datensätze werden unter einem zufälligen kanonischen ID-Dateinamen gespeichert (z. B. t-8f2kq0v3n1xw9d4e.json), sodass unabhängig erstellte Elemente auf Dateiebene nie kollidieren; nur ältere sequenzielle Dateinamen (ISS-041.json, aus Projekten, die vor kanonischen IDs existierten) können weiterhin Pfadkollisionen verursachen. Was kollidieren kann, ist die menschenlesbare Anzeige-ID: Beide Branches berechnen lokal die „nächste freie Nummer" und beide erzeugen T-042. Das ist kein Merge-Konflikt, sondern ein Duplikat, und es hat sein eigenes Werkzeug:

storybloq reconcile          # renumber duplicates; the copy already on the protected ref, else the earlier one, keeps the number
storybloq reconcile --ci     # detect only: exit non-zero if duplicates exist, mutate nothing

Umnummerierte Elemente behalten ihre alte Anzeige-ID in previousDisplayIds, sodass bestehende Verweise auf die alte Nummer weiterhin aufgelöst werden.

Auswahl eines ID-Allokators

team init --id-allocator local|git-refs bestimmt, wie Anzeige-IDs vergeben werden. Der Kompromiss:

Mit git-refs fügt team init außerdem remote-ref-reservations zu team.requiredFeatures hinzu, sodass Clients, die diese Fähigkeit nicht deklarieren, sich weigern, Elemente zu erstellen, statt lokal gegen ein git-refs-Team zu allokieren und zu kollidieren. Ein Hinweis: Aktuelle Mac-App-Versionen stammen aus der Zeit vor Reservierungen, deklarieren die Fähigkeit aber dennoch. Bis das Mac-Update ausgeliefert ist, solltest du vermeiden, Elemente aus der Mac-App in git-refs-Teams zu erstellen. storybloq team reserve tickets --count 5 reserviert einen Stapel von IDs im Voraus.

Schema-Version und ältere Clients

team init stempelt schemaVersion: 3 in .story/config.json. CLI-Versionen vor 1.5.0 verweigern ein Projekt mit schemaVersion 3 sauber, sowohl für Lese- als auch für Schreibvorgänge, mit einer Upgrade-Meldung (Config schemaVersion 3 exceeds max supported 2. Run: npm update -g @storybloq/storybloq). Der harte Fehlschlag ist beabsichtigt: Diese Clients verstehen Team-Modus-Daten nicht, und in Teams mit gemischten Versionen erzeugten sie zuvor stille partielle Lesevorgänge statt eines Fehlers.

Team-Repos, die vor der Sperre erstellt wurden, tragen schemaVersion: 2. Um ein bestehendes Team-Repo zu aktualisieren: Warte, bis jedes Teammitglied eine CLI 1.5.0+ ausführt, und setze dann schemaVersion manuell auf 3 (oder führe storybloq team init erneut aus, das dasselbe Upgrade durchführt). Ältere Mac-App-Builds zeigen ein Projekt mit schemaVersion 3 bis zum Update als schreibgeschützt an; es gehen keine Daten verloren.

Aktualisieren eines Repos, das älter als .story/.gitignore ist

team init und team setup schreiben .story/.gitignore, das die maschinenlokalen Dateien abdeckt (sessions/, snapshots/, status.json, federation-cache.json, channel-inbox/). Eine Gitignore entfernt keine bereits verfolgten Dateien aus der Verfolgung. Ein Projekt, das storybloq vor der Existenz der Gitignore eingeführt hat, kann daher bereits flüchtige Dateien in der Git-Historie haben. Prüfe einmal und entferne sie aus der Verfolgung:

git ls-files .story/ | grep -E 'sessions/|snapshots/|status\.json|federation-cache\.json|channel-inbox/'
git rm -r --cached --ignore-unmatch .story/sessions .story/snapshots .story/status.json .story/federation-cache.json .story/channel-inbox

Commite die Entfernung. Sitzungszustände zeichnen absolute Pfade auf (einschließlich deines Benutzernamens), daher lohnt sich dies vor dem ersten gemeinsamen Push.

Löschungen hinterlassen Grabsteine

Das Löschen eines Tickets, Issues, einer Notiz oder einer Lektion im Team-Modus entfernt es nicht aus dem gemeinsamen Repo. Die Datei bleibt erhalten, mit ihrem vollständigen ursprünglichen Inhalt, plus einem Lebenszyklus-Marker: lifecycle: "deleted", einem deletedAt-Zeitstempel und deletedBy, gesetzt auf die Git-user.email des Löschers. Das Auflösen eines Lösch-gegen-Bearbeitung-Konflikts kann ebenfalls die E-Mail des Auflösers als deletedBy auf einem synthetisierten Grabstein stempeln. Grabsteine bleiben im Repo, bis jemand storybloq gc --apply ausführt (Standard-Aufbewahrung: 30 Tage).

Die Kernaussage: Das Löschen eines Elements blendet es aus normalen Ansichten aus, entfernt aber weder den Inhalt noch deinen Identitätsstempel aus den Klonen der Teammitglieder. Führe storybloq gc aus, um in Frage kommende Grabsteine zu prüfen, und dann storybloq gc --apply, um sie zu entfernen, sobald sie die Aufbewahrungsfrist überschritten haben.

Was dein Team sieht

Der Team-Modus teilt den Zustand über das Repo, daher ist alles, was unter .story/ committet wird, für alle mit Repo-Zugriff sichtbar:

• Tickets, Issues, Notizen und Lektionen, einschließlich aller Freitextfelder.

• Übergaben: narrative Sitzungsdokumente, oft die detaillierteste Aufzeichnung dessen, was passiert ist und warum.

• Anspruchsblöcke auf in Bearbeitung befindlichen Elementen: die Git-Identität des Anspruchstellers (user.email), der Branchname und der Anspruchszeitstempel, plus eine claimedBySession-UUID, während eine autonome Sitzung an dem Element arbeitet.

• Ungelöste Merge-Konflikte: Nach einem divergenten Merge trägt der betroffene Datensatz die konfligierenden Werte beider Seiten (Basis, unser, deren) in seinem _conflicts-Block, bis jemand sie auflöst. Text, den ein Teammitglied geschrieben hat, der aber später in der Schlichtung verloren ging, bleibt bis zur Auflösung in der Datei sichtbar.

Die maschinenlokalen Dateien bleiben außerhalb des Repos, sobald die Gitignore eingerichtet ist: sessions/ (autonomer Sitzungszustand, einschließlich des events.log jeder Sitzung), snapshots/, status.json, federation-cache.json und channel-inbox/. Behandle committete .story/-Inhalte mit derselben Sorgfalt wie Commit-Meldungen und Code-Kommentare; sie reisen mit dem Repo.

Team-CI

Für Team-Modus-Projekte füge CI-Validierung hinzu, um doppelte displayIds und veraltete Referenzen vor dem Merge zu erkennen. Siehe TEAM_CI.md für einen einsatzbereiten GitHub-Actions-Workflow.

Verwandte Projekte

• @storybloq/lenses – MCP-Server und -Bibliothek für Multi-Lens-Code-Review. 9 spezialisierte Reviewer laufen parallel und liefern strukturierte Urteile; das autonome storybloq-Lens-Backend konsumiert es direkt.

• Storybloq für Mac – native macOS-App, die .story/ überwacht und live aktualisiert, während dein KI-Client arbeitet. Kostenlos im Mac App Store.

Support

Schreibe an shayegh@me.com für alles: Einrichtungsprobleme, Fragen, Feature-Wünsche oder einfach, um zu erzählen, was du baust. Fehlerberichte sind auch als GitHub-Issues willkommen.

Mitwirken

Issues und PRs sind willkommen. Für nicht-triviale Änderungen öffne zuerst ein Issue, damit wir die Richtung abstimmen können.

Entwicklungseinrichtung:

git clone https://github.com/Storybloq/storybloq.git
cd storybloq
npm install
npm test
npm run build

Lizenz

PolyForm Shield 1.0.0 – eine quellverfügbare, nicht-konkurrierende Lizenz (keine OSI-Open-Source-Lizenz).

Du darfst storybloq für jeden Zweck verwenden, einschließlich:

• persönliche und Hobby-Projekte

• Open-Source-Projekte

• interne Unternehmensnutzung

• kommerzielle Software, die du entwickelst

Ohne separate Lizenz darfst du storybloq nicht verwenden, um ein Produkt zu entwickeln, das damit konkurriert: Neuverpackung, Weiterverkauf, Hosting als verwalteter Dienst oder White-Labeling. Dafür kontaktiere shayegh@me.com.

Siehe LICENSE für den vollständigen Text und NOTICE für den erforderlichen Urheberrechtshinweis, den du bei Weiterverbreitung beifügen musst.