Agent Guide
| As of | |
|---|---|
| Version | 1.9.0 |
| Kind | guidance |
| Length | 1,522 words, about 7 min |
| Tags | ai-codingagentgatewayagent-guidancerlssupabasedrizzleapireactprettier |
The vault is content/docs/, in this repo. A change and the docs it makes false land in the same PR. Start with a narrow note for the task; do not load the entire vault.
Working with Pratik
Pratik builds Sidekick to learn full-stack development. The goal is to build fast without vibe coding: Pratik must know what is in the product, how it works and why. This applies to every session, whatever the task.
- Default: one explained piece at a time. Hand over a small piece of implementation (one function, one migration, one config block, one test file). Below it, explain what it does and why: the concept, how it fits Sidekick, and the alternatives you rejected. Then discuss it with Pratik. It's final only when Pratik agrees, and only then do you move on to the next piece. Explain in the most depth for:
- Supabase and Drizzle
- authentication
- repo setup
- DevOps and CI/CD
- Next.js, Tiptap and Mantine
- AI, RAG and the Vercel AI SDK
- hosting
- Pratik writes it when Pratik calls a piece core functionality, an important concept or something new to them. Teach instead of writing it: explain, let Pratik design and write it, then review. When Pratik is stuck, give the smallest hint first (a question, then a pointer, then a fragment), and the full answer only when asked.
- You code it only when Pratik asks, for work with no learning payoff, such as a presentational React component with CSS Modules. Say briefly what changed. Standing choice (Pratik, 2026-11-06): you write the
@sidekick/uicomponents and Pratik reviews them (Native UI). - Never: large unexplained changes, several pieces at once, or code landing in the repo before Pratik has agreed to it. Pratik picks the mode for each piece and can switch at any time. Plans may suggest which steps are worth writing yourself.
Where things stand
- Complete: Phases 0, 1 and 1.1, Front Door (walkthrough in Front Door: Hardening Walkthrough) and Phase 2 — Gatekeeper (walkthrough in Gatekeeper Walkthrough). Every API route goes through
withApiGuard(@sidekick/core/api);ALL_FEATURESis still empty, so no feature is granted yet. - Next: Phase 3 — Synergy, planned as lessons for part 3a (the store and its API), next lesson 4. Lesson 0 (one repo) is complete: the vault, the writings and the public site live in this repo, and arkive.blog is served by the Cloudflare Worker
sidekick-www. Lesson 1 (layer folders) is complete:core,uiandcopylive inpackages/foundation/, the empty@sidekick/synergyinpackages/platform/synergy, and lint fails a package in no layer. Lesson 2 (per-package migrations) is complete: each package that owns tables has its own Drizzle config and migrations table,db:migrateruns them in dependency order,pnpm test:integrationbuilds one database from every package's migrations, and@sidekick/test-utilsholds shared test helpers. Lesson 3 (entity index) is complete: Synergy'sentity_indexandversion_logwith RLS onuser_idonly, strict restore, the per-user lock throughwithUserLock(lint rulerequire-user-lock), and the repository'sregisterEntity,saveEntityContentandgetEntity; every table names its delete model. Part 3b is planned at Checkpoint 3a. Deferred follow-ups are in Backlogged / Unplanned (B6–B8 from Phase 2, B10 and B12 from lesson 0, B13 from lesson 3). - Toolchain: Node 24 (
.nvmrc24,engines.node24.x,engineStrict), pnpm 12 through Corepack, TypeScript 6.0 (held below 6.1), ESLint 10 flat config witheslint-plugin-import-xandeslint-plugin-boundaries7, Next.js 16, Vitest, PostgreSQL 17 in tests and CI. The public site (apps/www) is Astro 7, deployed with Wrangler 4 as a Cloudflare Worker. - Packages by layer: foundation in
packages/foundation/*, platform inpackages/platform/*, features inpackages/features/*(none exist yet; the workspace glob is already there). The registry,eslint-plugin-sidekick,opsandtest-utilsare singletons at the root ofpackages/. A package anywhere else failspnpm lint.
Commands
pnpm dev
pnpm build
pnpm lint
pnpm typecheck
pnpm format
pnpm prettier:check
pnpm test
pnpm test:integration
pnpm db:generate
pnpm db:migrate
pnpm ops:entitlements:grant --email <email> --all [--apply]db:generate, db:migrate and ops:* need the root .env.local; only the root scripts load it, and Turbo passes DATABASE_DIRECT_URL through to the db:* tasks. db:migrate runs each package's migrations in dependency order (core first). Generate one package's migration with pnpm db:generate --filter=<package> -- --custom --name=<name>. ops:* scripts print a plan and write only with --apply. Never commit secrets. test:integration builds one throwaway PostgreSQL 17 from every package's migrations and runs each package's integration tests against it; it needs the tools installed locally and is never cached.
Always true
- Do not invent product scope. Read the relevant PRD and phase note first.
- Preserve dependency direction (dependency flow): apps, the registry, features, platform and foundation, top to bottom; a layer may import any layer below it, never one above it or a sibling in its own layer, and packages never import apps. Platform packages never import each other.
packages/ops(privileged scripts) may import the registry, platform and foundation, and nothing may import it. The public site (apps/www) may import foundation exceptcore, and nothing imports it (D258).pnpm lintenforces it. - Mutations stay in the API layer. Every App Router route handler is wrapped in
withApiGuard(lint rulerequire-api-guard); Server Actions, the Pages Router and custompageExtensionsare banned. - Shared SQL functions are public API. Every package that owns tables has its own migrations and its own migrations table (
drizzle.__drizzle_migrations_<package>), but a trigger or function another package binds (core's soft-delete functions) is a contract: change it only in a way every caller survives.CREATE OR REPLACEchanges it for every package at once, with no error (Migration). - User-data queries go through
withRLS, the only public database entry point. Raw Drizzle and admin Supabase clients are server-only and lint-restricted to the wrappers that need them. The one privileged path ispackages/ops'swithPrivilegedDb(DATABASE_DIRECT_URL, bypasses RLS), for dev seeds, provisioning and break-glass scripts only. - Syncable entities use client-generated IDs and soft deletes; APIs are idempotent.
- User-visible copy belongs in
packages/copyuntil lesson I1, then in each package's catalog (Internationalization).@sidekick/uiholds no words: labels are props. - Project vocabulary lives in
content/docs/07-glossary/, one page per term (D226). When a skill asks forCONTEXT.md, write or update the glossary page instead; never create aCONTEXT.md. apps/wwwis temporary (Public site, D256): favour speed there. No CSS modules, no i18n, no extra strictness, and don't propose App-grade structure or tests for it. What still binds: the privacy and datum gates,publish: true, no URL changes, thesiteboundaries element, Prettier and green CI. Its replacement follows every rule.- UI is native first (D255): use the platform (
dialog,popover,details, native inputs and validation) before any library; Mantine leaves the App in lesson M1, so add no new Mantine component. - Prefer Server Components; use Client Components only for necessary interactivity.
How changes land
mainaccepts changes only through a branch and pull request. The CIchecksjob (prettier:check,lint,typecheck,build,test,test:integration) must pass; merges are squash-only.- Branch names say what the change is (Pratik, 2026-11-14):
<type>/<scope>/<description>, lowercase kebab-case, with the scope left out when the change has none. The type is a Conventional Commits type, the same word that starts the squash-merge title:feat,fix,refactor,docs,test,chore,ci,buildorperf. The scope is the package or area (synergy,core,www,vault). For examplefeat/synergy/entity-index,fix/core/rls-empty-setting,docs/synergy/lesson-3-close-out,chore/sql-prettier-formatting. When a tool or session assigns the branch name, use it, and give the PR a title in the same form. - Husky + lint-staged run Prettier on staged files before each commit.
- Renovate opens dependency PRs every Monday: minor and patch grouped and auto-merged on green
checks, majors one PR each for review (Dependency Dashboard). Do not hand-bump whatrenovate.jsonholds back: Node is never updated by Renovate,@types/nodestays on 24.x, TypeScript stays below 6.1.
Verify the way it really runs
- After a toolchain or config change, bypass Turbo's cache (
pnpm turbo build --force, likewiselint,typecheck). A cached result hid a TypeScript 6 build failure; CI has no cache. - Probe a lint rule through
pnpm lint, which runs ESLint from inside each package, not from the repo root. Boundaries enforced nothing untilboundaries/root-pathwas set, while root-level probes passed. - Prove a guard by watching it fail. The RLS proof caught
max_pipeline: 0breaking every transaction; onlyprepare: falsestays in the pooler config.
At the end of a phase
Everything about a phase lives in its folder under 04-phases/, named by number and nickname (03-synergy/): 00-plan.md, 02-walkthrough.md, 03-notes.md, and one lessons/lesson-N-slug/ folder per lesson holding 00-brief.md, 01-walkthrough.md and 02-notes.md. The number prefixes set the order in the site's folder view and don't appear in URLs. Write the step-by-step walkthrough, mark the plan note complete, and record learnings in notes.md (private, publish: false).
Read the smallest relevant guidance
| Task | Read first |
|---|---|
| Product scope / feature work | content/docs/04-phases/living-plan.md |
| API, database, or security | content/docs/08-ai-coding-harness/database-and-security.md |
| Tooling or package layout | content/docs/08-ai-coding-harness/architecture-invariants.md |
| Environment or commands | content/docs/08-ai-coding-harness/commands-and-environment.md |
| Why a rule exists, or what was decided | content/docs/06-decisions/log.md |
| AI, context, or RAG | Context Assembler → tiered context → RAG |
For an unfamiliar cross-cutting task, use the tag taxonomy to select notes before reading broadly.
When a document disagrees with code, identify and resolve the discrepancy before expanding the implementation. Update the vault note with a changed version when its contract changes.