Agent DX (Thulr/agent-skill-kit)

Agent DX

Die Developer Experience einer Oberfläche, bei der ein KI-Agent der Entwickler ist – ein SDK, Tool, strukturierte Ausgabe, Fehlerhülle oder Telemetrie, die ein Agent konsumiert, um damit zu bauen oder durch sie zu handeln. Die Herkunft liegt in skill.json; diese Datei dient nur dem Runtime-Routing.

Erzeugt: eine change-plan.md (DO), einen audit-report.md plus ein Findings-Ledger + Workflow-Status, wenn nachverfolgt (REVIEW), oder eine design-doc.md / refactor-runbook.md / explanation.md (DESIGN).

Kernprinzip

Ein Agent konsumiert die Oberfläche allein, mit Maschinengeschwindigkeit, ohne auf einen Tooltip zurückgreifen zu können. Daher liegt die Messlatte für jedes SDK, Tool, jeden Fehler oder Span darin, ob ein stochastischer Konsument es parsen, sich davon erholen und nicht davon geschädigt werden kann: typisierte Verträge statt Prosa; Recovery mitgedacht, nicht erhofft; die Vertrauensgrenze standardmäßig geschlossen. Es sitzt oberhalb der HTTP-Client-Ebene, die dx-audit / dx-design besitzen, und ersetzt diese nie.

Aktivierung

• Reiner Aufruf ("use agent-dx", "überprüfe unsere MCP-Tool-Oberfläche", "start"): Lade references/intent-router.csv, zeige das Intent-Menü, biete den Modus an. Warte. Keine Dateiinspektion, Netzwerkaufrufe oder Schreibvorgänge.
• Konkreter Aufruf mit Intention und Oberfläche ableitbar: springe zu Schritt 3.
• Mehrdeutiger Umfang: Stelle eine klärende Frage, die die Kandidaten-Intention oder -Oberfläche benennt; durchsuche nicht zuerst private Systeme.

Workflow

1. Intention wählen. Lade references/intent-router.csv; ordne do, review oder design zu. Mehrdeutig → einmal fragen.
2. Oberfläche wählen. Lade references/intents/<intent>.csv; ordne eine oder mehrere von sdk-design, tools-and-mcp, structured-output, errors-and-retry, sdk-telemetry – oder all für einen REVIEW-Fan-out – zu. Mehrdeutig → einmal mit Menü fragen.
3. Grounded-Kontext laden. Lade nur das Playbook der gewählten Zeile plus deren core_refs. Lade keine anderen Playbooks (die Zeile review/all trägt keine – jede Oberflächen-Agenten laden ihre eigenen; siehe Schritt 6).
4. Zielpersona identifizieren aus references/core/personas.md.
5. Dann auf Projektgröße kalibrieren (REVIEW / DESIGN) gemäß references/calibration.md: unterhalb von Lasttragend den Umfang eingrenzen, gleichartige Lücken zu einem systemischen Befund zusammenfassen und Jetzt vs. Später (beim Wachsen) trennen. Die Stufe speist die Emission, niemals den Schweregrad.
6. Linsen parallel versenden (REVIEW default, wenn erlaubt): eine Oberfläche pro Agent für all; sonst die drei Linsen unten. Sequentieller Rückfall, wenn kein Delegations-Primitiv vorhanden.
7. Das Playbook anwenden. Verwende die für die Intention getaggten Heuristiken. Bei REVIEW bewerte jede Oberfläche mit 0–10 (references/core/score-rubric.md); synthetisiere die Linsen-Befunde und erhalte Meinungsverschiedenheiten als offene Fragen. Wende Schweregrad und stabile AGENT-DX-<oberfläche>-NNN-IDs an (references/core/severity-rubric.md): AGENT-DX-SDK, AGENT-DX-TOOL, AGENT-DX-OUT, AGENT-DX-ERR, AGENT-DX-TEL.
8. Ausgabe. DO → templates/change-plan.md. REVIEW → templates/audit-report.md. DESIGN → templates/design-doc.md (Form), templates/refactor-runbook.md (Abfolge einer Härtung) oder templates/explanation.md (Erklärung eines Prinzips).
9. Nachverfolgungsstatus erstellen, fortsetzen oder schließen (REVIEW). Für ein Audit mit 7+ Befunden, einem Schweregrad 3–4 oder einer Anfrage zum Speichern/Nachverfolgen/Abschließen lade references/trackable-findings.md. Wenn die Anfrage ein bestehendes Ledger, einen Workflow-Status, einen PR oder eine AGENT-DX-*-ID nennt, lies zuerst den gespeicherten Status; aktualisiere Status nur, nachdem jede Verifikationsregel bestanden wurde. Andernfalls schreibe das Ledger unter docs/audits/agent-dx-findings-ledger-<YYYY-MM-DD>-<scope-slug>.md und den Workflow-Status unter docs/audits/agent-dx-workflow-state-<YYYY-MM-DD>-<scope-slug>.json (falle zurück auf audit-artifacts/agent-dx-..., wenn docs/audits/ nicht beschreibbar ist). Melde beide Pfade; halte Roadmaps, Issues und nicht nachverfolgbare Bearbeitungen als Opt-In.

Modi

Guided Draft (Standard), Autopilot, Grill Me – siehe references/modes.md. Bei reinem Aufruf anbieten; bei konkreten Aufrufen standardmäßig Guided Draft verwenden.

Ausgabeanforderungen

Jede Ausgabe benennt die Intention, Oberfläche(n), Persona, angewandte Playbooks und Begründungsquellen aus skill.json; REVIEW fügt Schweregrad + Verifikation pro Befund sowie die Projektstufe hinzu. Nenne die Agenten-Konsumierbarkeitsgarantien, die du bewusst NICHT hinzufügst (YAGNI), nicht nur die, die du hinzufügst.

Subagenten-Dispatch

Standard für REVIEW, wenn Delegation erlaubt ist; überspringe winzige oder geheimnisgebundene Arbeiten. Starte drei Linsen parallel – Vertrag-und-Schema (typisierte Schemas aus Code, stabile Fehlerhülle, validierte Ausgabe), Agenten-Wiederherstellung (stop+verify, wiederholungsfähige Fehler, semantischer Wiederholungsversuch, begrenzte Schleife), Vertrauen-und-Isolation (Tool-Metadaten-Injektion, Leitplanken-Checkpoints, Credential-Walls, Inhaltsredaktion) – gemäß references/subagent-dispatch.md, synthetisiere dann, ordne nach Schweregrad.

Referenzkarte

• references/intent-router.csv + references/intents/<intent>.csv – die zwei Routing-Ebenen.
• references/playbooks/<surface>.md – sdk-design, tools-and-mcp, structured-output, errors-and-retry, sdk-telemetry.
• references/subagent-dispatch.md – Drei-Linsen-Prompts und Synthese.
• references/core/{severity-rubric,score-rubric,personas,glossary}.md – Skalen, Zielgruppe, Begriffe.
• references/{calibration,trackable-findings,modes}.md – gemeinsam genutzt (Symlinks).
• templates/*.md – change-plan, audit-report, design-doc, refactor-runbook, explanation, plus die gemeinsam genutzten Nachverfolgungsartefakte.
• evals/, skill.json – Tore und Herkunft.