# AGENTS.md Instructions for coding agents working in this repository (contributing to AskDB itself). If you're an agent implementing AskDB *into a different project*, use the docs site's own `AGENTS.md` at `/AGENTS.md` on askdb.tools instead — this file is about developing AskDB. ## Stack pnpm workspace + Turborepo, TypeScript. Node 22.23.4+ to develop; published packages support `>=22.23.4` (current Node 22 LTS as of 2026-11; better-sqlite3 13 still segfaults below 22.14, #419). - `packages/core` — the NL-to-SQL pipeline (`ask()`), the built-in dialect specs (ADR 0029), schema artifact loader. - `packages/ai` — AI provider registry and the built-in providers (openai/anthropic/google/azure/gateway), one file each under `packages/ai/src/providers/`. - `packages/client` — config-driven facade (`createAskDb`) over `@askdb/core` + `@askdb/ai`. - `packages/introspect`, `packages/postgres`, `packages/mysql`, `packages/sqlite`, `packages/sqlserver` — introspection; the engine packages re-export core's dialect specs. - `packages/rag` — schema chunking/indexing/retrieval. - `packages/enrich` — schema-authoring helpers used by Studio. - `apps/cli` — the `askdb` binary. - `apps/http-api` — HTTP wrapper over core. - `apps/studio` — browser UI for schema enrichment. - `apps/docs-site` — Starlight docs site (askdb.tools). - `e2e` — private package: scripted replays of the verify-askdb feature map (Vitest for the CLI and API, Playwright for Studio) and the harness they share with the `verify-askdb` skill. ## Commands ```bash pnpm install pnpm build # turbo run build pnpm test # turbo run test — integration tests run when DATABASE_URL is set pnpm lint # oxlint over the repo (.oxlintrc.json, warnings fail), then turbo run lint — TypeScript noEmit pnpm e2e # verify-askdb replays; first run: pnpm -C e2e exec playwright install chromium pnpm docs:dev # docs site at 127.0.0.1:4310 pnpm docs:build ``` Before opening or updating a PR, run the release-style checks: ```bash pnpm smoke:install pnpm preflight ``` ## Agent skills Most skills are committed under `.agents/skills/`. `skills-lock.json` names the rest, from the maintainer's private skills repo: run `npx skills install` to restore them if you have access. The house rules they rely on are linked below. ### Issue tracker GitHub Issues on `Ygilany/AskDB`, via `gh`. Unimplemented plans (label `plan`), specs and doc/behavior discrepancies (label `discrepancy`) live there, not as new files in the repo. See `docs/agents/issue-tracker.md`. ### Project board Priorities and release scope live on GitHub Project #27. Read `docs/agents/project-board.md` before choosing your next item, when you find work outside your current item, and when you need a maintainer decision. ### Triage labels The five default roles (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`), with label strings matching the role names. See `docs/agents/triage-labels.md`. A report that might be a security issue, or a SQL check that misses something (label `security-hardening`): see `docs/agents/security-triage.md`. ### Domain docs Single-context: a root `CONTEXT.md` (created lazily) plus ADRs in `docs/adrs/`. See `docs/agents/domain.md`. ### Code review Every PR needs an independent review before it leaves draft, and always when an agent authored it. Review with a fresh agent using the `code-review` skill, which follows this repo's review profile. See `docs/agents/code-review.md`. ### Docs house style Docs follow the house style in `apps/docs-site/STYLE.md`. Before you write or restyle a docs-site page, use the `docs-site` skill: it has the page steps, the design rules and a screenshot tool for checking a page in both themes. ## Where product/architecture decisions live `docs/` is the constitution — check it before assuming behavior, not just the code: - `docs/mission.md` — north star, principles, non-goals - `docs/architecture.md` — package boundaries, install profiles - `docs/contracts/` — formal contracts (modes, sensitive fields, schema format) - `docs/adrs/` — architecture decision records; read the index, `docs/adrs/README.md`, before you plan a change `apps/docs-site/src/content/docs/` is the public-facing docs (askdb.tools) — treat it as a product surface, not just documentation. If you change a package's public API or add a new integration pattern, the docs site needs a corresponding update or agents integrating AskDB elsewhere will get stale guidance. ## Conventions - AskDB returns SQL; it never executes it. Any code path that runs generated SQL against a real database belongs in a host app or a fixture/test harness, not in `packages/core`. - `@askdb/ai`'s built-in providers (`createAiRegistry()`, `createAskDb({ config })`) and raw Vercel AI SDK `LanguageModel` objects are both first-party, equally supported ways to give `ask()` a model — don't privilege one over the other in new docs or examples without a reason tied to who owns provider config. Don't point new docs or examples at the removed `@askdb/ai-*` packages. - `@askdb/ai` declares `ai` as a peer and each `@ai-sdk/*` provider SDK as an optional peer with a wide floor (the oldest version its contract tests pass against; `pnpm test:ai-floors` checks it in CI) — don't hard-pin AI SDK versions in library packages; let the host app's `package.json` pin them. Built-in providers import their SDK lazily with the `.catch()` chained on the `import()` so esbuild doesn't require every SDK; webpack still does unless the host lists the missing ones in `externals` (see `packages/ai/src/providers/optional-peer.ts`). - Published ranges are what hosts install against, so a bump the range already allows moves only the lockfile. A floor rises by hand, for a security fix or a version AskDB needs, with a changeset naming which; raising an `ai` or `@ai-sdk/openai` floor raises the consumer lab's host pin with it, or its `host-peers` scenario fails (ADR 0015). - Add tests for behavior that affects public APIs, package output, SQL safety/validation, or user-facing workflows. Integration tests that need a live database run when their env var is set. Tests that need a real schema in every engine use the multi-engine fixture (`pnpm fixture:up`, `ASKDB_FIXTURE_HOST`; see `CONTRIBUTING.md`). - Add a changeset (`pnpm changeset`) for any change to a publishable package. A change confined to test files (`*.test.*`, `*.spec.*`, `__tests__/`, `__snapshots__/`, `test-utils.ts`) under a package's `src` needs none, and CI doesn't require one. The 12 packages in the `fixed` group in `.changeset/config.json` are on the 1.0 line and share one version: a breaking change to one of them is a `major` changeset, which after 1.0.0 moves all 12 to the next major (between `1.0.0-rc.1` and `1.0.0` the API is frozen, so a breaking change there needs the maintainer's decision; Changesets would only raise the `rc` number), unless it is confined to an experimental surface in ADR 0030, which takes a `minor` naming `askdb`, `@askdb/config` or, for `@askdb/client/charts`, `@askdb/client`. Studio, `@askdb/enrich` and `@askdb/rag` stay `0.x`: a breaking change there is a `minor`, never a `major`. See `docs/release.md`, "Version Posture". - Package versions change only in the Version PR (`changeset-release/main`), and approving it is the maintainer's release decision: once it's approved, its merge publishes to npm with no further approval. An agent never approves the Version PR, even when `gh` runs with the maintainer's credentials. It may enable auto-merge on it, or merge it, only after the maintainer has approved it. - Keep `apps/docs-site` accurate as you go, not as a follow-up: don't invent package names, APIs, or file paths there — verify against the actual source or existing docs content before writing a claim. - Markdown and MDX (docs, ADRs, skills, changesets, READMEs): one line per paragraph or list item, left for the editor to soft-wrap. Break lines only where the Markdown structure needs it — headings, list items, table rows, code blocks. ## Reporting to the maintainer The maintainer reads your end-of-turn reply top-down and wants the reasoning kept in it, so make it scannable, in this order: 1. **Answer**: the outcome or your recommendation, in one or two lines. 2. **Status table**: one row per PR, issue or check, when the turn touched several. 3. **Needs you**: only the decisions that are the maintainer's to make. 4. **Why**: the reasoning, under one short `###` heading per topic, a few bullets each, every bullet led by a bold phrase. State each point once, in the section it belongs to. Give verification as one line of results; the details go in the PR or issue body. # This is NOT the Turborepo you know Turborepo configuration, task behavior, and CLI commands can vary between installed versions and may differ from your training data. Resolve the `turbo` package from this file's directory or relevant workspace; in monorepos, it may not be visible from the repository root. For example, run `node -p "require.resolve('turbo/package.json')"` from a workspace that depends on `turbo`. Read `docs/README.md` inside that installed package first, then read the relevant pages from its `docs/` directory before changing Turborepo configuration or commands. Heed deprecation notices. These bundled docs match the installed package version and are available without network access. This block is written and re-added by `turbo` before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in `crates/turborepo-cli/src/cli/agent_guidance.rs`. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set `"agentGuidance": false` in the root `turbo.json` or `turbo.jsonc` to opt out; this does not remove an existing block. Keep the block committed with your work to avoid an uncommitted change on the next agent invocation.