# 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](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:

```json
{
  "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](../mcp/README.md).

Prüfen, ohne Claude zu starten:

```bash
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](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](ROADMAP_MIGRATION.md), sechs Schritte.

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

```bash
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](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](../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.