|
| 1 | +# Node.js Rules for everything-claude-code |
| 2 | + |
| 3 | +> Project-specific rules for the ECC codebase. Extends common rules. |
| 4 | +
|
| 5 | +## Stack |
| 6 | + |
| 7 | +- **Runtime**: Node.js >=18 (no transpilation, plain CommonJS) |
| 8 | +- **Test runner**: `node tests/run-all.js` — individual files via `node tests/**/*.test.js` |
| 9 | +- **Linter**: ESLint (`@eslint/js`, flat config) |
| 10 | +- **Coverage**: c8 |
| 11 | +- **Lint**: markdownlint-cli for `.md` files |
| 12 | + |
| 13 | +## File Conventions |
| 14 | + |
| 15 | +- `scripts/` — Node.js utilities, hooks. CommonJS (`require`/`module.exports`) |
| 16 | +- `agents/`, `commands/`, `skills/`, `rules/` — Markdown with YAML frontmatter |
| 17 | +- `tests/` — Mirror the `scripts/` structure. Test files named `*.test.js` |
| 18 | +- File naming: **lowercase with hyphens** (e.g. `session-start.js`, `post-edit-format.js`) |
| 19 | + |
| 20 | +## Code Style |
| 21 | + |
| 22 | +- CommonJS only — no ESM (`import`/`export`) unless file ends in `.mjs` |
| 23 | +- No TypeScript — plain `.js` throughout |
| 24 | +- Prefer `const` over `let`; never `var` |
| 25 | +- Keep hook scripts under 200 lines — extract helpers to `scripts/lib/` |
| 26 | +- All hooks must `exit 0` on non-critical errors (never block tool execution unexpectedly) |
| 27 | + |
| 28 | +## Hook Development |
| 29 | + |
| 30 | +- Hook scripts receive JSON on stdin — always `const input = JSON.parse(fs.readFileSync(0, 'utf8'))` |
| 31 | +- Async hooks: mark `"async": true` in `settings.json` with a timeout ≤30s |
| 32 | +- Blocking hooks (PreToolUse, stop): keep fast (<200ms) — no network calls |
| 33 | +- Use `run-with-flags.js` wrapper for all hooks so `CLAUDE_ECC_MODE` gating works |
| 34 | +- Always exit 0 on parse errors; log to stderr with `[HookName]` prefix |
| 35 | + |
| 36 | +## Testing Requirements |
| 37 | + |
| 38 | +- Run `node tests/run-all.js` before committing |
| 39 | +- New scripts in `scripts/lib/` require a matching test in `tests/lib/` |
| 40 | +- New hooks require at least one integration test in `tests/hooks/` |
| 41 | + |
| 42 | +## Markdown / Agent Files |
| 43 | + |
| 44 | +- Agents: YAML frontmatter with `name`, `description`, `tools`, `model` |
| 45 | +- Skills: sections — When to Use, How It Works, Examples |
| 46 | +- Commands: `description:` frontmatter line required |
| 47 | +- Run `npx markdownlint-cli '**/*.md' --ignore node_modules` before committing |
0 commit comments