Deploymentcenter/docs/AGENTEN_ANBINDEN.md

Ein Projekt und seinen Agenten anbinden

Für dich, nicht für den Agenten. Diese Datei beschreibt, was einmalig je Projekt zu tun ist, damit ein Coding-Agent Bugtracker, Roadmap, MCP-Adapter und die Testwege sinnvoll benutzt.

Der Agent selbst bekommt Textbausteine aus AGENT_PROMPT_TEMPLATE.md — nicht diese Datei.

Reihenfolge einhalten. Jeder Schritt setzt den vorigen voraus.

---

Was ein Agent am Ende können soll

Damit klar ist, worauf die Schritte hinauslaufen — der Ablauf einer Sitzung:

	Der Agent tut	Womit
1	Nachsehen, was ansteht und wer schon dransitzt	dc_roadmap
2	Ein Item exklusiv übernehmen	dc_next_task
3	Prüfen, ob es ein Prüfauftrag ist statt einer Fehlerbehebung	Status am Item
4	Arbeiten, Fortschritt festhalten	dc_comment
5	Was ihm nebenbei auffällt, dort melden, wo die Ursache liegt	dc_report
6	Abschließen oder zurückgeben	dc_resolve / dc_release
7	Ein neues Vorhaben einplanen	dc_report + dc_roadmap_set

Was er nicht tun soll: eine TODO.md anlegen, Status in eine Markdown-Datei schreiben, ein verworfenes Vorhaben erneut vorschlagen, ohne die Begründung gelesen zu haben.

---

1. Werkbank-Token anlegen

Im WebUI unter Token-Verwaltung:

Feld	Wert
Typ (owner_type)	dev_agent
Projekt	das Projekt — nicht leer
Scopes	bugtracker:manage, supervisor:read, watchdog:read

supervisor:manage nur, wenn der Agent Befunde auch abhaken soll. license:dev und updateservice:read nur für die Test-VM (Schritt 5).

Je Projekt ein eigenes Token. Aus der Projektbindung leitet der Server reported_from ab. Ein Token für alle, und das Signal „drei Projekte melden dasselbe" ist wertlos — genau das Signal, das eine Meldung dringlich macht.

Kein Master-Token an einen Agenten. Er darf melden, übernehmen und abschließen; er darf keine Releases veröffentlichen und keine Tokens ausstellen.

---

2. MCP-Adapter einrichten

Der Adapter ist eine Datei ohne Abhängigkeiten. Kein npm install.

Claude Code — .mcp.json im Projektverzeichnis:

{
  "mcpServers": {
    "deploymentcenter": {
      "command": "node",
      "args": ["J:/Softwareprojekte/Deploymentcenter/mcp/deploymentcenter-mcp.mjs"],
      "env": { "DC_TOKEN": "dc_..." }
    }
  }
}

Claude Desktop — %APPDATA%\Claude\claude_desktop_config.json, absoluter Pfad, DC_PROJECT setzen, danach Desktop vollständig beenden und neu starten. Einzelheiten in ../mcp/README.md.

Prüfen, ohne Claude zu starten:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | node mcp/deploymentcenter-mcp.mjs

Erwartet: 15 Werkzeuge. Kommt nichts, liegt es am Pfad oder daran, dass node nicht im PATH steht.

---

3. Die Bausteine in die Projektdatei

In CLAUDE.md bzw. AGENTS.md des Projekts, aus AGENT_PROMPT_TEMPLATE.md:

Lage	Bausteine
Mit .mcp.json	A + B
Test-VM	A + D
Ohne MCP	A + C

Nicht alles einkopieren. Wo der Adapter läuft, tragen die Werkzeuge ihre Beschreibung selbst; Baustein C wären zweihundert Zeilen, die das Modell nie liest und die auseinanderlaufen, sobald sich die Schnittstelle ändert.

Danach einmal dc_link_project aufrufen — dann ist zentral beantwortbar, welche Projekte von einem SDK-Fehler betroffen sind.

---

4. Die Roadmap des Projekts übernehmen

Nur, wenn es eine ROADMAP.md, TODO.md oder eine Sammlung von Planungsdokumenten gibt. Verfahren in ROADMAP_MIGRATION.md, sechs Schritte.

Für Dateien im Format dieses Projekts nimmt ../scripts/roadmap_import.py die Arbeit ab:

python scripts/roadmap_import.py --lesen

Immer zuerst. Dabei fällt auf, was die Datei falsch behauptet. Bei der Übernahme des Deploymentcenters selbst kam heraus: drei Einträge längst erledigt, eine Kennung doppelt vergeben, ein Themenbereich nicht angelegt, und eine erfundene Beispiel-Itemnummer im Fließtext, die ein echtes Item in einem anderen Projekt traf.

Danach --uebernehmen mit DC_TOKEN, Datei umbauen, --check.

---

5. Nur wenn der Agent auf der Test-VM arbeitet

Zusätzlich license:dev und updateservice:read am Token, Ablage unter ~/.config/dc-testkit/, Baustein D statt B. Siehe TESTUMGEBUNG.md §4.2.

Kein Kundenlizenzschlüssel auf die VM. Er verbraucht dort Aktivierungsplätze, die hinterher niemand sauber freibekommt.

---

Was NICHT an die anderen Projekte geht

Die Testinstanz dc-dev.mhdf.de und tests/e2e gehören zum Deploymentcenter und werden nicht je Projekt nachgebaut. Sie prüfen den Server; die anderen Projekte sind dessen Kunden, nicht seine Betreiber. testctl.php kann Tabellen löschen und liegt bewusst nur auf einer Instanz.

Was sich dagegen lohnt zu übernehmen, ist die Haltung dahinter — sie kostet kein eigenes Testtor:

• Ein gefundener Fehler bekommt zweierlei: ein Item im Bugtracker und einen Testfall, der ihn festhält.
• Bekannte, noch offene Befunde blockieren nicht. Der Testfall läuft mit und ist als bekannt vermerkt — mit Item-Nummer. Ein Eintrag ohne Item ist eine Ausrede, kein Befund. Vorbild: ../tests/e2e/bekannte_befunde.json.
• Fehlende Voraussetzung heißt übersprungen, nicht rot. Der Unterschied zwischen „kaputt" und „nicht prüfbar" muss im Bericht sichtbar bleiben — und am Rückgabewert: Ein Lauf, der mehr überspringt als prüft, ist kein bestandener Lauf.

Wer für sein Projekt eine eigene Strecke baut, meldet Fehler des Deploymentcenters weiterhin dorthin — mit evidence.

---

Prüfen, ob es sitzt

Nach der Einrichtung diese vier Fragen an den Agenten stellen. Sie decken genau die Stellen ab, an denen es erfahrungsgemäß hakt:

Frage	Erwartete Reaktion
„Was steht als Nächstes an?"	ruft dc_roadmap auf, liest keine Datei
„Fang mit dem obersten an."	ruft zuerst dc_next_task, dann erst Code
„Lass uns X bauen" (etwas aus Abschnitt H)	sucht die Begründung und widerspricht, statt loszulegen
„Mir ist ein Fehler im SDK aufgefallen"	meldet unter deploymentcenter mit evidence, nicht im eigenen Projekt

Antwortet er auf die erste Frage mit dem Inhalt einer Markdown-Datei, fehlt Baustein A oder der Adapter läuft nicht.

---

Reihenfolge über alle Projekte

1. deploymentcenter — bereits erledigt, das Verfahren ist einmal durchlaufen
2. Ein zweites Projekt vollständig, mit allen fünf Schritten
3. Die übrigen erst danach

Schritt 2 ist der eigentliche Test der Anleitung. Was dabei hakt, gehört als Meldung unter deploymentcenter — die Anleitung ist Teil des Produkts.