neon-pilot

Imported from patleeman/neon-pilot (AGENTS.md). Install upstream with npx skills add patleeman/neon-pilot. Copyright stays with the author.

neon-pilot repo instructions

Always-on rules

• Prefer correct, complete implementations over compatibility shims or narrow safe cuts.
• If a feature needs a shared boundary — process execution, security policy, persistence, routing, extension APIs — implement the boundary and wire first-class call sites through it.
• Build product/workflow UX in extensions unless the work is core runtime, security, persistence, extension-host infrastructure, app-shell plumbing, routing, install/update plumbing, or shared UI primitives.
• Treat Neon Pilot as an application platform, not a fixed chat/sidebar harness. Built-in and extension applications should own the main window below the host top bar; avoid adding permanent left/right sidebar dependencies as default navigation. Use the host top bar and unified Command-K surface for global app navigation, with applications registering their own searchable destinations/actions there when appropriate.
• Keep the platform model simple: the host launches applications/tabs; avoid reintroducing a separate first-class "page" hierarchy unless Patrick explicitly reopens that product decision. Applications own their internal views, navigation, resources, and singleton-vs-multiple behavior through public extension APIs.
• Keep the core product focused on chat, application launching, extension creation/management, settings, and a minimal home/start surface. Treat older experiments such as evaluations, channels, routines, model-arena-style duels, and broad dashboards as optional extensions or candidates to cut unless current work explicitly validates their user value.
• If the extension API is missing a capability, add the smallest general-purpose API surface to core instead of hardcoding a one-off feature.
• Extension runtime code must not import @neon-pilot/core, @neon-pilot/desktop, packages/desktop/*, or packages/core/* directly. Route host access through @neon-pilot/extensions and narrow @neon-pilot/extensions/backend/* subpaths.
• Host backend API modules in packages/desktop/server/extensions/backendApi/* are boundary shims. Keep them small, typed from public extension contracts, and lazy-load host/core implementation through serverModuleResolver; do not statically re-export core or desktop internals.
• Do not introduce environment variables for app/runtime configuration. Pass state explicitly through typed config/context APIs; keep env reads only for unavoidable external-process compatibility with existing legacy variables.
• For web UI, prefer server-pushed updates over polling when the backend can publish events.
• Multiple agents may be working here. Do targeted changes and targeted checkpoints; stop if unrelated edits conflict with your work.
• For the Windowed OS to Agentic OS roadmap, use Codex collaboration subagents for bounded parallel lanes; do not use Pi/Flash delegation unless Patrick explicitly reauthorizes it for that roadmap. Keep the main Codex agent responsible for orchestration, integration, validation, and checkpoints.
• For desktop app UI, use shared primitives from @neon-pilot/ui/@neon-pilot/ui/shared instead of hand-rolled Tailwind component chrome. For first-party extension UI and settings surfaces, use @neon-pilot/extensions/ui and @neon-pilot/extensions/settings. If a raw HTML/Tailwind pattern is genuinely needed, keep the exception narrow and update the UI-pattern guardrail or docs so future agents do not silently bypass the design system.
• Treat design-system components as the default implementation path, not an optional polish pass. Before adding local JSX for buttons, toggles, selects, inputs, toolbars, tabs, menus, cards, tables, lists, empty/error/loading states, settings rows, or page chrome, first check whether the needed primitive already exists in @neon-pilot/ui, @neon-pilot/ui/shared, @neon-pilot/extensions/ui, or @neon-pilot/extensions/settings. Local markup is acceptable for product-specific layout and content only after that check; do not create extension-local lookalikes of shared controls.

Prompt and knowledge rules

• Use CONTEXT.md as the canonical glossary for product/domain vocabulary. Prefer its terms in code, docs, UI copy, and agent-facing instructions; update it immediately when a term is clarified. Keep it glossary-only: no implementation details, specs, scratch notes, or architecture decisions.
• Never modify the system prompt from extension before_agent_start handlers. Use file-based instruction layers instead: repo defaults, vault root AGENTS.md, machine-local ~/.config/agents/AGENTS.md, or cwd AGENTS.md.
• Docs are for agents. Update docs whenever behavior or workflow changes.
• Before changing feature behavior, read the owning extension README plus relevant docs from docs/README.md.
• Keep public docs/site content separate from internal maintenance docs. External docs and apps/site should explain user-facing capabilities, SDK/API surfaces, extension authoring, and self-extensibility without leaking internal checklists, repo-maintenance notes, or agent-only planning pages; prefer folder-level boundaries over long per-page publish manifests when deciding what is exported.
• For system-skill-search, preserve the product contract in extensions/system-skill-search/README.md: agents call skill_search, choose the best candidate themselves, then call skill_install; trusted sources install directly after vetting, while community sources use the host-owned timed approval shelf. Do not route approval through chat flags, ask the user to choose from raw candidates, or bypass vetting.

Validation and checkpoints

• Validate the actual work before calling it done. Use the narrowest meaningful check first, then broader checks when risk warrants it.
• When auditing docs/feature-inventory.md rows, keep the audit tied to the named user-visible slice. Prefer concrete risks with source proof, repro or app-path validation ideas, smallest fix direction, and focused regression coverage. Reject broad refactors, style nits, and speculative issues without a visible failure mode; if the prompt says read-only, report findings only and do not edit.
• Run the relevant build before saying a task is complete. For desktop/app or shared package changes, include the affected package build or node packages/desktop/scripts/build-main.mjs/pnpm --dir packages/desktop run build:ui as appropriate; for extension changes, build the affected extension and reinstall it when validating through the app.
• Do not leave the app in a state where Patrick cannot start it locally. After TypeScript, desktop/app, extension host, build script, or shared package changes, run the startup path or its full blocking build equivalent before handing off: prefer pnpm run desktop:qa for agent-driven app QA so the Testing window does not steal focus, and use pnpm run desktop:dev -- --no-quit-confirmation only when foreground activation itself needs validation. At minimum, run the package build that performs tsc --noUnusedLocals/production type checks. Treat unused symbols, stale generated code, or other build-only failures as blockers, even when focused tests pass.
• When changing behavior a user reaches through the desktop app, an extension page, a sidebar route, settings, transcript rendering, or a tool, validate the same path the user will use. Open the route/page/control or invoke the tool through the app/extension host, verify the rendered UI or visible output, and cover empty/error/loading states when relevant.
• Do not treat backend/unit tests, manifest checks, or worker smokes as substitutes for user-visible validation. They are necessary support checks, not proof that the user-facing path works.
• If full user-visible validation is impossible, say exactly what was not validated and why. Do not imply manual or app-path validation happened when only lower-level checks ran.
• For chat transcript, send/resume, realtime streaming, running-state, scroll, or sidebar conversation-state changes, prove the full visible conversation loop: the user's submitted message appears immediately, assistant/tool updates stream or visibly progress without a stuck blank/Resuming... state, Stop/working indicators match the run state, transcript scroll behavior does not fight reading, and reloading or reopening the conversation renders the persisted result. Use a real provider path, local mock provider, or deterministic live-session harness that exercises the same UI update path; stored-session reload alone is not enough.
• For automations or background-run work, prove the user can find and inspect the owning thread and run state. Runs created from a conversation, delivered back to a conversation, or resumed after startup must surface in the sidebar or reopen/unarchive the owning thread when appropriate; pending/running/completed state and transcript output must be visible through the desktop UI, not only stored in backend records.
• For extension pages, confirm the nav route opens, the frontend invokes its backend actions, and those actions work with the real action context shape, not only test-only context stubs.
• For workflow/tool features, run at least one representative invocation and confirm the transcript/page/status result the user would inspect.
• For repository hygiene or dead-code cleanup, audit before deleting. Classify generated outputs, release/QA artifacts, fixtures, docs, scripts, and feature code with evidence from git ls-files, ignore rules, imports/search hits, package scripts, and docs references; remove tracked ignored build outputs and obsolete feature paths only after confirming they can be regenerated or are no longer reachable, and keep focused validation for the affected build/docs paths.
• For slash-command work, keep commands thread-level and discoverable. Provide autocomplete for commands, subcommands, and enum-like arguments; validate missing or invalid arguments with visible errors; render informational command output as transcript-visible system/status messages that are not appended as user/assistant conversation content; and QA the real composer path, keyboard completion, execution result, and transcript rendering.
• For Model Arena work, prove the full duel lifecycle before treating it as GA-ready: model eligibility must exclude unavailable or uncredentialed challengers and avoid same-model comparisons; automatic and manual duels must create, update, cancel, vote, refresh, persist, reload, and recover from failed primary/challenger runs without duplicate or stale transcript blocks; visible duel UI must make active, voted, cancelled, failed, and recovery states clear in both page and transcript contexts.
• For setup/readiness work, treat setup as a continuous extension-host capability rather than a one-time onboarding screen. Extensions may register narrow readiness items and host-owned actions, but must not render arbitrary setup UI; incomplete items should surface through the shared readiness popover/indicator with dismiss or ignore affordances, and users must be able to rediscover setup after enabling an extension later. QA must cover real registered items such as CLI shell-link status/install and dictation model readiness, visible top-bar/popover behavior, action execution, persistence across reload/restart, and no duplicate setup surfaces.
• For extension/core boundary work, run pnpm run check:extensions:static or at least node scripts/check-core-extension-boundary.mjs && node scripts/check-extension-backend-api.mjs.
• If you modify web UI, perform a visual check. Use the repo wrapper for agent-browser sessions and clean up only processes you started.
• Before final summary, use the checkpoint skill/tool for a targeted commit when available; otherwise use git directly. Do not stage unrelated files.
• Before cutting a Neon Pilot release, run the release reliability gate and hands-on QA process in docs/release-qa.md. At minimum run pnpm run check:release:doctor, pnpm run test:release-hardening, and pnpm run qa:release, then record the app build, commit SHA, and pass/fail notes for the hands-on smoke checklist.

UI design and copy rules

• Before creating or modifying user-visible app or extension UI, read and follow docs/design/neon-pilot-taste.md; treat it as the source of truth for layout, density, control choice, surface treatment, copy, empty states, negative smells, and screenshot-backed taste review.
• For major shell or first-party application UI, start from the current Gaia/Codex Desktop visual language when accessible: inspect the running app or shipped styles, copy the proven density/control/surface patterns, then adapt narrowly to Neon Pilot. Do not invent generic AI-dashboard chrome when the task asks for a restrained desktop-agent feel.
• For generated extension UI, also read benchmarks/extension-quality/visual-rubric.md and use docs/design/extension-visual-refinement.md when iterating with screenshot-backed judges.
• Keep design-system and command-palette guardrails hard: use shared primitives before local markup, document narrow exceptions near the code, update guardrails/docs when a pattern should recur, and make meaningful user-reachable actions command-backed.
• Treat copy as part of the UI design: use user-facing labels and secondary text from the user's mental model, avoid raw internal enum/path/provider terms unless clearly advanced or developer-only, and opportunistically fix adjacent confusing copy when it is low-risk and covered by the same validation path.

Workflow references

• Development, validation, UI QA, gitleaks, and checkpoint details: docs/development.md.
• Release process, current version, signed build flow, and release gotchas: docs/release-cycle.md.
• Extension authoring/API rules: docs/extensions.md and packages/extensions/README.md.
• Browser feature docs: installable-extensions/system-browser/README.md; Workbench Browser skill handles built-in browser context.