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..bcc451dc5 100644 --- a/.claude/skills/update-stack/SKILL.md +++ b/.claude/skills/update-stack/SKILL.md @@ -5,60 +5,65 @@ 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.** + +Stack modules: `home`, `auth`, `users`, `tasks`, `uploads` — Stack core: `lib/` (existing files), `config/defaults/` (stack-owned files only) + +### 1. Setup remote + merge ```bash -git remote add devkit-node https://github.com/pierreb-devkit/Node.git +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 ``` -### 2. Fetch the latest stack changes +### 2. Resolve conflicts + +| File | Rule | +|------|------| +| Stack module (`modules/home\|auth\|users\|tasks\|uploads`) | `git checkout --theirs ` | +| `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` | 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 | + +After resolving `package.json`: ```bash -git fetch devkit-node +npm install --package-lock-only +git add package-lock.json ``` -### 3. Merge the stack updates +Stage all resolved files and complete the merge: ```bash -git merge devkit-node/master +git add -u +git merge --continue ``` -### 4. Handle conflicts +### 3. `/verify` -Focus on these high-conflict areas: +All failures here are regressions from conflict resolution. Fix before Phase 2. -- `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 +--- -### 5. Verify after merge +## Phase 2 — Project alignment -```bash -npm run lint -npm test -``` +**Goal: project-specific modules work and match stack patterns.** + +### 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 any pattern drift flagged by `ERRORS.md`. -## 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/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 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.