PilotSwarm

The order of operations for changing a live agent safely — diagnose, patch, publish, converge, verify, roll back. Use whenever you are about to modify an agent package that something is already running on.

Deploy PilotSwarm to AKS using the repo's canonical scripts and checks. Use when refreshing secrets, building/pushing the worker image, rolling out to AKS, or verifying provider/model changes in the live cluster.

Reset remote PilotSwarm state for AKS safely. Use when wiping the PilotSwarm database/blob state, clearing stale orchestration history, or recovering from namespace drift and replay/nondeterminism issues.

Use when bringing up a fresh, isolated PilotSwarm environment (`mysandbox`, `myenv2`, etc.) via the npm Bicep/GitOps orchestrator at `deploy/scripts/deploy.mjs`. Covers `new-env` scaffolding, EDGE_MODE × TLS_SOURCE selection, the `all` aggregate, per-service redeploys with `--steps`, force-redeploy semantics, verification, and teardown. Strictly separate from the legacy bash path operated by `scripts/deploy-aks.sh`.

Use after deploying a PilotSwarm stamp with VPN_GATEWAY_ENABLED=true when an operator needs the Azure VPN client profile (azurevpnconfig.xml). Wraps deploy/scripts/auth/Get-VpnClientProfile.ps1 — downloads the gateway-issued profile zip via 'az network vnet-gateway vpn-client generate' and extracts it under the gitignored deploy/envs/local/<env>/vpn-client/ folder. The XML is the same for every user (no per-user credentials), and end users still authenticate with their own Entra ID at connect time.

How to compute model latency and estimated $ cost from PilotSwarm observability data. Read this before reporting that a model is "slow" or "expensive" — most apparent slowness is orchestration overhead, not model inference, and most cost numbers are guesses unless they reference a real published price card.

How to inspect, render, and reason about the shared knowledge GRAPH — for the facts-manager (report graph size/health, render the graph as Markdown/Mermaid, spot orphan or duplicate entities) and for the agent-manager (forensics: what graph search a session ran and what it returned). Read this before answering any question about graph structure, graph contents, or a session's graph-search behaviour. Only relevant when a knowledge graph is configured; if the graph tools are absent, this deployment has no graph and the skill does not apply.

How a PilotSwarm session maps to a duroxide orchestration. Read this before concluding that an "idle" session means its orchestration is broken, not running, or stuck. Most idle sessions are completely healthy — they're just dehydrated and waiting for the next stimulus.

The editing pass order, the measure-don't-assert rule, and which surface answers which question.

Evidence, timestamp, numerical, and communication standards for stock and finance research.

Compact valuation discipline for DCF, multiples, and scenario analysis.

The shape of PilotSwarm — the pieces, how a turn flows through them, and the rules that constrain each layer.

Modify or extend the PilotSwarm terminal UI. Covers the shared-first architecture across ui-core, ui-react, and packages/app/tui, the current layout and visual conventions, prompt/question behavior, and the requirement to keep maintainer docs updated as the TUI evolves.

Use when packaging and deploying a PilotSwarm-based app to Azure or AKS. Covers remote worker parity, environment/config wiring, manifests, and rollout constraints.

Use when creating or updating a plugin-driven CLI/TUI app on top of PilotSwarm. Covers plugin.json branding, agent/skill layout, worker modules, keybinding/help sync, and the DevOps sample structure.

Use when creating or updating an SDK-first app on top of PilotSwarm. Covers the client/worker split, plugin layering, tool registration, tests, and the DevOps sample structure.

Prepare and cut a PilotSwarm release. Use when validating release readiness, updating release-facing docs and templates, checking npm packaging, and handling commit/push/tag/publish flow.

Use when bringing up a PilotSwarm portal stamp with `PORTAL_AUTH_PROVIDER=entra` and no existing `PORTAL_AUTH_ENTRA_CLIENT_ID`. Drives the Entra app-registration step (create app, configure redirect URIs, optionally define app roles + require assignment, capture tenant/client IDs). Skip entirely for `PORTAL_AUTH_PROVIDER=none` or when a client ID is already supplied.

Workarounds for common Azure issues: RBAC with Conditional Access, PostgreSQL region restrictions, Key Vault + CSI Driver setup.

Use when a PilotSwarm app needs stock PostgreSQL for runtime storage plus HorizonDB for enhanced facts, semantic/lexical search, and the knowledge graph. Covers env topology, horizonConfigFromEnv wiring, harvester agents, Azure secret/resource guidance, and the rule that Docker defaults remain stock Postgres.

Use when an SDK or CLI app needs to ingest external sources into durable, searchable knowledge and an open knowledge graph. Covers enabling the EnhancedFactStore + GraphStore providers, authoring a crawler:true agent, the crawl→graph→reader flow, ACL/scopeKey evidence, and tests.

Use when creating or updating a browser portal on top of PilotSwarm. Covers portal branding, plugin.json.portal, named-agent exposure, auth add-ons, and remote deployment wiring.

Reference for adding a Tier 3 worker AKS cluster to a PilotSwarm deployment. Covers provisioning, identity, Dockerfile changes, entrypoint, manifests, and verification.

System maintenance agent that monitors and cleans up completed/zombie sessions.

Work with Azure HorizonDB (preview) — its AI/embedding features, extension allow-listing, AGE/pgvector/pg_durable quirks, and the connection/TLS gotchas discovered while bringing up the horizon-facts incubator. Use when connecting to a HorizonDB cluster, enabling extensions, writing AGE Cypher, wiring in-DB embeddings via pg_durable df.http(), or debugging "extension not allow-listed" / "access to library not allowed" / "self-signed certificate" / Cypher syntax errors.

Run and analyze the horizon-facts cross-model evaluation sweep (graph-grounded vs parametric+web closed-QA), sweeping harvester × query × judge models into a 3×3×3 score tensor with an LLM-generated bias-aware report. Use when collecting fresh sweep results, re-running a subset of cells, changing the model set, or interpreting judge bias.

Use when adding or removing users / groups from the 'admin' or 'user' app roles on a PilotSwarm portal Entra app. Wraps deploy/scripts/auth/Set-PortalAuthAssignments.ps1 — idempotent, re-runnable, resolves UPNs / object ids / group display names. Required after `Setup-PortalAuth.ps1 -CreateAppRoles` when admission is role-driven. Other skills/agents that need to grant or revoke portal access should delegate here instead of generating the Graph calls themselves.

Use when creating or editing PilotSwarm .agent.md files, prompt-layer manifests, or builder templates that generate agents. Covers schemaVersion/version frontmatter, SemVer bump guidance, and session.prompt_layers expectations.

Infrastructure and resource monitoring agent. Tracks compute, storage, database, and runtime footprint.

Expert knowledge on durable timer patterns for recurring tasks, polling, and scheduled actions.

Use when creating or editing PilotSwarm app agents in agents/*.agent.md. Covers schemaVersion/version frontmatter, version bump guidance, and prompt layer version visibility.

Add or modify a PostgreSQL schema migration for the CMS or Facts store. Covers creating migration functions, stored procedure changes, diff file generation, and TypeScript caller updates.

Use when changing PilotSwarm durable orchestration behavior, continue-as-new state, or replay-sensitive control flow.

Investigate live Duroxide orchestration behavior, session-affined activities, worker routing, hydration/dehydration, and AKS log/DB evidence. Use when tracing which pod ran a session activity, why warm state was missing, or whether a failure was caused by affinity loss, explicit dehydration, or a worker crash.

Diagnose and fix nondeterminism errors in the duroxide orchestration. Covers the replay model, common violations, and how to audit orchestration code for determinism.

Run and analyze PilotSwarm performance workflows, starting with SDK sub-agent spawn perf. Use when collecting fresh perf baselines, comparing runs, generating stable perf reports, or updating perf memory and next steps.

Use when setting up cross-cluster AKS access with Workload Identity, RBAC, and kubectl configuration for PilotSwarm workers.

Add a new integration test to PilotSwarm test suite. Tests verify end-to-end flows through PilotSwarmClient, duroxide orchestration, and the Copilot SDK.

Diagnose and fix a failing integration test in PilotSwarm. Covers the full call chain from PilotSwarmSession.sendAndWait through duroxide orchestration to CopilotSession, common failure patterns, and how to inspect orchestration and CMS state.

Deployment best practices — canary patterns, rollback triggers, and health check interpretation.