Dokumentation

Leitfäden und die vollständige Befehlsreferenz für nxf — immer synchron mit der ausgelieferten Version.v0.27.0

Erste Schritte

nxf ist die nexus-flow Agent-CLI: eine schlanke, deterministische, offline-first Schnittstelle über dem Engine-Kern. Dieser Leitfaden führt Sie von einem leeren Verzeichnis zu einer geplanten, nachverfolgten Arbeitseinheit. Jeder Befehl unterstützt --json für maschinenlesbare, byte-stabile Ausgabe — das ist der Vertrag, auf dem Agenten aufbauen.

Installation

Laden und installieren Sie das neueste Release mit dem Installationsskript:

curl -fsSL https://nxf.nxsflow.com/install.sh | sh

Es erkennt Ihre Plattform, verifiziert den Download (sha256 + Signatur) und legt die drei Suite-Binaries in Ihrem PATH ab: `nxf` (den Issue-Tracker), `nxm` (dauerhaftes Agenten-Gedächtnis) und `nxs` (das Umbrella, das sie zusammenführt). Sie installieren einmal und entscheiden pro Workspace, welche Tools Sie aktivieren. Prüfen Sie es:

nxf --version

Einen Workspace initialisieren

Ein Workspace ist ein .nxs/-Verzeichnis in Ihrem Projekt — ein geteilter Speicher, in den jedes aktivierte Tool schreibt. Am schnellsten richten Sie ihn über das Umbrella ein, das fragt, welche Tools Sie nutzen wollen, und alles verdrahtet:

nxs init

Es assembliert die geteilten Agent-Dateien und setzt einen einzelnen nxs prime-SessionStart-Hook, sodass Ihr Agent ab dann den Kontext jedes aktiven Tools mit einem Aufruf lädt (siehe Das nxs-Umbrella). Für einen Agenten oder ein Skript ist es nicht-interaktiv — nxs init --module flow --module memory (oder --json) richtet denselben Stand ohne Prompt ein.

Wenn Sie nur den Issue-Tracker wollen, initialisieren Sie ihn direkt. Das ist eine bewusste Plugin-Wahl — es gibt keine Voreinstellung, denn das Plugin bestimmt das Vokabular, das Sie lesen und schreiben (siehe Plugins). Für Softwarearbeit wählen Sie issue-tracker:

nxf init --plugin issue-tracker

Beide Wege landen auf demselben .nxs/-Workspace und demselben nxs prime-Hook. Jede id in diesem Workspace wird unter einem kurzen, stabilen Namensraum namens prefix vergeben (die Beispiele unten verwenden ab12). Führen Sie nxf init --help aus, um die verfügbaren Plugins und ihre Beschreibungen zu sehen.

Ihre ersten Items erstellen

Items sind Projekte und Tasks. Erstellen Sie ein Projekt, um die Arbeit zu gruppieren, dann die Tasks darunter. Der --json-Datensatz ist die kanonische Form — beachten Sie die Feldnamen auf Engine-Ebene (type, belongs_to, status), die sich unabhängig vom aktiven Plugin nie ändern:

$ nxf create --type epic --title "Ship v1" --description "Cut the first release" --priority P1 --json
{"archived":null,"assignee":null,"belongs_to":null,"closed_at":null,"closing_comment":null,"completion_criterion":null,"defer_until":null,"deleted":null,"description":"Cut the first release","design":null,"due":null,"id":"ab12.0001","priority":"1","status":"open","title":"Ship v1","type":"epic"}

$ nxf create --type feature --title "Write the CLI" --description "Build the command-line tool" --priority P1 --due 2026-12-31 --parent ab12.0001 --json
{"archived":null,"assignee":null,"belongs_to":"ab12.0001","closed_at":null,"closing_comment":null,"completion_criterion":null,"defer_until":null,"deleted":null,"description":"Build the command-line tool","design":null,"due":"2026-12-31","id":"ab12.0002","priority":"1","status":"open","title":"Write the CLI","type":"feature"}

Der neue Task belongs_to das Projekt (über --parent), hat ein Fälligkeitsdatum und trägt Priorität 1.

Sehen, woran zu arbeiten ist

Zustände wie *ready* und *next* sind abgeleitet, nie gespeichert (siehe Kernkonzepte). Da nichts es blockiert, ist die Arbeit ready, und next ordnet sie nach der Policy des Plugins. Die menschliche Ansicht spricht das issue-tracker-Vokabular — P1, open:

$ nxf next

0001  P1  open  [epic]  Ship v1
0002  P1  open  [feature]  Write the CLI
    ↳ 0001 · Ship v1

Das ist die gesamte Schleife: einmal init, Arbeit create, dann ready/next Ihnen sagen lassen, wohin es geht. Lesen Sie von hier aus Kernkonzepte für das Modell, oder Befehle für eine vollständige Arbeitssitzung.

Das nxs-Umbrella

nxs ist das Plattform-Umbrella über der Suite. Dieselbe Installation liefert alle drei Binaries; nxs führt zusammen, was Sie in einem Workspace aktivieren — über den einen geteilten .nxs/-Speicher:

nxs init — die Suite einrichten: wählen, welche Tools genutzt werden (interaktiv, oder

--module …/--json für einen Agenten), die geteilten Agent-Dateien assemblieren und den einzelnen nxs prime-Hook verdrahten.

nxs prime — das Session-Bootstrap, das der Hook ausführt: es fächert an das prime jedes

aktiven Tools mit einer geteilten Uhr aus und hängt die Ergebnisse aneinander. Ein flow-only- Workspace liefert genau flows prime; memorys kommt dazu, sobald Sie es hinzufügen.

nxs sync bind / nxs sync run — den geteilten Speicher mit einem Relay synchronisieren (ein

Op-Log, also ist Synchronisieren eine Plattform-Operation, keine pro-Tool-Operation).

nxs migrate — den Workspace auf das aktuelle Schema heben und einen vor-v0.6.0-Workspace auf

das Umbrella-Modell aktualisieren (es schreibt einen alten nxf prime-Hook auf nxs prime um). Idempotent.

nxs doctor (Alias nxs status) — eine tool-übergreifende Diagnose: aktive Module,

Schema-Version, Replica-Identität, Sync-Status und Speicher-Integrität.

Jedes Tool behält seinen eigenen gebrandeten Init, wenn Sie es direkt tippen (nxf init, nxm init); alle landen auf demselben .nxs/-Speicher und demselben einzelnen nxs prime-Hook.

Einen MCP-Host verbinden

MCP-native Hosts — Claude Desktop, Claude Code, Cursor, Windsurf — können die nxf-CLI nicht bedienen, deshalb liefert nexus-flow einen MCP-Server (nxs mcp serve), der die Lese- und Schreiboperationen Ihres Boards als MCP-Tools über denselben geteilten .nxs/-Store bereitstellt. Dieser Leitfaden verbindet einen Host damit — auch für den Fall, dass noch nichts installiert ist.

Eine Host-Konfiguration startet nur einen *Befehl*. Einen Host zu verbinden sind also zwei Entscheidungen: welcher Befehl den Server startet und welchen Workspace er öffnet.

Der schnellste Weg: der `npx`-Runner (ohne Installation)

Wenn Sie Node haben (die meisten Rechner haben es), müssen Sie nichts vorab installieren. Verweisen Sie den Host auf den @nexus-flow/mcp-Runner — er lädt das signierte nxs, verifiziert es, cached es und startet den Server beim ersten Start.

Für Claude Desktop fügen Sie dies in claude_desktop_config.json ein und starten neu:

{
  "mcpServers": {
    "nxs": {
      "command": "npx",
      "args": ["-y", "@nexus-flow/mcp"]
    }
  }
}

Das bedient Ihr Standard-Board — einen nutzereigenen Workspace, den nexus-flow beim ersten Start automatisch anlegt (denselben, den die nexflow.it-Desktop-App nutzt, sodass Sie in beiden dasselbe Board sehen). Um ihn stattdessen auf ein bestimmtes Projekt zu richten, hängen Sie den Workspace nach -- an:

{
  "mcpServers": {
    "nxs": {
      "command": "npx",
      "args": ["-y", "@nexus-flow/mcp", "--", "--workspace", "/absoluter/pfad/zu/ihrem/projekt"]
    }
  }
}

Alles nach -- wird direkt an nxs mcp serve durchgereicht. Der erste Start lädt und verifiziert nxs (ein paar Sekunden); spätere Starts nutzen den Cache und starten sofort, auch offline.

Wenn Sie `nxs` bereits haben: `nxs mcp install`

Mit nxs auf Ihrem PATH registriert ein Befehl den Server in jedem installierten Host für Sie — ohne JSON von Hand zu bearbeiten:

nxs mcp install

Es schreibt einen idempotenten Eintrag, der den absoluten Pfad Ihres nxs-Binaries plus mcp serve nennt, und patcht Claude Desktop, Cursor und Windsurf, sofern gefunden (ein erneuter Lauf ändert nichts). Mit --setup wird im selben Schritt auch das Board angelegt — ein Befehl, der den Server registriert und den Workspace erzeugt, den er öffnet:

# Registrieren + personal-todo-Board am nutzereigenen Standard anlegen (Default für Wissensarbeit):
nxs mcp install --setup

# Registrieren + Coding-Board an dieses Projekt gepinnt anlegen:
nxs mcp install --setup --workspace "$PWD" --plugin issue-tracker

Um statt des direkten Binärpfads den portablen, maschinenunabhängigen npx-Eintrag von der Kommandozeile aus zu schreiben, fügen Sie --runner npx hinzu.

Den Workspace wählen

Da ein Host kein Arbeitsverzeichnis hat, kann der Server „dieses Projekt" nicht erraten — Sie sagen, welches Board er öffnet:

`--workspace` weglassen → der nutzereigene Standard-Workspace, beim ersten Start automatisch

angelegt. Ideal für ein einzelnes persönliches Board, geteilt über Ihre Hosts und die Desktop-App.

`--workspace <absoluter-pfad>` → das Board dieses Projekts. Legen Sie es zuerst an (`nxs mcp

install --setup --workspace <pfad> oder dort nxs init`) — ein expliziter Pfad ohne Board ist ein Fehler, keine automatische Anlage.

Ein einzelner laufender Server kann pro Tool-Aufruf auch auf ein anderes Board gerichtet werden,

indem man einem beliebigen Tool ein workspace-Argument übergibt — ein Server, viele Projekte, ohne erneute Registrierung.

`nxs` bootstrappen, wenn es nicht installiert ist

Zwei signierte Wege zu nxs, beide fail-closed:

Das Ein-Zeilen-Installationsskript (installiert nxf/nxm/nxs unter ~/.local/bin, ohne

sudo):

``bash curl -fsSL https://nxf.nxsflow.com/install.sh | sh ``

Der `npx`-Runner (oben) — er *ist* der Bootstrap für GUI-Hosts: er lädt und verifiziert nxs

bei Bedarf, sodass die Host-Konfiguration das Einzige ist, was Sie hinzufügen.

Sicherheit

Jeder Abrufpfad verifiziert, bevor er ausführt, und auf dem npx-Weg gibt es keine unsichere Ausnahme:

sha256 belegt, dass die Bytes beim Transport nicht verändert wurden.
minisign (eine Ed25519-Signatur über das Tarball, geprüft gegen einen im Installer und im Runner

eingebackenen öffentlichen Schlüssel) belegt, dass die Bytes wirklich von uns stammen. Ein manipuliertes Artefakt, ein falscher Schlüssel oder eine fehlende Signatur bricht ab, bevor etwas läuft.

Nur Bytes, die beide Prüfungen bestehen, werden gecached und ausgeführt. install.sh schlägt auf einem Host ohne verfügbaren Verifizierer fehl (statt unverifizierte Bytes zu installieren), und nxs self-update verifiziert immer erneut.

Andere Hosts

Dieselben Einträge funktionieren für Cursor und Windsurf (und jeden MCP-Host, der einen stdio-Befehl startet). nxs mcp install erkennt und patcht alle drei; um einen gezielt anzusprechen, übergeben Sie --host claude-desktop | cursor | windsurf. Sobald verbunden, sendet der Server beim Verbinden Nutzungshinweise, und flow_next liefert Ihre bereite Arbeit — rufen Sie es in jeder Sitzung zuerst auf.

Kernkonzepte

Dies ist das plugin-freie Herz von nexus-flow. Alles hier ist universell — dasselbe Modell liegt jedem Plugin zugrunde; nur die Worte darüber ändern sich (Plugins).

Das Datenmodell

Es gibt zwei Arten von Item:

Ein Projekt gruppiert Arbeit (ein Plugin nennt es vielleicht *Epic* oder *Project*).
Ein Task ist eine Arbeitseinheit (ein *Issue*, ein *Todo*).

Items tragen eine kleine, feste Menge an Feldern auf Engine-Ebene — wörtlich sichtbar in jedem --json-Datensatz: id, type, title, description, design, status (open / in_progress / closed), priority, due, defer_until, assignee, belongs_to und ein closing_comment. Zwei Beziehungen verbinden Items:

belongs-to: ein Task oder Projekt gehört zu genau einem übergeordneten Projekt (gesetzt mit

--parent). Das ist Containment — die Aufschlüsselung der Arbeit.

Abhängigkeiten: eine gerichtete *muss-zuerst-fertig*-Kante zwischen zwei beliebigen Items

(Projekt oder Task), unabhängig vom Containment.

Über Abhängigkeiten hinaus können Items Erwähnungen tragen — Freitext-Referenzen per Short-id, die festhalten "dieser Text spricht über jenes Item", ohne es jemals zu blockieren. Jede Änderung wird als History aufbewahrt, und das Schließen eines Items hält einen Schließkommentar fest (das *Warum*, nicht nur das *Dass*).

Die Ursprungs-Intention bewahren

Titel und Beschreibung werden kurz nach der Anlage festgezurrt und dann stabil gehalten — sie sind die Aufzeichnung dessen, *was wir uns am Anfang vorgenommen haben*. Korrigiere sie einmal direkt nach der Anlage (etwa um ein Review einzuarbeiten), und lass sie danach in Ruhe. Neuer Kontext und alles, was du während der Abarbeitung lernst, gehen in den Append-Only-Notizen- Stream (nxf note add), nicht in ein Umschreiben der Ursprungsfelder. (Das ist heute eine Konvention; ein künftiges Release kann sie durch einen irreversiblen Per-Field-Lock erzwingen.)

Wenn ein Item wirklich keinen Sinn mehr ergibt, baue es nicht zu etwas Fremdem um — das würde seine Historie auslöschen. Lege stattdessen ein neues Item an und schließe das alte mit einer Begründung, die auf das neue verweist (Schließen ist der einzige Weg, auf dem ein Item das Board verlässt; es gibt kein Hard-Delete). Das ursprüngliche Item bleibt, geschlossen, als Teil der Aufzeichnung erhalten.

Warum das wichtig ist: So entsteht über die Zeit das Paar „das wollten wir erreichen" (Beschreibung und Design) ↔ „so haben wir es am Ende abgeschlossen" (Schließkommentar und Notizen). Genau dieses Paar aus Absicht und Ergebnis ist das, woraus man später lernt. Überschreibt man die Ursprungs-Intention, verliert man die eine Hälfte davon — und damit die Möglichkeit zu lernen. (Intention zu bewahren nützt nur, wenn man sie wiederfindet: nxf search durchsucht auch geschlossene Items, sodass das Paar auffindbar bleibt.)

Abhängigkeiten und Blockieren

Eine Abhängigkeit besagt, dass das *from*-Item auf das *to*-Item warten muss. Angenommen, ab12.0002 ("Write the CLI") kann nicht beginnen, bevor ab12.0003 ("Spec sign-off") erledigt ist — fügen Sie die Kante hinzu:

$ nxf dep add ab12.0002 ab12.0003 --json
{"msg":"ab12.0002 -> ab12.0003","ok":true}

Solange der Blocker offen ist, ist das abhängige Item blocked:

$ nxf blocked --json
[{"archived":null,"assignee":null,"belongs_to":"ab12.0001","blockers":[{"id":"ab12.0003","status":"open"}],"closed_at":null,"closing_comment":null,"completion_criterion":null,"defer_until":null,"deleted":null,"description":"Build the command-line tool","design":null,"due":"2026-12-31","id":"ab12.0002","priority":"1","priority_label":"P1","status":"open","title":"Write the CLI","type":"feature","type_label":"feature"}]

Ableitung: ready / blocked / next

ready, blocked und next sind abgeleitet, nie gespeichert. Sie sind eine deterministische Berechnung über die Items und ihre Kanten — es gibt kein ready-Flag zu setzen oder zu vergessen. Ein Item ist ready, wenn es offen ist und keinen offenen Blocker hat; das Projekt und der nicht blockierte Task sind ready, während der blockierte Task fehlt:

$ nxf next --json
[{"archived":null,"assignee":null,"belongs_to":null,"closed_at":null,"closing_comment":null,"completion_criterion":null,"defer_until":null,"deleted":null,"description":"Cut the first release","design":null,"due":null,"id":"ab12.0001","parent":null,"priority":"1","priority_label":"P1","status":"open","title":"Ship v1","type":"epic","type_label":"epic"},{"archived":null,"assignee":null,"belongs_to":null,"closed_at":null,"closing_comment":null,"completion_criterion":null,"defer_until":null,"deleted":null,"description":"Approve the final spec","design":null,"due":null,"id":"ab12.0003","parent":null,"priority":"2","priority_label":"P2","status":"open","title":"Spec sign-off","type":"feature","type_label":"feature"}]

next ist ready, in die Reihenfolge gebracht durch die Ranking-Policy des aktiven Plugins — dieselbe Ableitung, ein Schritt mehr. Da alles berechnet ist, macht das Schließen des Blockers das abhängige Item bei der nächsten Abfrage sofort ready; nichts muss neu geflaggt werden.

Zeit: due und defer

Zwei Datumsfelder formen ein Item über die Zeit. due ist ein Zieldatum (es kann das Ranking beeinflussen). defer_until verbirgt ein Item, bis ein Datum eintritt — nützlich für Arbeit, die Sie noch nicht beginnen können. Die Ableitung ist zeitabhängig, aber dennoch deterministisch: Übergeben Sie --now, um den Referenzzeitpunkt zu fixieren. In einem frischen Workspace ein zurückgestellter Task:

$ nxf create --type feature --title "Pay quarterly taxes" --description "File the quarterly tax return" --priority P3 --defer 2026-07-01 --json
{"archived":null,"assignee":null,"belongs_to":null,"closed_at":null,"closing_comment":null,"completion_criterion":null,"defer_until":"2026-07-01","deleted":null,"description":"File the quarterly tax return","design":null,"due":null,"id":"ab12.0001","priority":"3","status":"open","title":"Pay quarterly taxes","type":"feature"}

Vor dem Defer-Datum ist er nicht ready:

$ nxf next --now 2026-06-15T00:00:00Z --json
[]

Am oder nach dem Datum liefert genau dieselbe Abfrage den Task — nur --now hat sich geändert:

$ nxf next --now 2026-08-01T00:00:00Z --json
[{"archived":null,"assignee":null,"belongs_to":null,"closed_at":null,"closing_comment":null,"completion_criterion":null,"defer_until":"2026-07-01","deleted":null,"description":"File the quarterly tax return","design":null,"due":null,"id":"ab12.0001","parent":null,"priority":"3","priority_label":"P3","status":"open","title":"Pay quarterly taxes","type":"feature","type_label":"feature"}]

Dieser Determinismus — gleiche Eingaben, gleiches --now, byte-identische Ausgabe — macht nexus-flow sicher steuerbar für Agenten. Als Nächstes: Sehen Sie, wie ein Plugin all das darstellt in Plugins, oder gehen Sie den vollen Befehlssatz durch in Befehle.

Befehle

Eine Tour durch die meistgenutzten nxf-Befehle, in der Reihenfolge, in der eine Sitzung sie gewöhnlich verwendet. Führen Sie nxf <command> --help aus für die knappe, generierte Referenz (Flags, Typen, Voreinstellungen); dieser Leitfaden fügt die Erzählung hinzu. Kombinieren Sie jeden Befehl mit --json für deterministische, agentenfreundliche Ausgabe.

Die Sitzung unten setzt den Erste-Schritte-Workspace unter dem issue-tracker-Plugin fort.

Inspizieren

show ist das vollständige menschliche Detail eines Items — Felder, Beschreibung, Abhängigkeiten und Notizen:

$ nxf show ab12.0002

0002 P1 Write the CLI
=====================

TYPE: feature
STATUS: in progress
PARENT: 0001

DESCRIPTION
-----------

Build the command-line tool

DEFINITION OF DONE
------------------



DESIGN
------

Thin CLI over the core.

NOTES
-----

- started on the command layer

list gibt jedes Item aus; mit --json ist es der kanonische, byte-stabile Schnappschuss (id-geordnet, nicht gerankt):

$ nxf list --json
[{"archived":null,"assignee":null,"belongs_to":null,"closed_at":null,"closing_comment":null,"completion_criterion":null,"defer_until":null,"deleted":null,"description":"Cut the first release","design":null,"due":null,"id":"ab12.0001","priority":"1","priority_label":"P1","status":"in_progress","title":"Ship v1","type":"epic","type_label":"epic"},{"archived":null,"assignee":"dev","belongs_to":"ab12.0001","closed_at":null,"closing_comment":null,"completion_criterion":null,"defer_until":null,"deleted":null,"description":"Build the command-line tool","design":"Thin CLI over the core.","due":"2026-12-31","id":"ab12.0002","priority":"1","priority_label":"P1","status":"in_progress","title":"Write the CLI","type":"feature","type_label":"feature"},{"archived":null,"assignee":null,"belongs_to":null,"closed_at":"2026-06-23T00:00:00Z","closing_comment":"approved","completion_criterion":null,"defer_until":null,"deleted":null,"description":"Approve the final spec","design":null,"due":null,"id":"ab12.0003","priority":"2","priority_label":"P2","status":"closed","title":"Spec sign-off","type":"feature","type_label":"feature"}]

search matcht über Titel, Beschreibung und Notizen:

$ nxf search "thin cli" --json
[{"archived":null,"assignee":"dev","belongs_to":"ab12.0001","closed_at":null,"closing_comment":null,"completion_criterion":null,"defer_until":null,"deleted":null,"description":"Build the command-line tool","design":"Thin CLI over the core.","due":"2026-12-31","id":"ab12.0002","priority":"1","priority_label":"P1","status":"in_progress","title":"Write the CLI","type":"feature","type_label":"feature"}]

Ein Item bearbeiten

claim markiert ein Item als in Bearbeitung und weist es zu:

$ nxf claim ab12.0002 --assignee dev --json
{"archived":null,"assignee":"dev","belongs_to":"ab12.0001","closed_at":null,"closing_comment":null,"completion_criterion":null,"defer_until":null,"deleted":null,"description":"Build the command-line tool","design":null,"due":"2026-12-31","id":"ab12.0002","priority":"1","status":"in_progress","title":"Write the CLI","type":"feature"}

update bearbeitet Felder — hier das design:

$ nxf update ab12.0002 --set "design=Thin CLI over the core." --json
{"archived":null,"assignee":"dev","belongs_to":"ab12.0001","closed_at":null,"closing_comment":null,"completion_criterion":null,"defer_until":null,"deleted":null,"description":"Build the command-line tool","design":"Thin CLI over the core.","due":"2026-12-31","id":"ab12.0002","priority":"1","status":"in_progress","title":"Write the CLI","type":"feature"}

note add hängt eine Worklog-Notiz an; note list liest sie zurück:

$ nxf note add ab12.0002 "started on the command layer" --json
{"body":"started on the command layer","id":"[..]"}

$ nxf note list ab12.0002

- started on the command layer

close schließt ein Item ab und hält einen Schließkommentar fest (das *Warum*):

$ nxf close ab12.0002 --reason done --json
{"archived":null,"assignee":"dev","belongs_to":"ab12.0001","closed_at":"2026-06-23T00:00:00Z","closing_comment":"done","completion_criterion":null,"defer_until":null,"deleted":null,"description":"Build the command-line tool","design":"Thin CLI over the core.","due":"2026-12-31","id":"ab12.0002","priority":"1","status":"closed","title":"Write the CLI","type":"feature"}

Die Arbeit strukturieren

dep add / dep remove verwalten die *muss-zuerst-fertig*-Kanten, die das Blockieren steuern (siehe Kernkonzepte):

$ nxf dep add ab12.0002 ab12.0003 --json
{"msg":"ab12.0002 -> ab12.0003","ok":true}

$ nxf dep remove ab12.0002 ab12.0003 --json
{"msg":"removed ab12.0002 -> ab12.0003","ok":true}

mention add / mention list / mention remove halten Freitext-Referenzen per Short-id fest — ein Verweis, der nie blockiert:

$ nxf mention add ab12.0002 ab12.0001 --json
{"msg":"ab12.0002 mentions ab12.0001","ok":true}

$ nxf mention list ab12.0002 --json
["ab12.0001"]

$ nxf mention remove ab12.0002 ab12.0001 --json
{"msg":"removed mention ab12.0002 -> ab12.0001","ok":true}

Einen Agenten bootstrappen

prime ist ein einziger Aufruf, der einem Agenten die plugin-bestimmte Zweckbeschreibung von nxf (purpose), die Arbeitsregeln, die gerankte next-Empfehlung (Top 7, laufende Arbeit zuerst), einen leverage-bewussten blocked-Schnappschuss, ein create-Beispiel mit dem Typ-Vokabular und der Prioritäts-Spanne des aktiven Plugins sowie die Befehlsreferenz (deren dep-Eintrag die Abhängigkeitsrichtung ausbuchstabiert) übergibt. Der deterministische Einstiegspunkt für eine automatisierte Sitzung:

$ nxf prime --json
{"blocked":[],"commands":[{"group":"Finding work","items":[{"name":"next","summary":"ready work in priority order (start here); add --include-in-progress for claimed work"},{"name":"blocked","summary":"list blocked work"},{"name":"show <id>","summary":"item detail with deps and notes"}]},{"group":"Creating & updating","items":[{"name":"create","summary":"create an item — see the `create` section above"},{"name":"update <id> --set k=v","summary":"edit fields"},{"name":"claim <id>","summary":"mark in progress"},{"name":"close <id> --reason","summary":"close with a comment"},{"name":"schema","summary":"introspect this plugin's field model (--json) before create/update"}]},{"group":"Dependencies & references","items":[{"name":"dep add <from> <to>","summary":"<from> depends on <to> (so <to> blocks <from> and must close first)"},{"name":"mention add <from> <to>","summary":"record a free-text short-id reference"}]},{"group":"Notes & search","items":[{"name":"note add <id> <text>","summary":"append a worklog note"},{"name":"search <query>","summary":"search title/description/design/DoD/notes"}]}],"context_recovery":"Run `nxs prime` after a context compaction, /clear, or a new session — hosts auto-call it in Claude Code when a nexus-flow workspace is resolved.","create":{"example":"nxf create --type <bug|chore|decision|epic|feature> --title /".../" --priority <P0|P1|P2|P3|P4>","long_text_hint":"Long text without shell escaping: pipe a field via STDIN (`--description -`), read it from a file (`--description-file <path>`), or pipe the whole item as JSON (`nxf create --json -`).","recommendation":"Always set --priority (named variants, highest first: P0 … P4); an item created without a priority ranks last in `next`."},"next":[{"id":"ab12.0001","parent":null,"priority":"1","status":"in_progress","title":"Ship v1","type":"epic"}],"next_total":1,"purpose":"nexus-flow is a software issue tracker for epics and issues. You record items, the dependencies between them, due/defer dates, and priority; `next` and `blocked` are then derived deterministically from that graph rather than stored, so the work list is always consistent.","rules":["Track all work in nexus-flow itself: open an item for every task rather than keeping a separate TODO list or scratch notes — the board is the single source of truth.","Find what to work on next: `nxf next`.","Claim work before starting it: `nxf claim <id>`.","Close with a reason: `nxf close <id> --reason <text>`.","Use `--json` everywhere for deterministic, machine-readable output.","Choose the containment edge deliberately: `parent` is gating — a child rests when its container rests (a deferred, blocked, or closed parent propagates down and hides or masks the child). For a loose association that must NOT gate the child, use `contributes_to` (e.g. cream belongs to the shopping list but only contributes to the birthday plan, so deferring the birthday never hides the cream).","Defer only for a real calendar date — a day before which the item genuinely cannot start (`--defer <date>` on create, or `nxf update <id> --set defer=<date>`); a placeholder date for /"someday, once X ships/" is an anti-pattern that hides the item on a false promise. To wait on an external DELIVERY instead — there are no cross-workspace dependencies — model the delivery as an open WAIT chore in this workspace (title it `WAIT: <what ships>`, e.g. `WAIT: acme-api v2`), have the dependents `nxf dep add <id> <wait-chore>` onto it, and CLOSE the chore — with the delivered version in the reason — to release the whole chain. Each workspace keeps its own anchor; see `nxf guide deferring-and-waiting`.","Correct an item's fields once shortly after creating it (e.g. to fold in a review); after that keep the fields stable and record what you learn while working as append-only notes (`nxf note add <id> <text>`), not field edits. The original title and description are preserved on purpose: paired with the closing comment they form the intent-vs-outcome pair you learn from, so when an item no longer fits, open a new one and close the old with a reason instead of rewriting it past recognition.","When you cite a task's short-id in free text (body or note), also record the reference: `nxf mention add <this-item> <cited-id>`. It keeps the citation resolvable if ids are remapped on sync, and never blocks (it is not a dependency)."],"session_close":["Capture unfinished work as a note so the next session has the context: `nxf note add <id> <text>`.","Close finished items with the reason they're done: `nxf close <id> --reason <text>`.","If the project is under version control, commit and push your code changes."],"workflows":[{"name":"Starting work","steps":["nxf next","nxf show <id>","nxf claim <id>"]},{"name":"Completing work","steps":["nxf close <id> --reason /".../"","nxf next   # pick up the next unblocked item"]},{"name":"Creating dependent work","steps":["nxf create --type <type> --title /".../" --priority <P…>","nxf create --type <type> --title /".../" --priority <P…>","nxf dep add <child> <prereq>   # child depends on prereq; prereq must close first"]}]}

Plugins

Ein Plugin bildet den universellen Kern auf die Sprache und Policy eines Konsumenten ab. Nichts in der CLI kodiert Vokabular fest — alles ergibt sich aus der aktiven Plugin-Konfiguration, einmal bei nxf init gewählt. Ein Plugin legt vier Dinge fest:

Vokabular: die Worte für die beiden Item-Typen und die drei Status.
Prioritätslabels: die Namen für die Prioritätsstufen 0–4.
Ranking: wie next die ready-Menge ordnet.
Darstellung: welche Felder list und show anzeigen.

Die zwei mitgelieferten Plugins

issue-tracker — Software-Issue-Tracking: Epics und Issues, P0–P4-Prioritäten,

abhängigkeitsbewusstes Ranking.

personal-todo — Persönliche To-do-Liste: Listen und Todos, now/soon/later-Prioritäten für

alltägliche Aufgaben.

Ihre Vokabulare unterscheiden sich:

issue-tracker: ein Projekt ist ein epic, ein Task ist ein issue; die Status sind

open / in progress / closed; die Prioritäten sind P0–P4; next rankt nach Priorität, dann Fälligkeitsdatum, dann id.

personal-todo: ein Projekt ist ein project, ein Task ist ein todo; die Status sind

todo / doing / done; die Prioritäten sind now / soon / later / someday / icebox; next rankt nach Priorität, dann id (kein Fälligkeitsdatum als Tiebreak).

Named Variants auflösen: types und priorities

type und priority sind beide *named variants* — eine kleine, plugin-definierte Menge mit fester Ordnung. nxf schema --json exponiert beide als gekeyte Map, sodass eine Regel jedes der beiden Felder auf jedem Item auflöst:

schema.types[item.type]           # "task" -> "issue"
schema.priorities[item.priority]  # "0"    -> "P0"

Der auf einem Item gespeicherte Wert ist der *Handle*, nicht das Label. Für priority ist dieser Handle ein Ordinal — "0" ist die höchste Priorität, aufsteigend gezählt — bewusst plugin-unabhängig, damit next numerisch ranken kann und gesyncte Items keine Fremd-Labels tragen. Die schema.priorities-Map übersetzt das Ordinal zurück in ein menschliches Label.

Ordinal-Stabilitätsvertrag. Innerhalb einer Schema-Version ist die Bindung Ordinal→Bedeutung stabil und append-only: priority.labels darf am Ende wachsen, aber Umsortieren oder Einfügen verschiebt die Bedeutung bereits gespeicherter Items und ist daher ein breaking Schema-Change — ein Schema-Version-Bump mit Migration, keine In-place-Änderung.

Gleiche Daten, nebeneinander

Die Naht ist am klarsten, wenn Sie die gleichen Befehle auf den gleichen Daten unter jedem Plugin ausführen. Beide Workspaces unten enthalten drei Tasks: zwei mit Priorität 1 (einer fällig 2026-02-01, einer fällig 2026-03-01) und einer mit Priorität 2.

next zeigt zwei Unterschiede auf einmal — das Vokabular und das Ranking. Unter issue-tracker gewinnt das früher fällige P1-Issue (Book venue) den Tiebreak:

$ nxf next

0002  P1  open  [feature]  Book venue
0001  P1  open  [feature]  Draft proposal
0003  P2  open  [feature]  Order badges

Unter personal-todo stehen dieselben beiden soon-Todos bei der Priorität gleich und fallen auf die id zurück, sodass das zuerst erstellte (Draft proposal) zuerst kommt — und die Labels sind nun now/soon/later, todo/doing/done:

$ nxf next

0001  soon  todo  [todo]  Draft proposal
0002  soon  todo  [todo]  Book venue
0003  later  todo  [todo]  Order badges

Dennoch ist der gespeicherte Datensatz derselbe — list --json ist id-geordnet und hängt nicht vom aktiven Plugin ab. Das Plugin legt Darstellung und Ranking darüber; es ändert nie die Daten. Das eine Feld, das ein Plugin besitzt, ist type: Das Typ-Set ist plugin-deklariert, also speichert issue-tracker feature, wo personal-todo todo speichert. Lässt man dieses eine Feld weg, sind die Datensätze byte-für-byte dieselben:

$ nxf list --json
[{"archived":null,"assignee":null,"belongs_to":null,"closed_at":null,"closing_comment":null,"completion_criterion":null,"defer_until":null,"deleted":null,"description":"Outline the event proposal","design":null,"due":"2026-03-01","id":"ab12.0001","priority":"1","priority_label":"P1","status":"open","title":"Draft proposal","type":"feature","type_label":"feature"},{"archived":null,"assignee":null,"belongs_to":null,"closed_at":null,"closing_comment":null,"completion_criterion":null,"defer_until":null,"deleted":null,"description":"Reserve the event space","design":null,"due":"2026-02-01","id":"ab12.0002","priority":"1","priority_label":"P1","status":"open","title":"Book venue","type":"feature","type_label":"feature"},{"archived":null,"assignee":null,"belongs_to":null,"closed_at":null,"closing_comment":null,"completion_criterion":null,"defer_until":null,"deleted":null,"description":"Print attendee name badges","design":null,"due":null,"id":"ab12.0003","priority":"2","priority_label":"P2","status":"open","title":"Order badges","type":"feature","type_label":"feature"}]

show macht den Vokabularunterschied an einem einzelnen Item konkret. Issue-tracker:

$ nxf show ab12.0002

0002 P1 Book venue
==================

TYPE: feature
STATUS: open

DESCRIPTION
-----------

Reserve the event space

DEFINITION OF DONE
------------------



DESIGN
------



NOTES
-----

personal-todo, dasselbe ab12.0002:

$ nxf show ab12.0002

0002 soon Book venue
====================

TYPE: todo
STATUS: todo

WHY
---

Reserve the event space

DONE WHEN
---------



PLAN
----



LOG
---

Diese Verdopplung ist keine Redundanz — sie *ist* die Erklärung. Das --json ist die Bedeutung; das Plugin ist, wie ein bestimmtes Publikum sie liest und rankt. Ein Plugin bei init zu wählen ist daher eine echte Entscheidung; führen Sie nxf init --help aus, um die Optionen zu sehen, bevor Sie sich festlegen.

Migration

Dieser Leitfaden behandelt zwei Arten von Migration: bestehende Arbeit nach nexus-flow zu bringen und zwischen Hauptversionen von nexus-flow selbst zu wechseln.

Einen bestehenden Tracker einbringen

nexus-flow hat keinen Massenimporter — und braucht keinen. Items werden über dasselbe nxf create erstellt, das Sie tagtäglich verwenden, also ist eine Migration ein kurzes Skript, das Ihren alten Tracker durchläuft und nxf einmal pro Item aufruft, wobei jeder Datensatz auf das Kernmodell abgebildet wird: ein --type (Projekt oder Task), ein --title, optional ein --parent, --priority, --due und --description. Erstellen Sie Abhängigkeiten danach mit nxf dep add neu. Da jeder Befehl --json annimmt und deterministisch ist, ist das Skript leicht zu schreiben und zu verifizieren:

# sketch: one create per legacy ticket, then wire dependencies
nxf create --type project --title "Imported backlog" --json
nxf create --type task --title "Legacy #1234" --parent ab12.0001 --priority P2 --json
nxf dep add ab12.0002 ab12.0003

Wählen Sie bei nxf init das Plugin, dessen Vokabular zum Quell-Tracker passt — das ist die einzige Vorab-Entscheidung, von der der Import abhängt.

Einen Sync-Stream binden

nexus-flow ist offline-first: Sie arbeiten lokal gegen .nxs/, und ein Sync-Stream bringt jede Replik auf der dauerhaften Server-Wahrheit zur Konvergenz. Binden Sie einen Stream einmal, dann führen Sie Sync aus, wann immer Sie sich wieder verbinden:

nxs sync bind --create
nxs sync run --remote https://your-relay.example.com

Die Arbeit geht zwischen den Läufen offline weiter; sync run tauscht Änderungen aus und führt sie deterministisch zusammen (die Engine ist eine CRDT, sodass gleichzeitige Bearbeitungen ohne Koordinator konvergieren). Der Server ist der dauerhafte Datensatz, kein Lock — niemand muss online sein, damit Sie Fortschritte machen.

Migration über Hauptversionen hinweg

nexus-flow folgt einfachem SemVer. Innerhalb einer Hauptversion sind Upgrades (nxs self-update) nahtlos einspielbar. Ein Sprung der Hauptversion (z. B. 1.x → 2.0) ist die einzige Stelle, an der eine Breaking Change landen darf, und jede solche Änderung wird mit einer Migrationsnotiz ausgeliefert, die beschreibt, was automatisch ist und was Ihre Aufmerksamkeit braucht. Diese Notizen werden pro Hauptversion zu einem einzigen Upgrade-Leitfaden zusammengefasst.

Lesen Sie die zusammengefassten Notizen für eine Hauptversion, bevor Sie darauf upgraden — sie liegen neben diesem Leitfaden auf der Website unter /docs und in den Release-Notes der Version. Innerhalb einer 0.x-Serie gibt es noch keine Stabilitätsgarantie, prüfen Sie also bei jedem Update das Changelog.

Befehlsreferenz

Aus dem Befehlsbaum der CLI generiert. Führen Sie einen Befehl mit --help aus, um alle Flags und Typen zu sehen.

nxf agent-manifest: Emit nxf's declared contribution to the shared agent files (the AGENTS.md/CLAUDE.md section, the prime command, the SessionStart hook) as data. The `nxs` umbrella assembles the shared files from each active module's manifest (spec §6.2); `--json` is the machine contract
nxf archive: Archive one or more items — "closed and put away". Cascades DOWN: each root and its whole `belongs_to` subtree are archived, but only when the root is closed and every descendant is closed (already-archived counts as closed). Atomic per root, independent between roots; the result reports each root's outcome plus the full list of ids actually archived (incl. cascaded). Archiving is reversible — see `unarchive`
nxf archived: List archived items (any status). Ordered by archive-date descending (most recent first); override with `--sort`
nxf blocked: List blocked items (open, with an open blocker or in a cycle). Ranked by default; override with `--sort id`
nxf claim: Claim an item: mark it in progress (and optionally assign it)
nxf close: Close an item, recording why. Closing is final (no hard delete), so a reason is required
nxf closed: List closed items (excluding archived). Ordered by close-date descending (most recent first); override with `--sort`
nxf contributes add: Record that `from` contributes to `to` (both must exist; never blocks)
nxf contributes list: List the items `id` contributes to
nxf contributes remove: Remove the `from -> to` contributes-to edge
nxf create: Create a new item — a complete item in one call. Title, description, and priority are required; design, the definition of done, a parent, and dependencies are optional. Run `nxf schema` for the active plugin's field model (labels, constraints, required fields)
nxf deferred: List deferred items (open, unblocked, with a future defer date) — the lane that is neither ready nor blocked. Ordered by defer-date ascending (soonest first); override with `--sort`
nxf dep add: Make `from` depend on `to`: `to` blocks `from`, so `from` stays blocked until `to` closes. Rejected if it would create a cycle
nxf dep remove: Remove the dependency where `from` depends on `to`
nxf guide: Print an embedded, offline guide; no topic lists the available topics
nxf init: Initialize a `.nxs` workspace in the current directory: set up flow, then delegate the shared agent files + the single `nxs prime` SessionStart hook to the `nxs` assembler. To set up the whole suite (and pick tools interactively), use `nxs init` instead
nxf label add: Attach a label to an item (idempotent). The label is trimmed; a blank label is rejected
nxf label list: List an item's labels (sorted)
nxf label remove: Detach a label from an item (observed-remove)
nxf list: List items, optionally filtered by status and/or type. Id-ordered by default (so the `--json` record stays plugin-independent); override with `--sort rank`
nxf mention add: Record that `from` cites the short-id `to` in its free text (no blocking)
nxf mention list: List the short-ids `id` mentions
nxf mention remove: Remove the `from -> to` reference
nxf next: List ready work — open, unblocked, not deferred — ranked by the active plugin's `next` policy. Add `--include-in-progress` to fold in actionable claimed work; override the order with `--sort id`
nxf note add: Append a note to an item. Pass `-` as the text to read the note body from STDIN (escaping-free, multi-line)
nxf note list: List an item's notes
nxf schema: Describe the active plugin's field model — vocabulary, priorities, and per field whether it is required on create / settable on update and how. `--json` is the machine contract; run it to learn what `create`/`update` accept in this workspace (the static `--help` cannot carry the active plugin's vocabulary)
nxf search: Search items by substring over title, description, design, DoD, and notes. Results are grouped by lane priority (next+in-progress → blocked → deferred → closed), each group in its natural order; archived items are excluded by default
nxf setup claude: Wire Claude Code: (re)assemble the shared agent files (AGENTS.md/CLAUDE.md) and the single SessionStart hook that runs `nxs prime` (the umbrella fan-out) plus the `nxs`/module permission allowlist, merged into `.claude/settings.json` (idempotent, never overwriting). The canonical verb is `nxs setup claude`; this delegates to it (host setup is an umbrella responsibility)
nxf show: Show one item with its dependencies and notes
nxf unarchive: Unarchive one or more items, making them visible again. Cascades UP only: each item and its ancestor chain resurface, but its children/siblings stay archived. Partial per root; the result reports each root's outcome plus the full list of ids actually unarchived
nxf update: Update item fields via `--set field=value` (repeatable). The long-form `description`/`design`/`completion_criterion` are ordinary `--set` fields. Run `nxf schema` for the settable fields and their plugin names. Convention: correct the field model once shortly after creation; once it is stable, record what you learn as append-only notes (`nxf note add`) rather than further field edits