ax-legacy

Use when modifying logging, error handling, or diagnostic messages — logger setup, transports, error diagnosis patterns in src/logger.ts and src/errors.ts

Use when modifying the trusted host process — server orchestration, message routing, IPC handler, request lifecycle, event streaming, file handling, plugin loading, or agent delegation in src/host/

Use when modifying the sandboxed agent process — runner, IPC client, local/IPC tools, tool catalog, prompt building, or identity loading in src/agent/

Use when modifying agent sandbox isolation -- Docker, Apple Container (macOS), or k8s providers in src/providers/sandbox/

Use when modifying IPC protocol between host and agent — schemas, actions, length-prefix framing, or Zod validation in ipc-schemas.ts and ipc-server.ts

AX project architecture and coding skills - use sub-skills for specific subsystems (agent, host, cli, providers, etc.)

Use this skill when the user asks for a capability the agent doesn't yet have — a new integration (Linear, GitHub, Notion, Slack, etc.), a new workflow, a new tool, or "can you check our team's X" where X is a service the agent has no existing connector for. Creates a proper AX skill under .ax/skills/<name>/ with the right frontmatter, credentials, and domain allowlist so the capability becomes permanent after admin approval. Use this skill whenever you'd otherwise be tempted to improvise with one-off scripts, `npm install`, or `execute_script` to reach an external service.

Petstore REST API via mock OpenAPI (e2e test fixture — do not use in production)

Linear via mock MCP (e2e test fixture — do not use in production)

Use when modifying configuration parsing, path resolution, environment variables, or OAuth token handling in config.ts, paths.ts, or dotenv.ts

Use when modifying data persistence — StorageProvider (database-backed), conversation history, message queue, session store, document store, file store, job store, or database migration utilities

Use when modifying persistent storage — message queues, conversations, sessions, documents, or database storage backend in src/providers/storage/

Use when modifying credential storage — database-backed credential provider in src/providers/credentials/

Use when modifying the git-native skills pipeline — skill format parsing, manifest generation, live skill-state derivation from git, the admin skill-approval flow, tuple-keyed skill credentials, or the post-receive cache-busting hook in src/host/skills/, src/utils/skill-format-parser.ts, and src/utils/manifest-generator.ts

Use when modifying agent runner implementations — pi-session (pi-coding-agent), claude-code (Agent SDK), LLM transport selection, MCP tool wiring, or stream handling in src/agent/runners/

Use when debugging MITM proxy issues, credential placeholder replacement failures, domain allowlist problems, sandbox HTTPS connectivity problems, curl exit 60 SSL errors, ECONNRESET crashes in the proxy, or modifying web-proxy.ts / credential-placeholders.ts / skills/domain-allowlist.ts

Use when modifying CLI commands — chat, send, bootstrap, provider, or adding new CLI commands in src/cli/

Use when debugging k8s-related issues, NATS IPC problems, HTTP IPC problems, workspace release failures, chat UI development iteration, or any issue in the sandbox/host/agent communication pipeline — starts with chat UI dev loop or e2e test infrastructure for fast repro, falls back to full kind cluster or local process harnesses only when needed

Use when modifying security mechanisms — taint budget, canary tokens, path traversal defense, sandbox isolation, scanner patterns, plugin integrity, or any security-sensitive code paths

Use when writing or debugging tests — test structure, fixtures, mocking patterns, common assertions, and gotchas for the vitest/bun test suite in tests/

Use when modifying the first-run setup, configuration wizard, bootstrap ritual, or profile defaults in src/onboarding/ and src/cli/bootstrap.ts

Use when modifying or extending the agent prompt system — adding modules, adjusting priority ordering, token budgeting, or bootstrap mode in src/agent/prompt/

Use when modifying scheduler providers — cron jobs, heartbeats, proactive hints, or active hours in src/providers/scheduler/

Use when adding new provider categories, modifying provider loading, plugin infrastructure, or understanding the provider contract pattern -- registry.ts, provider-map.ts, provider-sdk, and the create(config) convention

Use when modifying the event bus — in-process pub/sub, PostgreSQL pub/sub, or streaming event routing in src/providers/eventbus/

Use when modifying message channel providers — Slack integration, session addressing, or adding new channels (Discord, Telegram) in src/providers/channel/

Use when creating, editing, or reviewing any admin dashboard UI component. Covers the complete design system — colors, typography, components, layout, animations, and patterns.

Use when working with path validation (safePath), SQLite adapter, disabled provider stubs, tracing, asset resolution, embedding client, OpenAI-compat helpers, skill format utilities, DB migrator, content serialization, binary lookup, or install validation in src/utils/

Use when modifying web access providers -- proxied HTTP fetch, DNS pinning, taint tagging, text extraction, or web search in src/providers/web/

Use when modifying audit logging providers — database-backed audit logs or audit entry structure in src/providers/audit/

Use when modifying the shared database connection factory — SQLite, PostgreSQL, vector extensions, or Kysely instance management in src/providers/database/

Use as a step-by-step guide when adding a new provider implementation or an entirely new provider category to AX

Use when modifying LLM providers — Anthropic, OpenAI, multi-model router, traced wrapper, or mock provider in src/providers/llm/

Use when modifying memory/knowledge storage — the Cortex provider (embedding-based, SQLite/PostgreSQL) with SummaryStore, salience scoring, and LLM extraction in src/providers/memory/

Use when needing architectural inspiration from a similar project, wanting to see how another codebase solved a comparable problem, or the user says to look at how another project does something