feat(pi): first-class pi package with harness scaffolding and fleet subagent dispatch

README.md

@@ -99,6 +99,21 @@ npx @rafamacalaba/armada@latest new my-app
 
 Requires Node.js 22+ and an authenticated [opencode](https://opencode.ai) install. Run `armada doctor` to confirm your environment is ready.
 
+### Pi integration
+
+armada ships as a first-class [pi package](https://pi.dev/packages). Inside [pi](https://pi.dev) you get:
+
+- **14 skills** (`armada-contract`, `armada-dispatch`, `armada-gate`, `armada-tdd`, ...), loaded on-demand by the agent or invoked via `/skill:armada-contract`
+- **Prompt templates**: `/voyage <feature>`, `/contract`, `/fleet`, `/armada-status`
+- **Tools & commands**: `armada_fleet` / `armada_status` tools, `/armada-fleet`, `/armada-status`, `/armada-doctor` commands, and a force-push guard
+- **Fleet subagents**: the `armada_dispatch` tool runs the armada team (Galleon, Clipper, Corvette, ...) as isolated pi subagents — single or parallel — with armada's file-ownership boundaries enforced in each agent prompt
+
+```bash
+pi install npm:@rafamacalaba/armada
+```
+
+To run the full fleet inside pi, add `harnesses: ["opencode", "pi"]` (or just `["pi"]`) under `project:` in `armada.yaml` and re-run `armada init`. This scaffolds each role into `.pi/agents/<ship-name>.md` (frontmatter name/description/model, prompt body, edit boundaries) and writes `defaultProvider: "openrouter"` + the orchestrator's OpenRouter model into `.pi/settings.json`, so the whole fleet — orchestrator session and subagents — runs on OpenRouter. Since pi cannot use `opencode-*` model IDs, every role maps to its catalog OpenRouter fallback (override per role in `armada.yaml` with any `openrouter/*` ID). Requires `OPENROUTER_API_KEY` or an existing pi OpenRouter auth.
+
 ### OpenRouter Provider Discounts
 
 Save up to 20x on OpenRouter models by routing to discounted providers (Novita, StreamLake, Xiaomi):

TODO.md

@@ -30,6 +30,7 @@ All in-flight lanes merged. `feat/fleet-dashboard` (#59), `feat/artifacts-under-
 
 ### Wave 2 — first consumers (parallel)
 
+- [x] **Pi harness + fleet subagents** (2026-08-09). armada as a first-class pi extension, phase 2: `project.harnesses` manifest field (`opencode` default, `pi` opt-in); scaffold emits `.pi/agents/<ship-name>.md` per role with every role mapped to its catalog OpenRouter fallback (opencode-* IDs are unusable in pi) and `.pi/settings.json` defaulting the orchestrator session to OpenRouter; edit boundaries appended to the prompt body since pi has no SDK permission globs; `armada_dispatch` pi tool spawns fleet subagents (single + parallel, isolated context, JSON-mode subprocess) for the subagent workflow — orchestrator dispatches specialists and runs independent phases concurrently; extension contributes bundled skills + prompt templates via `resources_discover` in armada-managed repos. Verified live: subprocess events show the pinned openrouter model; single + parallel dispatch receipts. Tests: tests/pi-harness.test.js (9).
 - [ ] **Skills integration** (spec below). Requires: per-role configurability (shipped #52).
   Files: `src/skills/`, generator, manifest, prompts.
 - [x] **Security findings ledger** (#58) (2026-08-03). Per-feature SECURITY_FINDINGS.md schema, generator rendering, security prompt integration.

package.json

@@ -23,6 +23,7 @@
     "template",
     "agents",
     "presets",
+    "pi/**",
     "docs/RELEASING.md",
     "docs/WHY.md",
     "docs/auth-and-cost.md",
@@ -51,6 +52,7 @@
     "node": ">=22"
   },
   "keywords": [
+    "pi-package",
     "opencode",
     "agents",
     "orchestrator",
@@ -68,8 +70,15 @@
     "harness-engineering"
   ],
   "license": "MIT",
+  "pi": {
+    "skills": ["./src/skills"],
+    "prompts": ["./pi/prompts"],
+    "extensions": ["./pi/extensions"],
+    "image": "https://raw.githubusercontent.com/rafmacalaba/armada/main/docs/logo-v2.png"
+  },
   "peerDependencies": {
-    "opencode": "^1.18.0"
+    "opencode": "^1.18.0",
+    "typebox": "*"
   },
   "dependencies": {
     "yaml": "^2.9.0"