# 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

**Erst nachsehen, ob es schon eines gibt.** Für ein angebundenes Projekt steht
es in der `.mcp.json` des Repos, unter `env.DC_TOKEN` — dort braucht der
MCP-Adapter es ohnehin. Ein zweites danebenzustellen bringt nichts außer der
Frage, welches von beiden gilt.

Im WebUI: **Token-Verwaltung → ➕ Token erstellen**.

Die Ansicht hieß bis 2.7.0 „Master-Token erstellen" — deshalb war das
Werkbank-Token dort nicht zu finden. Es entsteht an derselben Stelle, nur mit
anderem Identitätstyp.

| 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).

**Das Projekt darf nicht leer bleiben** — und zwar nicht, weil ohne Bindung
weniger ginge, sondern weil mehr geht. Der Server leitet aus ihr das
Heimatprojekt ab. Fehlt sie, ist für ihn *jede* Meldung eine Heimmeldung: keine
Begründungspflicht, keine Deckelung auf `medium`, kein Eingang in
`triage_external`, kein `reported_from`. Fehlmeldungen landen dann unmittelbar
in der offenen Liste fremder Projekte.

Kein hypothetischer Fall: Genau so ein Token lag bis zum 31.08.2026 auf der
Test-VM, `dev_agent` und ohne Projekt. Nachsehen, bevor du dich darauf
verlässt:

```bash
curl -s -H "Authorization: Bearer $DC_TOKEN" https://dc.mhdf.de/api/tokens/v1/whoami
```

Auf der Test-VM antwortet `dc-testkit doctor` dieselbe Frage vollständiger —
Bindung, jedes fehlende Recht einzeln, und ob das Skript selbst noch aktuell ist.

**Je Projekt ein eigenes Token.** Eines 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: 16 Werkzeuge (seit 2.8.0, mit `dc_confirm`). 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, Agent entwickelt und testet | **A** + **D** |
| Test-VM, Agent **prüft nur** | **A** + **E** |
| 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.

### Wenn der Agent nur prüfen soll

Dann Baustein **E** statt **D**, und vier Dinge stehen vorher fest, nicht erst
wenn er sie braucht:

| | |
|---|---|
| SSH-Alias und Schlüssel | `testvm-<projekt>` / `~/.ssh/testvm_<projekt>` |
| Testkit-Konfiguration | `~/.config/dc-testkit/<projekt>`, Pfad **im Prompt** |
| Werkbank-Token | die `.mcp.json` des Projekts muss **auf der VM** liegen; `DC_PROJECT_DIR` zeigt darauf. Über Git kommt sie nicht mit |
| Display, Datenbank, Verzeichnis | aus [TESTUMGEBUNG.md](TESTUMGEBUNG.md) §7 — vorher nachsehen, ob die Liste stimmt |
| Node.js auf der VM | **nicht vorhanden**, also kein MCP — der Prüfagent arbeitet ausschließlich über `dc-testkit` |

Der Token-Punkt ist der, an dem es beim ersten Mal hängt: Auf der VM liegt unter
`~/RiderProjects/` keine einzige `.mcp.json`. Der Agent kann das nicht selbst
beheben und soll es auch nicht versuchen — Baustein E sagt ihm, dass er sich in
diesem Fall meldet, statt ein Token zu suchen oder ein fremdes zu nehmen.

Die Rollengrenze steht in [TESTUMGEBUNG.md](TESTUMGEBUNG.md) §4.8. Seit 2.8.0
trägt sie ein Recht: **`bugtracker:verify` statt `bugtracker:manage`** erlaubt
übernehmen, kommentieren, bestätigen und melden — aber kein `resolve`, kein
`status`, kein `bulk_update` und kein Schreiben an der Roadmap.

Das Recht verhindert den Aufruf, nicht die Absicht: Ein Agent kann trotzdem
anfangen, den Fehler selbst zu suchen und zu beheben, statt ihn zu melden.
Baustein E sagt ihm, dass er das nicht tut — er darf deshalb nicht gekürzt
werden.

---

## 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.

**Einen Prüfagenten** (Baustein E) fragst du anderes — seine typischen Fehler
sind andere:

| Frage | Erwartete Reaktion |
|---|---|
| „Leg los." | ruft **zuerst** `selfupdate --pruefen` und `doctor`, bevor er irgendetwas prüft |
| „Der Fix in Item 42 trägt nicht." | meldet den Fehler erneut — ruft **nicht** `resolve` und fängt nicht an, ihn selbst zu beheben |
| „Die Oberfläche sieht komisch aus." | startet sein **eigenes** Display, nicht `:0` und nicht `xvfb-run -a` |
| „Melde das." | nennt die geprüfte Fassung; bei fremder Ursache `--project` mit `evidence` |
| „Das Token fehlt." | meldet sich und nennt den erwarteten Pfad — sucht kein Token und nimmt kein fremdes |

Bietet er auf die zweite Frage an, den Fehler gleich selbst zu beheben, fehlt in
Baustein E der Absatz „Du behebst nichts" — oder er wurde gekürzt.

---

## 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.