flightdeck

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.

Known bugs and root causes encountered during Flightdeck development. Check this list before debugging — you may be hitting a known issue.

**Description:** Use when consolidating multiple similar formatting functions into one. Applies to any case where 2-3 functions share 80%+ logic but differ in output format or filtering.

Frontend development patterns for Flightdeck. Covers API calls, routing, component conventions, state management, and testing practices.

Flightdeck infrastructure reference. Covers monorepo structure, build system, database setup, environment config, and deployment.

**When to use:** When building UI that displays session metrics (tokens, costs, agent stats) and needs to work for both active and inactive/historical sessions.

**When to use:** When adding or modifying model selector dropdowns, or when working with the provider system and model availability.

**Description:** Use when fixing "module not found" errors for `@flightdeck/shared` during development, or when setting up dev scripts in npm workspace monorepos.

When rendering UI that depends on whether a project is "active" or "stopped" — buttons, badges, conditional sections. The `project.status` DB field is stale after server restarts.

When debugging provider selection, fallback behavior, or config persistence issues. Also when adding new provider-related settings.

**Description:** Use when debugging agents showing wrong or missing provider in the UI, or when modifying agent spawn/roster logic.

Step-by-step release process for Flightdeck, based on v0.3.0. Covers code cleanup, versioning, changelog, testing, and publishing.

When adding a new command or event that changes the task DAG and the secretary should know about it immediately (not wait for the 3-minute ContextRefresher poll).

Comprehensive reference for the Timeline component — the most complex UI in Flightdeck. Covers scroll/zoom, layout, session replay, SVG theming, React patterns, and testing.

**When to use:** When working on token usage tracking, cost attribution, or the CostBreakdown UI panel. Also useful when debugging why token data is missing.

When debugging why the analysis page shows missing or zero token data, or when adding new cost/usage visualizations.

**Description:** Use when debugging missing TypeScript build output in composite/incremental projects, especially after cleaning dist/ directories.

Documented user preferences from feedback. Follow these when building new features. Covers cost/token display, UI conventions, and design preferences.

Proven collaboration patterns for flightdeck-based multi-agent crews. Covers architect-first mapping, triple review, file lock coordination, context pressure, and DAG management. Use when planning any crew session with 3+ agents.

How the NotificationBatcher and IntegrationRouter work together for external messaging (Telegram, Slack, etc.). Use when adding new messaging integrations or modifying notification delivery.

How to use the signal+refetch WebSocket push pattern for real-time UI updates. Use when adding real-time features or replacing polling with push-based updates.

How the Trust Dial 3-level oversight system works and how to integrate new features with it. Use when building features that should behave differently based on the user's oversight level.

How to add external messaging platform integrations (Telegram, Slack, Discord) to Flightdeck — architecture, routing, event pipeline, and implementation template

Flightdeck commands (AGENT_MESSAGE, COMPLETE_TASK, GROUP_MESSAGE, etc.) must be emitted directly in your text response, not inside bash/tool calls. Use when agent commands are not being delivered or when '(no output)' appears in Agent Reports despite the agent doing work.

Patterns for orchestrating multi-agent crews in flightdeck-based sessions. Covers broadcast reliability, shared facts, CI noise management, and review diffing. Use when running sessions with 5+ agents or iterative review cycles.

How the Auto-DAG task lifecycle works — task states, dependency resolution, and common pitfalls

How to ensure new files are included in commits when using the COMMIT command's auto-scoping

When to use deterministic server-side WebSocket signals instead of client-side heuristics for UI state transitions

How project IDs are guaranteed in the flightdeck system — all spawn paths and fallback mechanisms

When coordinating multiple tasks across multiple agents, always use DECLARE_TASKS to create a task DAG instead of manual tracking. Applies whenever a project lead has 3 or more tasks to coordinate.