PolyPilot

Comprehensive guide for building and maintaining GitHub Agentic Workflows (gh-aw). Covers architecture, security boundaries, fork handling, safe outputs, anti-patterns, compilation, and troubleshooting. Use when creating or editing gh-aw workflow .md files, writing safe-outputs configurations, configuring fork PR handling, setting up integrity filtering, debugging "why doesn't my workflow trigger", or any task involving .github/workflows/*.md or .lock.yml files. Also use when asked about gh-aw features, slash commands, pre-agent-steps, protected files, or agentic workflow security.

Detect drift in instruction files and skills against upstream documentation sources. Checks when tracked GitHub issues close, reference pages change, or new platform features ship that aren't reflected locally. Use when asked to "check for drift", "are instructions up to date", "instruction drift", "check if gh-aw docs are current", "update instructions from upstream", "what changed upstream", or "have our instructions drifted". Also use proactively before major instruction file edits to ensure you're working with current information. Produces a drift report — never auto-edits files.

Complete API reference for GitHub.Copilot.SDK v0.2.2. Consult before implementing session lifecycle, orchestration, event handling, hooks, plan management, context compaction, tool monitoring, or any feature that interacts with the Copilot CLI server. Use when: (1) Adding new session management code, (2) Modifying event handlers, (3) Building orchestration/dispatch features, (4) Adding tool monitoring or permissions, (5) Working with plans, modes, or models, (6) Any feature touching CopilotService, (7) Updating the SDK NuGet package version.

Checklist and invariants for modifying IsProcessing state, event handlers, watchdog, abort/error paths, or CompleteResponse in CopilotService. Use when: (1) Adding or modifying code paths that set IsProcessing=false, (2) Touching HandleSessionEvent, CompleteResponse, AbortSessionAsync, or the processing watchdog, (3) Adding new SDK event handlers, (4) Debugging stuck sessions showing "Thinking..." forever or spinner stuck, (5) Modifying IsResumed, HasUsedToolsThisTurn, or ActiveToolCallCount, (6) Adding diagnostic log tags, (7) Modifying session restore paths (RestorePreviousSessionsAsync / EnsureSessionConnectedAsync) that must initialize watchdog-dependent state, (8) Modifying ReconcileOrganization or any code that reads Organization.Sessions during the IsRestoring window, (9) Session appears hung or unresponsive after tool use. Covers: 18 invariants from 13 PRs of fix cycles, the 21+ code paths that set/clear IsProcessing, and common regression patterns.

Real-time health monitoring for PolyPilot sessions. Use when the user asks to "monitor sessions", "watch for issues", "check health", "make sure everything is working", "keep an eye on things", or any request to continuously observe running PolyPilot sessions for reliability issues. Also use when the user reports a session is "stuck", "not responding", shows "Thinking..." forever, or threw a "Tool execution stuck" error — diagnose the issue using the techniques below. Covers: single sessions, multi-agent orchestration, sub-agent IDLE-DEFER, app restart recovery, and connection health.

Invariants, lifecycle documentation, and error recovery strategies for PolyPilot's multi-agent orchestration system. Use when: (1) Modifying dispatch logic in SendViaOrchestratorAsync or SendViaOrchestratorReflectAsync, (2) Touching worker execution, result collection, or synthesis phases, (3) Modifying PendingOrchestration persistence or resume logic, (4) Debugging orchestrator-worker communication failures, (5) Adding error handling around worker dispatch or completion, (6) Modifying OnSessionComplete coordination or TCS ordering, (7) Working with reflection loop concurrency (semaphores, queued prompts), (8) Modifying SessionIdleEvent handling or IDLE-DEFER logic (BackgroundTasks check). Covers: 5-phase dispatch lifecycle, IDLE-DEFER background task guard, restart recovery via PendingOrchestration, worker failure patterns, and connection error handling.

End-to-end workflow for building, deploying, inspecting, and debugging .NET MAUI and MAUI Blazor Hybrid apps as an AI agent. Use when: (1) Building or running a MAUI app on iOS simulator, Android emulator, Mac Catalyst, macOS (AppKit), or Linux/GTK, (2) Inspecting or interacting with a running app's UI (visual tree, tapping, filling text, screenshots, property queries), (3) Debugging Blazor WebView content via CDP, (4) Managing simulators or emulators, (5) Setting up MauiDevFlow in a MAUI project, (6) Completing a build-deploy-inspect-fix feedback loop, (7) Handling permission dialogs and system alerts, (8) Managing multiple simultaneous apps via the broker daemon. Covers: maui devflow CLI, androidsdk.tool, appledev.tools, adb, xcrun simctl, xdotool, and dotnet build/run for all MAUI target platforms including macOS (AppKit) and Linux/GTK.

Performance invariants and optimization knowledge for PolyPilot's render pipeline, session switching, persistence, caching layers, and startup performance. Use when: (1) Modifying RefreshSessions, GetOrganizedSessions, or SafeRefreshAsync, (2) Touching SaveActiveSessionsToDisk, SaveOrganization, or SaveUiState, (3) Working with LoadPersistedSessions or session directory scanning, (4) Modifying markdown rendering or the message cache, (5) Optimizing render cycle performance or adding Blazor component rendering, (6) Working with debounce timers or DisposeAsync cleanup, (7) Debugging startup slowness or blue screen on launch, (8) Modifying InitializeAsync or RestoreSessionsInBackgroundAsync. Covers: session-switch bottleneck fix, debounce flush requirements, expensive operation guards, cache invalidation strategy, render cycle analysis, and startup performance debugging.

Design rationale for PolyPilot's authentication approach. The copilot headless server authenticates on its own via its native credential store. PolyPilot NEVER reads the macOS Keychain directly — doing so triggers password dialogs and corrupts ACLs. Use when modifying auth-related code paths or StartServerAsync callers.

Generate polished release notes and update the README for PolyPilot releases. Use when: (1) A new version tag has been pushed and needs release notes, (2) The user asks to prepare release notes for a version, (3) The README needs updating with new features or a "What's New" section, (4) Preparing a release announcement or changelog entry. Covers: commit categorization, highlight extraction, README update strategy, GitHub Release body formatting, and the release workflow integration.

WiFi ADB deployment playbook for PolyPilot on macOS. Use when: (1) Deploying to a physical Android device over WiFi, (2) Troubleshooting ADB connection issues, (3) Building APKs for wireless install, (4) Managing the TCP proxy workaround for macOS firewall, (5) Recovering from broken ADB connections. Covers: proxy setup, port discovery, Fast Deployment gotchas, pairing, and the complete deploy checklist.