AGENTS.md

Guidance for AI coding agents working in this repository, a Bun monorepo: the web/next app, the api/hono service, and shared packages/* (auth, config, db, env), with build-only tooling in packages/scripts. The product here is inscope's own CLI in packages/cli (the inscope npm package) with its suite in tests/packages/cli; both are fork-owned paths a zerostarter sync never touches. Start each task with the codebase-map skill to orient, then load the task skill that fits (see Skills).

Workflow

• ALWAYS: Do every change in its own git worktree, never on the primary checked-out branch. Create it under .claude/worktrees/ (repo-root relative, one directory per worktree; never /tmp, home, or a sibling of the repo), and fork its branch from the latest canary: fetch first, then branch from origin/canary (git fetch origin canary && git worktree add .claude/worktrees/<name> -b <branch> origin/canary), so the change builds on current main.
• ALWAYS: Show the user a new or altered database schema and wait for their go before generating or applying a migration. Name the choices that are costly to reverse and stop; a shape is cheap to argue about and expensive to change once rows exist, and canary shares its database with production, so applying reaches production immediately. See the db-migration skill.
• ALWAYS: Point local database work at a disposable container (bunx pglaunch -k) set in the worktree's own .env, never the POSTGRES_URL that ships in the root .env. That one is the shared Neon database read by both canary and production, so a migration or a rename applied there reaches production immediately and under running code. Seed fake rows; real rows must never reach a screenshot or a PR. See the db-migration skill.
• ALWAYS: Keep documentation in sync with every change. Whenever code, structure, conventions, or tooling change, update the matching docs in the same change (e.g. web/next/content/docs/, README.md, the llms.txt/llms-full.txt context routes, skill docs under .agents/skills/ and .claude/skills/, and these agent guides AGENTS.md/CLAUDE.md). Docs must never drift. See the doc-sync skill.
• ALWAYS: When code, a convention, a command, a path, or tooling changes, review the skills in .agents/skills/ that touch it and update them in the same change, so every skill stays accurate and relevant. A skill that describes old behavior misleads every agent that loads it, which is worse than no skill. If a change makes a skill obsolete, remove it; if it reveals a gap, consider adding one.

Code

• ALWAYS: Use @/ for imports, if applicable.
• ALWAYS: Put every test under the repo-root tests/ directory, mirroring the path of the file it covers (api/hono/src/lib/sql.ts is tested by tests/api/hono/src/lib/sql.test.ts). One bun run test runs the suite; a package never carries its own test/ directory or test script. That script builds packages/* first, because a test reaches a shared package through its exports, which point at dist, so on a fresh checkout an unbuilt package resolves to nothing. Only the shared packages are built, not the apps: a test imports app code by source path and never through dist. tests/ is fork-excluded, so the root script no-ops where the directory is absent. Note bun test skips dot-directories, which is why .github/scripts tests live under tests/github/scripts/. An end-to-end test mirrors the router or page its requests hit and carries the .e2e.test.ts suffix (api/hono/src/routers/admin.ts is driven by tests/api/hono/src/routers/admin.e2e.test.ts), imports the stack helper at tests/stack.ts, drives the artifact over HTTP without importing app source, and skips itself when either of E2E_API_URL and E2E_WEB_URL is unset, which is how bun run test stays green without a stack; bun run test:e2e names the compose ports unless those variables say otherwise, refuses any host that is not local, and needs a local-stage stack (NODE_ENV=local with AGENT_SIGNIN_ENABLED=true) so the agent can sign in, with both OAuth credential pairs set to any value, the id and the secret of each, since a provider registers only when both halves are present and the providers snapshot lists all three.
• ALWAYS: Put a new build or tooling script in packages/scripts/src/, not .github/scripts/, and declare the dependencies it imports on that package. It is a real workspace package, so turbo prune carries it into the Docker build without an extra COPY.
• ALWAYS: Prefer a Bun-native API when the file runs under Bun and one exists (Bun.file, Bun.write, Bun.spawn); otherwise use a Node built-in with the node: protocol prefix (import { join } from "node:path", require("node:fs")), never the bare specifier. Code that runs under Node in any environment (the packages/cli npm binary in the canonical starter, web/next, where next dev runs under Node while Docker and Vercel serve it under Bun, and shared packages/env) stays on node:. See the runtime-apis skill.
• ALWAYS: Keep enumerable lists alphabetical (A→Z), union/enum members, env-var schemas and their runtimeEnv/turbo.json mirrors, and the docs that list them, so the code and its docs stay in the same order. Use a meaningful order (flow, priority, required-then-optional) only where alphabetical would obscure intent. API response schemas are included, and they order by relevance first, then A→Z: where one key is what the response is about and the rest describe it, that key leads and the others sort after it (users, then hasNextPage, page, perPage, total). Everything else, a row's own fields included, is plain A→Z with id in its alphabetical place rather than hoisted. Sorting the subject too would put it in a different position on every endpoint, which is the drift this rule exists to prevent.
• ALWAYS: Version every root catalog entry with a caret range (^1.2.3), never an exact pin or a tilde. .github/scripts/deps-manager.ts rewrites exact and tilde specs on postinstall, including specs it promotes into the catalog from a workspace dep, and reports the rest (wildcards, dist-tags, compound ranges) for a manual fix. There is no opt-out: no pin survives an install, so pinning deliberately means changing the rule in that script and recording why in .github/notes/dependencies.md.
• Do not comment unnecessarily. Only comment if it is absolutely necessary.
• Keep comments on a single line; do not split one across multiple // lines or use multi-line /* */ blocks.
• NEVER: Use em-dashes (the long dash, U+2014) in code, comments, docs, or copy. Regular hyphens are fine; for a pause or aside, use a comma, colon, or period.

inscope CLI

• ALWAYS: Keep packages/cli at zero runtime dependencies; hand-roll validation rather than add a library. Logic lives in src/; bin/ is the CLI surface (arg parsing, prompts, output). Inside the package, @/ is src/ and ~/ is the package root.
• ALWAYS: After changing a snapshot-pinned generator (packages/cli/src/generators/{gitconfig,hook,mcp}.ts), run bun test tests/packages/cli --update-snapshots and review the snapshot diff: it is the review surface, so a moved snapshot is a change to decide on, never noise to silence.
• ALWAYS: Pair a generator's pure render function (config in, text out, snapshot-pinned) with its side-effecting apply; write every file through the atomic writer in src/io.ts, and edit shared dotfiles (~/.zshrc, ~/.gitconfig) only inside a marked managed block (src/managed-block.ts).
• ALWAYS: When a command, flag, field, or behavior changes, update README.md and the bundled self-skill packages/cli/skills/inscope/SKILL.md in the same change, and run the ship skill before committing.
• ALWAYS: Read the inherited skills with this fork in mind: here packages/cli is inscope's CLI, not zerostarter's scaffolding CLI, tests/ is kept, and the CLI publishes from release.yml, not cli-release.yml (codebase-map, release, and runtime-apis describe the canonical starter).
• ALWAYS: Apply the single-line comment rule to new code; the CLI's existing multi-line comment blocks predate the fork and change only when the code around them does.
• ALWAYS: Load the bundled inscope self-skill from .agents/skills/inscope, a link to packages/cli/skills/inscope (the skills tables below skip links, so it is not listed there).
• ALWAYS: Keep .github/workflows/release.yml under that name: npm Trusted Publishing for inscope is bound to it. It publishes a canary when a push to canary touches packages/cli, packages/scripts, or tests, and latest once auto-release tags a version. A test version of a PR is gh workflow run release.yml -f pr=<n>, not upstream's /release comment (see CONTRIBUTING.md, Releasing).

Dashboard

• ALWAYS: Keep the dashboard read-only and local: every /api/inscope route sits behind requireLocal and stays out of next dev's /api rewrite in web/next/next.config.ts, which passes a caller's forged forwarding headers along; it returns tokens and keychain items as booleans only, and maps library results field by field. A test touching inscope state seals HOME with tests/inscope/sandbox.ts, never the developer's own, and the dashboard's e2e suites also skip without E2E_INSCOPE_SANDBOX, which tests/inscope/serve.ts sets (see CONTRIBUTING.md, Dashboard).
• ALWAYS: Read the inherited codebase-map, design, api-endpoint, and dev skills with the dashboard in mind, rather than editing them, which would stop their sync: here they also cover the (inscope) route group and components/inscope/, requireLocal as a second source of 403, inscopeConfigErrorResponses for the 422 an invalid config returns, and inscopeWorkspaceErrorResponses for the 404 an unknown workspace returns; and the navbar the dev skill points to for logging in is hidden on the dashboard's pages, / included (see Logging in (agents)).

UI

• ALWAYS: Follow the design skill for UI, styling, and design decisions (it holds the canonical conventions). Update it in the same change when a convention changes.
• ALWAYS: For any frontend or UI change, verify it in a real browser with agent-browser before opening or updating a PR; drive the actual page or flow, do not rely on type-check and lint alone. Run the end-to-end flow when the change spans it or when asked. Capture screenshots and attach them to the PR with gh pr comment --attach. See the ui-verify skill.

Commits

• Make atomic commits in the Conventional Commits format. See the gh-commit skill.
• NEVER: Include "Co-authored-by" in commit messages.

Working notes

• Write audit reports (any kind) to .github/notes/audits/ as dated files (YYYY-MM-DD-<topic>.md). Audits are transient working docs: delete one once its findings are fully addressed (shipped or consciously won't-fixed) so the directory does not accumulate stale records.
• Track planned, in-progress, and parked work in .github/notes/plans/ (an index plus one file per item), not in dated audit files or scattered across issues; issues are the inbox, folded in and closed once captured.
• A fork starts both directories itself: .github/notes/ is the starter's own working record and does not ship.

Logging in (agents)

Signs in as LocalAgent (agent@local.host). The route is gated: set AGENT_SIGNIN_ENABLED=true in .env first (it is off by default, so the route 404s without it and a deployed default env never exposes it). Then click Login (agents) in the dev UI's navbar menu (the dashboard's pages, / included, hide that navbar under next dev, so open any other path first; one that 404s shows it too), or use curl:

WEB=$(bunx portless get inscope); API=$(bunx portless get api.inscope)
curl -sS -c cookies.txt -X POST -H "Origin: $WEB" "$API/api/agents/sign-in-as"
curl -sS -b cookies.txt "$API/api/v1/user"

Local-only (needs NODE_ENV=local and AGENT_SIGNIN_ENABLED=true) and requires a trusted Origin header. See api/hono/src/routers/agents.ts if needed.

Skills

Skills live in .agents/skills (symlinked to .claude/skills and .github/skills, so every agent tool reads the same files). Each is a SKILL.md with a description trigger and a literal procedure; only the description is scanned until a skill matches. Start with codebase-map to orient, then load the task skill that fits. Custom skills are maintained in this repo; vendored skills are copied verbatim from an upstream project (re-vendor to update, do not hand-edit).

Custom

Vendored (upstream, copied verbatim)