🧭

Node Template

Agentic-Engineering-ready Node.js + PostgreSQL backend. Your map to every skill, agent, command, rule, and the PostgreSQL Architect's Handbook.

running · v0.1.0 · production · port 5005

What you have

The boilerplate ships with 23 skills, 4 agents, 19 slash commands, 7 auto-loaded rules, and the PostgreSQL Architect's Handbook — all pre-wired.

23 skills — auto-triggered templates
4 agents — read-only reviewers
19 commands — slash workflows
7 rules — auto-loaded per glob

Quick start

Fast path — one command (cross-platform)

Works on macOS, Linux, Windows, WSL, Git Bash. Pure Node, no bash required.

npm run bootstrap

The wizard prompts for DB, Redis, JWT, SMTP, S3, admin user — writes .env.local, runs install, migrate, seed, and optionally starts the server.

Manual path

npm install
cp .env.example .env.local — edit DB_USERNAME / DB_PASSWORD / JWT_SECRET. DATABASE_URL composes from DB_* via ${"$"}{VAR} expansion.
npx prisma migrate dev --name init
npx prisma db seed
npm run dev

Try the auth flow

The sample Auth module is live. Paste-and-run.

curl -X POST http://localhost:5005/api/v1/auth/register \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com","password":"supersecret","full_name":"You"}'

curl -X POST http://localhost:5005/api/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com","password":"supersecret"}'

Me — paste the token from /login

curl http://localhost:5005/api/v1/auth/me \
  -H 'authorization: Bearer <TOKEN>'

Swagger UI · raw OpenAPI JSON · /api/health

Patterns — for X, reach for Y

The boilerplate doesn't prescribe one workflow. Pick the pattern that fits the task.

New feature

Fast path: scaffold-crud-module skill generates controller, service, route, types, migration, Swagger in one shot.

Deliberate path: /research_codebase → /create_plan → /implement_plan. Human approval between plan and execution.

Bug fix

Invoke debug-issue skill for an investigation template. Pair with code-review-graph MCP's get_impact_radius to trace blast before you touch anything. Commit via /git-commit.

Refactor

Start with the refactor-safely skill — pairs impact analysis with the change plan. Always run get_impact_radius + query_graph pattern=callers_of before touching anything shared.

Review code

Run /review-pr for a full audit or /review for staged/uncommitted changes. For vulnerability scans, spawn @security-reviewer-agent — severity-ranked, read-only.

Schema / architecture

Before you code: answer the 10 Designer Questions in the handbook.

While designing: design-prisma-model skill enforces audit fields, soft-delete, naming, indexes.

For review: spawn @system-architect-agent — reviews schema, relationships, indexes, multi-tenancy, migration safety, all grounded in the handbook.

New permission

Use add-permission skill — covers the full loop: P.* constant → seed → attach to role → requirePermission(P.X) middleware → cache invalidation.

The toolbox

Every asset, one click away. Each toggle links to files on disk.

Skills — 23, auto-triggered by task match

Scaffolding

scaffold-crud-module — full CRUD in one shot
create-controller · create-service · create-route
create-background-job (BullMQ) · create-websocket-handler

Database

design-prisma-model · create-migration · seed-data
optimize-prisma-query · timezone-safe-query

Infrastructure

redis-cache-pattern · file-upload-s3
env-config-field · swagger-doc

RBAC & Review

add-permission · rbac-architecture
code-review · review-pr · review-changes
debug-issue · explore-codebase · refactor-safely

Each skill lives at .claude/skills/<name>/SKILL.md.

Agents — 4, read-only, invoked explicitly

@system-architect-agent — schema + architecture review, grounded in the PostgreSQL Architect's Handbook
@security-reviewer-agent — severity-ranked vulnerability audit
@quality-gate-agent — typecheck + prisma validate + tests + lint (runs via /pre-flight)
@test-generator-agent — finds missing test companions, generates Vitest specs

Commands — 19, slash commands

RPI workflow

/research_codebase — parallel exploration, writes thoughts/shared/research/
/create_plan — task breakdown, human approval gate
/implement_plan — one subagent per task

Quality

/pre-flight — typecheck → prisma → tests → lint → review
/review — backend review on uncommitted/staged

Session

/save_progress · /resume_work

Git helpers

/git-status · /git-branch · /git-commit · /git-push · /git-pull · /git-sync
/git-log · /git-conflicts · /git-stash · /git-undo · /git-pr · /git-help

Rules — 7, auto-loaded per file glob

backend-stack-architecture.md — request lifecycle, module map
routing-and-rbac.md — route structure, requirePermission patterns
services-and-prisma.md — service layer, Prisma conventions
testing-rules.md — Vitest patterns, mocking
environment-config.md — process.env zero-tolerance rule
mcp-graph-tools.md — when to use code-review-graph vs grep
postgres-design-mindset.md — 10 questions, 10 rules, PSQL defaults

MCP — code-review-graph — knowledge graph, structural queries

Prefer these over grep/read for codebase exploration — faster, cheaper, gives structural context.

semantic_search_nodes · query_graph — exploring code by name or pattern
get_impact_radius — blast radius of a change
detect_changes + get_review_context — code review
get_architecture_overview + list_communities — high-level shape

Configured in .mcp.json. Auto-updates via PostToolUse hook in .claude/settings.json.

Works across agent platforms

🤖 Claude Code

Primary support. Open this folder in Claude Code — skills auto-trigger, agents via @name, commands via /name.

Entry: CLAUDE.md · rules in .claude/rules/.

⚡ Codex

Codex CLI reads AGENTS.md at the repo root automatically. Same rules, different surface.

Entry: AGENTS.md.

✨ Cursor

Open the folder in Cursor — .cursor/rules/*.mdc auto-load based on file globs.

Entry: .cursor/rules/ (5 files).

Where things live

Path	What
`src/config/config.ts`	Single source of truth for env. Zero `process.env` elsewhere.
`src/db/prisma.ts`	Prisma client singleton.
`src/db/redis.ts`	Redis client + blacklist + JSON helpers.
`src/middleware/`	`authenticate`, `requirePermission`, `errorHandler`, `responseHandler`, `internalSecret`.
`src/routes/app.routes.ts`	`AppRoute` base class — extend for every feature.
`src/controller/`	Class-based controllers with `@openapi` JSDoc.
`src/services/`	Business logic, Prisma queries, flat DTOs.
`src/jobs/` · `src/workers/`	BullMQ queues and worker processors.
`src/ws/baseWebSocket.ts`	WebSocket base class (JWT handshake, per-user conn map).
`src/utils/`	`appError`, `handleResponse`, `fileUpload`, `email`, `hash`, `cacheKeys`, `dateTimezone`.
`prisma/`	Schema, migrations, seed.
`documents/postgres-architect-handbook.md`	PSQL dev reference.