feat: Pi-Extension für Crew-Routing und Quota-Balance

.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: ci
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: Install dev dependencies
+        run: npm install --no-fund --no-audit
+      - name: Unit tests
+        run: npm test

.gitignore

@@ -2,3 +2,7 @@ node_modules/
 .no-mistakes/
 *.log
 .DS_Store
+*.tsbuildinfo
+.pi/
+dist/
+coverage/

AGENTS.md

@@ -0,0 +1,38 @@
+# AGENTS.md — firstmate-crew-knowledge
+
+Pi-Package (`pi-package`), das Firstmate bei Crew-Routing und Quota-Balance unterstützt.
+
+## Was dieses Repo ist
+
+- Installierbare Extension: `package.json` → `"pi": { "extensions": ["./index.ts"] }`
+- Tools: `crew_route`, `crew_balance`, `crew_apply_dispatch`, `crew_suggest_primary`
+- Knowledge: `knowledge/*.json` (Task-Klassen, Provider, Profile)
+- Logik in `src/`
+
+## Was es nicht ist
+
+- Kein Ersatz für Firstmate-Core (`bin/fm-spawn.sh`, Intake-Urteil, `quota-array-dispatch`)
+- Kein Auto-Spawn, kein Credential-Store, kein Billing
+
+## Firstmate-Verträge (Pointer)
+
+Autoritative Firstmate-Doku liegt im Firstmate-Home (nicht hier kopieren):
+
+- Dispatch-Schema / `config/crew-dispatch.json` → Firstmate `docs/configuration.md` (Crew dispatch profiles) und `docs/examples/crew-dispatch.json`
+- Array-Auflösung → Firstmate-Skill `quota-array-dispatch`
+- Spawn-Flags → `bin/fm-spawn.sh --harness/--model/--effort`
+- Quota-Daten → `quota-axi --json` (Skill `quota-axi`)
+
+## Lokale Konventionen
+
+- User-facing Docs: Deutsch; kurze English-Section in README ok
+- Commits/PR: Deutsch, ohne AI-Co-Author-Meta
+- Writes nur unter dem aufgelösten Home/config (siehe README) und nur bei explizitem Tool-Call (`dryRun=false`)
+- Tests: `npm test` (Node built-in test runner, Fixtures, kein Netz)
+
+## Maintaining this file
+
+Keep this file for knowledge useful to almost every future agent session in this project.
+Do not repeat what the codebase already shows; point to the authoritative file or command instead.
+Prefer rewriting or pruning existing entries over appending new ones.
+When updating this file, preserve this bar for all agents and keep entries concise.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thelad-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,5 +1,86 @@
 # firstmate-crew-knowledge
 
-Pi-Extension für Firstmate: modell- und harness-Routing pro Task plus ausgewogene Quota über Cursor, Claude, Codex und Grok.
+Pi-Extension für [Firstmate](https://github.com/thelad-dev): empfiehlt pro Task-Klasse konkrete `{harness, model, effort}`-Profile und balanciert die Nutzung über die Captain-Subscriptions **Cursor**, **Claude**, **ChatGPT/Codex** und **Grok (xAI)**.
 
-Status: MVP in Arbeit. Installation und Nutzung folgen nach dem ersten Release.
+> **Wichtig:** Dieses Paket **ersetzt weder Firstmate-Urteil noch `fm-spawn`**. Firstmate bleibt Owner von Intake, `quota-array-dispatch` und dem finalen Spawn. Die Tools liefern nur Empfehlungen, Spawn-Flags und optional eine `crew-dispatch.json`.
+
+## Install
+
+```bash
+# npm (sobald published)
+pi install npm:firstmate-crew-knowledge
+
+# GitHub
+pi install git:github.com/thelad-dev/firstmate-crew-knowledge
+
+# lokaler Checkout
+pi install /pfad/zu/firstmate-crew-knowledge
+```
+
+Voraussetzung: Node ≥ 22.6, Pi Coding Agent. Für Live-Quota: [`quota-axi`](https://www.npmjs.com/package/quota-axi) auf `PATH` (`quota-axi --json`).
+
+## English (short)
+
+Installable Pi package (`pi-package`) that classifies crew work, recommends `--harness/--model/--effort` for Firstmate’s `fm-spawn`, and ranks providers from live `quota-axi --json`. It can dry-run or write `config/crew-dispatch.json` under the resolved Firstmate home. It does **not** auto-spawn and does **not** replace Firstmate judgment.
+
+## Firstmate-Anbindung
+
+| Oberfläche | Zweck |
+| --- | --- |
+| Tool `crew_route` | Task-Text → Klasse + Spawn-Flags + Tradeoff/Quota-Evidence |
+| Tool `crew_balance` | Live-Quota sortiert (Headroom/Runway), degraded wenn `quota-axi` fehlt |
+| Tool `crew_apply_dispatch` | Erzeugt Firstmate-`crew-dispatch.json` (Default: **dry-run**; `merge` hängt fehlende `when`-Regeln an und verweigert unlesbare/ungültige Bestandsdateien) |
+| Tool `crew_suggest_primary` | Listet/sucht authentifizierte Pi-Session-Modelle (`modelRegistry` / `scopedModels`) und empfiehlt ein Primary-Switch-Ziel nur darunter (kein Model-Switch, keine Crew-Panes) |
+| Command `/crew-route …` | Slash-Einstieg: vollständige `crew_route`-Ausgabe via Widget/Notify/Status (ohne Truncation, ohne Editor) |
+
+### Empfohlener Ablauf im Primary
+
+1. Task skizzieren → `crew_route` (oder `/crew-route …`).
+2. Output lesen: Zeile `spawn: --harness … --model … --effort …` plus Rationale.
+3. Optional `crew_balance` für den Gesamtblick über Subscriptions.
+4. Optional `crew_apply_dispatch` dry-run; bei Bedarf mit `dryRun=false` nach `$FM_HOME/config/crew-dispatch.json` schreiben.
+5. **Firstmate** wählt final (ggf. Array via `quota-array-dispatch`) und ruft auf:
+
+```bash
+bin/fm-spawn.sh <task-id> <project> --mode … --yolo … \
+  --harness … --model … --effort …
+```
+
+Schema der Dispatch-Datei entspricht Firstmate `docs/examples/crew-dispatch.json` (`rules[].when/use/why`, `default`).
+
+### Umgebungsvariablen
+
+| Variable | Bedeutung |
+| --- | --- |
+| `FM_HOME` | Operational Home; Schreibziel `config/crew-dispatch.json` |
+| `FM_ROOT_OVERRIDE` | Fallback, wenn `FM_HOME` unset |
+
+Ohne aufgelöstes Home (`FM_HOME` oder Fallback `FM_ROOT_OVERRIDE`) nur Dry-Run/Anzeige — **keine** Writes. Writes gehen ausschließlich nach `<Home>/config/…` (explizites Tool mit `dryRun=false`).
+
+## Knowledge-Pack
+
+Datengetrieben unter [`knowledge/`](knowledge/):
+
+- `task-classes.json` — trivial_fix, standard_ship, hard_multi_file, research_web_live, scout_audit
+- `providers.json` — Rollen/Stärken Claude · Codex · Cursor · Grok, Pi-Model-Muster (`provider/model`)
+- `profiles.json` — konkrete Profile + Dispatch-Template
+
+Tabellen aktualisieren, ohne Scorer-Code anzufassen.
+
+## Fail-closed / Degraded
+
+- `quota-axi` fehlt oder schlägt fehl → klare Meldung, Offline-Heuristik aus Knowledge, Label **`degraded`**. Abbruch der Tool-Ausführung ist Cancellation, nicht Degraded.
+- Unbekannte Quota (einschließlich stale Snapshots) wird **nicht** als 0 behandelt; erschöpfte Provider werden gemieden, wenn Alternativen existieren.
+- Keine Secrets, keine Billing-APIs außer dem lokalen `quota-axi`.
+
+## Entwicklung
+
+```bash
+npm test
+```
+
+Tests laufen ohne Netzwerk gegen Fixture-JSON unter `tests/fixtures/`.
+
+## Lizenz
+
+MIT