EdwardAstill/agentfiles

Mission (für Agenten)

Dieses Repository ist ein wachstumsorientiertes Agenten-Toolset. Jede Aufgabe ist eine Gelegenheit, das System selbst zu verbessern – aber füge nur etwas hinzu, wenn es absolut einen Zweck erfüllt und der beste Weg ist, diesen zu erfüllen. Aufblähung ist ein schwerwiegender Fehler: Wrapper um bestehende Befehle, Dokumentation, die andere Dokumente wiederholt, CLIs mit einem einzigen sinnvollen Aufrufer. Bevor du etwas Neues hinzufügst, frage: Gibt es diese Fähigkeit bereits? Reicht ein einfaches rg / cat / touch? Wenn ja, füge nichts hinzu.

Wenn du etwas entdeckst, das es wert ist, festgehalten zu werden, füge es mit af note an oder erstelle eine Datei direkt in research/lessons/. Die Recherche-Skills existieren, damit sich das System selbst unterrichten kann – nutze sie, bevor du auf Vermutungen zurückgreifst.

Bevor du architektonische Änderungen planst, konsultiere das Agentenwissen

research/knowledge/ ist das Langzeitgedächtnis des Projekts – der destillierte Output von allem in research/ (Papiere, Projekte, Dokumentation, Lektionen). Bevor du Änderungen am Toolset, der Orchestrierung oder dem Skillsystem vorschlägst, prüfe, was bereits erforscht wurde:

af ak list                           # Index der research/knowledge/ Seiten
af ak show <slug>                    # Eine Seite lesen
af ak grep "<pattern>"               # Volltextsuche innerhalb von knowledge/
rg "<pattern>" research/             # Suche im gesamten research-Baum (auch Rohdaten)
af archetype match "<user intent>"   # Passt diese Aufgabe zu einer bekannten Form?

Wenn eine Wissensseite das Thema bereits abdeckt, baue darauf auf, anstatt es neu zu entdecken. Wenn eine Lektion dem widerspricht, was du tun willst, stoppe und gleiche ab.

Wöchentlicher Verbesserungszyklus

Die Selbstverbesserungsmechanik wirkt nur, wenn jemand sie ausführt. Plane wöchentlich af log review + af skill-usage summary ein (Cron oder Kalendererinnerung) und handle nach der Ausgabe:

# ~/.config/systemd/user/... oder crontab -e
0 9 * * 0  /home/benutzer/.local/bin/af log review >> ~/.claude/logs/reviews/$(date +\%F).md

Überfliege nach der Überprüfung:

• ~/.claude/logs/observations.md – Anomalien und Lektionen, die von af log review erstellt wurden. Befördere jedes wiederkehrende Muster zu einer Skill-Änderung oder einer Wissensseite (siehe die Promotionsregel in research/knowledge/README.md).
• af skill-usage summary – die "nie geladen"-Liste zeigt dir, was im Katalog Ballast ist; "Top Dispatch Chains" schlägt Kandidaten für Trigger-Verkabelungen vor.

Wenn zwei aufeinanderfolgende Wochen nichts hervorbringen, das eine Aktion erfordert, ist das immer noch ein Signal – protokolliere die "No-Op-Review" in research/lessons/, um einer Überanpassung des Rituals vorzubeugen.

---

agentfiles – Claude Code Anleitung

Dieses Repository ist die Quelle der Wahrheit für eine persönliche Claude-Code-Skill-Suite. Skills werden über af install in ~/.claude/skills/ (benutzerebene) oder .claude/skills/ (projektebene) als symbolische Links installiert.

Slash-Befehle

Skills verwenden die Form /skill-name (z. B. /git-expert, /brainstorming). Dies sind die manuellen Überschreibungen – verwende sie, wenn du genau weißt, was du willst. Andernfalls übernimmt der Executor die automatische Weiterleitung.

Für den täglichen Gebrauch musst du diese nicht eingeben – using-agentfiles wird zu Sitzungsbeginn ausgelöst und das System leitet automatisch über den Executor weiter.

Welcher Skill wann

Situation	Skill
Neue Aufgabe (Standard)	executor
Neue Funktion / Komponente / Design	brainstorming zuerst, dann executor
Fehler oder unerwartetes Verhalten	systematic-debugging
Unbekannte Codebasis	codebase-explainer
Umsetzungsplan ausführen	writing-plans → subagent-driven-development
Python / TypeScript / Rust / Typst Arbeit	python-expert / typescript-expert / rust-expert / typst-expert
API-Design oder -Überprüfung	api-architect
Datenbankschema / Migrationen / Abfragen	database-expert
Sicherheitsaudit	security-review
Leistungsprobleme	performance-profiling
Umfangreiche Umstrukturierung	refactoring-patterns
Docker / K8s / Terraform	infrastructure-expert
Abhängigkeitsupdates / CVE-Scans	dependency-management
Logging / Tracing / Metriken	observability
Web-Barrierefreiheit	accessibility
Git-Operationen / Worktrees	git-expert / git-worktree-workflow
GitHub PRs, Issues, Actions	github-expert / github-actions-expert
"Wie verwende ich X?" – API-Nachschlagewerk	docs-agent
"Sollte ich X verwenden?" – Abwägungen	research-agent
Fragen aus Referenzmaterial beantworten	test-taker
Notizen oder interaktive Lektionen schreiben	readrun
Parallele Multi-Agenten-Arbeit	manager
Skill erstellen oder bearbeiten	writing-skills

Wichtige Fakten

• Skills befinden sich in agentfiles/<kategorie>/.../<skill-name>/SKILL.md – vier Kategorien: management/, planning/, coding/, research/
• Jede Kategorie hat einen Verteiler unter agentfiles/<kategorie>/SKILL.md, der zum richtigen Blattskill weiterleitet
• Führe af agents --tree aus, um die vollständige Live-Hierarchie zu sehen
• Regionale Dokumentation unter agentfiles/<kategorie>/REGION.md – der Manager liest diese während der Planung
• Installation: ./install.sh (Bootstrap), dann af install (vollständige Installation). Oder ./bootstrap.sh für neue Maschinen.
• CLI: af <unterbefehl> – Python-CLI unter tools/python/src/af/, installiert über uv tool

Skill-Dateiformat

---
name: skill-name          # Kleinbuchstaben, nur Bindestriche
description: >
  Verwende bei [Auslösebedingungen]. Bleibe unter insgesamt 1024 Zeichen.
  Dies ist das, was Claude liest, um zu entscheiden, ob der Skill aufgerufen werden soll.
---

Das Beschreibungsfeld ist das Einzige, das für andere Skills sichtbar ist, ohne diesen Skill aufzurufen. Schreibe es so, dass eindeutig ist, wann es ausgelöst werden soll.

Regionsdokumentations-Synchronisationsregel

Immer wenn ein neuer Blattskill hinzugefügt oder entfernt wird, aktualisiere die REGION.md für seine Kategorie.

Regionale Dokumente (agentfiles/<kategorie>/REGION.md) sind die Skill-Kataloge, die der Manager während der Planung liest. Jeder Eintrag verwendet das Überschriftenformat ### skill-name. Wenn sie von der Realität abweichen, wird der Manager falsch planen.

Führe vor dem Einchecken von Änderungen an agentfiles/ af check aus, um sicherzustellen, dass alle Blattskills einen Eintrag in der REGION.md ihrer Kategorie haben.

manifest.toml

Deklariert Tool-Anforderungen pro Skill und welche Bin-Einträge zu installieren sind. Aktualisiere es bei:

• Hinzufügen eines neuen Skills mit Tool-Anforderungen
• Hinzufügen eines neuen Bin-Eintrags
• Ändern der Tool-Anforderungen eines Skills

[skills.skill-name]
tools = ["Bash", "Read"]   # Claude-Code-Toolnamen
mcp = ["context7"]         # MCP-Servernamen (optional)

Checkliste zum Hinzufügen eines neuen Skills

• Entscheide, welche Kategorie: management/, planning/, coding/ oder research/
• Erstelle agentfiles/<kategorie>/[unterkategorie/]<skill-name>/SKILL.md mit gültigem Frontmatter
• Füge den Ordner scripts/ hinzu, wenn der Skill Helfer-Skripte benötigt
• Füge einen Eintrag zu manifest.toml unter [skills.<skill-name>] hinzu
• Füge einen Eintrag zur agentfiles/<kategorie>/REGION.md der Kategorie unter ### skill-name hinzu
• Führe af install aus (der symbolische Link wird in der nächsten Sitzung erkannt)

Architekturnotizen

Zweipfad-Orchestrierung:

• executor – Standardeinstiegspunkt für jede neue Aufgabe. Orientiert sich mit af context/af status, trifft die Weiterleitungsentscheidung inline und bearbeitet die Aufgabe durchgängig. Bindet spezialisierte Skills inline über das Skill-Tool ein. Verifikation ist VOR der Meldung des Abschlusses PFLICHT. Eskaliert an den Manager mit einem strukturierten HANDOFF CONTEXT-Block, wenn parallele Arbeit wirklich notwendig ist.
• manager – nur für echte Multi-Agenten-Arbeit. Liest den Handoff-Kontext vom executor, führt einen Planungsüberprüfungsdurchlauf durch (Design? Git-Strategie? Koordination?), entsendet Agenten und überprüft dann die Ergebnisse mit adaptiver Neuplanung, falls Agenten scheitern. Berater (design-advisor, git-advisor, coordination-advisor) werden nur inline geladen, wenn die entsprechende Entscheidung nicht offensichtlich ist.

Spezialisten sind Skill-Bibliotheken, keine Weiterleitungsziele. Sie werden inline vom executor mit Skill("name") geladen. Sie werden nur dann als Unteragenten entsendet, wenn der Manager explizit parallele Domänenarbeit benötigt.

Git-Experte gibt einen WORKTREE CONTEXT-Block aus – andere Skills sollten danach Ausschau halten, wenn sie wissen müssen, wo Änderungen vorzunehmen sind.

Skills sind unabhängig – jeder Skill funktioniert eigenständig. Die Orchestratoren fügen Koordination hinzu, sie ersetzen nicht die eigenständige Nutzung.

Installation

Zweistufige Installation:

1. Bootstrap (./install.sh): Installiert die af-CLI und den agentfiles-manager-Skill global. Minimal – keine Skill-Auswahl, keine CLI-Tools.
2. Vollständige Installation (af install): Installiert alle Skills, Hooks und CLI-Tools. Unterstützt --global (Standard), --local, --skill, --category, --remove, --dry-run.

Zwei Modi:

• Modus A – alles global: ./install.sh && af install installiert alle Skills global. Funktioniert projektübergreifend ohne projektspezifische Einrichtung.
• Modus B – nur Manager: ./install.sh installiert nur den Manager. Dann in jedem Projekt "Projekt einrichten" sagen, und agentfiles-manager wählt die relevanten Skills aus und installiert sie lokal unter .claude/skills/.

Verwendet symbolische Links, keine Kopien. Änderungen an Skill-Dateien werden sofort übernommen – keine Neuinstallation erforderlich.

Der Manifest-TOML-Parser ist eine einfache awk/grep-Pipeline – halte manifest.toml sauber und vermeide ungewöhnliche Formatierungen (Inline-Kommentare in Wertzeilen, mehrzeilige Arrays usw.).