add Claude Code support alongside Codex

AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-This repository is a Node.js backend template maintained for human developers and Codex.
+This repository is a Node.js backend template maintained for human developers and AI coding agents (Codex, Claude Code, Cursor, and others).
 
 ## Read this first
 
@@ -45,6 +45,7 @@ A task is complete only when:
 - Active execution plans: `docs/exec-plans/active/`
 - Completed execution plans: `docs/exec-plans/completed/`
 - Codex project config: `.codex/`
+- Claude Code project config: `CLAUDE.md`
 - Database migrations: `migrations/`
 - Worktree/bootstrap helpers: `scripts/`
 

CLAUDE.md

@@ -0,0 +1,95 @@
+# CLAUDE.md
+
+Project instructions for Claude Code. Read this before making any changes.
+
+## What this is
+
+A Node.js backend template with a harness-engineering overlay for AI coding agents. See `AGENTS.md` for the full operational contract.
+
+## Bootstrap
+
+```sh
+npm ci || npm install
+npm run worktree:bootstrap   # if working in a worktree
+npm run dev:stack:up          # when you need DB, Redis, or observability
+```
+
+## Verify before declaring done
+
+```sh
+npm run verify
+```
+
+This runs: lint, format check, architecture inventory, docs validation, quality score, tests, and smoke tests.
+
+## Key commands
+
+| Task              | Command                                  |
+| ----------------- | ---------------------------------------- |
+| Start dev server  | `npm run start:dev`                      |
+| Run tests         | `npm run test`                           |
+| Smoke test        | `npm run test:smoke`                     |
+| Lint + fix        | `npm run lint:fix`                       |
+| Format            | `npm run format`                         |
+| New migration     | `npm run migration:new -- --name=<slug>` |
+| Run migrations    | `npm run migrate`                        |
+| Migration status  | `npm run migrate:status`                 |
+| Check plan claims | `npm run claim:check`                    |
+| Start local stack | `npm run dev:stack:up`                   |
+| Stop local stack  | `npm run dev:stack:down`                 |
+| Quality score     | `npm run quality:score`                  |
+
+## Project structure
+
+```
+bin/www           → entry point (clustering)
+init.js           → master process init (DB bootstrap, cron)
+app.js            → Express app setup
+config/           → DB, env loading, migrations, startup guard
+models/           → Sequelize models
+migrations/       → Umzug schema migrations
+middleware/       → auth, validation, rate limiting, errors
+routes/v1/        → versioned API routes
+controllers/v1/   → request handlers
+service/v1/       → business logic + workflow engine
+helper/           → auth, casbin, cron, mail, SMS, PDF, uploads
+utils/            → constants, formatters, pagination, time
+scripts/          → bootstrap, verification, plan helpers
+docs/             → architecture, workflow, quality, security docs
+```
+
+## Request flow
+
+```
+bin/www → init.js → app.js → middleware → routes → controllers → services → models → DB
+```
+
+## Rules
+
+- Read files before changing them.
+- Keep changes small and verifiable.
+- Extend existing patterns — don't create parallel ones.
+- Use the existing bootstrap/startup flow (`bin/www` → `init.js` → `app.js`).
+- Use the built-in Umzug migration system for schema changes. Don't add alternate migration tools.
+- Use canonical integrations (see `AGENTS.md`) — don't introduce parallel libraries for uploads, SMS, mail, PDF, or pagination.
+- Don't delete template features unless explicitly asked.
+- Update docs when architecture or behavior changes.
+- For multi-agent work: check `docs/exec-plans/active/`, run `npm run claim:check`, respect existing claims.
+
+## Environment
+
+- `.env.development` — default local config
+- `.env.worktree` — worktree-specific overrides (auto-generated by bootstrap)
+- `.env.local` — personal overrides (gitignored)
+- Priority: `.env.local` > `.env.worktree` > `.env.{NODE_ENV}`
+
+## DB safety
+
+- `init.js` guards DB bootstrap — only runs against worktree-local DB unless `ALLOW_NON_LOCAL_STARTUP_DB_BOOTSTRAP=true`.
+- Use `SKIP_STARTUP_MIGRATIONS=true` for local tasks that don't need DB.
+
+## Testing
+
+- Framework: Mocha + Supertest
+- Test files: `test/**/*.test.js`
+- Always run `npm run test` before committing.

docs/ARCHITECTURE.md

@@ -10,9 +10,10 @@ Process bootstrap -> Environment loading -> Optional instrumentation -> Request
 
 ## Harness-engineering overlay
 
-The repository also includes a repo-native operating layer designed for Codex and other coding agents:
+The repository also includes a repo-native operating layer designed for AI coding agents (Codex, Claude Code, and others):
 
-- `AGENTS.md`: short operational contract for agents.
+- `AGENTS.md`: short operational contract for all agents.
+- `CLAUDE.md`: project instructions for Claude Code.
 - `docs/`: versioned system of record for architecture, workflow, quality, reliability, and security.
 - `docs/MIGRATIONS.md`: canonical schema-change workflow for downstream projects.
 - `docs/OBSERVABILITY.md`: local logs, metrics, traces, and query workflows.
@@ -37,4 +38,4 @@ Application code and repo operations are separate concerns:
 - Stateful business workflows can be implemented in `service/v1/` with Sequelize models backing assignment, workflow action, and escalation rules.
 - Agent operating guidance lives in repo-root docs and scripts.
 
-This keeps the backend template usable for normal development while making the repository legible to Codex.
+This keeps the backend template usable for normal development while making the repository legible to AI coding agents.

docs/WORKFLOW.md

@@ -23,6 +23,18 @@
 9. Use `npm run migration:new -- --name=<slug>` for schema changes. Master startup bootstraps models and applies pending migrations through the built-in migrator only when the DB target matches the expected worktree-local stack or `ALLOW_NON_LOCAL_STARTUP_DB_BOOTSTRAP=true` is set for an intentional deployment-style environment. For local non-DB tasks, agents may temporarily use `SKIP_STARTUP_MIGRATIONS=true` to bypass the startup bootstrap path. Do not add a second migration tool or alternate startup path.
 10. Run `npm run verify` before review or merge.
 
+## Claude Code workflow
+
+1. Open the repo directory in Claude Code (`claude` CLI).
+2. Claude Code reads `CLAUDE.md` automatically for project-specific instructions.
+3. For isolated work, use Claude Code's built-in worktree support or create one manually.
+4. Run `npm run worktree:bootstrap` in each new worktree.
+5. Use `npm run dev:stack:up` when the task needs local DB, Redis, or observability services.
+6. Run `npm run claim:check` and use active execution plans in `docs/exec-plans/active/` for medium or large tasks. Respect any existing claim that overlaps your intended scope.
+7. Use `npm run migration:new -- --name=<slug>` for schema changes. The same DB guard and migration rules from the Codex workflow apply.
+8. Run `npm run verify` before declaring work done.
+9. Use `/commit` to commit changes following project conventions.
+
 ## Worktree workflow
 
 ```sh