justinramos101/agent-skill-kit

Agent DX

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

Erzeugt: eine change-plan.md (DO), eine audit-report.md plus Findings-Ledger + Workflow-State bei Nachverfolgung (REVIEW) oder eine design-doc.md / refactor-runbook.md / explanation.md (DESIGN).

Kernprinzip

Ein Agent konsumiert die Oberfläche allein, mit maschineller Geschwindigkeit, ohne Tooltip als Rückfall. Daher ist die Messlatte für jedes SDK, Werkzeug, jeden Fehler oder Span, ob ein stochastischer Konsument es parsen, sich davon erholen und nicht davon geschädigt werden kann: typisierte Verträge statt Prosa; Wiederherstellung von Grund auf entworfen, nicht erhofft; die Vertrauensgrenze standardmäßig geschlossen. Es sitzt oberhalb der HTTP-Client-Ebene, die dx-audit / dx-design besitzen, und ersetzt sie nie.

Aktivierung

• Bare-Aufruf („use agent-dx“, „start“): Zeige ein kompaktes Menü: Moduswahl (geführt / Autopilot / frag mich?) und nummerierte Absichten aus dem Router. Warten. Keine Dateiinspektion, keine Netzwerkaufrufe, keine Schreibvorgänge.
• Konkreter Aufruf mit Absicht und ableitbarer Oberfläche: Springe zu Schritt 3.
• Mehrdeutiger Aufruf: Frage einmal – z. B. „Prüfst du ein SDK, ein Werkzeugschema, eine strukturierte Ausgabehülle oder eine Telemetrie-Oberfläche?“ oder „Ist das eine Vertrags-/Wiederherstellungsprüfung oder eine Vertrauensgrenzen-Auditierung?“

Workflow

1. Absicht wählen. Lade references/intent-router.csv; gleiche mit do, review oder design ab. Mehrdeutig → einmal fragen.
2. Oberfläche wählen. Lade references/intents/<intent>.csv; gleiche eine oder mehrere von sdk-design, tools-and-mcp, structured-output, errors-and-retry, sdk-telemetry ab – oder all für ein REVIEW-Fan-out. Mehrdeutig → einmal mit dem Menü fragen.
3. Kontext laden. Lade nur das Playbook der gewählten Zeile plus deren core_refs. Lade keine anderen Playbooks (die review/all-Zeile trägt keins – jede Oberflächen-Agentin lädt ihr eigenes; siehe Schritt 6).
4. Die Zielpersona identifizieren aus references/core/personas.md.
5. Dann an den Projektumfang anpassen (REVIEW / DESIGN) gemäß references/calibration.md: Unterhalb von Lasttragend, Umfang eingrenzen, gleichartige Mechanismen-Lücken in einen systemischen Befund zusammenfassen und Jetzt vs. Später (wenn es wächst) trennen. Die Stufe speist die Emission, niemals die Schwere.
6. Linsen parallel versenden (REVIEW-Standard, wenn erlaubt): eine Oberfläche pro Agent für all; ansonsten die drei folgenden Linsen. Sequentieller Rückfall, wenn kein Delegationsprimitiv vorhanden.
7. Das Playbook anwenden. Verwende die für die Absicht getaggten Heuristiken. Bei REVIEW bewerte jede Oberfläche mit 0–10 (references/core/score-rubric.md); synthetisiere Linsen-Befunde und erhalte Meinungsverschiedenheiten als offene Fragen. Wende Schweregrade 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. Ausgeben. DO → templates/change-plan.md. REVIEW → templates/audit-report.md. DESIGN → templates/design-doc.md (Form), templates/refactor-runbook.md (Ablauf einer Härtung) oder templates/explanation.md (ein Prinzip erklären).
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-State, einen PR oder eine AGENT-DX-*-ID nennt, lies zuerst den gespeicherten Zustand; aktualisiere Status nur, nachdem jede Verifikationsregel bestanden wurde. Ansonsten schreibe das Ledger unter docs/audits/agent-dx-findings-ledger-<YYYY-MM-DD>-<scope-slug>.md und den Workflow-State unter docs/audits/agent-dx-workflow-state-<YYYY-MM-DD>-<scope-slug>.json (Rückfall auf audit-artifacts/agent-dx-... wenn docs/audits/ nicht beschreibbar ist). Melde beide Pfade; halte Roadmaps, Issues und Nicht-Nachverfolgungs-Änderungen als Opt-in.

Falsche Richtung? Falls der Benutzer sagt, dass das nicht gemeint war, gehe zurück zu Schritt 1 (Absicht wählen) – flicke nicht in die falsche Richtung. Wiederhole das korrigierte Verständnis und plane neu.

Modi

Geführter Entwurf (Standard), Autopilot, Frag mich – siehe references/modes.md. Beim Bare-Aufruf anbieten; bei konkreten Aufrufen auf Geführten Entwurf standardmäßig einstellen.

Ausgabeanforderungen

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

Subagent-Versand

Standard für REVIEW, wenn Delegation erlaubt ist; überspringe kleine oder geheimnisgebundene Arbeiten. Versende drei Linsen parallel – Vertrag-und-Schema (typisierte Schemata aus Code, stabile Fehlerhülle, validierte Ausgabe), Agenten-Wiederherstellung (stoppen+prüfen, wiederholungsförmige Fehler, semantische Wiederholung, begrenzte Schleife), Vertrauen-und-Isolation (Tool-Metadaten-Injektion, Schutzleisten-Checkpoints, Credential-Walls, Inhaltsredaktion) – gemäß references/subagent-dispatch.md, dann synthetisiere, geordnet nach Schweregrad.

Referenzkarte

• references/intent-router.csv + references/intents/<intent>.csv – die beiden 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/*.md – Schweregrad, Bewertung, Personas, Glossar.
• references/{calibration,trackable-findings,modes}.md – gemeinsam (Symlinks).
• templates/*.md – change-plan, audit-report, design-doc, refactor-runbook, explanation, plus die gemeinsamen Nachverfolgungs-Artefakte.
• evals/, skill.json – Tore und Herkunft.