neon-pilot AGENTS.md

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.