aapastech/claude-skill-session-backlog

Aapastech Session Backlog: nie eine Aufgabe verlieren

Lange Sitzungen und Multi-Task-Prompts führen dazu, dass KI-Assistenten Arbeit fallen lassen. Frühe Anfragen verblassen, während sich ein späterer Durchgang in ein Detail vertieft. Dieses Skill behebt das mit einem Rückstand (Backlog), der auf dem eigenen Computer des Benutzers lebt. Das Gesprächsgedächtnis ist nicht die Quelle der Wahrheit; der Rückstand ist es. Eine Aufgabe, die nicht im Rückstand ist, existiert nicht, und eine Aufgabe im Rückstand ist erst erledigt, wenn sie als Erledigt oder Abgebrochen markiert ist.

Es funktioniert mit jedem Assistenten oder Agenten, der entweder Shell-Befehle auf dem Computer des Benutzers ausführen oder MCP-Tools aufrufen kann. Jede Sitzung auf diesem Computer, egal mit welchem Tool oder Modell, teilt denselben Rückstand.

Datenschutzregel: Aufgabendaten bleiben auf dem Gerät, das die Arbeit ausführt. Kopieren Sie den Rückstand nie in einen Cloud-Dienst, eine gehostete Seite, einen Connector oder ein geteiltes Dokument. Wenn kein Benutzergerät erreichbar ist, verwenden Sie stattdessen den Offline-Modus (Abschnitt 9).

1. Rückstand finden und Engine ausführen

Wenn Ihre Tool-Liste backlog_*-Tools enthält (der MCP-Server, Abschnitt 11), verwenden Sie diese. Sie bilden eins-zu-eins auf die unten stehenden Befehle ab und übernehmen die Ordnerverwaltung, Kodierung und Aktualisierungen für Sie. Überspringen Sie den Rest dieses Abschnitts.

Andernfalls ist der Rückstand ein Ordner, der bl.py (die Engine), config.json, tasks/ (eine JSON-Datei pro Aufgabe), sessions/, board.html und BOARD.md enthält. Suchen Sie in dieser Reihenfolge:

1. Ein Ort, den der Benutzer Ihnen mitgeteilt hat, in seinen Einstellungen, seinem Gedächtnis oder Projektanweisungen.
2. Die Umgebungsvariable BACKLOG_DIR, falls gesetzt.
3. ~/Documents/Aapastech-Backlog (Standard).
4. ~/Documents/Claude-Backlog (der Ordnername, der vor v3 verwendet wurde; behalten Sie ihn bei, wenn sich dort die Aufgaben des Benutzers befinden).

Ausführung. In diesem Dokument ist bl <Befehl> eine Kurzform. Geben Sie immer den vollständigen Befehl ein; speichern Sie ihn nie in einer Shell-Variablen ($BL … funktioniert in zsh, der Standard-Shell auf macOS, nicht).

Shell	Befehl
macOS / Linux (bash, zsh)	python3 ~/Documents/Aapastech-Backlog/bl.py <Befehl> …
Windows PowerShell	py -3 "$HOME\Documents\Aapastech-Backlog\bl.py" <Befehl> … (falls py fehlt, versuchen Sie python)
Windows cmd	py -3 "%USERPROFILE%\Documents\Aapastech-Backlog\bl.py" <Befehl> …
Git Bash on Windows	py -3 ~/Documents/Aapastech-Backlog/bl.py <Befehl> …

bl where gibt den Ordner und die Engine-Version aus, die verwendet wird. Unter Windows wird Documents oft in OneDrive verschoben (%USERPROFILE%\OneDrive\Documents). Wenn ~\Documents nicht existiert, suchen Sie dort und bieten Sie an, BACKLOG_DIR zu setzen, damit jede Sitzung denselben Ordner findet.

Python. Die Engine benötigt Python 3.8+ und sonst nichts.

• macOS: Der erste python3-Aufruf auf einem neuen Mac kann den Dialog „Installiere Kommandozeilen-Entwicklertools" von Apple öffnen. Sagen Sie dem Benutzer, dass dies erwartet und sicher zu akzeptieren ist, oder installieren Sie Python von python.org.
• Windows: Python ist normalerweise nicht installiert. Wenn sowohl py -3 als auch python fehlschlagen, bitten Sie den Benutzer, Python 3 von python.org mit aktiviertem „Add python.exe to PATH" zu installieren, oder winget install Python.Python.3.12. Fallen Sie nicht auf etwas anderes zurück.

2. Erster Start auf einem Gerät (Bootstrap)

Wenn noch kein Rückstand existiert:

1. Erstellen Sie den Ordner ~/Documents/Aapastech-Backlog (oder den vom Benutzer gewählten Ort).
2. Kopieren Sie scripts/bl.py aus dem eigenen Ordner dieses Skills hinein. Es ist eine einzelne Python-Datei, die nur die Standardbibliothek verwendet und das Board enthält.
3. Stellen Sie dem Benutzer eine kurze Frage: welcher Name für Aufgaben angezeigt werden soll, die auf ihn warten, und in welche Bereiche seine Arbeit fällt (3–8 Bereiche, z.B. Kunden, Produkte, Verwaltung, Privat). Schlagen Sie Bereiche aus dem vor, was Sie bereits über ihn wissen. Führen Sie dann aus: bl init --owner "<Name>" --areas "Bereich1,Bereich2,…,Privat,KI-Ops" Fügen Sie --title "<Board-Titel>" hinzu, wenn der Benutzer einen eigenen Boardnamen wünscht (Standard ist „Aapastech Backlog").
4. Teilen Sie ihnen den Ort des Boards mit: file://…/Aapastech-Backlog/board.html. Bieten Sie an, es zu öffnen (bl board --open), und schlagen Sie vor, den Tab zu pinnen.
5. Schlagen Sie vor, das Skill immer aktiv zu machen, z.B. in den persönlichen Einstellungen oder Anweisungen des Assistenten: „Laden Sie das Session-Backlog-Skill zu Beginn jeder Sitzung und vor jeder Aufgabe mit Arbeitsinhalt."

Aktualisierungen: Wenn bl version eine niedrigere Version als scripts/bl.py in diesem Skill ausgibt (suchen Sie nach VERSION = "…"), kopieren Sie die neue bl.py über die alte. Aufgabendaten und Konfiguration bleiben unberührt.

3. Sitzungsidentität (einmal pro Sitzung)

Wählen Sie eine stabile Sitzungs-ID und verwenden Sie sie bei jedem Aufruf erneut:

• Wenn Ihre Plattform der Sitzung eine URL oder ID gibt, verwenden Sie diese und übergeben Sie die URL als --url.
• Andernfalls: <Oberfläche>-<YYYYMMDD-HHMM> mit der Startzeit der Sitzung, z.B. desktop-20261018-1652, code-20261018-0910, api-20261018-1200, sched-20261019-0600.

bl session --id <SID> --label "<Oberfläche> · <Hauptthema>" --surface code|desktop|cloud|api|scheduled [--url <Link>]

Dies gibt die offenen Aufgaben dieser Sitzung sowie nicht beanspruchte oder veraltete Aufgaben von anderen Orten aus. Erwähnen Sie überfällige oder auf den Benutzer wartende Aufgaben in einer Zeile. Geben Sie nicht die gesamte Liste aus.

4. Der Durchgangs-Loop (jeder Durchgang mit Arbeitsinhalt)

A. Zuerst erneut lesen. Zu Beginn jedes Durchgangs nach dem ersten führen Sie bl open --session <SID> aus. Tun Sie dies besonders, wenn der Prompt ein tiefer Einblick in eine Unteraufgabe ist. Dieser Schritt verhindert, dass andere Arbeit vergessen wird. Überspringen Sie ihn nie.

B. Vor der Arbeit erfassen. Jede neue Anfrage wird in einem Stapel erfasst, bevor mit der Arbeit begonnen wird. Das schließt Randbemerkungen wie „auch…“, „erinnere mich an…“, „später…“, „vergiss nicht…“ ein. Schreiben Sie den Stapel mit Ihrem Dateischreibwerkzeug in eine JSON-Datei und übergeben Sie dann den Pfad. Eine Datei funktioniert in jeder Shell; das Piping von JSON durch echo bricht unter Windows-Shells und verstümmelt nicht-ASCII-Text.

[
 {"title":"Preisseite neu gestalten","area":"Produkt","eta":"1h","priority":"P1",
  "source":"Prompt 16:52: Preisseite neu machen","next":"Aktuellen Text holen",
  "children":[{"title":"Aktuellen Text prüfen","eta":"10m"},
              {"title":"2 Layouts entwerfen","eta":"30m"},
              {"title":"Ausgewähltes Layout veröffentlichen","eta":"20m"}]},
 {"title":"Lieferant antworten","area":"Verwaltung","eta":"15m","status":"waiting_user","next":"Benutzer muss Menge bestätigen"}
]

bl batch --session <SID> <Pfad-zu-datei.json> (legen Sie die Datei in Ihrem Scratch- oder Temp-Ordner ab, nicht im Projekt des Benutzers).

Spielen Sie die Erfassung in einer kompakten Zeile zurück, damit der Benutzer sie korrigieren kann:

Erfasst: T-0042 Preisseite (1h) → T-0043 Prüfung (10m), T-0044 Layouts (30m), T-0045 Veröffentlichung (20m); T-0046 Lieferantwort (wartet auf Sie).

Prüfen Sie zuerst bl list und aktualisieren Sie eine vorhandene Aufgabe anstatt ein Duplikat zu erstellen. Fügen Sie "parent":"T-0042" (oder --parent T-0042 bei bl add) hinzu, um eine Unteraufgabe unter eine bestehende Aufgabe zu setzen.

C. Beanspruchen, dann arbeiten. Führen Sie bl claim <ID> --session <SID> [--eta 20m] aus, bevor Sie mit einer Aufgabe beginnen. Wenn die Beanspruchung abgelehnt wird, weil eine andere aktive Sitzung sie besitzt, lassen Sie sie in Ruhe. Beanspruchungen sind gesperrt, sodass niemals zwei Sitzungen beide eine gewinnen können. Arbeiten Sie nach Möglichkeit parallel. Die orchestrierende Sitzung aktualisiert den Rückstand für ihre Unteragenten und übergibt jedem Unteragenten seine Aufgaben-ID.

D. Fortlaufend aktualisieren. bl update <ID> --session <SID> --log "Entscheidung / Erkenntnis" [--next "…"] [--output <Pfad oder Link>] [--status blocked|waiting_user|ready]

• Halten Sie die Entscheidungen des Benutzers in seinen eigenen Worten fest.
• Jede von Ihnen erstellte Datei oder jeder Link wird in --output aufgenommen.
• Warten auf den Benutzer bedeutet --status waiting_user --next "<genau das, was Sie brauchen>".

E. Ehrlich abschließen. Führen Sie bl done <ID> --session <SID> --log "geliefert …" --output … erst aus, nachdem Sie das Ergebnis überprüft haben. Eine übergeordnete Aufgabe kann nicht geschlossen werden, während ihre Unteraufgaben noch offen sind. Um eine Aufgabe abzubrechen, führen Sie bl drop <ID> --session <SID> --reason "…" aus. Löschen Sie nie etwas.

F. Fußzeile. Beenden Sie jede Antwort, die Arbeit beinhaltete, mit der einzeiligen Ausgabe von bl footer --session <SID> [--exclude <IDs, die gerade gemeldet wurden>].

5. Bereiche

Jede übergeordnete Aufgabe erhält einen Bereich aus config.json (bl areas listet sie auf). Unteraufgaben erben den Bereich ihrer übergeordneten Aufgabe. Wählen Sie die am besten passende. Fügen Sie einen neuen Bereich hinzu (bl areas --add "Name") nur, wenn klar eine neue fortlaufende Arbeitssparte erkennbar ist, und erwähnen Sie es dabei. bl areas --rename ALT NEU benennt einen Bereich in der Konfiguration und bei jeder Aufgabe um.

6. Zeitaufwand (jede Aufgabe hat einen)

• Die Zeitaufwand ist die Echtzeit für den Assistenten zur Fertigstellung, unter der Annahme paralleler Arbeit. Er beträgt normalerweise 5–60 Minuten, manchmal Stunden und selten Tage. Format: 10m, 45m, 2h, 1h30m, 1d.
• Enthalten ist Zeit zur Überprüfung des Ergebnisses.
• Der Countdown beginnt bei Beanspruchung oder Erstellung. Das Board zeigt überfällige Aufgaben rot an.
• Wenn Sie die Zeit überschreiten, schätzen Sie sofort neu: --eta 1h --eta-reason "…". Lassen Sie keine Aufgabe stillschweigend überfällig werden.
• Bei einer waiting_user-Aufgabe ist die Zeitaufwand die Zeit zur Fertigstellung, nachdem der Benutzer antwortet.

7. Sitzungsübergreifende Regeln

• Eine Beanspruchung bleibt aktiv, solange ihre Sitzung die Aufgabe weiter aktualisiert. Nach 24 Stunden ohne Bearbeitung ist sie veraltet, und jede Sitzung kann sie übernehmen (die Übernahme wird protokolliert).
• Verwenden Sie --force nie bei einer aktiven Beanspruchung ohne Zustimmung des Benutzers.
• Lassen Sie vor dem Ende einer längeren Arbeitsphase jede beanspruchte Aufgabe mit einem --next, auf das eine neue Sitzung kalt reagieren könnte. Geben Sie unfertige Arbeit mit --status ready --log "freigegeben: <Zustand>" frei.
• Für „Was ist offen?", „Wo stehen wir?" oder „Was hat die andere Sitzung gemacht?", antworten Sie aus bl list (--all, --area X, --session Y), nicht aus dem Gesprächsgedächtnis.
• Der Rückstand gehört zu einem Gerät. Sitzungen auf anderen Geräten oder in der Cloud verwenden ihn nur über einen Link zu diesem Gerät.
• Wenn ein Befehl sagt, dass eine Aufgabe beschäftigt ist, schreibt eine andere Sitzung gerade daran. Wiederholen Sie es einmal nach einem Moment.

8. Wann Erfassung übersprungen werden soll

Überspringen Sie die Erfassung nur für eine einmalige Frage, die in derselben Antwort vollständig beantwortet wird. Erfassen Sie alles andere: alles mit einem lieferbaren Ergebnis, alles, das mehr als einen Durchgang umfasst, und alles Zurückgestellte. Im Zweifelsfall erfassen Sie es.

9. Offline-Modus (kein Benutzergerät erreichbar)

1. Spiegeln Sie die Aufgaben in der eigenen Aufgabenliste Ihrer Plattform (falls vorhanden) oder einer Checkliste in Ihrer Antwort (falls nicht).
2. Stellen Sie jede beabsichtigte bl.py-Operation, ein JSON-Objekt pro Zeile, in backlog-pending.jsonl in Ihrem Scratch-Bereich (niemals im Projekt des Benutzers): {"cmd":"add","args":{…},"at":"<iso>"}.
3. Sagen Sie dem Benutzer einmal: „Ihr Computer ist nicht erreichbar, daher werden Rückstandsaktualisierungen in eine Warteschlange gestellt und synchronisiert, sobald er wieder verfügbar ist."
4. Versuchen Sie es in jedem Durchgang erneut mit dem Gerät. Sobald es erreichbar ist, spielen Sie die Warteschlange der Reihe nach ab und führen Sie bl open aus.
5. Wenn die Sitzung endet, bevor die Synchronisierung erfolgt ist, muss die letzte Antwort die nicht synchronisierten Aufgaben vollständig auflisten.

10. Das Board

board.html wird bei jedem Schreibzugriff neu generiert und aktualisiert sich alle 30 Sekunden selbst. Es zeigt:

• Schwimmbahnen nach Bereich, mit den Spalten Zu erledigen / In Arbeit / Blockiert / Wartet auf / Erledigt
• Soort und Countdown auf jeder Karte, mit überfälligen Aufgaben in Rot
• Welche Sitzung jede Aufgabe erstellt, bearbeitet und abgeschlossen hat
• Durchklick zum vollständigen Protokoll und den Ausgaben

BOARD.md ist dasselbe Board als Text.

Wenn der Benutzer es sehen möchte („Zeig mir meinen Rückstand", „Öffne das Board", „Was ist offen?"):

• Auf dem Computer, der den Rückstand enthält, führen Sie bl board --open aus, um es im Standardbrowser zu öffnen.
• Wenn kein Browser auf diesem Computer erreichbar ist (z.B. ein Telefon-Chat), fügen Sie eine kurze Zusammenfassung aus bl list ein, gruppiert nach Bereich, mit überfälligen und auf Benutzer wartenden Aufgaben zuerst.
• Das Board ist eine lokale Datei. Es wird nie veröffentlicht, hochgeladen oder geteilt.

11. Plattformhinweise

• MCP-Clients (beliebiges Assistenten- oder Agentenframeworks). scripts/backlog_mcp.py ist ein stdlib-MCP-Server über stdio, der backlog_session, backlog_open, backlog_add, backlog_claim, backlog_update, backlog_done, backlog_drop, backlog_list, backlog_show, backlog_footer, backlog_board, backlog_init und backlog_where bereitstellt. Registrieren Sie ihn mit dem Befehl python3 (Windows py, Argumente -3 <Pfad>) und Argumenten <Pfad zu backlog_mcp.py>, optional mit env BACKLOG_DIR. Er führt dasselbe bl.py aus, sodass Shell- und MCP-Routen einen gemeinsamen Rückstand haben.
• API-gesteuerte Agenten. Ein Modell, das über eine API aufgerufen wird, hat von sich aus keinen Zugriff auf die Dateien des Benutzers. Der Entwickler führt den MCP-Server (oder bl.py hinter seinem eigenen Tool) auf dem Rechner aus, der den Rückstand besitzt, und gibt dem Modell diese Werkzeuge. Gehostete Code-Sandboxes sind temporär, daher geht ein Rückstand dort verloren, wenn die Sandbox endet; bewahren Sie ihn nicht dort auf.
• Claude Desktop / Cloud / Telefon-Sitzungen, die mit dem Computer des Benutzers verbunden sind (Gerätewerkzeuge wie device_bash, device_request_folder_access, device_commit_files; laden Sie sie über Ihre Tool-Suche, falls sie zurückgestellt sind). Der Rückstandsordner oder sein übergeordneter Ordner (z.B. ~/Documents) muss ein verbundener Ordner sein; falls nicht, rufen Sie device_request_folder_access einmal mit dem Grund „um Ihren Aufgabenrückstand auf diesem Computer zu behalten" auf. Führen Sie dann Befehle über device_bash mit dem verbundenen Pfad aus (z.B. python3 $HOME/mnt/Documents/Aapastech-Backlog/bl.py …). Um bl.py über die Brücke zu installieren, legen Sie die Datei bereit und übertragen Sie sie an das Gerät (device_commit_files).
• Claude Code / Codex / Cursor / andere Codierungsagenten führen die Engine direkt in ihrer Shell aus, gemäß der Tabelle in Abschnitt 1.

Befehlsreferenz

bl init    [--owner NAME] [--areas "A,B,C"] [--title T]       Erstsetup / Besitzer, Bereiche oder Boardtitel ändern
bl version                                                    Engine-Version
bl where                                                      Rückstandsordner, Engine-Version, Board-Link
bl areas   [--add NAME …] [--rename ALT NEU]                  Bereiche auflisten / hinzufügen / umbenennen
bl session --id SID --label L --surface S [--url U]           Eine Sitzung registrieren; offene Aufgaben ausgeben
bl open    --session SID                                      Offene Aufgaben dieser Sitzung + nicht beanspruchte
bl batch   --session SID datei.json|-                         Viele hinzufügen (verschachtelte "children" = Unteraufgaben)
bl add     --session SID --title T --area A --eta 20m [--parent ID] [--status S] [--next N] [--priority P1]
bl claim   ID --session SID [--eta 20m] [--force]
bl update  ID --session SID [--status S] [--eta E --eta-reason R] [--next N] [--log L] [--output O] [--area A] [--title T]
bl done    ID --session SID [--log L] [--output O] [--force]
bl drop    ID --session SID --reason R
bl list    [--all] [--area A] [--session SID] [--json]
bl show    ID
bl footer  --session SID [--exclude IDs]
bl board   [--open]