@getpipher/armory-fleet

The armory suite's subagent orchestrator for the pi coding agent — a cross-harness, superpowers-native fleet where every agent is armory-native from birth.

Why · Features · Quick start · Architecture · The fleet panel · Workflows-as-code · Cost-aware tiers · Roadmap · Ecosystem

Why

The pi-subagent ecosystem is crowded — nicobailon/pi-subagents (2688⭐), tintinweb/pi-subagents (702⭐), QuintinShaw/pi-dynamic-workflows (287⭐), kky42/pi-flow (66⭐), teelicht/pi-superagents (54⭐). Three structural gaps remain open, and armory-fleet owns all three — then reaches parity on the rest to be the best pi-subagent package in the ecosystem.

| Gap | Status quo | armory-fleet | |---|---|---| | Armory-native integration | No external package can integrate with the armory suite; they don't own it. | Agents that sync to armory-todo, hydrate from armory-memory, see via vision, and edit via cursor by default — uncopyable. | | Cross-harness peers | Only one early attempt runs Claude Code + Pi as peer backends, foreground-only. | First-class dual-arsenal topology — pi and Claude Code spawn as sibling backends from one fleet. | | Superpowers-native lifecycle | Only one attempt wraps the superpowers skill pipeline, synchronous-only. | The full superpowers lifecycle (brainstorm → plan → implement → review → finish) with checkpoints, quality gates, and lifecycle hooks baked in. |

Beyond those: a fleet TUI, cron/interval scheduling, git worktree isolation, cost accounting, quality gates, workflows-as-code, and a journaled event-bus — all in one package.

Vision, spine, and the 7-SPEC roadmap live in PRD.md. The landscape deep-read (11+ packages mapped, 5 contenders deep-read) is in research/.

Features at a glance

| Capability | What you get | |---|---| | 🧬 Armory-native agents | Every child syncs to armory-todo, hydrates from armory-memory, sees via vision, edits via cursor — by default, from birth. No bolt-on. | | 🏛️ Cross-harness backends | Spawn pi and Claude Code sessions as peer backends from one fleet. Auto-detect Claude; hook-parity keeps both on equal footing. | | 🦸 Superpowers lifecycle | brainstorm → plan → implement → review → finish, checkpoint-driven, skill-loaded per phase. /fleet-implement <task> runs the whole pipeline. | | 🎚️ Cost-aware tiers | economy / standard / frontier model tiers with cost caps + context floors. Route cheap work to cheap models, escalate when it matters. Live cost $ + context % per run. | | 🚦 Quality gates | verification-before-completion, completeness-check, gate, verify — built-in. Register your own. Composite helpers: judgePanel, loopUntilDry, retry. | | 🧩 Workflows-as-code | Author multi-phase workflows in a JS DSL with agent(), pipeline(), phase(), checkpoint(). 5 builtins ship: adversarial-review, code-review, codebase-audit, deep-research, multi-perspective. Journaled + resumable. | | 🖥️ Fleet TUI | /fleet opens an interactive panel: Runs, Tiers, Lifecycle, Workflows, Conversation viewer. Live widget, mid-run Steer/Stop, edit-resume, save-as. | | ⏱️ Scheduling | Cron expressions, intervals, one-shot ISO datetimes. PID-locked scheduler, session-scoped (no catch-up). Background runs on isolated git worktrees. | | 🔒 Worktree isolation | Background runs get isolated git worktrees (in-place fallback for non-git cwds). Foreground runs share the session cwd. | | 📒 RunLog + journaling | Every run is journaled; interrupted workflows recover on restart. A results inbox lets the model pull completed background runs. | | 🔄 Edit-and-resume | Re-run a workflow by replaying the unchanged prefix and re-running only the edited suffix. | | 📡 Vision built-in | describe_image tool is wired into child sessions — agents can see screenshots and diagrams without leaving the fleet. |

Quick start

Install

armory-fleet is a pi extension — it loads inside pi, no build step.

# 1. Add to your pi packages (~/local-dev/arsenal or your package dir)
pnpm add @getpipher/armory-fleet

# 2. Register in ~/.pi/agent/settings.json

// ~/.pi/agent/settings.json
{
  "packages": [
    "@getpipher/[email protected]"
    // + its armory siblings: armory-todo, armory-memory, vision, cursor
  ]
}

# 3. Reload pi (/reload) and open the panel
pi
# inside pi → /fleet

Your first subagent (model-callable tool)

The subagent tool is what the model calls to delegate a focused task. Every child is armory-native by default.

// the agent calls this — not you
subagent({
  agent: "general-purpose",
  task: "Audit src/auth/ for token-handling bugs; report findings.",
  // optional: model, lifecycle, todoId, background, isolation, schedule, maxTurns
});

| Param | Effect | |---|---| | agent | Agent definition to spawn (from agents/ or discovered). | | task | The prompt handed to the child. | | model | Override the session model. Tip: omit to inherit the session model, or use Ollama/... when the session is on Ollama — don't cross providers. | | lifecycle | Run the task through a superpowers lifecycle (e.g. default) instead of a single delegate. | | todoId | Link the run to an existing armory-todo entry. | | track | Default true (syncs to armory-todo). Pass false only for throwaway lookups. | | background | Fire without awaiting — run goes to the async pool on an isolated git worktree. | | isolation | worktree (default for bg in a git repo) · none (in-place) · auto. | | schedule | Cron (0 9 * * 1-5), interval (30m), or one-shot ISO datetime. Session-scoped, no catch-up. | | maxTurns | Per-run turn budget (default 20). Raise for complex multi-step tasks. |

Your first workflow

Workflows are plain JS files evaluated in a sandboxed vm realm. The orchestration primitives — agent, parallel, pipeline, phase, gate, judgePanel, loopUntilDry, retry, checkpoint, verify, workflow, log — are injected globals (no imports). The only thing you export is meta.

// ship-feature.js — drop into a workflows/ dir discovered by WorkflowRegistry
export const meta = {
  name: 'ship-feature',
  description: 'Plan → implement → 3 parallel review angles with a gate',
  phases: [{ title: 'Plan' }, { title: 'Implement' }, { title: 'Review' }],
}

phase('Plan')
const plan = await agent('Plan this feature: ' + args.task, { tier: 'low' })

phase('Implement')
const impl = await agent(`Implement the plan:\n${plan}`, { tier: 'medium' })

phase('Review')
const angles = ['security', 'performance', 'correctness']
const reviews = await parallel(
  angles.map((a) => () => agent(`Review the implementation for ${a} issues.`, { tier: 'low' })),
)

// gate: revise the synthesis until it passes a validator
const synthesis = await gate(
  async (_feedback, n) => n === 0
    ? agent(`Synthesize ${reviews.length} reviews.`, { tier: 'low' })
    : agent('Revise synthesis per feedback.', { tier: 'low' }),
  (v) => typeof v === 'string' && v.length > 200 ? { ok: true } : { ok: false, feedback: 'more detail' },
  { attempts: 3 },
)

return { plan, impl, reviews, synthesis }

Open /fleet → Workflows, pick ship-feature, run it. The panel shows live phase progress; mid-run you can Steer (inject a message) or Stop. The realm also exposes args, cwd, and a budget object ({ total, spent(), remaining() }) so workflows can self-limit.

Your first lifecycle run

/fleet-implement Refactor the auth module to use the new session API --auto

Runs brainstorm → plan → implement → review → finish autonomously. Drop --auto for checkpointed mode (pauses at each checkpoint; continue/revise/abort from /fleet → Lifecycle).

Architecture

                        ┌─────────────────────────────────────────────┐
                        │              pi host session                 │
                        │   (loads @getpipher/armory-fleet extension)  │
                        └───────────────────────┬─────────────────────┘
                                                │
        ┌───────────────────────────────────────┼───────────────────────────────────────┐
        ▼                                       ▼                                       ▼
  subagent tool                          fleet tool                           /fleet panel
  (model-callable)                  (workflow runner)                    (FleetView TUI)
        │                                       │                                       │
        ▼                                       ▼                                       ▼
  createAgentSession()                WorkflowController                  Runs · Tiers · Lifecycle
  (pi SDK child)                      + ConcurrencyPool                   Workflows · Conversation
        │                             + adapters                            + live widget
        ├─→ armory-todo sync          + journal/resume
        ├─→ armory-memory hydrate           │
        ├─→ vision (describe_image)         ▼
        ├─→ lifecycle + gates          backend registry
        └─→ tier routing               (pi | Claude Code)

Core engine

• Engine primitive: createAgentSession() from the pi SDK — child Pi sessions, in-memory or file-backed SessionManager, ResourceLoader. Each child is wrapped to emit session_init on subscribe so the fleet can track it from the first event.
• Child loader: buildChildLoader() threads armory-todo, armory-memory, and vision into every child's resource + tool set — armory-native from birth, cwd-agnostic.
• Concurrency: a single-slot lock for foreground runs + a ConcurrencyPool for parallel workflow branches.
• Turn budget: engine/turn-budget.ts caps each child's run; the subagent tool surfaces exhaustion as a structured status (not a silent truncation).

Armory integration (the uncopyable layer)

| Sibling | What the fleet wires in | Where | |---|---|---| | armory-todo | Every run syncs to the cross-session TODO store. Pass todoId to link. | src/todo-sync/ | | armory-memory | Children hydrate project memory on spawn. Shared port, cwd-agnostic. | src/memory-hydrate/ | | vision | describe_image tool is wired into child sessions. | src/vision/ | | cursor | Children edit through the cursor extension when present. | (via child loader) |

Cross-harness backends

src/backend/ ships a backend registry with pi (default) and Claude Code as peer backends. detectClaude() auto-discovers Claude; PI_HOOK_PARITY / CLAUDE_HOOK_PARITY tables keep both backends on equal footing. hook-parity.ts normalizes lifecycle/event hooks across harnesses. A ResumeStore persists backend session IDs so cross-harness runs can resume.

Superpowers lifecycle

The default lifecycle (src/lifecycle/default.ts) is the superpowers-native 5-phase pipeline:

| Phase | Skills loaded | Checkpoint? | Gates | |---|---|---|---| | brainstorm | brainstorming | ✅ | — | | plan | writing-plans | ✅ | completenessCheck | | implement | executing-plans, test-driven-development, verification-before-completion | ❌ | verification-before-completion, completenessCheck, gate | | review | requesting-code-review, receiving-code-review | ✅ | — | | finish | finishing-a-development-branch | — | — |

Custom lifecycles: drop a YAML file in your lifecycles/ dir, register via discoverLifecycles(). Gates are registered on a GateRegistry (fleet-register-gate command for runtime extensibility).

Quality gates

Built-in (src/lifecycle/gates/): verification-before-completion, completeness-check, gate, verify.

Composite helpers (src/workflows/helpers/) — usable from any workflow:

| Helper | What it does | |---|---| | judgePanel | Run N judge agents; majority/weighted verdict. | | loopUntilDry | Re-run an agent until a dry-run gate passes. | | retry | Retry an agent with backoff on failure. | | checkpoint | Pause a workflow for human review. | | completeness-check / gate / verify | Gate wrappers for workflow use. |

Cost-aware tiers

src/tiers/ ships three built-in tiers:

| Tier | Models | Cost cap | Context floor | |---|---|---|---| | economy | Ollama/minimax-m3:cloud | — | — | | standard | Ollama/glm-5.2:cloud, Ollama/minimax-m3:cloud | — | — | | frontier | anthropic/claude-sonnet-4, Ollama/glm-5.2:cloud | $5 | 200k ctx |

Live cost $ and context % are tracked per run and surfaced in the Tiers view. Override per-run with model, or let the tier registry route based on the task class.

Operational runtime

src/runtime/ — the async/scheduling spine:

• async-runner.ts — background dispatch (fire-and-forget).
• run-journal.ts + run-log.ts — durable run records; reconcile.ts reattaches orphaned runs on restart.
• concurrency-pool.ts — bounded parallel branches.
• results-inbox.ts — the model pulls completed background runs via the fleet_results tool.
• resume.ts — scan for resumable runs + workflows.

Scheduling + worktree

src/scheduling/ — cron expressions (expressions.ts), a Scheduler with PID-locking (pid-lock.ts), session-scoped (no catch-up). src/worktree/ — WorktreeService for isolated bg-run worktrees + DiffService for reviewable diffs.

The fleet panel

/fleet opens an interactive TUI panel (TUI-only; in non-interactive modes use the subagent tool).

| View | What it shows | |---|---| | Runs | Running + recent subagents; status, cost, context %, agent, model. Action submenu: Steer, Stop, View conversation. | | Tiers | Per-tier model lists, cost caps, context floors. Configure routing. | | Lifecycle | Active lifecycle runs; Continue/Revise/Abort at checkpoints. | | Workflows | Registered workflows + live runs. Run, edit-resume, save-as, view result, checkpoint. | | Conversation | The full message timeline for any selected run. |

A live FleetWidget can render in the pi footer/overlay for at-a-glance fleet status while you work.

Slash commands

| Command | Purpose | |---|---| | /fleet | Open the interactive fleet panel (TUI). | | /fleet-implement <task> [--lifecycle <name>] [--auto] | Run a task through the superpowers lifecycle. | | /fleet-register-gate | Register a custom gate on the fleet gate registry (extensibility). |

Model-callable tools

| Tool | Purpose | |---|---| | subagent | Delegate a focused task to a child agent (sync foreground or async background). | | fleet | Run + control fleet workflows (JS orchestration: agent, pipeline, phase, checkpoints). | | fleet_results | Pull completed background run results from the inbox. |

Workflows-as-code

Workflows are authored in a JS DSL (src/workflows/source.ts parses; vm-realm.ts evaluates). 5 builtins ship in src/workflows/builtin/:

| Workflow | Description | Phases | |---|---|---| | adversarial-review | Red-team + blue-team review with judge panel | Attack → Defend → Judge | | code-review | 7 parallel review angles plus verification | Review → Verify | | codebase-audit | File-tree scan with completeness check | Scan → Audit | | deep-research | 3-round discovery loop with de-duplication | Discover → Synthesize | | multi-perspective | 4 personas review the same artifact | Review → Merge |

Every workflow run is journaled (workflows/journal.ts) and resumable. edit-resume replays the unchanged prefix from cache and re-runs only the edited suffix. runtime/controller.ts orchestrates; runtime/pause-gate.ts handles checkpoints; runtime/adapters.ts binds the controller to the fleet's spawn + accounting.

Full JS DSL API reference: docs/workflows.md — export const meta, agent()/parallel()/pipeline()/phase(), the 7 helpers, the script context, worked examples, and the error surface.

Roadmap

armory-fleet follows a PRD → SPEC-N (brainstorm → spec → plan → implementation) pipeline. 16/16 phases done through v0.12.0.

| SPEC | Headline | Status | Artifact | |---|---|---|---| | PRD | Master PRD | ✅ done | PRD.md | | RESEARCH | Landscape research (11+ packages, 5 deep-reads) | ✅ done | research/ | | SPEC-1 | Core engine + armory-todo sync | ✅ done | PR #1 · 547319b | | SPEC-2 | Deep armory integration (memory/vision/cursor) | ✅ done · @0.2.0 | PR #2 · c6e727c | | SPEC-3 | Cross-harness peers (pi + Claude Code) | ✅ done · @0.3.0 | PR #4 · 5bb75fb | | SPEC-4 | Superpowers-native lifecycle | ✅ done · @0.4.0 | PR #5 · 67ff9b4 | | SPEC-5a | Operational runtime (async/scheduling/worktree) | ✅ done · @0.5.2 | PR #6 · 52e3477 | | SPEC-5b-1 | RunLog seam + Runs view | ✅ done · @0.6.0 | PR #7 · 54b1b10 | | SPEC-5b-2 | Live widget + FleetView + Q9 | ✅ done · @0.7.0 | PR #8 · 9266a7 | | SPEC-5b-3 | Conversation viewer + timeline fix | ✅ done · @0.8.0 | PR #9 · adc0034 | | SPEC-5b-4 | Mid-run steering (Steer) + Stop | ✅ done · @0.9.1 | PR #10 + #11 + #12 | | SPEC-6-1 | Cost-aware tiers + cost $ + context % + Tiers view | ✅ done · @0.10.x | PR #15/#16/#17 | | SPEC-6-2 | Quality gates + lifecycle hooks | ✅ done · @0.11.0 | PR #18 · cda5e2b | | v0.11.1 | bg dispatch isolation split (non-git cwd fix) | ✅ done · @0.11.1 | PR #19 · 51956e0 | | SPEC-6-3 | Workflows-as-code (release-gate completion) | ✅ done · @0.12.0 | PR #21 · 9986ad1 | | SPEC-6-4 | Event-bus RPC + live conversation viewer → v1.0 | 🚧 next | — |

See the full release history and the PRD §8 for the roadmap rationale.

Ecosystem

armory-fleet is the orchestrator in the getpipher armory suite — the default substrate it runs agents on:

| Package | Role | |---|---| | armory-todo | Global cross-session TODO store (the fleet syncs every run to it). | | armory-memory | Project memory hydration for child agents. | | vision | The describe_image tool, wired into fleet children. | | cursor | Custom editor component for the pi TUI. |

Conventions

• No build step — extensions ship raw .ts via tsx at pi runtime. pnpm typecheck + pnpm test:run before release.
• Tests — node:test via tsx in test/*.test.mts, importing from ../src/.... 593 passing.
• Publish — CI on v* tags using the getpipher NPM_TOKEN org secret (release.yml mirrors armory-todo: idempotent npm publish + GitHub Release).
• Interactive-first UX — every capability lands as a /fleet panel tab/view + action submenu first, then the model-callable tool action.

Verify locally

pnpm install
pnpm typecheck
pnpm test:run --test-timeout=30000   # 593/593

Release-gate smoke (mandatory before any release)

pi --no-extensions -e ./src/index.ts --no-session --approve
# inside: /fleet → Workflows → verify the 5 builtins render + a workflow runs end-to-end

Compatibility

• pi ^0.81.1
• Node >=22 (tsx runtime)
• Platform: macOS, Linux, WSL

License

MIT — see LICENSE. © RECTOR (@rz1989s).

Built with Ihsan · Maintained by RECTOR · getpipher