ARMADA

The ARMADA builder. Works a single GitHub issue end-to-end: research, plan, implement in an isolated git worktree, validate with the project's own build/test/lint commands, and open a PR. Trigger when the user says "work on issue", "pick up #123", "build this issue", "implement #123", "start on the backlog item", references a GitHub issue number to implement, or invokes /shipwright. Also the default target that crows-nest dispatches to. Has an address-review mode: given a PR and its review comments, it triages each (agree/discuss/disagree), implements the agreed changes, re-validates, pushes, and replies per thread — triggered by "address review comments", "respond to the review", "fix the PR feedback". Accepts a GitHub issue number, a free-text description, or a PR number plus review findings. Stack-agnostic — it runs whatever build/test commands the repo configures.

The ARMADA cartographer. Owns *per-repo* knowledge: it mines completed fleet runs for reusable, actionable heuristics and maintains a reviewable knowledge base under `.armada/cartography/`, so the fleet specialises to a repo over time without anyone hand-writing AGENTS.md guidance. It analyses one completed run from the evidence already on the issue/PR — the original issue, the PR diff, commit/retry history, muster + human review comments, build/test failures, and the resolution path — and emits `heuristic / evidence / confidence` entries, paying special attention to human corrections, repeated failures, and repeated successes. It dedupes, updates, and prunes against existing cartography, then commits the changes into the active ARMADA PR so they ride the muster review + autoMerge gate. shipwright reads cartography before building; crows-nest auto-runs it (best-effort, side-channel) at its reconcile points when the `cartography` config key is on. Trigger when the user says "learn from this run", "update the c

The ARMADA inspection before sailing. Reviews an open pull request through two independent lenses in parallel — a conventions/correctness code-review pass and a codex-rescue root-cause second opinion — consolidates and dedupes the findings, posts them as inline PR review comments plus a top-level summary, and returns the findings as structured data for the fleet to act on. Trigger when the user says "muster", "review this PR", "inspect the diff", "run a review pass", "review PR #123", or invokes /muster. Also the review stage that crows-nest dispatches inside its ready-PR pipeline. Accepts a PR number (or the current branch's PR) and an optional review effort level.

The ARMADA lookout. A single, maximally parallel scheduler that watches two tracks over a GitHub repo at once: a new-issue track that dispatches each labelled issue into the fleet to be built, and a ready-PR track that drives each labelled pull request through a review → address → re-validate → gated-merge pipeline. Runs as a recurring watch via /loop: each tick scans both tracks in one batched scan, builds a dependency/conflict graph spanning them, and dispatches every independent runnable unit — builds and reviews together — concurrently up to a bound, serialising only where a true dependency or file-level conflict forces it. Can also run an opt-in public-intake track that screens unsolicited issues from the general public for prompt-injection and abuse, then re-authors the safe, good ones as fresh chartered issues. Trigger when the user says "watch for issues", "start the crows-nest", "keep an eye on the backlog", "listen for new issues", "watch for ready PRs", "review and merge PRs", "screen public sugges

The ARMADA lighthouse — the fleet's autonomous reconnaissance. Every other ship is reactive (shipwright builds existing issues, muster reviews existing PRs); lighthouse is the one that *proactively finds* work. It surveys the repository for valuable future work — failing/skipped tests, TODO/FIXME, missing coverage, stale or contradicted docs, dependency/security smells, architectural gaps, recurring pitfalls — and, when the app is runnable, explores it live with Playwright to surface UX/functional findings (degrading to static-only when there's no runnable app). It turns each high-value, non-duplicate finding into a well-formed GitHub issue via the charter flow, filed UNARMED by default (charter --no-arm) so a human review stays the gate. Every run is bounded by a configurable budget (runtime, Playwright time, issues, findings) and reports what it did and did not cover. crows-nest dispatches it opportunistically as low-priority background work only when the fleet has spare capacity; existing build and review

The ARMADA sea-trial — the shakedown run. The fleet's true RUNTIME verification step: beyond unit tests, lint, and static validate, it actually LAUNCHES the project's app (via .armada/config.json → commands.run) and DRIVES a real user flow with Playwright to prove a change behaves correctly live — then reports pass/fail with evidence (screenshots, console/network errors). It is the runtime layer on top of shipwright's own validate step and the repo-local `verify` skill: green tests prove the code compiles and the old assertions still hold; sea-trial proves the change actually works when a user drives it. Every run is BOUNDED by a runtime budget and is READ-ONLY w.r.t. the fleet/source tree — it launches and drives the app, it never Writes/Edits, stages, or commits; the project commands it runs are fenced on a clean checkout and their side effects are never committed. It DEGRADES GRACEFULLY: no runnable app (no commands.run) → skip with a clear note; no Playwright/ browser → launch-only smoke, no drive; a rout

Commission the ARMADA fleet in the current repository — the one-time (idempotent) setup that every other ARMADA skill depends on. Detects the project's build/test/lint/run commands and base branch, writes .armada/config.json, creates the GitHub trigger + state labels, checks gh auth, and prints how to arm the crows-nest watch. Trigger when the user says "commission armada", "set up armada", "initialise armada", "armada bootstrap", "get armada ready", just installed the ARMADA plugin, or invokes /commission. Also auto-invoked by crows-nest and shipwright when they find the repo isn't commissioned yet. Safe to re-run.

The ARMADA lookout's instrument — a live, procedurally-charted view of the fleet. Renders the whole armada:* label state machine that crows-nest runs as a beautiful, animated sea-chart in the browser: the horizon (new-issue track), the harbour (ready-PR pipeline), the crows-nest vantage (the scheduler's current tick — what's dispatched / held and why), and an optional cartography layer (the repo's learned chart). It reads the SAME GitHub state crows-nest scans (§2a) into a fleet-state.json and never mutates anything — it is a view, not a controller. Ships move through their real states; the coastline is procedurally generated and seeded from repo identity (stable run-to-run); weather reflects fleet health (storms when units are blocked). Trigger when the user says "show the fleet", "open spyglass", "visualise the armada", "watch the fleet on a chart", "fleet dashboard", "what's the fleet doing", or invokes /spyglass. Accepts an optional trigger label (defaults to .armada/config.json) and an optional watch cad

The ARMADA quartermaster — the fleet's cost governor. spyglass already SEES per-run cost; quartermaster turns that observability into GOVERNANCE, so the fleet stays within a budget without a human watching the meter. It reads the SAME read-only cost signals spyglass consumes (the per-run post-mortems under out/costs/<run>.json + the run→worktree map) and runs in two modes: `report` (today's total spend, the in-flight/accruing portion, per-run spends, a burn-rate in USD/hour, and a simple end-of-day forecast at the current rate) and `check` (an allow/pause verdict against the budgets in .armada/config.json — budget.perRunUSD / budget.perDayUSD). crows-nest consults `check` BEFORE it dispatches a build and HOLDS new work — reason surfaced — when the verdict is PAUSE. It is read-only w.r.t. the cost data, dependency-free, and degrades OPEN — no budget set allows cleanly, and missing cost data allows + warns (a governor never blocks the fleet on missing data). Trigger when the user says "check the budget", "what

The ARMADA voyage record. Turns a shipped change into a short, narrated, chaptered walkthrough video for stakeholders and attaches it to the PR — stack-agnostic and configured per repo. On first use in a repo it establishes a reusable staging recipe (launch / stage / reach) saved under .armada/logbook/ and reuses it on later runs; it supports web UIs, CLIs/TUIs, and APIs, launching the app via the repo's own `commands.run`. Plans 3-6 product-owner-facing chapters, records and narrates them with a provider-pluggable, env-keyed, hash-cached TTS pipeline, muxes to one video, uploads it as a per-PR GitHub release asset, and comments the link. Trigger when the user says "record a walkthrough", "make a demo video", "record a done video for PR X", "record a walkthrough video for the stakeholders", or invokes /logbook. Also the walkthrough shipwright offers to hand off to for user-visible features.

The ARMADA foghorn — the fleet's voice. It SPEAKS fleet activity aloud through a pluggable, env-keyed, hash-cached TTS pipeline (the same one logbook uses), booming across the water so you HEAR what the fleet is doing without watching labels or the loop. It's a narrator — READ-ONLY w.r.t. the fleet: it never claims, merges, or relabels. Four voices: a headless bell-hook narration designed to be crows-nest's bellCommand (speaks shipped/blocked/awaiting from the ARMADA_BELL_* context, no LLM required); live tick commentary alongside a /loop watch; an on-demand spoken fleet status (an audible spyglass, reusing the read-only gh snapshot); and a short free-text flavour prompt that steers the tone, defaulting to a gruff, proud nautical harbourmaster. Verbosity controls length and a notify-style gate keeps routine ticks quiet. With no audio engine it degrades to printing the line — it never errors. Trigger when the user says "speak the fleet", "narrate the fleet aloud", "say the fleet status", "turn on the foghorn",

Turn a rough request into a well-formed, fleet-ready GitHub issue — then arm it. charter drafts a structured issue (imperative title, problem/goal, concrete testable acceptance criteria, scope, dependencies, notes) following issue best practices and this repo's house style, confirms the draft with you, creates it via gh with the right type label, and — by default — adds the triggerLabel from .armada/config.json so crows-nest picks it up with no extra step. Trigger when the user says "create an issue", "file a PBI", "charter a task", "new backlog item", "raise a ticket", "draft an issue", "open a work order", or invokes /charter. Distinct from commission (which sets the repo up); charter authors and arms the work that flows into the fleet.