Merge pull request #3165 from pierreb-devkit/docs/condense-ai-instruction-files

docs(ai): condense AI instruction files, remove duplication

Author: PierreBrisorgueil

.claude/agents/stack-maintainer.md

@@ -41,10 +41,3 @@ You are the stack maintainer agent. Your role is to protect the mergeability and
 - Don't write code
 - Keep reviews short and focused
 
-## Example review
-
-```
-🔴 Critical: `.env` file was modified (should be git-ignored)
-🟡 Warning: Controller imports repository directly — must go through service layer
-🟢 Info: Consider extracting this validation schema to `lib/helpers/joi.js` for reuse
-```

.github/copilot-instructions.md

@@ -7,16 +7,7 @@
 
 ## Canonical commands
 
-- Dev: `npm start` (alias: `npm run dev`)
-- Debug: `npm run debug`
-- Tests: `npm test` / `npm run test:unit` (one-shot) or `npm run test:watch` (watch)
-- Coverage: `npm run test:coverage`
-- Lint: `npm run lint`
-- Lint fix: `npm run lint:fix`
-- Format: `npm run format`
-- Seed: `npm run seed:dev`
-- Commit: `npm run commit`
-- Release (CI): `npm run release:auto`
+Scripts: see `package.json` → `scripts` section.
 
 ## Available prompts
 

AGENTS.md

@@ -9,11 +9,6 @@ For architecture, modularity rules, guardrails, naming, commands, and definition
 - 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] <scope>: <wrong> -> <right>`
-
 ## Codex prompt routing
 
 Use `.github/prompts/*` as task playbooks:
@@ -27,8 +22,3 @@ Use `.github/prompts/*` as task playbooks:
 | Naming | `.github/prompts/naming.prompt.md` |
 | PR | `.github/prompts/pull-request.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

CLAUDE.md

@@ -12,24 +12,7 @@ The `.claude/` folder contains embedded settings, skills, and agents that are av
 
 ## Canonical commands
 
-| Command          | Script                   | Description                                    |
-| ---------------- | ------------------------ | ---------------------------------------------- |
-| **Dev**          | `npm start`              | Start dev server at `http://localhost:3000/`   |
-| **Dev (alias)**  | `npm run dev`            | Alias for `npm start`                          |
-| **Debug**        | `npm run debug`          | Start with nodemon and inspector               |
-| **Prod**         | `npm run prod`           | Start in production mode                       |
-| **Test**         | `npm test`               | Run all tests (one-shot)                       |
-| **Unit test**    | `npm run test:unit`      | Run unit tests once (alias of `npm test`)      |
-| **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                        |
-| **Format**       | `npm run format`         | Format with Prettier                           |
-| **Seed**         | `npm run seed:dev`       | Seed development database                      |
-| **Commit**       | `npm run commit`         | Commit with commitizen                         |
-| **Release**      | `npm run release`        | Manual release (standard-version)              |
-| **Release (CI)** | `npm run release:auto`   | Semantic release for CI                        |
-| **Docker**       | `docker-compose up`      | Start with docker-compose                      |
+Scripts: see `package.json` → `scripts` section.
 
 ## Preflight
 
@@ -75,13 +58,7 @@ Use `.claude/skills/*/SKILL.md` as the primary workflow source for Claude.
 
 ## 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.
+See README — stack merge workflow section.
 
 ## Definition of done
 

README.md

@@ -153,22 +153,7 @@ This stack ships preconfigured instruction and prompt files for Claude Code, Git
 
 ### 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     |
-| `/pull-request`  | Full PR lifecycle: branch, commit, issue, monitor     |
-
-### Layered Architecture Rules
-
-- 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
-- Tests are organized per module: `modules/*/tests/`
+Skills available via `/verify`, `/feature`, `/create-module`, `/update-stack`, `/naming`, `/pull-request` — see `.claude/skills/` for details.
 
 ### Stack Merge Workflow
 
@@ -178,6 +163,8 @@ git fetch devkit-node
 git merge devkit-node/master
 ```
 
+> Caution: resolve conflicts manually to preserve downstream customizations before pushing.
+
 ## :pencil2: Contribute
 
 Open issues and pull requests on [GitHub](https://github.com/pierreb-devkit/Node).