diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..f4a52d69 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,199 @@ +# AGENTS.md + +Standards for anyone — human or coding agent — working in this repository: the +workspace map, the Definition of Done, and the conventions that keep changes +consistent. + +## What this is (and isn't) + +This is the **repo-root contributor/agent standards doc** — how to find your +way around the Dawn monorepo, what "done" means for a change, and the rules +that keep the codebase consistent. It's the canonical entrypoint; see +[Cross-links](#cross-links) for how it relates to `CONTRIBUTING.md` and +`CONTRIBUTORS.md`. + +**This is not** the runtime `workspace/AGENTS.md` capability. Dawn ships a +built-in capability +(`packages/core/src/capabilities/built-in/agents-md.ts`) that auto-injects the +contents of an **app's** `/workspace/AGENTS.md` into that agent's +system prompt as its persistent "# Memory" — re-read every turn, updated by +the agent itself via `writeFile`. That's an end-user Dawn app feature, +documented at [dawnai.org/docs/memory](https://dawnai.org/docs/memory). The +name collision is real: this file (repo root, for contributors) and that file +(inside a generated app's `workspace/`, for the agent at runtime) share a +filename but nothing else. If you're looking for the runtime feature, this +isn't it. + +## Workspace map + +Every `packages/*` directory is a pnpm workspace member (verify: `pnpm -r list --depth -1`). One-line purpose is each package's own `README.md` first line. + +**Core framework** + +| Package | Purpose | +|---|---| +| `@dawn-ai/sdk` | The author-facing TypeScript SDK — `agent()`, `defineMiddleware()`, `allow()`/`reject()`, and the type primitives the CLI consumes. | +| `@dawn-ai/core` | Filesystem-based route discovery, app config loading, state-field resolution, and typegen primitives that the Dawn CLI builds on. | +| `@dawn-ai/cli` | The `dawn` CLI — local HMR dev runtime, route execution, validation, typegen, and the build step that produces LangSmith deployment artifacts. | +| `@dawn-ai/langgraph` | LangGraph runtime adapters and route module contracts (`graphAdapter`, `workflowAdapter`, `defineEntry`) used by the CLI. | +| `@dawn-ai/langchain` | LangChain backend adapters — materializes `chain` routes and provider-aware `agent` routes (tool conversion, streaming, retry). | + +**Capabilities & integrations** + +| Package | Purpose | +|---|---| +| `@dawn-ai/ag-ui` | AG-UI protocol translation for Dawn's local runtime — maps runtime stream chunks to AG-UI events and back, so CopilotKit and other AG-UI clients can drive Dawn agents. | +| `@dawn-ai/permissions` | Permission and access-control primitives for Dawn agents — gating tool and resource access at runtime. | +| `@dawn-ai/workspace` | Filesystem-backed workspace utilities for Dawn agents — reading, writing, and managing files in an agent's working directory. | +| `@dawn-ai/sandbox` | Reference sandbox providers for Dawn workspace execution — a Docker-backed `SandboxProvider` that redirects the workspace filesystem and shell tools into a per-thread isolated environment. | +| `@dawn-ai/vite-plugin` | Vite plugin for Dawn's typegen pipeline (extracts tool types and generates route ambient declarations). | + +**Storage & memory** + +| Package | Purpose | +|---|---| +| `@dawn-ai/memory` | Deterministic long-term memory storage and recall for Dawn's typed `memory.ts` capability — the storage/ranking layer under `@dawn-ai/core`. | +| `@dawn-ai/memory-pgvector` | Postgres + pgvector backend for Dawn's typed long-term memory store, for deployments where SQLite is too local (multiple instances, shared DB, HNSW retrieval at scale). | +| `@dawn-ai/sqlite-storage` | SQLite-backed storage adapter for Dawn — durable persistence for agent state and runtime data. | + +**Testing & evals** + +| Package | Purpose | +|---|---| +| `@dawn-ai/testing` | Testing utilities for Dawn apps — helpers for exercising routes, tools, and agent behavior in unit and scenario tests. | +| `@dawn-ai/evals` | Evaluation harness for Dawn agents — running and scoring agent behavior against datasets and scenarios. | + +**Scaffolding & tooling** + +| Package | Purpose | +|---|---| +| `create-dawn-ai-app` | Scaffold a new Dawn app — generates a working application from the supported starter templates with Dawn's canonical layout wired for local development. | +| `@dawn-ai/devkit` | Internal scaffold templates and dev-time tooling shared between `@dawn-ai/cli` and `create-dawn-ai-app`. | +| `@dawn-ai/config-typescript` | Shared TypeScript compiler configurations (`base`, `library`, `node`, `nextjs`) for Dawn workspace packages. | +| `@dawn-ai/config-biome` | Shared Biome lint/format configuration used by Dawn workspace packages. | + +**Apps** + +| Package | Purpose | +|---|---| +| `@dawn-ai/web` (`apps/web`) | The documentation website (dawnai.org) and its content/nav. | + +**Examples** (`examples/*`, pnpm workspace members; consume Dawn via `workspace:*` and are typechecked in CI) + +| Package | Purpose | +|---|---| +| `@dawn-example/chat-server` / `@dawn-example/chat-web` (`examples/chat`) | Foundational agent-harness primitives (filesystem + bash) end-to-end, plus planning, skills, subagents, workspace, and HITL permissions, with a disposable smoke-test web client. | +| `@dawn-example/memory` (`examples/memory/server`) | Long-term memory with a backend-switchable store — zero-setup SQLite by default, Postgres + pgvector via `DATABASE_URL`, hybrid keyword + vector recall via `OPENAI_API_KEY`. | +| `@dawn-example/research-server` / `@dawn-example/research-web` (`examples/research`) | The flagship deep-research assistant example — routes, tools, subagents, memory, planning, offloading, HITL permissions, and an optional Docker sandbox. | + +Note: `examples/chat/package.json` and `examples/research/package.json` are +orchestration-only (`private: true`, one level above `server`/`web`) and are +**not** themselves pnpm workspace members — the actual members are the +`server`/`web` subdirectories, matched by the `examples/*/*` glob in +`pnpm-workspace.yaml`. + +**Charts** (Helm charts under `charts/`, not pnpm workspace members) + +| Chart | Purpose | +|---|---| +| `charts/dawn-app` | Runs a built Dawn app image (from `langgraphjs dockerfile`) on Kubernetes as a Deployment + Service, with optional Ingress, HorizontalPodAutoscaler, and PodDisruptionBudget, wired to the in-cluster `kubernetesSandbox` orchestrator ServiceAccount. | +| `charts/dawn-sandbox-infra` | Cluster-side infrastructure for the Dawn `kubernetesSandbox` provider — namespace, least-privilege RBAC, default-deny egress, quotas/limits, Pod Security Standards, and a PVC reaper. | + +`test/` and `scripts/` are repo-level (verification lanes and workspace +scripts respectively) — not workspace packages. + +## Definition of Done + +The exact gates a change must pass are the `validate` job in +`.github/workflows/ci.yml`, in order: + +1. `pnpm lint` +2. `pnpm check:build-cache` +3. `pnpm build` +4. `pnpm typecheck` +5. `pnpm test` +6. `node scripts/check-docs.mjs` +7. `pnpm pack:check` +8. `pnpm verify:harness:self-test` +9. `pnpm verify:harness:framework` +10. `pnpm verify:harness:runtime` +11. `pnpm verify:harness:smoke` + +On pull requests, a separate `changesets` job also runs +`node scripts/check-changesets.mjs` to require a changeset for user-facing +package changes. + +Run `pnpm ci:validate` locally to approximate this lane (it exists as a +script in the root `package.json`). It runs the same lint → build-cache → +build → typecheck → test → docs-check → pack-check → harness sequence, plus a +few extra local-only release-script unit tests +(`test:release-publish`, `test:upload-release-assets`, +`test:backfill-release-tags`) that aren't separate CI steps. + +**Gated lanes** — these run as separate CI jobs behind env flags or dedicated +infrastructure, not part of `validate`, and aren't required for most PRs: +`sandbox-docker` (`DAWN_TEST_DOCKER=1`), `pgvector-docker` +(`DAWN_TEST_PGVECTOR=1`), `sandbox-k8s` (`DAWN_TEST_K8S=1`, kind + Calico), +`sandbox-k8s-e2e` / `sandbox-docker-e2e` (`DAWN_TEST_SMOKE_E2E=1`, full-arc +deployed-app smoke), `chart-validate` (Helm lint + kubeconform), and +`chart-apply-smoke` (kind install smoke). + +## Conventions + +- **Changesets are a fixed group, patch on 0.x.** All publishable packages + release together (`.changeset/config.json`'s `fixed` group). On a 0.x train + a `minor` bump takes every package to `1.0.0` — use `patch` unless you + intend a real 1.0 release. +- **`exactOptionalPropertyTypes: true`.** Never assign `{ x: undefined }` to + an optional field; use a conditional spread (`...(x !== undefined ? { x } : {})`) + instead, or the type checker will reject it. +- **Never run bare `biome check --write`.** It mass-reformats the whole + workspace. Use `pnpm lint` (or `pnpm lint:fix` to auto-fix), or scope Biome + to the files you changed. +- **Import specifiers: `src/` uses `.js`, `test/` uses `.ts`.** This is + NodeNext ESM — source files import sibling `src/*.ts` modules with a `.js` + extension; test files import with `.ts`. Follow the existing pattern in the + package you're editing. +- **Examples/docs/scaffolds use gpt-5-family models only** (canonical default + `gpt-5-mini`; no `gpt-4o`, though it stays in the provider registry, + validation tests, and recorded fixtures). This is a project convention, not + currently enforced by `scripts/check-docs.mjs` — check it by eye when + touching examples. +- **Branch per PR; pin before dispatching parallel/subagent work.** In a + multi-worktree setup, a subagent's commits can land on a detached HEAD + tracking the wrong branch if the feature branch isn't checked out first. +- **Build before running anything against `dist/`.** Packages compile + `src/*.ts` to a gitignored `dist/`, and consumers import the built output — + a stale or skewed `dist/` (from a branch switch or a per-package filtered + build) produces false negatives in ad-hoc scripts. Run `pnpm build` first; + see `CONTRIBUTING.md`'s "Build before running anything against `dist/`". +- **Banned doc phrases.** `scripts/check-docs.mjs` greps `README.md`, + `CONTRIBUTING.md`, `CONTRIBUTORS.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, + `apps/web/app`, `apps/web/content`, `docs/` (excluding + `docs/superpowers/`), and `packages/` for stale or overstated wording — + e.g. the retired `dawn-ai.org` domain, provider-prefixed model ids + (`openai:gpt...`), the old `agent.bindTools` / `.dawn/generated` / + `auto-bound`/`auto-registered` phrasing, and claims like "byte-identical" + or "speaks the LangSmith protocol natively" that overstate local/prod + parity. This file (`AGENTS.md`) isn't in that scanned set, but keep it + honest anyway — see the `forbiddenContent` list in + `scripts/check-docs.mjs` for the exact patterns. +- **Always run commands from the repo root.** Turbo and workspace-package + resolution assume it. + +## Where things live + +- Docs site content: `apps/web/content/docs/*.mdx` (nav registered in + `apps/web/app/components/docs/nav.ts`). +- Specs, plans, audits, runbooks: `docs/superpowers/`. +- CI: `.github/workflows/ci.yml`. +- Changeset config (fixed group, patch-on-0.x): `.changeset/config.json`. + +## Cross-links + +- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — the public PR path: setup, issues, + PRs, CLA/DCO, code of conduct. +- [`CONTRIBUTORS.md`](./CONTRIBUTORS.md) — internal monorepo guide: local + setup, the `--mode internal` scaffold path, and verification lanes. Its + per-package responsibilities point back at the workspace map above. +- [`README.md`](./README.md) — project overview and quickstart. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0959651e..dc05960f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,8 @@ Thanks for helping improve Dawn. This guide covers the public contribution path for issues, pull requests, and package changes. For detailed monorepo layout, package ownership, and verification lanes, see [CONTRIBUTORS.md](./CONTRIBUTORS.md). +Standards, the workspace map, and the Definition of Done for any change live in [AGENTS.md](./AGENTS.md) — read that first. + ## Development Setup Use Node.js `>=22.12.0` and pnpm `10.33.0`. diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 60eaf8dd..7eb62529 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -4,6 +4,8 @@ This guide is for engineers working inside the Dawn monorepo. It covers the current repo layout, package boundaries, local setup, verification commands, and where the living documentation lives. +Canonical standards (workspace map, Definition of Done, and conventions) live in [AGENTS.md](./AGENTS.md); see that first. + ## Repository Layout - `apps/web` contains the documentation website and user-facing docs pages. @@ -14,14 +16,11 @@ This guide is for engineers working inside the Dawn monorepo. It covers the curr ## Package Responsibilities -- `@dawn-ai/core` owns app discovery, config loading, validation, and route type generation. -- `@dawn-ai/sdk` owns the author-facing contract: types, helpers, runtime context, middleware, and tool authoring. -- `@dawn-ai/langgraph` owns LangGraph-specific route module contracts and adapter code. -- `@dawn-ai/langchain` owns LCEL chain support and provider-aware `agent()` materialization. -- `@dawn-ai/cli` owns the user-facing commands and the local runtime behavior. -- `create-dawn-ai-app` owns app scaffolding. -- `@dawn-ai/devkit` owns shared template and file-generation helpers. -- `@dawn-ai/config-typescript` and `@dawn-ai/config-biome` own the shared workspace configuration packages. +See the [workspace map in AGENTS.md](./AGENTS.md#workspace-map) for the full, +current list of all 19 `packages/*` plus apps, examples, and charts — this +section used to duplicate a partial list and drifted out of date. Keep the +map in `AGENTS.md` current when a package is added or its scope changes; +don't re-list packages here. ## Local Setup diff --git a/README.md b/README.md index 2049bb0b..19abbf39 100644 --- a/README.md +++ b/README.md @@ -190,7 +190,7 @@ The built-in `agent()` route materializes to a LangChain chat model. Dawn infers --- -Contributions welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). Repo layout and dev commands in [CONTRIBUTORS.md](./CONTRIBUTORS.md). Security: [SECURITY.md](./SECURITY.md). Please follow the [Code of Conduct](./CODE_OF_CONDUCT.md). +Contributions welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). Repo layout and dev commands in [CONTRIBUTORS.md](./CONTRIBUTORS.md). Standards, workspace map, and Definition of Done in [AGENTS.md](./AGENTS.md). Security: [SECURITY.md](./SECURITY.md). Please follow the [Code of Conduct](./CODE_OF_CONDUCT.md). ## License diff --git a/docs/superpowers/plans/2026-07-12-agents-md.md b/docs/superpowers/plans/2026-07-12-agents-md.md new file mode 100644 index 00000000..35a684ce --- /dev/null +++ b/docs/superpowers/plans/2026-07-12-agents-md.md @@ -0,0 +1,69 @@ +# Root `AGENTS.md` — implementation plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans. Steps use checkbox (`- [ ]`) syntax. + +**Goal:** A canonical repo-root `AGENTS.md` — workspace map + Definition of Done + first-class conventions — cross-linked from README/CONTRIBUTING/CONTRIBUTORS. + +**Architecture:** A single markdown file at repo root plus three one-line cross-links. Pure docs, zero runtime risk. + +**Spec:** `docs/superpowers/specs/2026-07-12-agents-md-design.md` + +--- + +## Task 1: Write `AGENTS.md` + +**Files:** +- Create: `AGENTS.md` (repo root) + +- [ ] **Step 1: Write the file** with these sections (content from the spec; verify every fact against the repo as you write): + + 1. **"What this is (and isn't)"** — one paragraph: repo-root contributor/agent standards. Explicit callout that this is NOT the runtime `workspace/AGENTS.md` agent-memory capability (`packages/core/src/capabilities/built-in/agents-md.ts`), which injects an *app's* `workspace/AGENTS.md` into the agent prompt — link `/docs/sandbox` or the capabilities docs for that. + 2. **Workspace map** — grouped table `package → one-line purpose`. Generate the list by reading each `packages/*/package.json` name + the first line of each `packages/*/README.md` (do not trust the spec's list blindly — re-derive so it's current). Groups: Core framework / Capabilities & integrations / Storage & memory / Testing & evals / Scaffolding & tooling / Apps / Examples / Charts. Note `test/` + `scripts/` are repo-level, not packages. + 3. **Definition of Done** — the exact gates from `.github/workflows/ci.yml` `validate` job (read it, list the step `run:` commands in order: `pnpm lint`, `pnpm check:build-cache`, `pnpm build`, `pnpm typecheck`, `pnpm test`, `node scripts/check-docs.mjs`, `pnpm pack:check`, `pnpm verify:harness:self-test`, `verify:harness:framework`, `verify:harness:runtime`, `verify:harness:smoke`) + the `changesets` gate. Mention the gated lanes (`sandbox-docker`, `pgvector-docker`, `sandbox-k8s`, `sandbox-{docker,k8s}-e2e`, `chart-validate`, `chart-apply-smoke`) run behind env flags. State: `pnpm ci:validate` approximates the DoD locally (confirm this script exists in root `package.json`). + 4. **Conventions** — each a rule + one-line why: fixed-group changesets → `patch` on 0.x (a `minor` bumps all to 1.0.0); `exactOptionalPropertyTypes` → conditional-spread optionals; never bare `biome check --write` (use `pnpm lint`); `src`→`.js` / `test`→`.ts` import specifiers (NodeNext); `model:` examples must be gpt-5 family (`check-docs.mjs` enforces); branch-per-PR + pin the branch before dispatching parallel agents; build before running against `dist/` (link `CONTRIBUTING.md`); banned doc phrases (`check-docs.mjs`); run commands from repo root. + 5. **Where things live** — docs site (`apps/web/content/docs/*.mdx`), specs/plans (`docs/superpowers/`), CI (`.github/workflows/ci.yml`), changeset config (`.changeset/config.json`). + 6. **See also** — links to `CONTRIBUTING.md`, `CONTRIBUTORS.md`, `README.md`. + + No banned phrases (mirror the `check-docs.mjs` ban list even though AGENTS.md isn't scanned — keep it honest). Any `model:` mention → gpt-5 family. + +- [ ] **Step 2: Verify facts** + + Run and reconcile the doc against reality: + - `ls packages` and `for d in packages/*; do node -e "console.log(require('./$d/package.json').name)"; done` — every package appears in the map. + - `grep -nE "run:" .github/workflows/ci.yml` under the `validate:` job — every gate is listed. + - Confirm `ci:validate` in root `package.json`. + +- [ ] **Step 3: Commit** + +```bash +git add AGENTS.md +git commit -m "docs: canonical root AGENTS.md — workspace map, Definition of Done, conventions" +``` + +--- + +## Task 2: Cross-links + +**Files:** +- Modify: `README.md`, `CONTRIBUTING.md`, `CONTRIBUTORS.md` + +- [ ] **Step 1:** Add a one-line link to `AGENTS.md` as the canonical standards entrypoint near the top of each: + - `README.md` — in the contributing/dev section (find where it points at CONTRIBUTING). + - `CONTRIBUTING.md` — a line under the intro: standards + workspace map live in `AGENTS.md`. + - `CONTRIBUTORS.md` — point its per-package responsibilities at the `AGENTS.md` workspace map (so the two lists don't diverge); keep its scaffold-internal/local-setup content. + +- [ ] **Step 2: Commit** + +```bash +git add README.md CONTRIBUTING.md CONTRIBUTORS.md +git commit -m "docs: link AGENTS.md as the canonical standards entrypoint" +``` + +--- + +## Task 3: Verify + PR + +- [ ] **Step 1:** `node scripts/check-docs.mjs` → must PASS (AGENTS.md is not under `apps/web/content/docs`, so it should not need nav registration — confirm no failure). Run `pnpm lint` (a root markdown file shouldn't trip Biome, but confirm). +- [ ] **Step 2:** Rebase on `origin/main`, push branch, open PR. No changeset (no `packages/**` change). Watch `validate` + advisory review; address findings. + +**Notes for executor:** Branch is its own (e.g. `docs/agents-md`); pin before any subagent dispatch. This is docs-only — no TDD tests, but every claim must be verified against the live repo (that's the "test"). diff --git a/docs/superpowers/specs/2026-07-12-agents-md-design.md b/docs/superpowers/specs/2026-07-12-agents-md-design.md new file mode 100644 index 00000000..41a9b171 --- /dev/null +++ b/docs/superpowers/specs/2026-07-12-agents-md-design.md @@ -0,0 +1,71 @@ +# Root `AGENTS.md` — design + +**Date:** 2026-07-12 +**Status:** approved (brainstorm) +**Topic:** A canonical repo-root `AGENTS.md` — one standards doc (workspace map + Definition of Done + conventions) for human contributors and coding agents. + +## Problem + +Contributor/agent standards are scattered and incomplete: +- `CONTRIBUTING.md` — public PR path (setup, `pnpm ci:validate`, build-before-`dist`, changesets, CLA/DCO). Good but not agent-oriented and has no package map. +- `CONTRIBUTORS.md` — internal monorepo guide with per-package responsibilities for only ~8 of 19 packages, the `--mode internal` scaffold path, verification lanes. +- The high-value **conventions** (patch/fixed-group changesets, `exactOptionalPropertyTypes` spreads, never bare `biome check --write`, `src`→`.js`/`test`→`.ts` imports, gpt-5-only examples, branch-per-PR, banned doc phrases) live **only in dated `docs/superpowers/plans/*` files** — invisible to a new contributor or a coding agent. + +There is **no root `AGENTS.md`**, which is the emerging convention coding agents look for at repo root. + +**Name-collision hazard (must be addressed):** Dawn ships a runtime capability (`packages/core/src/capabilities/built-in/agents-md.ts`) that injects an *app's* `/workspace/AGENTS.md` into the agent's system prompt as "# Memory". ~10 such runtime files exist under `examples/*/server/workspace/`, `packages/devkit/templates/*`, `apps/web/`. A repo-root contributor `AGENTS.md` means something completely different. The doc must open by stating this distinction. + +## Goal + +A single `AGENTS.md` at repo root that is the canonical entrypoint for "how to work in this repo," linked from `README.md`, `CONTRIBUTING.md`, and `CONTRIBUTORS.md`. It does not replace those two (per decision — keep all three, cross-link); it consolidates the map + DoD + conventions that currently have no home. + +## Non-goals + +- Not deleting or rewriting `CONTRIBUTING.md`/`CONTRIBUTORS.md` (they keep their roles; we add cross-links and, where `CONTRIBUTORS.md`'s partial package list overlaps, point it at the AGENTS.md map rather than maintaining two divergent lists). +- Not documenting the runtime `workspace/AGENTS.md` capability beyond the one-paragraph disambiguation (that's `/docs/*` territory). +- Not a tutorial (that's `getting-started.mdx`). + +## Structure of `AGENTS.md` + +1. **What this file is (and isn't)** — repo-root contributor/agent standards. Explicit callout: *not* the runtime `workspace/AGENTS.md` agent-memory feature (link to the sandbox/capabilities docs for that). +2. **Workspace map** — all 19 packages grouped, `name → one-line purpose` (from each package's README first line): + - Core framework: `@dawn-ai/sdk`, `@dawn-ai/core`, `@dawn-ai/cli`, `@dawn-ai/langgraph`, `@dawn-ai/langchain` + - Capabilities/integrations: `@dawn-ai/ag-ui`, `@dawn-ai/permissions`, `@dawn-ai/workspace`, `@dawn-ai/sandbox`, `@dawn-ai/vite-plugin` + - Storage/memory: `@dawn-ai/memory`, `@dawn-ai/memory-pgvector`, `@dawn-ai/sqlite-storage` + - Testing/evals: `@dawn-ai/testing`, `@dawn-ai/evals` + - Scaffolding/tooling: `create-dawn-ai-app`, `@dawn-ai/devkit`, `@dawn-ai/config-typescript`, `@dawn-ai/config-biome` + - Apps: `@dawn-ai/web` + - Examples: `@dawn-example/chat`, `examples/memory`, `@dawn-example/research` + - Charts (not pnpm members): `dawn-app`, `dawn-sandbox-infra` + - Note: `test/` and `scripts/` are repo-level, not workspace packages. +3. **Definition of Done** — the exact gates a change must pass, derived from `.github/workflows/ci.yml` `validate` job: `pnpm lint` · `check:build-cache` · `pnpm build` · `pnpm typecheck` · `pnpm test` · `check-docs` · `pack:check` · `verify:harness:{self-test,framework,runtime,smoke}`; plus the `changesets` gate (PRs). Note the gated lanes (`sandbox-docker`, `pgvector-docker`, `sandbox-k8s`, `*-e2e`, `chart-*`) and that they run behind env flags. State the one-liner: run `pnpm ci:validate` locally to approximate the DoD. +4. **Conventions (promoted to first-class)** — each a short rule + why: + - Changesets: the publishable set is a **fixed group** — on 0.x a `minor` bumps everyone to 1.0.0, so use `patch` unless intentionally releasing 1.0. + - `exactOptionalPropertyTypes: true` → conditional-spread optionals, never `{ x: undefined }`. + - Never bare `biome check --write` (mass-reformats); use `pnpm lint` or scope to changed files. + - `src/` imports use `.js` specifiers, `test/` uses `.ts` (NodeNext ESM). + - Any `model:` example in docs/examples/scaffolds must be **gpt-5 family** (`check-docs.mjs` enforces). + - Branch per PR; when dispatching parallel agents, pin the branch first (multi-worktree detached-HEAD hazard). + - Build before running anything against `dist/` (link to `CONTRIBUTING.md`'s section rather than re-deriving). + - Banned doc phrases (`check-docs.mjs` greps them out) — link to the list. + - Always run commands from the repo root (Turbo/workspace resolution). +5. **Where things live / how to find them** — one-liners: docs site (`apps/web/content/docs/*.mdx`), specs+plans (`docs/superpowers/`), CI (`.github/workflows/ci.yml`), changeset config (`.changeset/config.json`). +6. **Cross-links** — `CONTRIBUTING.md` (PR/CLA), `CONTRIBUTORS.md` (scaffold-internal path + local setup), `README.md`. + +## Maintenance / drift control + +The workspace map and DoD can drift as packages/CI change. Two low-cost guards (either/both, decided at plan time): +- A `scripts/check-agents-md.mjs` (optional, added to the `validate` lane) that asserts every `packages/*` dir appears in the AGENTS.md map and every `validate`-job step name appears in the DoD section. This keeps the doc honest automatically. +- At minimum, a comment in `AGENTS.md` pointing maintainers to update it when adding a package or a CI gate. + +Recommendation: ship the doc first; add the check as a fast-follow only if drift proves real (YAGNI). + +## Testing + +- `node scripts/check-docs.mjs` still passes (AGENTS.md is not under `apps/web/content/docs`, so it's not part of the site nav topology — confirm the docs-check doesn't require registration for a root markdown file). +- If the optional `check-agents-md.mjs` guard is built, it gets a unit test (fixture repo dir → asserts pass/fail on a missing package/gate). +- Links in `AGENTS.md` resolve (manual + the guard if built). + +## Rollout + +Single PR: `AGENTS.md` + the three cross-links (`README.md`, `CONTRIBUTING.md`, `CONTRIBUTORS.md`). No changeset (no `packages/**` change). Smallest, zero-runtime-risk of the three DX follow-ups — good first.