Levix-Digital/plan-memory

📐 Fertigkeit zur Projektplanerinnerung (plan-memory)

Pfade: <skills_root> ist der Ordner, der diese Fertigkeit enthält (das übergeordnete Verzeichnis dieses SKILL.md-Ordners). Verwenden Sie den tatsächlichen absoluten Pfad, wenn Sie die Befehle ausführen.

Die plan-memory-Fertigkeit bewahrt 100% vollständige, unkomprimierte Architekturpläne, strategische Roadmaps und mehrstufige Baupläne eines Projekts, die von allen Beteiligten gemeinsam genutzt werden.

• Quelle der Wahrheit: eine Markdown-Datei pro Plan im Projekt-Repository, docs/plans/<plan_id>.md (YAML-Frontmatter + Planinhalt). Pläne werden versioniert, überprüft und zusammen mit dem Code gemergt. Ändern Sie den Ordner mit "plans_dir" in der .dev-cycle.json des Projekts.
• Suchindex: eine lokale ChromaDB unter ~/.ai-code-agent-memory/plan-memory/db (überschreibbar mit PLAN_MEMORY_DB), Sammlung plan_index. Sie ist wegwerfbar: Jeder Befehl synchronisiert sie aus den Dateien (per SHA-256), und rebuild_index (Engine) erstellt sie neu.
• Projekt: Wird aus dem Git-Repository des aktuellen Verzeichnisses (oder --dir) aufgelöst: project_name in .dev-cycle.json, andernfalls der Repository-Ordnername, normalisiert in Kebab-Schreibweise. --project überschreibt dies.
• Ebenen: das Backlog (docs/BACKLOG.md) erfasst Aufgaben in Sekunden, ohne Analyse, gruppiert unter Epics; die Roadmap (docs/ROADMAP.md) ordnet die Releases und weist ihnen Aufgaben zu; ein Plan wird erstellt, wenn der Benutzer Backlog-Elemente befördert, und enthält die Analyse und Planung (siehe „Backlog“ und „Roadmap“).
• Spec Kit-Umschläge: Wenn das Projekt Spec Kit verwendet, ist ein Feature-Plan ein Umschlag (spec_dir) eines Spec Kit-Ordners (specs/NNN-slug/), der die Details enthält; Suche, Abweichungserkennung und get_plan lesen die Artefakte des Ordners zusammen mit dem Plan (siehe „Pläne mit Spec Kit“).
• Leitprinzip: Null-Kompression / Null-Verlust. Pläne werden in ihrer Gesamtheit (Mermaid-Diagramme, Tabellen, Schritte, Formeln, Begründungen) als dauerhaftes Wissen für jeden Entwickler und jede Sitzung bewahrt.

---

🏛️ Plan-Dateiformat

---
plan_id: my_app_blueprint_v1_2_0_two_stage_search
project: my-app
title: Zweistufige Suche mit lokalem Re-Ranking
kind: feature              # feature (Standard) | bug
version: v1.2.0
status: in_progress        # draft | planned | active | in_progress | completed | superseded
author: Jane Doe           # git user.name des Erstellers
created_at: '2026-10-15T16:36:00'
updated_at: '2026-10-16T09:10:00'
session_id: 8abbc3bf-...   # Konversation, in der der Plan entstand (optional)
tags: [search, reranker]
supersedes: my_app_blueprint_v1_1_0_search
superseded_by: null
parent_plan_id: null
backlog_items: [FEAT-004]  # Backlog-Elemente, die der Plan liefert (optional)
spec_dir: specs/004-reranker  # Spec Kit-Ordner mit den Details des Plans (optional)
milestones:
- name: M1 Laufzeitbasis
  done: true
  done_at: '2026-10-15'
  by: Jane Doe
- name: M2 Reranker
  done: false
status_log:
- at: '2026-10-15T16:36:00'
  by: Jane Doe
  status: active
  note: Plan erstellt
---

# Plantitel

...vollständiger Planinhalt in Markdown...

• Die Skripte überschreiben nur das Frontmatter; der Inhalt wird einmalig von save_plan geschrieben (oder von Hand bearbeitet). Meilenstein- und Statusänderungen erzeugen kleine, lesbare Diffs.
• Der Dateiname ist die Plan-ID. Abstammungsfelder (supersedes, superseded_by, parent_plan_id) verweisen auf andere Plan-IDs.
• Die Skripte committen niemals. Der Agent committed die Plan-Dateien zusammen mit der Arbeit, die sie beschreiben (siehe „Team-Workflow“).

---

⚙️ Befehle

Alle Skripte befinden sich in <skills_root>/plan-memory/ und akzeptieren --dir <Projektverzeichnis> (Standard: aktuelles Verzeichnis) und --project <Name>.

1. Plan speichern/aktualisieren mit Abstammung (save_plan)

Schreibt docs/plans/<plan_id>.md mit dem vollständigen Plan, ohne Kürzungen oder Zusammenfassungen. Das Speichern einer vorhandenen ID aktualisiert Titel, Inhalt und Felder unter Beibehaltung von Autor, Erstellungsdatum und Meilensteinfortschritt. --supersedes markiert den älteren Plan als superseded. save_plan läuft auf der nativen Engine. In sh-Shells (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory save_plan \
  --title "Integrierte Roadmap: Python -> Rust, Model Router & Model Kit" \
  --file "path/to/plan.md" \
  --version "v1.2.0" \
  --tags "roadmap,rust_refactor,model_router" \
  --milestones "Priorität 1,Priorität 2,Meilenstein 3" \
  --status "active" \
  --session-id "<session_id>" \
  --supersedes "<old_plan_id>"

Führen Sie in PowerShell stattdessen & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory save_plan [Argumente] aus. Optionen: --id (Standard: <Projekt>_<Titel>-Slug), --parent-id, --content anstelle von --file, --kind feature|bug, --backlog-items "BUG-001,FEAT-002" (verknüpft die Elemente, die dadurch planned werden), --spec-dir specs/NNN-slug (der Plan ist der Umschlag dieses Spec Kit-Ordners).

2. Meilenstein- und Fortschrittsverfolgung (check_milestone)

check_milestone läuft auf der nativen Engine. In sh-Shells (Linux, macOS, Git Bash):

# Fortschritt und Checkliste des letzten aktiven Plans (oder --id <plan_id>):
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --list

# Meilenstein als abgeschlossen markieren (Datum und Autor werden aufgezeichnet):
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --milestone "Priorität 1" --notes "Abgeschlossen via PR #319"

# Meilenstein auf ausstehend zurücksetzen:
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --milestone "Priorität 1" --uncheck

Führen Sie in PowerShell stattdessen & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory check_milestone [Argumente] aus. Der erste abgeschlossene Meilenstein verschiebt einen active-Plan zu in_progress; der letzte verschiebt ihn zu completed.

3. Architekturabweichungs-Detektor (detect_drift)

Vergleicht einen Implementierungsvorschlag, ein Issue oder einen neuen Prompt mit dem aktiven Plan: semantische Ähnlichkeit, Meilensteinabdeckung und -reihenfolge sowie die eigenen Anti-Pattern-Regeln des Projekts. detect_drift läuft auf der nativen Engine. In sh-Shells (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory detect_drift --proposal "Priorität 1: Baue den nativen ReAct-Orchestrator in Rust, der das Python LangGraph ersetzt"
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory detect_drift --file "path/to/proposal.md" --strict   # Exit-Code != 0 bei Konflikt

Führen Sie in PowerShell stattdessen & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory detect_drift [Argumente] aus.

Anti-Pattern-Regeln befinden sich im Schlüssel drift_rules der .dev-cycle.json des Projekts (wird von --dir aufwärts gesucht). Ohne Regeln werden nur Ähnlichkeit und Meilensteine geprüft.

"drift_rules": [
  { "tech": "langchain", "conflict_msg": "Der Basisplan entfernt LangChain." },
  {
    "tech": "parallele Datenbank",
    "negative_markers": ["single source", "settings.db"],
    "proposal_allow": [],
    "conflict_msg": "Der Vorschlag deutet auf eine parallele Datenbank hin, was gegen die Single Source of Truth verstößt."
  }
]

Eine Regel löst einen Konflikt aus, wenn ein gültiger Plan (active/in_progress) die Technologie tech zusammen mit einem Ablehnungsmarker erwähnt und der Vorschlag die Technologie ohne einen erlaubten Ausdruck erwähnt.

• negative_markers (optional): Wörter, die die Ablehnung markieren. Standard: remove, replace, without, forbidden, ... sowie deren portugiesische Entsprechungen, die beibehalten werden, solange vorhandene Pläne noch nicht übersetzt sind.
• proposal_allow (optional): Ausdrücke, die eine Erwähnung akzeptabel machen. Standard: without <tech>, remove <tech>, replace <tech>, ... sowie deren portugiesische Entsprechungen.

4. Pläne auflisten (list_plans)

list_plans läuft auf der nativen Engine. In sh-Shells (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory list_plans [--status active] [--kind bug]

Führen Sie in PowerShell stattdessen & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory list_plans [Argumente] aus.

5. Vollständigen Plan lesen (get_plan)

get_plan läuft auf der nativen Engine. In sh-Shells (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory get_plan --id "<plan_id>"
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory get_plan                  # letzter aktiver Plan

Führen Sie in PowerShell stattdessen & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory get_plan [Argumente] aus.

6. Semantische Suche (search_plans)

search_plans läuft auf der nativen Engine. In sh-Shells (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory search_plans --query "Wie implementiere ich den Model Router im Chat?" [--limit 5] [--all-projects]

Führen Sie in PowerShell stattdessen & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory search_plans [Argumente] aus.

7. Lebenszyklus-Status aktualisieren (update_plan_status)

Setzt den Status des Plans, zeichnet ihn im Status-Log auf und aktualisiert die verknüpften Backlog-Elemente. update_plan_status läuft auf der nativen Engine. In sh-Shells (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory update_plan_status --id "<plan_id>" --status "completed" --notes "Priorität 1 und 2 ausgeliefert."

Führen Sie in PowerShell stattdessen & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory update_plan_status [Argumente] aus.

8. Export (export_plan)

Kopiert einen Plan an einen anderen Ort, als JSON oder Markdown mit oder ohne Frontmatter. export_plan läuft auf der nativen Engine. In sh-Shells (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory export_plan --id "<plan_id>" --format json --output-dir "out/"

Führen Sie in PowerShell stattdessen & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory export_plan [Argumente] aus.

9. Index neu aufbauen (rebuild_index)

rebuild_index läuft auf der nativen Engine. In sh-Shells (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory rebuild_index [--project <name>] [--dir <path>]

Führen Sie in PowerShell stattdessen & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory rebuild_index [Argumente] aus.

---

📥 Backlog (backlog)

Die erste Planungsebene: eine Markdown-Datei (backlog.file in .dev-cycle.json, standardmäßig docs/BACKLOG.md), die beim ersten add aus templates/BACKLOG_TEMPLATE.md erstellt wird.

## Bugs | Features | Improvements | Adjustments | Epics | Closed

### BUG-001: Frontier-Voreinstellung wählt eine veraltete Modell-ID
- **Severity**: high              # bugs: critical | high | medium | low
- **Status**: open                # open | planned | in_progress (done | dropped | duplicate | superseded unter Closed)
- **Found**: 2026-10-16, v0.45.0, PR #333
- **Plan**: -                     # plan id nach der Promotion
- **Description**: `/preset frontier` setzt `claude-3-7-sonnet`, was vom Anbieter abgelehnt werden könnte.

Features (FEAT-NNN), Improvements (IMP-NNN) und Adjustments (ADJ-NNN) haben Priority (high, medium, low) anstelle von Severity. Jedes Element außer einem Epic kann - **Epic**: EPIC-NNN haben. Epics (EPIC-NNN, Abschnitt ## Epics) gruppieren die Elemente des gesamten Produkts; sie haben Priority, Status (open bis zur Schließung), Found und Description, keinen Plan, und werden nie befördert: ihre Elemente werden befördert. validate warnt vor einem offenen Epic, dessen Elemente alle geschlossen sind. IDs werden nie wiederverwendet: geschlossene Elemente bleiben unter ## Closed mit einem - **Closed**:-Hinweis (Datum und Pull-Request, Grund, duplicate of <ID> oder superseded by <ID>[, <ID>...]). Ein Element ist superseded, wenn es durch andere, besser definierte Elemente ersetzt wird (eine Idee, die nach der Entstehung aufgeteilt oder umgeformt wurde); ein duplicate ist dieselbe Anfrage, die doppelt erfasst wurde.

backlog läuft auf der nativen Engine: "<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory backlog <Befehl> [Argumente] in sh-Shells (Linux, macOS, Git Bash). Führen Sie in PowerShell stattdessen & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory backlog [Argumente] aus.

Aufgabe	Befehl
Erfassen	backlog add --type bug|feature|improvement|adjustment|epic --title "<t>" --description "<d>" [--severity S] [--priority P] [--epic EPIC-NNN] [--found-in "v1.2.0, PR #12"]
Fehlgeschlagene manuelle Tests erfassen	backlog add --from-failed --run vX.Y.Z-rc.N [--severity S]
Zusammenfassung (Fehler vor neuer Arbeit zuerst)	backlog summary [--json]
Auflisten, Anzeigen	backlog list [--type T] [--status S] [--epic EPIC-NNN] [--all] [--json], backlog show <ID>
Ändern	backlog set <ID> [--title] [--description] [--severity] [--priority] [--status] [--plan] [--epic ID|-]
In einen Plan befördern	backlog promote <ID> [<ID> ...] [--title T] [--id PLAN_ID] [--version V] oder --into <PLAN_ID>
Schließen	backlog close <ID> [--ref "PR #12"], drop <ID> --reason R, duplicate <ID> --of <ID>, supersede <ID> --by <ID>[,<ID>...], reopen <ID>
Validieren	backlog validate

• Erfassen kostet nichts: keine Analyse, kein Plan. Der Benutzer macht es mit dem /backlog-Befehl; der Agent macht es für Fehler, die er außerhalb des aktuellen Gültigkeitsbereichs findet.
• Befördern erstellt einen draft-Plan aus templates/BUG_PLAN_TEMPLATE.md (jedes Element ein Fehler: Reproduktion, Beweise und Grundursache, Fehlerbehebungsentwurf, Regressionstest) oder templates/FEATURE_PLAN_TEMPLATE.md, mit den kopierten Elementen in seinem Abschnitt Backlog items, und verknüpft beide Richtungen. Die Analyse wird in diesem Plan festgehalten; er wird erneut als active gespeichert, mit Meilensteinen, zur Genehmigung.
• Verknüpfte Elemente folgen ihrem Plan: planned, während der Plan im Entwurf oder aktiv ist, in_progress, wenn er in Arbeit ist, und als done geschlossen, wenn er abgeschlossen ist (check_milestone und update_plan_status auf der Engine).
• Triage ist die Entscheidung des Benutzers: Der Agent befördert, verwirft oder priorisiert niemals eigenständig.
• Das Skript committed niemals und weigert sich, eine Datei umzuschreiben, deren Struktur es nicht lesen kann, so dass manuelle Bearbeitungen niemals verloren gehen.

---

🗺️ Roadmap (roadmap)

Die Releases des Produkts in Lieferreihenfolge (roadmap.file in .dev-cycle.json, standardmäßig docs/ROADMAP.md), die beim ersten add aus templates/ROADMAP_TEMPLATE.md erstellt wird.

# Projekt-Roadmap: `my-app`

| Release | Datum | Status | Elemente |
|---------|-------|--------|----------|
| v1.1.0  | 2026-10-01 | released | FEAT-001, BUG-002 |
| v1.2.0  | 2026-12-15 | geplant | IMP-001, FEAT-003 |

roadmap läuft auf der nativen Engine: "<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory roadmap <Befehl> [Argumente] in sh-Shells (Linux, macOS, Git Bash). Führen Sie in PowerShell stattdessen & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory roadmap [Argumente] aus.

Aufgabe	Befehl
Neues Release hinzufügen	roadmap add --version v1.2.0 --date 2026-12-15
Release-Elemente verwalten	roadmap link <VERSION> <ID> [<ID> ...], roadmap unlink <VERSION> <ID> [<ID> ...]
Status setzen	roadmap status <VERSION> --status planned|released|cancelled
Anzeigen	roadmap show [--json]

---

🧩 Plan-Templates

Pläne werden aus Vorlagen im Ordner <skills_root>/plan-memory/templates/ erstellt:

• BUG_PLAN_TEMPLATE.md – Grundursachenanalyse, Reproduktion, Fehlerbehebungsentwurf, Testliste.
• FEATURE_PLAN_TEMPLATE.md – Ziele, Kontext, Entwurf, Meilensteine, Risiken.

Die Agenten können auch Vorlagen für bestimmte Sprachmodelle aus dem templates/agent/-Unterordner lesen.

---

🧩 Pläne mit Spec Kit

Wenn das Repository einen spec_dir in .dev-cycle.json hat, ist plan-memory mit Spec Kit integriert. Ein Feature-Plan wird dann zum Umschlag eines Spec Kit-Ordners (specs/NNN-slug/), der die detaillierten Spezifikationen enthält.

---

🤝 Team-Workflow

Pläne sind Code: versioniert, überprüft, gemergt.

1. Entdecken: Der Benutzer oder Agent erfasst ein Backlog-Element (backlog add) für eine Aufgabe außerhalb des aktuellen Plans.
2. Analysieren: Der Benutzer befördert das Element zu einem Plan (backlog promote), was aus der Vorlage einen Plan im Entwurfsstatus erstellt. Der Agent schreibt die Analyse in den Plan und setzt ihn auf active.
3. Arbeiten: Der Agent folgt dem aktiven Plan und markiert Meilensteine als erledigt (check_milestone). Der Fortschritt wird an das Backlog und die Roadmap weitergegeben.
4. Abschließen: Wenn der letzte Meilenstein abgeschlossen ist, wird der Plan auf completed gesetzt. Alle verknüpften Backlog-Elemente werden geschlossen.
5. Überprüfen: Die Roadmap wird aktualisiert (roadmap status released), wenn eine Version ausgeliefert wird.

Die Agenten committen niemals Pläne selbst. Pläne werden zusammen mit dem Code committet, den sie beschreiben.

---

🧪 Plan-Validierung (validate_plans)

Ein Dienstprogramm, das überprüft, ob:

• Alle Pläne gültiges YAML-Frontmatter haben
• Alle plan_id-Werte eindeutig sind
• Abstammungsverweise (supersedes, parent_plan_id) auf vorhandene Pläne verweisen
• backlog_items auf vorhandene Backlog-Elemente verweisen
• Meilensteine konsistent sind (keine Lücken)

validate_plans läuft auf der nativen Engine: "<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory validate_plans [--dir <Pfad>] in sh-Shells (Linux, macOS, Git Bash).

---

🧠 Agenten-Verhalten

• Der Agent speichert Pläne immer vollständig, ohne Zusammenfassungen.
• Der Agent beachtet die Anti-Pattern-Regeln und warnt bei Abweichungen (detect_drift) und schlägt Alternativen vor.
• Der Agent führt keine Triages durch. Der Benutzer entscheidet, welche Elemente befördert oder geschlossen werden.
• Der Agent sucht automatisch im aktiven Plan nach relevanten Details (search_plans), bevor er neuen Code generiert.
• Der Agent informiert über alle relevanten Pläne, wenn er eine neue Aufgabe erhält, die den Umfang des aktuellen Plans überschreitet.

---

🔧 Konfiguration

Schlüssel	Typ	Standard	Beschreibung
plans_dir	string	docs/plans	Verzeichnis für Plan-Dateien (relativ zum Projektstamm)
backlog.file	string	docs/BACKLOG.md	Backlog-Datei
roadmap.file	string	docs/ROADMAP.md	Roadmap-Datei
drift_rules	array	[]	Anti-Pattern-Regeln (siehe detect_drift)
spec_dir	string	–	Spec Kit-Stammverzeichnis (optional)
agent.strategy	string	none	Wie der Agent Pläne verwendet: none, active (liest den/letzten aktiven Plan), planned (liest geplante Pläne)

---

🔍 Fehlerbehebung

• Index ist leer oder veraltet: Führen Sie rebuild_index aus.
• Befehl nicht gefunden: Stellen Sie sicher, dass dev-cycle im Pfad ist oder verwenden Sie den absoluten Pfad zu <skills_root>/dev-cycle-protocol/bin/dev-cycle.
• Datei wird nicht aktualisiert: Das Skript schreibt nur das Frontmatter; der Inhalt bleibt unverändert.