Menu
When debugging provider selection, fallback behavior, or config persistence issues. Also when adding new provider-related settings.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
How the multi-backend adapter system works — AgentAdapter interface, ACP protocol, session resume, and how to add new provider adapters
When debugging why an agent has the wrong provider/model, or when modifying agent creation or delegation flows.
How to get agents to use group chats for peer coordination in flightdeck-based crews. Covers hub-and-spoke anti-pattern, auto-grouping triggers, and file-lock-linked groups. Use when setting up multi-agent crews with 3+ agents or diagnosing why agents aren't collaborating directly.
When fetching from the `/coordination/activity` API and you only need specific action types (e.g., `progress_update`, `task_completed`, `delegated`).
When fetching activity data for UI display, or debugging why activity-based features show empty/stale data.
Architecture decisions and patterns from Flightdeck development (Phases 2–4). Covers feature architecture, state management, component patterns, and API design.
| name | provider-config-dual-system |
| description | When debugging provider selection, fallback behavior, or config persistence issues. Also when adding new provider-related settings. |
When to use: When debugging provider selection, fallback behavior, or config persistence issues. Also when adding new provider-related settings.
Flightdeck has two independent config systems that both store provider settings:
packages/server/src/config.tsflightdeck.config.yaml)container.configprovider, cliCommand, cliArgs, maxConcurrentAgents, dbPathpackages/server/src/config/ConfigStore.tsconfig table (key-value pairs)PUT /settings APIactiveProviderId, activeModelId, binaryOverride, argsOverride, envOverride, cloudProviderThese two systems can disagree. A user sets provider: claude in YAML, but ConfigStore still has activeProviderId: copilot from a previous session. Which wins?
At startup, container.ts bridges YAML → ConfigStore:
// packages/server/src/container.ts — inside createContainer()
if (yamlProvider && yamlProvider !== currentStored) {
configStore.writePartial({ activeProviderId: yamlProvider });
}
This runs once at boot. A hot-reload handler also exists for YAML file changes.
Override leak on provider switch: When writePartial({ activeProviderId: newProvider }) is called, it only updates the provider ID. Old overrides (binaryOverride, argsOverride, envOverride, cloudProvider) from the previous provider persist and may break the new one. The fix is to clear overrides when switching:
configStore.writePartial({
activeProviderId: newProvider,
binaryOverride: null,
argsOverride: null,
envOverride: null,
cloudProvider: null,
});
Provider availability vs configuration: A provider can be configured but not installed (binary missing). ProviderManager.resolveAvailableProvider() handles this by falling back to the first installed provider.
Agent-level provider: Each agent stores its own provider field in the agent_roster DB table. This is set at spawn time and should inherit from the parent agent during delegation (see AgentLifecycle.ts:100-104).
| File | What it does |
|---|---|
packages/server/src/config.ts | ServerConfig defaults, YAML loading, env var resolution |
packages/server/src/config/ConfigStore.ts | Runtime DB-persisted config (key-value) |
packages/server/src/container.ts | Bridge: syncs YAML provider → ConfigStore at startup |
packages/server/src/providers/ProviderManager.ts | Provider resolution, fallback logic, getActiveProviderId() |