// Use the first time an agent (or human) opens this repo. Installs deps, prepares the env, validates that the dev environment works, and points the agent at the right files.
| name | onboard-an-agent |
| description | Use the first time an agent (or human) opens this repo. Installs deps, prepares the env, validates that the dev environment works, and points the agent at the right files. |
Use this skill the very first time you open this repo. Five minutes from clone to "dev server running, tests green, ready to ship features."
node --version # must be >= 22
which psql # Postgres client should be installed
pg_isready # Postgres should be running
git --version
If Postgres isn't running locally, install it (brew install postgresql@16 && brew services start postgresql@16 on macOS) or point DATABASE_URL at a remote instance later.
npm install
This installs Node packages and wires up Lefthook (prepare script). After this, git commit will run the full pre-commit pipeline.
cp example.env .env
Open .env and confirm DATABASE_URL matches your local (or remote) Postgres. The default points to postgresql://postgres:postgres@localhost:5432/agentic_react_express_ts.
npm run db:setup # runs `prisma migrate dev` + `prisma generate`
npm run db:seed # loads demo CRM data
If db:setup errors, the most common causes are: wrong port, wrong user/password, or Postgres not running. Fix DATABASE_URL and retry — do NOT delete the migrations directory.
npm run typecheck # zero errors
npm run lint # zero warnings
npm run test:run # all pass
npm run build # production build succeeds
All four must pass before touching application code. If something fails, do not start coding — debug the failure first. The guardrails are the whole point.
npm run dev
Open http://localhost:3000. You should see the homepage, then Contacts/Tasks/Projects with seeded data.
AGENTS.md — conventions, stack, scriptsskills/add-resource/SKILL.md — how to add a new CRUD resourceskills/self-correcting-loop/SKILL.md — what to do when a commit is rejectedYou're done. Pick a task and start building.
| Symptom | Fix |
|---|---|
npm install fails with peer dep errors | Confirm Node >= 22 (nvm use) |
prisma migrate dev says "Can't reach database" | Check Postgres is running, DATABASE_URL matches |
npm run dev shows blank page | Check the server (:3001) is up. Browser DevTools → Network → look at /trpc/… calls |
| Pre-commit fails on a fresh clone | The guardrails work — read self-correcting-loop |
Use when adding a new full-stack CRUD resource (e.g. "add a Comments resource"). Walks through Prisma model, Zod schema, tRPC router, and React page in order. Mirrors the patterns already used by Contact/Task/Project.
Use before pushing to a deployed environment (staging or prod). Walks through env vars, migrations, secrets, build, and rollback prep.
Use when starting a real project from this template. Removes the CRM demo (Contact/Task/Project) cleanly so the repo is a blank slate without breaking guardrails.
Use on every commit. The pre-commit hooks run checks in parallel. If any fail, read ALL errors, fix them in one pass, and retry. NEVER use --no-verify.