diff --git a/.claude/skills/naming/SKILL.md b/.claude/skills/naming/SKILL.md index 6f358f839..cbed19eb4 100644 --- a/.claude/skills/naming/SKILL.md +++ b/.claude/skills/naming/SKILL.md @@ -45,6 +45,6 @@ From a module name (e.g., `my-feature`): ## Layer Order -Controllers → Services → Repositories → Models +Routes → Controllers → Services → Repositories → Models Never skip layers. Controllers must not call repositories directly. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..4cdc446f9 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,63 @@ +# Devkit Node - Copilot Instructions + +## Preflight + +- Read `ERRORS.md` before proposing changes or code reviews +- If a new recurring mistake occurs, append one line to `ERRORS.md` using `[YYYY-MM-DD] : -> ` + +## Canonical commands + +- Dev: `npm start` +- Debug: `npm run debug` +- Tests: `npm test` (watch: `npm run test:watch`) +- Coverage: `npm run test:coverage` +- Lint: `npm run lint` +- Lint fix: `npm run lint:fix` +- Seed: `npm run seed:dev` +- Commit: `npm run commit` + +## Available prompts + +Use `.github/prompts/*.prompt.md` for guided workflows: + +| Task | Prompt file | +| ---- | ----------- | +| Verify | `.github/prompts/verify.prompt.md` | +| Feature | `.github/prompts/feature.prompt.md` | +| Create module | `.github/prompts/create-module.prompt.md` | +| Update stack | `.github/prompts/update-stack.prompt.md` | +| Naming | `.github/prompts/naming.prompt.md` | + +## Always-on guardrails + +- Never commit secrets or credentials (`.env*`, `secrets/**`, keys, tokens) +- Do not introduce cross-module coupling without explicit justification +- Avoid risky renames or moves of core stack paths used by downstream merges +- Keep changes minimal and merge-friendly for downstream projects +- Flag security or mergeability risks explicitly in reviews + +## Architecture and modularity + +- Layer order is strict: **Routes → Controllers → Services → Repositories → Models** +- Controllers must not call repositories directly — always go through services +- Each module is self-contained in `modules/{name}/` +- Shared code goes in `lib/helpers/` or `lib/services/` with explicit justification +- Keep tests in `modules/*/tests/` + +## Naming conventions + +- Folders: kebab-case +- Controllers: `{module}[.{name}].controller.js` +- Services: `{module}[.{name}].service.js` +- Repositories: `{module}.repository.js` +- Models (Mongoose): `{module}.model.mongoose.js` +- Schemas: `{module}.schema.js` +- Policies: `{module}[.{name}].policy.js` +- Routes: `{module}.routes.js` +- Tests: `{module}.{type}.tests.js` + +## Definition of done + +- `npm run lint` passes +- `npm test` passes +- Cross-module impact is documented and justified when present diff --git a/.github/prompts/create-module.prompt.md b/.github/prompts/create-module.prompt.md new file mode 100644 index 000000000..d0a02e236 --- /dev/null +++ b/.github/prompts/create-module.prompt.md @@ -0,0 +1,5 @@ +# Create Module + +Full playbook: `.claude/skills/create-module/SKILL.md` + +Read `ERRORS.md` before applying changes. diff --git a/.github/prompts/feature.prompt.md b/.github/prompts/feature.prompt.md new file mode 100644 index 000000000..e48067b31 --- /dev/null +++ b/.github/prompts/feature.prompt.md @@ -0,0 +1,5 @@ +# Feature + +Full playbook: `.claude/skills/feature/SKILL.md` + +Read `ERRORS.md` before coding. diff --git a/.github/prompts/naming.prompt.md b/.github/prompts/naming.prompt.md new file mode 100644 index 000000000..7d1c09d4f --- /dev/null +++ b/.github/prompts/naming.prompt.md @@ -0,0 +1,5 @@ +# Naming + +Full playbook: `.claude/skills/naming/SKILL.md` + +Read `ERRORS.md` before proposing renames. diff --git a/.github/prompts/update-stack.prompt.md b/.github/prompts/update-stack.prompt.md new file mode 100644 index 000000000..3490ee5c1 --- /dev/null +++ b/.github/prompts/update-stack.prompt.md @@ -0,0 +1,5 @@ +# Update Stack + +Full playbook: `.claude/skills/update-stack/SKILL.md` + +Read `ERRORS.md` before merge decisions. diff --git a/.github/prompts/verify.prompt.md b/.github/prompts/verify.prompt.md new file mode 100644 index 000000000..14a31772b --- /dev/null +++ b/.github/prompts/verify.prompt.md @@ -0,0 +1,5 @@ +# Verify + +Full playbook: `.claude/skills/verify/SKILL.md` + +Read `ERRORS.md` before running. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..9f77ab8b6 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,42 @@ +## Summary + +- What changed: +- Why: +- Supersedes / Related: + +## Scope + +- Module(s) impacted: +- Cross-module impact: `none` / `yes` (if yes, justify) +- Risk level: `low` / `medium` / `high` + +## Validation + +- [ ] `npm run lint` +- [ ] `npm test` +- [ ] Manual checks done (if applicable) + +## Guardrails check + +- [ ] No secrets or credentials introduced (`.env*`, `secrets/**`, keys, tokens) +- [ ] No risky rename/move of core stack paths +- [ ] Changes remain merge-friendly for downstream projects +- [ ] Tests added or updated when behavior changed + +## Optional: Infra/Stack alignment details + +### Before vs After (key changes only) + +| Area | Before | After | Notes | +| ---- | ------ | ----- | ----- | +| | | | | + +- Upstream parity target / source: +- Automation or policy impact (CI, Dependabot, auto-merge, majors, permissions): +- Rollback plan: + +## Notes for reviewers + +- Security considerations: +- Mergeability considerations: +- Follow-up tasks (optional): diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 000000000..6c5e755a0 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,6 @@ +{ + "recommendations": [ + "github.copilot", + "github.copilot-chat" + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 000000000..ba6e793db --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,7 @@ +{ + "github.copilot.chat.codeGeneration.useInstructionFiles": true, + "github.copilot.enable": { + "javascript": true, + "markdown": true + } +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..237693298 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,33 @@ +# Devkit Node Stack - Agent Guide + +Use this guide when operating as an engineering agent in this repository. +For architecture, modularity rules, guardrails, naming, commands, and definition of done — see `CLAUDE.md`. + +## Mission + +- Keep the stack mergeable for downstream projects +- Keep changes secure and free of secrets +- Enforce module boundaries and layered architecture + +## Preflight + +- Read `ERRORS.md` before proposing changes or code reviews +- If the AI makes a new recurring mistake, append one line to `ERRORS.md` using `[YYYY-MM-DD] : -> ` + +## Codex prompt routing + +Use `.github/prompts/*` as task playbooks: + +| Task | Prompt | +| ---- | ------ | +| Verify | `.github/prompts/verify.prompt.md` | +| Feature | `.github/prompts/feature.prompt.md` | +| Create module | `.github/prompts/create-module.prompt.md` | +| Update stack | `.github/prompts/update-stack.prompt.md` | +| Naming | `.github/prompts/naming.prompt.md` | + +## Review output convention + +- `Critical`: must fix before merge (security, breakage, mergeability risk) +- `Warning`: should be reviewed (coupling, architecture drift) +- `Info`: non-blocking suggestion diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..ad99ab526 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,81 @@ +# Devkit Node Stack - Claude Code Setup + +This repository is the Node / Express / Mongoose / JWT stack from Devkit. It can run as a standalone backend or as part of a fullstack setup with companion stacks such as Vue or Swift. + +It is designed to be cloned into downstream projects and kept up-to-date through upstream merges. + +## How to use Claude Code here + +Source of truth: `README.md` + `package.json` scripts. + +The `.claude/` folder contains embedded settings, skills, and agents that are available immediately after cloning. + +## Canonical commands + +| Command | Script | Description | +| ------------- | ------------------------ | ---------------------------------------------- | +| **Dev** | `npm start` | Start dev server at `http://localhost:3000/` | +| **Debug** | `npm run debug` | Start with nodemon and inspector | +| **Test** | `npm test` | Run all tests | +| **Watch** | `npm run test:watch` | Run tests in watch mode | +| **Coverage** | `npm run test:coverage` | Generate test coverage | +| **Lint** | `npm run lint` | Check code quality | +| **Lint fix** | `npm run lint:fix` | Auto-fix linting issues | +| **Seed** | `npm run seed:dev` | Seed development database | +| **Commit** | `npm run commit` | Commit with commitizen | +| **Docker** | `docker-compose up` | Start with docker-compose | + +## Preflight + +- Read `ERRORS.md` before proposing changes or code reviews +- If the AI makes a new recurring mistake, append one line to `ERRORS.md` using `[YYYY-MM-DD] : -> ` + +## Modularity rules + +- Keep each module as independent as possible +- Avoid cross-module imports and coupling +- Layer order is strict: **Routes → Controllers → Services → Repositories → Models** +- Controllers must not call repositories directly — always go through services +- Keep config, routes, and business logic inside the module boundary (`modules/{name}/`) +- Put shared code in `lib/helpers/` or `lib/services/` only with explicit justification +- Keep tests organized per module: `modules/*/tests/` + +## Always-on guardrails + +- Never commit secrets or credentials (`.env*`, `secrets/**`, keys, tokens) +- Do not introduce cross-module coupling without explicit justification +- Avoid risky renames or moves of core stack paths used by downstream merges +- Keep changes minimal and merge-friendly for downstream projects +- Flag security or mergeability risks explicitly in reviews + +## Available embedded skills + +Use `.claude/skills/*/SKILL.md` as the primary workflow source for Claude. + +| Skill | Description | +| ---------------- | ----------------------------------------------------- | +| `/verify` | Run quality loop (lint + tests) | +| `/create-module` | Create a new module from the `tasks` template | +| `/feature` | Implement a feature while enforcing module isolation | +| `/update-stack` | Merge upstream stack updates into downstream projects | +| `/naming` | Apply or audit naming conventions | + +## Embedded agent + +- `stack-maintainer` (`.claude/agents/stack-maintainer.md`): quick review guard for mergeability, security, and modularity. + +## Stack merge workflow + +```bash +git remote add devkit-node https://github.com/pierreb-devkit/Node.git +git fetch devkit-node +git merge devkit-node/master +``` + +Resolve conflicts carefully to preserve downstream customizations and keep future merges clean. + +## Definition of done + +- `npm run lint` passes +- `npm test` passes +- Cross-module impact is documented and justified when present diff --git a/ERRORS.md b/ERRORS.md new file mode 100644 index 000000000..4d9a504ba --- /dev/null +++ b/ERRORS.md @@ -0,0 +1,13 @@ +# AI Error Log + +Use this file as a compact memory of recurring AI mistakes. + +## Rules + +- One error per line +- Keep each line actionable and specific +- Use format: `[YYYY-MM-DD] : -> ` +- Add only confirmed/recurrent mistakes and avoid duplicates + +## Entries + diff --git a/README.md b/README.md index 731712d8d..90f4c271a 100644 --- a/README.md +++ b/README.md @@ -141,19 +141,25 @@ With [Vue](https://github.com/pierreb-devkit/Vue) stack as frontend: docker-compose up ``` -## :robot: Claude Code Setup +## :robot: AI Setup -This stack ships with an embedded [Claude Code](https://claude.ai/claude-code) configuration in the `.claude/` folder — works immediately after cloning, no additional setup needed. +This stack ships preconfigured instruction and prompt files for Claude Code, GitHub Copilot, and OpenAI Codex. Each tool requires its own client installation and authentication — the repository provides the configuration so it works out-of-the-box once the tool is set up. -### Available Skills +| Tool | Config | +| ----------------- | ------------------------------------------------------------------- | +| Claude Code | `.claude/` — skills embedded, works on clone | +| GitHub Copilot | `.github/copilot-instructions.md` + `.github/prompts/` | +| OpenAI Codex | `AGENTS.md` | -| Skill | Description | -| ---------------- | -------------------------------------------------------- | -| `/verify` | Run quality loop (lint + tests) | -| `/create-module` | Create new module by duplicating the `tasks` template | -| `/feature` | Implement feature following layered architecture rules | -| `/update-stack` | Merge stack updates into downstream projects | -| `/naming` | Check or apply file and folder naming conventions | +### Claude Code — Available Skills + +| Skill | Description | +| ---------------- | ----------------------------------------------------- | +| `/verify` | Run quality loop (lint + tests) | +| `/create-module` | Create new module by duplicating the `tasks` template | +| `/feature` | Implement feature following layered architecture rules | +| `/update-stack` | Merge stack updates into downstream projects | +| `/naming` | Check or apply file and folder naming conventions | ### Layered Architecture Rules