phases-agents

English · Français

Ein lokaler MCP-Server, der Fähigkeiten deterministisch entdeckt, validiert und auswählt. Nur Python-Standardbibliothek, keine Laufzeitabhängigkeiten.

Ein Server. Fünf Werkzeuge. Nichts wird hinter deinem Rücken ausgeführt.

Warum

KI-Agenten improvisieren. Stelle dieselbe Frage zweimal und du erhältst zwei verschiedene Pläne. Das ist für Brainstorming in Ordnung, aber für Audit- und Compliance-Arbeit inakzeptabel.

phases-agents beseitigt die Improvisation. Es profiliert ein lokales Projekt, validiert einen Katalog von Fähigkeiten gegen einen strengen Vertrag und liefert einen Plan, der wiederholbar ist. Gleiches Ziel, gleicher Katalog, gleiche Parameter, gleiche Entscheidung.

Prinzip

configured root identifiers
→ bounded discovery
→ official validation
→ immutable registry
→ verified cache
→ detector profile
→ deterministic selection
→ MCP plan

Der Server wählt aus und legt offen. Das aufrufende Modell liest die ausgewählten Fähigkeiten und entscheidet mit seinen eigenen Werkzeugen, was es damit tut. Der Server führt niemals eine Fähigkeit aus.

Architektur

Der normative Vertrag liegt in core/SKILLS_CONTRACT.md (Französisch).

Schnellstart

Ein Beispielpaket wird in examples/skills/ mitgeliefert. Drei Schritte erzeugen einen echten Plan.

git clone https://github.com/Cherridsaid/phases-agents && cd phases-agents

Erstelle skills-roots.json, das auf die Beispielwurzel zeigt:

{
  "config_version": "1.0",
  "roots": [
    { "id": "demo", "path": "/absolute/path/to/phases-agents/examples/skills" }
  ]
}

python server.py --skills-config /absolute/path/to/skills-roots.json

Der Server liest JSON-RPC zeilenweise von der Standardeingabe. Ein phases_agents_plan-Aufruf gegen ein Python-Projekt wählt dann hello-python aus:

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"phases_agents_plan",
 "arguments":{"root_ids":["demo"],"target":"/absolute/path/to/a/project",
 "today":"2026-08-27","plan_version":"B3",
 "client_capabilities":["filesystem_read","filesystem_search"]}}}

Zwei Planformate koexistieren. "B3" benennt das versionierte Format, nicht eine Serverversion; sein offizielles Schema ist core/PLAN_B3_SCHEMA.json. Verwende es für neue Arbeiten. Ohne plan_version liefert das Legacy-Format eine flache Liste von Schritten; es wird beibehalten, damit bestehende Aufrufer nicht brechen, und wird vor der Entfernung veraltet. client_capabilities wird nur in B3 akzeptiert, da die Angabe, was der Client kann, nur in diesem Format Sinn ergibt.

Einen MCP-Client verbinden

Claude Code (.mcp.json im Wurzelverzeichnis deines Projekts):

{
  "mcpServers": {
    "phases-agents": {
      "command": "python",
      "args": [
        "/absolute/path/to/phases-agents/server.py",
        "--skills-config",
        "/absolute/path/to/skills-roots.json"
      ]
    }
  }
}

Codex verwendet dasselbe Befehls-/Argumentenpaar in seiner eigenen Konfigurationsdatei. Es ist kein Token und keine Umgebungsvariable erforderlich.

MCP-Werkzeuge

detect(target)
list_skills(root_ids, today)
get_skill(root_ids, today, skill_id)
plan(root_ids, target, today, constraints?)
plan(root_ids, target, today, plan_version, client_capabilities?)
refresh_skills(root_ids, today)

today wird injiziert und nicht von einer Uhr gelesen, sodass jeder Aufruf wiederholbar ist. get_skill nimmt eine Kennung, niemals einen Pfad, und sein Inhalt stammt aus dem validierten Snapshot. Absolute Pfade und erkannte Geheimnisse werden in der öffentlichen Ausgabe maskiert. Jede kodierte JSON-RPC-Antwort bleibt unter 1 MiB.

Der erste Aufruf erstellt das validierte Register. Warme Aufrufe verifizieren Metadaten, ohne Inhalte erneut zu lesen. refresh_skills erzwingt einen Neuaufbau.

Ein Skill-Paket schreiben

Jedes Paket ist ein direktes Kind einer Wurzel und enthält mindestens:

<root>/<skill-id>/SKILL.md
<root>/<skill-id>/phases.json

Der schnellste Weg ist, examples/skills/hello-python/ zu kopieren und die Kennung umzubenennen.

SKILL.md-Frontmatter

Fünf Schlüssel sind erlaubt. Alle optional, alle werden geprüft, wenn vorhanden.

Die vierzehn erforderlichen Abschnitte

Jeder ist eine Markdown-Überschrift (##), in beliebiger Reihenfolge. Abschnittstitel sind französisch, weil sie zum Vertrag gehören; den Inhalt kannst du in jeder Sprache schreiben.

Loi centrale · Ce que ce skill fait · Ce que ce skill ne fait pas · Conditions d'activation · Conditions d'exclusion · Capacites necessaires · Interdictions · Methode d'audit · Contrat de preuve · Format de sortie · Conditions de blocage · Limites connues · Exemples d'entree · Exemple de sortie attendue

phases.json-Felder

Alle erforderlich: schema_version, id, version, title, description, domain, project_types, platforms, activation, exclusions, requires_capabilities, optional_capabilities, forbidden_capabilities, execution_mode, human_approval, output_schema, rules_path, references_path, scripts_path, tests_path, files.

output_schema verwendet die symbolische Form core:SCHEMA_NAME.json.

Geschlossene Vokabulare

project_types muss sich mit dem überschneiden, was der Detektor ausgeben kann: apk, python, skill_package, solana, web.

activation.any verwendet Profilfakten: collects_personal_data, has_api, has_apk, has_authentication, has_database, has_ecommerce, has_eu_context, has_file_upload, has_javascript, has_python, has_rust, has_skill_packages, has_solana, has_source_code, has_typescript, has_web, uses_ai, uses_payments.

requires_capabilities, optional_capabilities und forbidden_capabilities verwenden: browser, dependency_installation, filesystem_read, filesystem_search, filesystem_write, human_question, shell, target_code_execution, web.

Bereitgestellte Fähigkeiten sind ein offenes Vokabular: Jeder Katalog benennt, was er mitbringt, und nur die Form wird erzwungen (^[a-z][a-z0-9_]{0,63}$). Nur Client-Fähigkeiten sind geschlossen, weil sie das Protokoll beschreiben und nicht deine Domäne.

Eine domain von legal, juridique, regulatory oder compliance löst ein zusätzliches Regime aus: Jede zitierte Regel muss eine offizielle Quelle, eine Rechtsordnung und ein Prüfdatum tragen.

Was das Schema sagt und nicht sagt

SKILL_MANIFEST_SCHEMA.json beschreibt die Form von phases.json: erforderliche Felder, Typen, geschlossene Vokabulare.

Die Schema-Engine ist bewusst minimal. Sie wendet enum, minLength und minItems an und sonst nichts: kein pattern, kein if/then, kein oneOf. Ein Schema, das diese Schlüsselwörter verwendet, würde selbst abgelehnt.

Die Konsequenz ist wichtig: Bedingte Regeln leben in validator.py, das die Quelle der Wahrheit bleibt. Die Versionsregel ist das Beispiel — provides_capabilities ist in einem 1.0-Manifest verboten und in einem 1.1-Manifest erforderlich. Diese Regel wird durchgesetzt und getestet, ist aber nicht im Schema ausdrückbar. Lies required nicht als den gesamten Vertrag.

Ein Paket nur mit SKILL.md schlägt fehl. Ein ungültiges Paket blockiert das Register, anstatt still zu degradieren.

Identität

phases.json.id ist die Identität, und SKILL.md.name muss damit übereinstimmen. Das Verzeichnis muss denselben Schlüssel tragen. Schlüssel werden mit NFKC normalisiert und dann casefold, sodass Homoglyphen keine zweite Identität einschmuggeln können. Jede Kollision blockiert den gesamten Build; kein Paket wird willkürlich gewählt.

Auswahl

Jede gültige Fähigkeit im Register landet in genau einer Kategorie, mit ihrer Begründung. Nichts wird still verworfen.

Das einzige bewiesene automatische Signal ist:

project_types ∩ profile.types

Plattform, Domäne und Fähigkeiten filtern nur, wenn der Aufrufer diese Einschränkungen liefert. Eine verbotene Fähigkeit lehnt den Skill ab. Es wird kein semantischer Score erfunden, und der Plan wird nach Kennung sortiert.

Ein leerer Plan ist explizit gültig: Er trägt NO_COMPATIBLE_SKILL.

Der B3-Plan klassifiziert jede installierte Fähigkeit über skills_selected, skills_not_applicable und skills_blocked; jede Fähigkeit erscheint genau einmal. skills_missing listet Fähigkeiten ohne ausführbaren Anbieter auf, abgeleitet nur aus bestätigten Fakten. Eine Lücke beweist niemals Nicht-Konformität — sie sagt, dass ein als notwendig erachtetes Audit nicht abgedeckt ist.

Grenzen

• maximal 16 Wurzeln

• nur direkte Tiefe

• maximal 1.000 Pakete

• 10.000 Einträge pro Wurzel

• SKILL.md auf 256 KiB begrenzt

• eine einzelne Referenz auf 256 KiB begrenzt, insgesamt 1 MiB

• Snapshots auf 16 MiB begrenzt

• öffentliches Ergebnis auf 1 MiB begrenzt

• 100 Probleme pro Paket

• Fingerabdruck auf 100.000 Knoten begrenzt

Aufrufer dürfen diese Grenzen nur senken, nie erhöhen.

Laufzeitbeschränkungen

• Python >=3.11

• keine Laufzeitabhängigkeit von Drittanbietern

• kein implizites Netzwerk

• keine Laufzeit-Shell

• kein Zielcode ausgeführt

• keine implizite Uhr

• keine Telemetrie

• kein Skill heruntergeladen

pytest ist nur eine Entwicklungsabhängigkeit.

Tests

python -m pytest -q

Erwartetes Ergebnis:

729 passed, 2 skipped
0 failed

Normative Texte werden mit LF-Zeilenenden ausgecheckt, erzwungen durch .gitattributes. Einige Windows-Symlink-Tests werden übersprungen: Sie benötigen ein lokales Windows-Privileg. Windows-Junctions werden wirklich getestet.

Beweisniveau

Der Validator bestätigt nur eines:

STRUCTURALLY_VALIDATED

Er verifiziert nicht das echte Ziel. TARGET_VERIFIED bleibt in V1 verboten.

Sicherheit

Der Lader lehnt Reparse-Punkte ab. Lesevorgänge sind begrenzt und eingeschränkt. Die Ausgabe ist sortiert und deterministisch.

Eine Designentscheidung verdient deine Aufmerksamkeit: detect und plan nehmen einen target-Pfad, der nicht auf die konfigurierten Wurzeln beschränkt ist, weil es darum geht, ein beliebiges Projekt zu profilieren. Führe diesen Server unter einem Konto aus, dessen Reichweite du akzeptierst, und verbinde ihn nur mit einem vertrauenswürdigen Client. Das vollständige Bedrohungsmodell findest du in SECURITY.md.

Nicht-Garantien

• keine universelle semantische Relevanz

• kein externer Skill wird automatisch genehmigt

• keine Prüfung von Skriptinhalten

• kein Beweis für ein tatsächlich eingehängtes Ziel

• keine vollständige Windows-Atomarität

• keine universelle HTML-Erkennung

• keine universelle Geheimnis-Erkennung

• keine garantierte Rechtskonformität

• kein Marktplatz, keine entfernte Quelle

Lizenz

Apache-2.0. Siehe LICENSE und NOTICE.