From 8e5d897c34a9fd39295b591fae69b566868acc52 Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Mon, 2 Mar 2026 17:03:48 +0100 Subject: [PATCH 1/6] chore(update-stack): rework skill as 2-phase ISO merge + remove stack-maintainer agent - Phase 1: ISO merge with explicit --theirs rules for stack modules and lib - Phase 2: project alignment via MIGRATION.md + tasks reference module - Remove stack-maintainer agent (guardrails covered by CLAUDE.md + skill) - Update CLAUDE.md: remove agent reference --- .claude/agents/stack-maintainer.md | 43 --------------- .claude/skills/update-stack/SKILL.md | 79 ++++++++++++++-------------- CLAUDE.md | 6 +-- 3 files changed, 41 insertions(+), 87 deletions(-) delete mode 100644 .claude/agents/stack-maintainer.md diff --git a/.claude/agents/stack-maintainer.md b/.claude/agents/stack-maintainer.md deleted file mode 100644 index df5b8be60..000000000 --- a/.claude/agents/stack-maintainer.md +++ /dev/null @@ -1,43 +0,0 @@ -# Stack Maintainer Agent - -You are the stack maintainer agent. Your role is to protect the mergeability and security of the Devkit Node stack. - -## Responsibilities - -### 1. Protect mergeability - -- **Prevent risky renames**: Core stack files should stay in their original locations -- **Avoid structure breakage**: Don't move modules, change folder structures, or rename core files under `lib/` or `config/` -- **Stable paths**: Ensure downstream projects can merge updates cleanly -- **Flag risky changes**: Warn about changes that might cause merge conflicts in `lib/services/`, `lib/middlewares/`, or `config/defaults/` - -### 2. Sanity-check for security - -- **Secret leakage**: Check for accidentally committed secrets, tokens, or credentials -- **Broad permissions**: Review permission changes for security risks -- **Dependencies**: Flag suspicious or risky dependency additions -- **Env vars**: Ensure sensitive config uses `DEVKIT_NODE_*` env vars, not hardcoded values -- **Auth bypass**: Watch for changes that weaken JWT/Passport validation or policy middleware - -### 3. Verify modularity - -- **Cross-module coupling**: Flag unnecessary imports between modules -- **Layer violations**: Ensure controllers don't call repositories directly (must go through services) -- **Module boundaries**: Keep logic isolated within `modules/{name}/` β€” controllers, services, repositories, models, policies, routes, tests - -## When invoked - -- Review proposed changes briefly -- Flag any concerns with severity: - - πŸ”΄ **Critical**: Must fix (security, breakage) - - 🟑 **Warning**: Should review (coupling, patterns, layer violations) - - 🟒 **Info**: Good to know (suggestions) -- Be concise β€” this is a quick sanity check, not a full audit - -## What NOT to do - -- Don't run workflows or execute commands -- Don't implement features -- Don't write code -- Keep reviews short and focused - diff --git a/.claude/skills/update-stack/SKILL.md b/.claude/skills/update-stack/SKILL.md index e0657631d..312c645ed 100644 --- a/.claude/skills/update-stack/SKILL.md +++ b/.claude/skills/update-stack/SKILL.md @@ -5,60 +5,61 @@ description: Merge the latest changes from the Devkit Node stack repository into # Update Stack Skill -Pure git workflow for merging stack updates while preserving downstream customizations. +Two-phase workflow. Phase 1 brings the stack down ISO. Phase 2 aligns the project. -## Steps +## Phase 1 β€” ISO merge -### 1. Add the stack remote (if not already added) +**Goal: stack modules and lib exit this phase identical to upstream. Zero downstream logic in them.** -```bash -git remote add devkit-node https://github.com/pierreb-devkit/Node.git -``` +Stack modules: `home`, `auth`, `users`, `tasks`, `uploads` β€” Stack core: `lib/`, `config/defaults/` -### 2. Fetch the latest stack changes +### 1. Setup remote + merge ```bash +git remote get-url devkit-node >/dev/null 2>&1 || git remote add devkit-node https://github.com/pierreb-devkit/Node.git git fetch devkit-node +git merge devkit-node/master ``` -### 3. Merge the stack updates +### 2. Resolve conflicts + +| File | Rule | +|------|------| +| Stack module (`modules/home\|auth\|users\|tasks\|uploads`) | `git checkout --theirs ` | +| `lib/` | `git checkout --theirs ` (core framework β€” always ISO) | +| `package-lock.json` | `git checkout --theirs package-lock.json` β€” regenerate after `package.json` is resolved | +| `ERRORS.md` | Union merge β€” keep every line from both sides, never drop | +| `MIGRATION.md` (if present) | Read it (needed for Phase 2), then `git checkout --theirs` | +| `config/defaults/.js` | `--ours` (downstream-only file) | +| `package.json` | `--ours` then merge upstream version bumps | + +After resolving `package.json`: ```bash -git merge devkit-node/master +npm install --package-lock-only +git add package-lock.json ``` -### 4. Handle conflicts +### 3. `/verify` + +All failures here are regressions from conflict resolution. Fix before Phase 2. -Focus on these high-conflict areas: +--- -- `config/defaults/` β€” Merge stack defaults carefully, preserve downstream overrides -- `lib/services/` β€” Accept stack changes unless downstream has specific customizations -- `package.json` β€” Keep downstream dependencies, accept stack dependency updates -- `modules/*/` β€” Stack only ships `tasks`, `home`, `auth`, `users`, `uploads` β€” downstream modules are safe +## Phase 2 β€” Project alignment -### 5. Verify after merge +**Goal: project-specific modules work and match stack patterns.** -```bash -npm run lint -npm test -``` +### 4. Apply MIGRATION.md (if present) + +Read the last entries β€” they list breaking changes requiring updates in project modules. Apply each one to non-stack modules. + +### 5. Align project modules + +Diff project modules against `modules/tasks` (stack reference). Fix pattern drift per `ERRORS.md`: + +- Layer order: Routes β†’ Controllers β†’ Services β†’ Repositories β†’ Models (no controllerβ†’repository direct calls) +- JSDoc on all functions +- `async/await + try/catch` in controllers and services -## Conflict Strategy - -| File/Dir | Strategy | -| ---------------------- | --------------------------------------------- | -| `config/defaults/` | Preserve downstream values, take stack structure | -| `lib/` | Prefer stack (core framework code) | -| `modules/tasks/` | Prefer stack (reference module) | -| `modules/home/` | Prefer stack (core module) | -| `modules/auth/` | Prefer stack (security β€” take updates) | -| `modules/users/` | Prefer stack unless customized | -| `modules/uploads/` | Prefer stack unless customized | -| Custom modules | Always keep downstream | -| `package.json` | Merge carefully, keep both dependency sets | - -## Notes - -- Stack modules (`tasks`, `home`, `auth`, `users`, `uploads`) are reference implementations β€” downstream may customize them -- Custom modules added downstream will never conflict -- After merge, check `config/defaults/development.js` to ensure new stack config keys are present +### 6. `/verify` diff --git a/CLAUDE.md b/CLAUDE.md index 29a594253..621e3802e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,7 +8,7 @@ It is designed to be cloned into downstream projects and kept up-to-date through Source of truth: `README.md` + `package.json` scripts. -The `.claude/` folder contains embedded settings, skills, and agents that are available immediately after cloning. +The `.claude/` folder contains embedded settings and skills that are available immediately after cloning. ## Canonical commands @@ -52,10 +52,6 @@ Use `.claude/skills/*/SKILL.md` as the primary workflow source for Claude. | `/naming` | Apply or audit naming conventions | | `/pull-request` | Full PR lifecycle: draft, CI, monitor loop, iterate | -## Embedded agent - -- `stack-maintainer` (`.claude/agents/stack-maintainer.md`): quick review guard for mergeability, security, and modularity. - ## Stack merge workflow See README β€” stack merge workflow section. From 52396645afca84efb1094f20e6694621f6d518ec Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Mon, 2 Mar 2026 17:10:34 +0100 Subject: [PATCH 2/6] fix(update-stack): address review feedback from pass 1 - Clarify config/defaults ownership (stack-owned files ISO, project.js downstream-only) - Add git add + merge --continue step after conflict resolution - Full commands in all table rows (no --ours shorthand) - Fix MIGRATION.md row to include file path - Remove backslash escaping in table pipe pattern --- .claude/skills/update-stack/SKILL.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/.claude/skills/update-stack/SKILL.md b/.claude/skills/update-stack/SKILL.md index 312c645ed..11e7bbc56 100644 --- a/.claude/skills/update-stack/SKILL.md +++ b/.claude/skills/update-stack/SKILL.md @@ -11,7 +11,7 @@ Two-phase workflow. Phase 1 brings the stack down ISO. Phase 2 aligns the projec **Goal: stack modules and lib exit this phase identical to upstream. Zero downstream logic in them.** -Stack modules: `home`, `auth`, `users`, `tasks`, `uploads` β€” Stack core: `lib/`, `config/defaults/` +Stack modules: `home`, `auth`, `users`, `tasks`, `uploads` β€” Stack core: `lib/`, `config/defaults/` (stack-owned files only β€” `config/defaults/.js` is downstream-only and will never conflict) ### 1. Setup remote + merge @@ -27,11 +27,11 @@ git merge devkit-node/master |------|------| | Stack module (`modules/home\|auth\|users\|tasks\|uploads`) | `git checkout --theirs ` | | `lib/` | `git checkout --theirs ` (core framework β€” always ISO) | +| `config/defaults/development.js`, `production.js`, etc. | `git checkout --theirs ` (stack-owned defaults) | | `package-lock.json` | `git checkout --theirs package-lock.json` β€” regenerate after `package.json` is resolved | | `ERRORS.md` | Union merge β€” keep every line from both sides, never drop | -| `MIGRATION.md` (if present) | Read it (needed for Phase 2), then `git checkout --theirs` | -| `config/defaults/.js` | `--ours` (downstream-only file) | -| `package.json` | `--ours` then merge upstream version bumps | +| `MIGRATION.md` (if present) | Read it (needed for Phase 2), then `git checkout --theirs MIGRATION.md` | +| `package.json` | `git checkout --ours package.json` then merge upstream version bumps | After resolving `package.json`: @@ -40,6 +40,13 @@ npm install --package-lock-only git add package-lock.json ``` +Stage all resolved files and complete the merge: + +```bash +git add . +git merge --continue +``` + ### 3. `/verify` All failures here are regressions from conflict resolution. Fix before Phase 2. From 85d238ea435276b5cdae8ca5674b6c42dfd610a4 Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Mon, 2 Mar 2026 18:02:43 +0100 Subject: [PATCH 3/6] fix(update-stack): add downstream-only new files rule to conflict table --- .claude/skills/update-stack/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.claude/skills/update-stack/SKILL.md b/.claude/skills/update-stack/SKILL.md index 11e7bbc56..7fef2b87a 100644 --- a/.claude/skills/update-stack/SKILL.md +++ b/.claude/skills/update-stack/SKILL.md @@ -32,6 +32,7 @@ git merge devkit-node/master | `ERRORS.md` | Union merge β€” keep every line from both sides, never drop | | `MIGRATION.md` (if present) | Read it (needed for Phase 2), then `git checkout --theirs MIGRATION.md` | | `package.json` | `git checkout --ours package.json` then merge upstream version bumps | +| Downstream-only new files (new modules, helpers, lib additions, scripts) | Never delete β€” these do not exist in the stack, `git checkout --ours ` if flagged | After resolving `package.json`: From f44f0b2631416fc83c1de251e992d1ec61b63318 Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Mon, 2 Mar 2026 18:09:13 +0100 Subject: [PATCH 4/6] fix(update-stack): address review feedback from pass 2 - Replace git add . with git add -u (no untracked staging) - Clarify lib ownership: existing files ISO, new additions downstream --- .claude/skills/update-stack/SKILL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude/skills/update-stack/SKILL.md b/.claude/skills/update-stack/SKILL.md index 7fef2b87a..c2c852253 100644 --- a/.claude/skills/update-stack/SKILL.md +++ b/.claude/skills/update-stack/SKILL.md @@ -11,7 +11,7 @@ Two-phase workflow. Phase 1 brings the stack down ISO. Phase 2 aligns the projec **Goal: stack modules and lib exit this phase identical to upstream. Zero downstream logic in them.** -Stack modules: `home`, `auth`, `users`, `tasks`, `uploads` β€” Stack core: `lib/`, `config/defaults/` (stack-owned files only β€” `config/defaults/.js` is downstream-only and will never conflict) +Stack modules: `home`, `auth`, `users`, `tasks`, `uploads` β€” Stack core: `lib/` (existing files), `config/defaults/` (stack-owned files only) ### 1. Setup remote + merge @@ -26,7 +26,7 @@ git merge devkit-node/master | File | Rule | |------|------| | Stack module (`modules/home\|auth\|users\|tasks\|uploads`) | `git checkout --theirs ` | -| `lib/` | `git checkout --theirs ` (core framework β€” always ISO) | +| `lib/` | `git checkout --theirs ` (existing stack framework files β€” always ISO) | | `config/defaults/development.js`, `production.js`, etc. | `git checkout --theirs ` (stack-owned defaults) | | `package-lock.json` | `git checkout --theirs package-lock.json` β€” regenerate after `package.json` is resolved | | `ERRORS.md` | Union merge β€” keep every line from both sides, never drop | @@ -44,7 +44,7 @@ git add package-lock.json Stage all resolved files and complete the merge: ```bash -git add . +git add -u git merge --continue ``` From de9968797592c00e5e51a5c29177e720adef4dbd Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Mon, 2 Mar 2026 18:19:52 +0100 Subject: [PATCH 5/6] chore(verify,update-stack): read ERRORS.md in verify, simplify ERRORS row in update-stack --- .claude/skills/update-stack/SKILL.md | 2 +- .claude/skills/verify/SKILL.md | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/.claude/skills/update-stack/SKILL.md b/.claude/skills/update-stack/SKILL.md index c2c852253..2ed5137d1 100644 --- a/.claude/skills/update-stack/SKILL.md +++ b/.claude/skills/update-stack/SKILL.md @@ -29,7 +29,7 @@ git merge devkit-node/master | `lib/` | `git checkout --theirs ` (existing stack framework files β€” always ISO) | | `config/defaults/development.js`, `production.js`, etc. | `git checkout --theirs ` (stack-owned defaults) | | `package-lock.json` | `git checkout --theirs package-lock.json` β€” regenerate after `package.json` is resolved | -| `ERRORS.md` | Union merge β€” keep every line from both sides, never drop | +| `ERRORS.md` | Merge stack entries + project entries β€” never drop lines | | `MIGRATION.md` (if present) | Read it (needed for Phase 2), then `git checkout --theirs MIGRATION.md` | | `package.json` | `git checkout --ours package.json` then merge upstream version bumps | | Downstream-only new files (new modules, helpers, lib additions, scripts) | Never delete β€” these do not exist in the stack, `git checkout --ours ` if flagged | diff --git a/.claude/skills/verify/SKILL.md b/.claude/skills/verify/SKILL.md index d946f6ab7..a14f744c5 100644 --- a/.claude/skills/verify/SKILL.md +++ b/.claude/skills/verify/SKILL.md @@ -9,9 +9,10 @@ Run lint β†’ tests and report results. ## Steps -1. Run `npm run lint` to check code quality (read-only, no auto-fix) -2. Run `npm test` to run all tests -3. Summarize results: +1. Read `ERRORS.md` β€” scan changed files for any pattern listed as wrong. Flag violations before running tooling. +2. Run `npm run lint` to check code quality (read-only, no auto-fix) +3. Run `npm test` to run all tests +4. Summarize results: - βœ… All checks passed β†’ ready to commit - ❌ Some checks failed β†’ show what failed and suggest next action From c82930642bd3b06e19a637b50560cad991fa216e Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Mon, 2 Mar 2026 18:24:52 +0100 Subject: [PATCH 6/6] chore(update-stack): remove pattern list from Phase 2, defer to ERRORS.md --- .claude/skills/update-stack/SKILL.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/.claude/skills/update-stack/SKILL.md b/.claude/skills/update-stack/SKILL.md index 2ed5137d1..bcc451dc5 100644 --- a/.claude/skills/update-stack/SKILL.md +++ b/.claude/skills/update-stack/SKILL.md @@ -64,10 +64,6 @@ Read the last entries β€” they list breaking changes requiring updates in projec ### 5. Align project modules -Diff project modules against `modules/tasks` (stack reference). Fix pattern drift per `ERRORS.md`: - -- Layer order: Routes β†’ Controllers β†’ Services β†’ Repositories β†’ Models (no controllerβ†’repository direct calls) -- JSDoc on all functions -- `async/await + try/catch` in controllers and services +Diff project modules against `modules/tasks` (stack reference). Fix any pattern drift flagged by `ERRORS.md`. ### 6. `/verify`