ai-devcontext 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abu Hurayra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# ai-devcontext
+
+Instantly bootstrap AI coding assistant configuration into any project — `CLAUDE.md`, `claude.local.md`, `.claude/` (rules, skills, commands, agents, hooks, workflows), and `.cursor/` (rules, commands, skills, hooks).
+
+## Install
+
+```bash
+npm install -g ai-devcontext
+```
+
+Or run it once without installing:
+
+```bash
+npx ai-devcontext init
+```
+
+## Usage
+
+From the root of any project:
+
+```bash
+devcontext init
+```
+
+This copies the full template tree into your project, skipping any file that already exists, marks shell command scripts executable, and adds `claude.local.md` / `.claude/settings.local.json` to your `.gitignore`.
+
+## What gets created
+
+```
+CLAUDE.md                  Root project guide (stack, build/test/lint, conventions)
+claude.local.md            Personal, git-ignored local notes
+
+.cursor/
+├── .cursorignore
+├── cursor.json
+├── .cursorrules           Legacy fallback rules
+├── rules/                 Scoped rules (backend, UI conventions)
+├── commands/               Dev task scripts (lint, format, test, docker, db, etc.)
+├── skills/code-reviewer/
+└── hooks/after-edit.sh
+
+.claude/
+├── settings.json
+├── settings.local.json    Machine-specific, git-ignored
+├── rules/                 Architecture + security checklist
+├── skills/testing-patterns/
+├── commands/               Same dev task scripts as .cursor/commands/
+├── agents/security-scanner/
+├── hooks/after-edit.sh
+└── workflows/deployment-guide.md
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "ai-devcontext",
+  "version": "1.0.0",
+  "description": "Instantly bootstrap AI configuration templates (CLAUDE.md, .claude/, .cursor/) into any project.",
+  "type": "module",
+  "bin": {
+    "devcontext": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "templates"
+  ],
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "fs-extra": "^11.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "ai",
+    "cursor",
+    "claude",
+    "devtools",
+    "cli",
+    "templates"
+  ],
+  "author": "Abu Hurayra <abu.hurayra@sjinnovation.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abuhurayra0889/ai-devcontext-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/abuhurayra0889/ai-devcontext-cli/issues"
+  },
+  "homepage": "https://github.com/abuhurayra0889/ai-devcontext-cli#readme"
+}

package/src/index.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// ESM __dirname fix
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Files that should never be committed by the consuming project.
+const GITIGNORE_ENTRIES = ['claude.local.md', '.claude/settings.local.json'];
+
+const program = new Command();
+
+program
+  .name('devcontext')
+  .description('Bootstrap AI configuration templates into your project.')
+  .version('1.0.0');
+
+async function copyTemplateTree(srcDir, destDir, targetDir) {
+  const entries = await fs.readdir(srcDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    const relPath = path.relative(targetDir, destPath);
+
+    if (entry.isDirectory()) {
+      await copyTemplateTree(srcPath, destPath, targetDir);
+      continue;
+    }
+
+    const exists = await fs.pathExists(destPath);
+    if (exists) {
+      console.log(chalk.yellow(`  ⚠  Skipped  → ${relPath}  (already exists)`));
+      continue;
+    }
+
+    await fs.ensureDir(path.dirname(destPath));
+    await fs.copy(srcPath, destPath);
+
+    if (entry.name.endsWith('.sh')) {
+      await fs.chmod(destPath, 0o755);
+    }
+
+    console.log(chalk.green(`  ✔  Created  → ${relPath}`));
+  }
+}
+
+async function updateGitignore(targetDir) {
+  const gitignorePath = path.join(targetDir, '.gitignore');
+  const existing = (await fs.pathExists(gitignorePath))
+    ? await fs.readFile(gitignorePath, 'utf8')
+    : '';
+
+  const missing = GITIGNORE_ENTRIES.filter(
+    (entry) => !existing.split('\n').some((line) => line.trim() === entry)
+  );
+
+  if (missing.length === 0) return;
+
+  const header = existing.trim().length > 0 ? '\n\n# devcontext: local/personal AI context\n' : '# devcontext: local/personal AI context\n';
+  await fs.appendFile(gitignorePath, header + missing.join('\n') + '\n');
+  console.log(chalk.green(`  ✔  Updated  → .gitignore`));
+}
+
+program
+  .command('init')
+  .description('Copy AI context templates into the current working directory.')
+  .action(async () => {
+    const templatesDir = path.resolve(__dirname, '../templates');
+    const targetDir = process.cwd();
+
+    console.log(chalk.cyan('\n⚙  Initializing AI context templates...\n'));
+
+    try {
+      await copyTemplateTree(templatesDir, targetDir, targetDir);
+      await updateGitignore(targetDir);
+
+      console.log(chalk.bold.greenBright('\n✅  Done! AI context templates are ready.\n'));
+    } catch (err) {
+      console.error(chalk.red('\n❌  Failed to copy templates:'), err.message);
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);

package/templates/.claude/agents/security-scanner/security-scanner.md

@@ -0,0 +1,27 @@
+---
+name: security-scanner
+description: Use proactively after changes touching auth, input handling, or data access to scan for OWASP-class vulnerabilities. Runs in an isolated sandbox with read access to the diff.
+tools: Read, Grep, Glob, Bash
+---
+
+# Security Scanner Agent
+
+## Identity
+You audit code changes for security vulnerabilities. You do not fix issues yourself —
+you report findings for the calling agent or user to act on.
+
+## Scope
+- Injection risks: SQL/NoSQL, command, path traversal
+- Auth/authz: missing checks, ownership bypass, token handling
+- Secrets: hardcoded credentials, secrets in logs or error responses
+- Dependency risks: known-vulnerable packages introduced by the change
+
+## Process
+1. Read the diff or changed files provided.
+2. Cross-reference against `.claude/rules/security-checklist.md`.
+3. For each finding, report: file, line, the concrete exploit scenario, and severity.
+4. Do not report style or correctness issues outside of security — that's a different agent's job.
+
+## Boundaries
+- Read-only: never modify files
+- Never execute code from the diff being audited

package/templates/.claude/commands/clean.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Removes build artifacts and caches so the next install/build starts from a clean slate.
+set -euo pipefail
+
+rm -rf dist build coverage .turbo .next .cache node_modules/.cache
+echo "Cleaned build artifacts and caches. Run 'npm install' if node_modules was affected."

package/templates/.claude/commands/db-migrate.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Task runner invoked by name or agent intent: applies pending database migrations.
+set -euo pipefail
+
+echo "Running database migrations..."
+npm run migrate

package/templates/.claude/commands/docker-down.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Stops and removes the local Docker Compose stack.
+set -euo pipefail
+
+docker compose down

package/templates/.claude/commands/docker-up.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Builds and starts the local Docker Compose stack in the background.
+set -euo pipefail
+
+if [ ! -f "docker-compose.yml" ] && [ ! -f "compose.yml" ]; then
+  echo "No docker-compose.yml/compose.yml found in this project."
+  exit 1
+fi
+
+docker compose up -d --build
+docker compose ps

package/templates/.claude/commands/format.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Formats the codebase with Prettier (or the project's configured formatter).
+set -euo pipefail
+
+if npm run format --if-present; then
+  exit 0
+fi
+
+npx --no-install prettier --write . 2>/dev/null || echo "No formatter configured — add a 'format' script or Prettier config."

package/templates/.claude/commands/lint-fix.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Runs the linter in autofix mode.
+set -euo pipefail
+
+npm run lint --if-present -- --fix

package/templates/.claude/commands/new-resource.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Scaffolds a new REST resource: model + controller + route stub.
+# Usage: new-resource.sh <ResourceName>   e.g. new-resource.sh Invoice
+set -euo pipefail
+
+NAME="${1:-}"
+if [ -z "$NAME" ]; then
+  echo "Usage: new-resource.sh <ResourceName>"
+  exit 1
+fi
+
+LOWER="$(echo "${NAME:0:1}" | tr '[:upper:]' '[:lower:]')${NAME:1}"
+
+mkdir -p models controllers routes
+
+cat > "models/${NAME}.js" <<EOF
+import mongoose from 'mongoose';
+
+const ${LOWER}Schema = new mongoose.Schema(
+  {
+    // TODO: define fields
+  },
+  { timestamps: true }
+);
+
+export default mongoose.model('${NAME}', ${LOWER}Schema);
+EOF
+
+cat > "controllers/${LOWER}Controller.js" <<EOF
+import ${NAME} from '../models/${NAME}.js';
+
+export async function list(req, res) {
+  const items = await ${NAME}.find();
+  res.json(items);
+}
+
+export async function getById(req, res) {
+  const item = await ${NAME}.findById(req.params.id);
+  if (!item) return res.status(404).json({ error: { code: 'NOT_FOUND', message: '${NAME} not found' } });
+  res.json(item);
+}
+
+export async function create(req, res) {
+  const item = await ${NAME}.create(req.body);
+  res.status(201).json(item);
+}
+
+export async function update(req, res) {
+  const item = await ${NAME}.findByIdAndUpdate(req.params.id, req.body, { new: true });
+  if (!item) return res.status(404).json({ error: { code: 'NOT_FOUND', message: '${NAME} not found' } });
+  res.json(item);
+}
+
+export async function remove(req, res) {
+  await ${NAME}.findByIdAndDelete(req.params.id);
+  res.status(204).end();
+}
+EOF
+
+cat > "routes/${LOWER}Routes.js" <<EOF
+import { Router } from 'express';
+import * as ${LOWER}Controller from '../controllers/${LOWER}Controller.js';
+
+const router = Router();
+
+router.get('/', ${LOWER}Controller.list);
+router.get('/:id', ${LOWER}Controller.getById);
+router.post('/', ${LOWER}Controller.create);
+router.patch('/:id', ${LOWER}Controller.update);
+router.delete('/:id', ${LOWER}Controller.remove);
+
+export default router;
+EOF
+
+echo "Created models/${NAME}.js, controllers/${LOWER}Controller.js, routes/${LOWER}Routes.js"
+echo "Remember to mount the router in your app entrypoint and fill in the schema fields."

package/templates/.claude/commands/outdated-deps.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Reports outdated dependencies. Read-only — does not upgrade anything automatically.
+set -euo pipefail
+
+npm outdated || true
+echo ""
+echo "Review before upgrading — check changelogs for breaking changes, especially major bumps."

package/templates/.claude/commands/seed-db.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Seeds the local database with fixture/development data.
+set -euo pipefail
+
+npm run seed --if-present || echo "No 'seed' script defined in package.json."

package/templates/.claude/commands/test-watch.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Runs the test suite in watch mode for tight feedback loops during development.
+set -euo pipefail
+
+npm test -- --watch

package/templates/.claude/commands/typecheck.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Runs the TypeScript compiler in check-only mode, if the project uses TS.
+set -euo pipefail
+
+if [ -f "tsconfig.json" ]; then
+  npx --no-install tsc --noEmit
+else
+  echo "No tsconfig.json found — nothing to typecheck."
+fi

package/templates/.claude/hooks/after-edit.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Automated cleanup/formatting script, fired after Claude modifies a file.
+set -euo pipefail
+
+FILE="${1:-}"
+[ -z "$FILE" ] && exit 0
+
+case "$FILE" in
+  *.js|*.jsx|*.ts|*.tsx|*.json|*.css)
+    npx --no-install prettier --write "$FILE" 2>/dev/null || true
+    ;;
+esac

package/templates/.claude/rules/architectural-docs.md

@@ -0,0 +1,7 @@
+# Architectural Documentation Principles
+
+- Document decisions, not implementation — code already shows *what*; docs should explain *why*
+- Keep architecture docs close to the code they describe; prefer a short README per module over one giant doc
+- When a doc and the code disagree, the code wins — flag the doc as stale rather than trusting it blindly
+- Record trade-offs considered and rejected, not just the chosen path — future readers need to know what was ruled out and why
+- Avoid documenting anything derivable by reading the code (file layout, obvious naming) — it will rot

package/templates/.claude/rules/security-checklist.md

@@ -0,0 +1,25 @@
+# Security Checklist
+
+Run through this before finalizing any change that touches input handling, auth, or data access.
+
+## Input & Injection
+- All user input is validated/sanitized before use (never trust client data)
+- Database queries use parameterization/ODM query builders — no string-concatenated queries
+- File paths derived from user input are validated against traversal (`../`)
+- Shell commands never interpolate unsanitized user input
+
+## Auth & Access Control
+- Every endpoint checks authentication before authorization
+- Authorization checks resource ownership, not just role — a valid token isn't enough
+- Tokens/secrets are never logged, echoed in error messages, or committed to source
+
+## Data Handling
+- Secrets and credentials come from environment variables, never hardcoded
+- Sensitive fields (passwords, tokens) are hashed/encrypted at rest, never stored plaintext
+- Responses don't leak internal details (stack traces, DB errors) to the client
+
+## Dependencies
+- New dependencies are checked for maintenance status and known CVEs before adding
+- Prefer built-in APIs over adding a dependency for something trivial
+
+Flag any violation explicitly with a `⚠️ Security:` prefix rather than silently fixing or ignoring it.

package/templates/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run *)",
+      "Bash(npm test)",
+      "Bash(git status)",
+      "Bash(git diff*)",
+      "Bash(git log*)"
+    ],
+    "deny": [
+      "Bash(git push --force*)",
+      "Bash(rm -rf *)"
+    ]
+  }
+}

package/templates/.claude/settings.local.json

@@ -0,0 +1,5 @@
+{
+  "permissions": {
+    "allow": []
+  }
+}

package/templates/.claude/skills/testing-patterns/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: testing-patterns
+description: Conventions for writing and running tests in this project — use when adding or modifying tests.
+---
+
+# Testing Patterns
+
+## When to use
+When writing new tests, fixing failing tests, or asked to add test coverage.
+
+## Conventions
+- Test files live next to the code they test, or under a mirrored `__tests__`/`test` directory — match whatever the repo already does
+- One behavior per test; test names describe the behavior, not the implementation
+- Use real dependencies where feasible; mock only true external boundaries (network, third-party APIs, time)
+- Cover the golden path plus the edge cases that actually matter for this code — not exhaustive permutations
+- A failing test must fail for the reason it claims to — verify by temporarily breaking the code under test
+
+## Running tests
+```bash
+npm test              # full suite
+npm test -- <pattern>  # filtered run
+```

package/templates/.claude/workflows/deployment-guide.md

@@ -0,0 +1,13 @@
+# Deployment Guide
+
+Strict, chronological steps for shipping a release. Do not reorder or skip steps.
+
+1. Confirm `main` is green in CI (build, lint, test all passing)
+2. Bump the version (`npm version <patch|minor|major>`)
+3. Update the changelog with user-facing changes since the last release
+4. Push the version commit and tag: `git push && git push --tags`
+5. Confirm the release workflow in GitHub Actions builds and pushes the Docker image
+6. Deploy to staging first; run smoke tests against staging
+7. Promote staging to production
+8. Watch error/latency dashboards for 15 minutes post-deploy before considering the deploy complete
+9. If anything regresses, roll back immediately rather than attempting a forward fix under pressure

package/templates/.cursor/.cursorignore

@@ -0,0 +1,12 @@
+node_modules/
+dist/
+build/
+coverage/
+.next/
+.turbo/
+*.log
+.env
+.env.*
+*.lock
+*.min.js
+*.map

package/templates/.cursor/.cursorrules

@@ -0,0 +1,24 @@
+# Cursor AI Rules (legacy fallback — prefer .cursor/rules/*.mdc)
+
+## Project Philosophy
+- Write clean, readable, and maintainable code above all else.
+- Prefer explicit over implicit; avoid magic unless well-documented.
+- Follow SOLID principles and separation of concerns.
+
+## Code Style
+- Use `async/await` — never raw `.then()/.catch()` chains
+- Always destructure imports: `import { foo } from 'bar'`
+- Prefer `const` > `let`; never use `var`
+- File names: `kebab-case.js`, component names: `PascalCase.jsx`
+- Max function length: ~40 lines. Extract if longer.
+
+## Error Handling
+- All async functions must have a `try/catch` block
+- Never silently swallow errors — always log or rethrow
+- Use structured error objects: `{ code, message, details }`
+
+## AI Behavior
+- Do not generate commented-out code
+- Do not add unnecessary boilerplate or placeholder TODO blocks
+- When refactoring, touch only the requested scope
+- Always suggest the simplest solution first

package/templates/.cursor/commands/build-and-test.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# AI-invokable task: install, lint, test, and build in one pass.
+set -euo pipefail
+
+npm install
+npm run lint
+npm test
+npm run build

package/templates/.cursor/commands/clean.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Removes build artifacts and caches so the next install/build starts from a clean slate.
+set -euo pipefail
+
+rm -rf dist build coverage .turbo .next .cache node_modules/.cache
+echo "Cleaned build artifacts and caches. Run 'npm install' if node_modules was affected."

package/templates/.cursor/commands/docker-down.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Stops and removes the local Docker Compose stack.
+set -euo pipefail
+
+docker compose down

package/templates/.cursor/commands/docker-up.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Builds and starts the local Docker Compose stack in the background.
+set -euo pipefail
+
+if [ ! -f "docker-compose.yml" ] && [ ! -f "compose.yml" ]; then
+  echo "No docker-compose.yml/compose.yml found in this project."
+  exit 1
+fi
+
+docker compose up -d --build
+docker compose ps

package/templates/.cursor/commands/format.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Formats the codebase with Prettier (or the project's configured formatter).
+set -euo pipefail
+
+if npm run format --if-present; then
+  exit 0
+fi
+
+npx --no-install prettier --write . 2>/dev/null || echo "No formatter configured — add a 'format' script or Prettier config."

package/templates/.cursor/commands/lint-fix.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Runs the linter in autofix mode.
+set -euo pipefail
+
+npm run lint --if-present -- --fix

package/templates/.cursor/commands/new-resource.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Scaffolds a new REST resource: model + controller + route stub.
+# Usage: new-resource.sh <ResourceName>   e.g. new-resource.sh Invoice
+set -euo pipefail
+
+NAME="${1:-}"
+if [ -z "$NAME" ]; then
+  echo "Usage: new-resource.sh <ResourceName>"
+  exit 1
+fi
+
+LOWER="$(echo "${NAME:0:1}" | tr '[:upper:]' '[:lower:]')${NAME:1}"
+
+mkdir -p models controllers routes
+
+cat > "models/${NAME}.js" <<EOF
+import mongoose from 'mongoose';
+
+const ${LOWER}Schema = new mongoose.Schema(
+  {
+    // TODO: define fields
+  },
+  { timestamps: true }
+);
+
+export default mongoose.model('${NAME}', ${LOWER}Schema);
+EOF
+
+cat > "controllers/${LOWER}Controller.js" <<EOF
+import ${NAME} from '../models/${NAME}.js';
+
+export async function list(req, res) {
+  const items = await ${NAME}.find();
+  res.json(items);
+}
+
+export async function getById(req, res) {
+  const item = await ${NAME}.findById(req.params.id);
+  if (!item) return res.status(404).json({ error: { code: 'NOT_FOUND', message: '${NAME} not found' } });
+  res.json(item);
+}
+
+export async function create(req, res) {
+  const item = await ${NAME}.create(req.body);
+  res.status(201).json(item);
+}
+
+export async function update(req, res) {
+  const item = await ${NAME}.findByIdAndUpdate(req.params.id, req.body, { new: true });
+  if (!item) return res.status(404).json({ error: { code: 'NOT_FOUND', message: '${NAME} not found' } });
+  res.json(item);
+}
+
+export async function remove(req, res) {
+  await ${NAME}.findByIdAndDelete(req.params.id);
+  res.status(204).end();
+}
+EOF
+
+cat > "routes/${LOWER}Routes.js" <<EOF
+import { Router } from 'express';
+import * as ${LOWER}Controller from '../controllers/${LOWER}Controller.js';
+
+const router = Router();
+
+router.get('/', ${LOWER}Controller.list);
+router.get('/:id', ${LOWER}Controller.getById);
+router.post('/', ${LOWER}Controller.create);
+router.patch('/:id', ${LOWER}Controller.update);
+router.delete('/:id', ${LOWER}Controller.remove);
+
+export default router;
+EOF
+
+echo "Created models/${NAME}.js, controllers/${LOWER}Controller.js, routes/${LOWER}Routes.js"
+echo "Remember to mount the router in your app entrypoint and fill in the schema fields."

package/templates/.cursor/commands/outdated-deps.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Reports outdated dependencies. Read-only — does not upgrade anything automatically.
+set -euo pipefail
+
+npm outdated || true
+echo ""
+echo "Review before upgrading — check changelogs for breaking changes, especially major bumps."

package/templates/.cursor/commands/seed-db.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Seeds the local database with fixture/development data.
+set -euo pipefail
+
+npm run seed --if-present || echo "No 'seed' script defined in package.json."

package/templates/.cursor/commands/test-watch.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Runs the test suite in watch mode for tight feedback loops during development.
+set -euo pipefail
+
+npm test -- --watch

package/templates/.cursor/commands/typecheck.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Runs the TypeScript compiler in check-only mode, if the project uses TS.
+set -euo pipefail
+
+if [ -f "tsconfig.json" ]; then
+  npx --no-install tsc --noEmit
+else
+  echo "No tsconfig.json found — nothing to typecheck."
+fi

package/templates/.cursor/cursor.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://cursor.sh/schema/cursor.json",
+  "rules": {
+    "directory": ".cursor/rules"
+  },
+  "editor": {
+    "formatOnSave": true
+  }
+}

package/templates/.cursor/hooks/after-edit.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Fires automatically after the AI modifies a file.
+# Keep this fast — it runs synchronously in the edit loop.
+set -euo pipefail
+
+FILE="${1:-}"
+[ -z "$FILE" ] && exit 0
+
+case "$FILE" in
+  *.js|*.jsx|*.ts|*.tsx)
+    npx --no-install prettier --write "$FILE" 2>/dev/null || true
+    ;;
+esac

package/templates/.cursor/rules/backend-rules.mdc

@@ -0,0 +1,19 @@
+---
+description: Backend/API conventions
+globs:
+  - "server/**/*"
+  - "backend/**/*"
+  - "**/controllers/**/*"
+  - "**/routes/**/*"
+  - "**/models/**/*"
+alwaysApply: false
+---
+
+# Backend Rules
+
+- API routes follow REST conventions: `GET /api/resource`, `POST /api/resource`, `PATCH /api/resource/:id`
+- Controllers stay thin — business logic lives in services, not route handlers
+- Every route handler validates input before touching the database
+- Never trust client-supplied IDs for authorization — always check ownership server-side
+- Return consistent error shapes: `{ error: { code, message } }`
+- Log errors with enough context to reproduce (request id, user id, input shape) — never log secrets

package/templates/.cursor/rules/ui-conventions.md

@@ -0,0 +1,8 @@
+# UI Conventions (applies globally to frontend assets)
+
+- Components are function components using hooks — no class components
+- Co-locate component styles: `Button.jsx` + `Button.module.css`
+- Keep components under ~150 lines; extract subcomponents or hooks when larger
+- Derive state where possible instead of syncing it with `useEffect`
+- Accessibility is not optional: interactive elements need proper roles, labels, and keyboard support
+- Avoid inline styles except for values computed at runtime

package/templates/.cursor/skills/code-reviewer/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: code-reviewer
+description: Reviews a diff for correctness bugs, security issues, and unnecessary complexity before it's committed.
+---
+
+# Code Reviewer
+
+## When to use
+Invoke before committing or opening a PR, or when explicitly asked to review changes.
+
+## Steps
+1. Get the diff (`git diff` for unstaged, `git diff --staged` for staged).
+2. Check correctness: does the change do what it claims, including edge cases?
+3. Check security: input validation, auth checks, injection risks (see `.claude/rules/security-checklist.md` if present).
+4. Check scope: does the diff touch only what's needed, or drag in unrelated changes?
+5. Report findings ranked by severity. Don't restate the diff — only flag actionable issues.

package/templates/CLAUDE.md

@@ -0,0 +1,46 @@
+# Project Context
+
+## Role
+You are a senior full-stack engineer working within this codebase.
+Your primary goals are correctness, simplicity, and developer ergonomics.
+
+## Stack
+<!-- Replace with your actual stack. Example (MERN): -->
+- **Frontend:** React 18 SPA, Vite bundler, TailwindCSS
+- **Backend:** Node.js + Express REST API, ES Modules
+- **Database:** MongoDB Atlas, Mongoose schemas
+- **Auth:** JWT access tokens (15min) + HTTP-only refresh tokens (7d)
+- **Deployment:** Docker + GitHub Actions CI/CD
+
+## Build, Test, Lint
+```bash
+npm install       # install dependencies
+npm run dev       # start local dev server
+npm test          # run test suite
+npm run lint      # run linter
+npm run build     # production build
+```
+
+## Coding Conventions
+- Match the existing code style in the file you're editing over any generic default
+- Prefer small, focused functions and modules over large ones
+- Keep naming consistent with surrounding code (case style, verb/noun patterns)
+- Validate configuration and environment variables at startup, not at point of use
+- Don't introduce new dependencies when the standard library or an existing dependency covers the need
+
+## Response Guidelines
+- Respond with working code, not pseudocode
+- When modifying existing files, show only the changed diff, not the entire file
+- If a request is ambiguous, ask one clarifying question before proceeding
+- Flag security risks explicitly with a `⚠️ Security:` prefix
+- Prefer built-in APIs over adding new dependencies
+
+## Out of Scope
+- Do not suggest switching the core stack unless a critical flaw is identified
+- Do not refactor unrelated code in the same response
+- Do not generate files containing real secrets or credentials
+
+## See Also
+- [.claude/rules/](.claude/rules/) — additional context-injected rules (architecture, security)
+- [.claude/workflows/deployment-guide.md](.claude/workflows/deployment-guide.md) — deployment procedure
+- `claude.local.md` — your personal, git-ignored local notes (not committed)

package/templates/claude.local.md

@@ -0,0 +1,11 @@
+# Local Notes (git-ignored)
+
+Personal, machine-specific context for working with Claude Code on this project.
+This file is not committed — use it for scratch notes, WIP context, or preferences
+you don't want to impose on the rest of the team.
+
+## Examples of what to put here
+- Local environment quirks (ports, service URLs, test accounts)
+- In-progress investigation notes
+- Personal shortcuts or aliases you want Claude to know about
+- Anything from CLAUDE.md you want to temporarily override for yourself