Skip to content

Commit 0db45bd

Browse files
PierreBrisorgueilPierreBrisorgueil
committed
feat: add Claude Code setup with skills and aligned README
- Add .claude/settings.json with Node-specific permissions - Add .claude/agents/stack-maintainer.md agent - Add skills: verify, create-module, feature, naming, update-stack - Rewrite README to align with Vue stack (pierreb-devkit branding, same structure)
1 parent a25fd39 commit 0db45bd

8 files changed

Lines changed: 618 additions & 83 deletions

File tree

‎.claude/agents/stack-maintainer.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Stack Maintainer Agent
2+
3+
You are the stack maintainer agent. Your role is to protect the mergeability and security of the Devkit Node stack.
4+
5+
## Responsibilities
6+
7+
### 1. Protect mergeability
8+
9+
- **Prevent risky renames**: Core stack files should stay in their original locations
10+
- **Avoid structure breakage**: Don't move modules, change folder structures, or rename core files under `lib/` or `config/`
11+
- **Stable paths**: Ensure downstream projects can merge updates cleanly
12+
- **Flag risky changes**: Warn about changes that might cause merge conflicts in `lib/services/`, `lib/middlewares/`, or `config/defaults/`
13+
14+
### 2. Sanity-check for security
15+
16+
- **Secret leakage**: Check for accidentally committed secrets, tokens, or credentials
17+
- **Broad permissions**: Review permission changes for security risks
18+
- **Dependencies**: Flag suspicious or risky dependency additions
19+
- **Env vars**: Ensure sensitive config uses `WAOS_NODE_*` env vars, not hardcoded values
20+
- **Auth bypass**: Watch for changes that weaken JWT/Passport validation or policy middleware
21+
22+
### 3. Verify modularity
23+
24+
- **Cross-module coupling**: Flag unnecessary imports between modules
25+
- **Layer violations**: Ensure controllers don't call repositories directly (must go through services)
26+
- **Module boundaries**: Keep logic isolated within `modules/{name}/` — controllers, services, repositories, models, policies, routes, tests
27+
28+
## When invoked
29+
30+
- Review proposed changes briefly
31+
- Flag any concerns with severity:
32+
- 🔴 **Critical**: Must fix (security, breakage)
33+
- 🟡 **Warning**: Should review (coupling, patterns, layer violations)
34+
- 🟢 **Info**: Good to know (suggestions)
35+
- Be concise — this is a quick sanity check, not a full audit
36+
37+
## What NOT to do
38+
39+
- Don't run workflows or execute commands
40+
- Don't implement features
41+
- Don't write code
42+
- Keep reviews short and focused
43+
44+
## Example review
45+
46+
```
47+
🔴 Critical: `.env` file was modified (should be git-ignored)
48+
🟡 Warning: Controller imports repository directly — must go through service layer
49+
🟢 Info: Consider extracting this validation schema to `lib/helpers/joi.js` for reuse
50+
```

‎.claude/settings.json‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
{
2+
"mcpServers": {},
3+
"permissions": {
4+
"files": {
5+
"deny": [
6+
".env",
7+
".env.*",
8+
"secrets/**",
9+
"**/*.pem",
10+
"**/*.key",
11+
"**/*.enc",
12+
"**/credentials.json",
13+
"**/credentials.yml",
14+
"**/credentials.yaml",
15+
"**/*-key.json",
16+
"**/*_rsa",
17+
"**/*_dsa",
18+
"**/*_ecdsa",
19+
"**/*_ed25519"
20+
]
21+
},
22+
"bash": {
23+
"allow": [
24+
{
25+
"command": "git status",
26+
"prompt": "Check git status"
27+
},
28+
{
29+
"command": "git diff",
30+
"prompt": "View git diff"
31+
},
32+
{
33+
"command": "git diff *",
34+
"prompt": "View git diff for specific files"
35+
},
36+
{
37+
"command": "git log",
38+
"prompt": "View git log"
39+
},
40+
{
41+
"command": "git log *",
42+
"prompt": "View git log with options"
43+
},
44+
{
45+
"command": "git show *",
46+
"prompt": "Show git commit details"
47+
},
48+
{
49+
"command": "npm start",
50+
"prompt": "Start dev server"
51+
},
52+
{
53+
"command": "npm run debug",
54+
"prompt": "Start debug server"
55+
},
56+
{
57+
"command": "npm run prod",
58+
"prompt": "Start production server"
59+
},
60+
{
61+
"command": "npm test",
62+
"prompt": "Run tests"
63+
},
64+
{
65+
"command": "npm run test:watch",
66+
"prompt": "Run tests in watch mode"
67+
},
68+
{
69+
"command": "npm run test:coverage",
70+
"prompt": "Generate test coverage"
71+
},
72+
{
73+
"command": "npm run lint",
74+
"prompt": "Check code quality"
75+
},
76+
{
77+
"command": "npm run seed:dev",
78+
"prompt": "Seed development database"
79+
},
80+
{
81+
"command": "npm run commit",
82+
"prompt": "Commit with commitizen"
83+
},
84+
{
85+
"command": "docker-compose up",
86+
"prompt": "Start docker-compose services"
87+
},
88+
{
89+
"command": "docker-compose up -d",
90+
"prompt": "Start docker-compose in background"
91+
},
92+
{
93+
"command": "docker-compose down",
94+
"prompt": "Stop docker-compose services"
95+
},
96+
{
97+
"command": "docker-compose ps",
98+
"prompt": "Show docker-compose status"
99+
}
100+
],
101+
"deny": [
102+
{
103+
"pattern": "rm -rf *",
104+
"reason": "Destructive command"
105+
},
106+
{
107+
"pattern": "sudo *",
108+
"reason": "Requires elevated privileges"
109+
},
110+
{
111+
"pattern": "curl * | *sh",
112+
"reason": "Arbitrary code execution risk"
113+
},
114+
{
115+
"pattern": "wget * | *sh",
116+
"reason": "Arbitrary code execution risk"
117+
},
118+
{
119+
"pattern": "git push *",
120+
"reason": "Automatic push not allowed"
121+
},
122+
{
123+
"pattern": "npm publish",
124+
"reason": "Package publishing requires explicit approval"
125+
},
126+
{
127+
"pattern": "npm run seed:mongodrop",
128+
"reason": "Destructive database operation"
129+
}
130+
]
131+
}
132+
}
133+
}

‎.claude/skills/create-module/SKILL.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
name: create-module
3+
description: Create a new feature module by duplicating the canonical `tasks` module template. Use when adding a new module to the application, scaffolding a new domain area from scratch, or generating the boilerplate for a new feature.
4+
---
5+
6+
# Create Module Skill
7+
8+
Create a new module by copying and renaming the `tasks` template module.
9+
10+
## Prerequisites
11+
12+
- The canonical template module `modules/tasks` must exist
13+
- You need a name for the new module (kebab-case)
14+
15+
## Steps
16+
17+
### 1. Ask for the module name
18+
19+
Prompt user for the new module name in kebab-case (e.g., `my-feature`, `user-settings`)
20+
21+
### 2. Derive naming conventions
22+
23+
Follow `/naming` for the full reference. Quick summary from the module name (e.g., `my-feature`):
24+
25+
- **kebab-case**: `my-feature` (folder names, file prefixes, routes)
26+
- **PascalCase**: `MyFeature` (Mongoose model names, class names)
27+
- **lowerCamelCase**: `myFeature` (variable names, function names, JS exports)
28+
- **UPPER_SNAKE_CASE**: `MY_FEATURE` (constants)
29+
30+
### 3. Duplicate the module
31+
32+
```bash
33+
cp -r modules/tasks modules/{new-module-name}
34+
```
35+
36+
### 4. Rename references
37+
38+
Search and replace the following tokens across the new module:
39+
40+
- `tasks` → `{new-module-name}` (kebab-case)
41+
- `Tasks` → `{NewModuleName}` (PascalCase)
42+
- `task` → `{new-module}` (singular kebab-case, if applicable)
43+
- `Task` → `{NewModule}` (singular PascalCase, if applicable)
44+
45+
Files to check in `modules/{new-module-name}/`:
46+
47+
- File names (controllers, services, repositories, models, policies, routes, tests)
48+
- Mongoose model name and collection name
49+
- Route paths and prefixes
50+
- Joi validation schemas
51+
- Policy function names
52+
- Test descriptions and fixture data
53+
54+
### 5. Show rename plan (if broad changes)
55+
56+
If renaming affects many files, show a brief plan before applying changes.
57+
58+
### 6. Apply renames carefully
59+
60+
Use safe search+replace to avoid false positives:
61+
62+
- Be case-sensitive
63+
- Match whole words where possible
64+
- Don't rename unrelated code (e.g., "tasks" in comments about other features)
65+
66+
### 7. Run verify
67+
68+
```bash
69+
npm run lint
70+
npm test
71+
```
72+
73+
### 8. Report results
74+
75+
Provide a summary:
76+
77+
- ✅ Module created at: `modules/{new-module-name}`
78+
- ✅ Renamed tokens: `tasks` → `{new-module-name}`, etc.
79+
- ✅ Verification: lint passed, tests passed
80+
- 📝 Next steps: Customize the model schema, update business logic in services, register routes in `lib/services/express.js` if needed
81+
82+
## Module Structure
83+
84+
```
85+
modules/{new-module-name}/
86+
├── controllers/
87+
│ └── {module}.crud.controller.js
88+
├── services/
89+
│ └── {module}.crud.service.js
90+
├── repositories/
91+
│ └── {module}.repository.js
92+
├── models/
93+
│ └── {module}.model.js
94+
├── policies/
95+
│ └── {module}.crud.policy.js
96+
├── routes/
97+
│ └── {module}.routes.js
98+
└── tests/
99+
└── {module}.integration.tests.js
100+
```
101+
102+
## Notes
103+
104+
- Preserves the layered architecture: controllers → services → repositories → models
105+
- Follows modularity rules: keeps the module self-contained
106+
- Policy functions control route authorization — update them for your use case

‎.claude/skills/feature/SKILL.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
name: feature
3+
description: Implement a new feature or modify existing functionality following the project's layered architecture and modularity rules. Use when adding features, modifying existing ones, or ensuring correct isolation within module boundaries.
4+
---
5+
6+
# Feature Skill
7+
8+
Implement features with strict layer ordering and module isolation.
9+
10+
## Steps
11+
12+
### 1. Identify target module(s)
13+
14+
Before coding, determine:
15+
16+
- Which module(s) does this feature belong to?
17+
- Default to **ONE module** unless strictly necessary
18+
- If it spans multiple modules, explain why and minimize coupling
19+
20+
### 2. Apply layer rules
21+
22+
Respect the strict layer order — never skip or reverse it:
23+
24+
```
25+
Routes → Controllers → Services → Repositories → Models
26+
```
27+
28+
- **Routes** (`routes/`): Define HTTP endpoints, apply policy middleware
29+
- **Controllers** (`controllers/`): Handle HTTP req/res, call services, format responses via `lib/helpers/responses.js`
30+
- **Services** (`services/`): Business logic, call repositories, throw `AppError` for domain errors
31+
- **Repositories** (`repositories/`): Database access only, use Joi schemas for validation
32+
- **Models** (`models/`): Mongoose schema definition
33+
34+
### 3. Apply modularity rules
35+
36+
- **Isolate feature logic** inside the module boundary
37+
- **Avoid cross-module imports** unless absolutely required
38+
- If shared code is needed:
39+
- Place it in `lib/helpers/` or `lib/services/`
40+
- Provide **explicit justification** for why it must be shared
41+
- Keep these inside the module (`modules/{module}/**`):
42+
- Controllers, services, repositories, models, policies, routes, tests
43+
44+
### 4. Use existing helpers
45+
46+
Before writing new utilities, check:
47+
48+
- `lib/helpers/responses.js` — JSend response wrapper (`success`, `error`)
49+
- `lib/helpers/AppError.js` — Custom error class for domain errors
50+
- `lib/helpers/errors.js` — Error formatting utilities
51+
- `lib/helpers/joi.js` — Shared Joi validation helpers
52+
- `lib/middlewares/policy.js` — Authorization middleware
53+
- `lib/middlewares/model.js` — Model middleware
54+
55+
### 5. Follow API response format
56+
57+
All API responses must use the JSend wrapper:
58+
59+
```js
60+
// Success
61+
res.status(200).json(responses.success(data));
62+
// Error (caught by controller)
63+
res.status(err.status).json(responses.error(err.message, err.errors));
64+
```
65+
66+
### 6. Run verify
67+
68+
```bash
69+
npm run lint
70+
npm test
71+
```
72+
73+
## Notes
74+
75+
- Config is loaded from `config/` and overridable via `WAOS_NODE_*` env vars
76+
- Authentication is handled via Passport JWT middleware — don't reimplement
77+
- All policies must use `lib/middlewares/policy.js` patterns

0 commit comments

Comments
 (0)