eng-skills 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# eng-skills
+
+**Battle-tested Claude Code engineering conventions, scaffolded into any repo in one command.**
+
+```bash
+npx eng-skills init
+```
+
+Most Claude Code advice lives in blog posts. This package turns it into files: an
+*enforced* documentation protocol, safety hooks, and research-first workflows —
+extracted from a production monorepo where this exact system sustained
+**100+ feature docs, 100+ fix docs, and a full ADR log** without the docs going stale.
+
+## Why
+
+Two facts about working with coding agents:
+
+1. **CLAUDE.md instructions are advisory; hooks are deterministic.** An instruction
+   like "always document your changes" gets skipped under context pressure. A Stop
+   hook that refuses to end the turn does not.
+2. **Sessions are ephemeral.** Whatever the agent learned — why a decision was made,
+   what a fix's root cause was — evaporates unless it's written where the next
+   session will look.
+
+eng-skills wires those two facts together: hooks that *force* the knowledge base to
+stay current, and a knowledge base structured so future sessions (and humans)
+actually benefit from it.
+
+## What you get
+
+```
+CLAUDE.md                  # protocol + TODO(onboard) markers Claude fills in itself
+docs/
+  README.md                # the knowledge-base map and "the rule"
+  CHANGELOG-AUTO.md        # append-only machine-written edit log
+  _templates/              # feature / fix / decision / phase templates
+  features/  fixes/        # one doc per feature, one per bug fix
+  decisions/               # numbered ADRs (seeded with ADR-0001)
+  phases/  plans/  specs/  # living progress checklists + planning artifacts
+.claude/
+  settings.json            # hook wiring (merged safely into an existing file)
+  hooks/
+    pre-edit.mjs           # PreToolUse: reminds about the protocol on first code edit
+    post-edit.mjs          # PostToolUse: logs every edit to CHANGELOG-AUTO.md
+    stop-gate.mjs          # Stop: BLOCKS ending a turn that changed code but not docs
+    guard.mjs              # PreToolUse(Bash): denies rm -rf, force push, .env exfil, …
+  commands/
+    onboard.md             # /onboard — Claude researches YOUR codebase, fills CLAUDE.md
+    feature.md             # /feature — research → plan → implement → verify → document
+    fix.md                 # /fix — reproduce → root-cause → fix → prove → document
+    decide.md              # /decide — record an ADR
+    phase.md               # /phase — honest progress review, phase-gate closeout
+```
+
+Everything is dependency-free Node (~150 lines of hooks total). No runtime, no daemon,
+nothing to keep updated.
+
+## How the enforcement works
+
+- **pre-edit** (PreToolUse) — on the first code edit of a turn, injects a reminder
+  of the docs protocol into Claude's context. Never blocks.
+- **post-edit** (PostToolUse) — appends `timestamp | session | tool | file | ±lines`
+  to `docs/CHANGELOG-AUTO.md` for every tracked edit, and records whether the turn
+  touched code, docs, or both.
+- **stop-gate** (Stop) — when Claude tries to end the turn: if code changed but
+  `docs/` didn't, it returns `{"decision": "block"}` and Claude must write the doc
+  before finishing. Includes the `stop_hook_active` loop guard.
+- **guard** (PreToolUse on Bash) — deny-list for destructive commands (`rm -rf` on
+  broad paths, `git push --force`, `git reset --hard`, `DROP TABLE`, `.env`
+  exfiltration, credential directories). Hooks fire even under
+  `--dangerously-skip-permissions`, so this holds in unattended runs.
+
+The result: **you cannot end a turn that changed source code without documenting it**,
+and you get a free forensic edit log on the side.
+
+## Using it on an existing codebase
+
+`init` is non-destructive and idempotent:
+
+- Files that already exist are **skipped** (use `--force` to overwrite).
+- An existing `.claude/settings.json` gets our hooks **merged in** — your
+  permissions and existing hooks are preserved.
+- An existing `CLAUDE.md` gets the docs-protocol section **appended**, nothing else touched.
+
+Then open Claude Code and run **`/onboard`**: Claude reads your manifests, CI config,
+and source layout, fills in every `TODO(onboard)` marker in `CLAUDE.md` (stack,
+verified commands, hard invariants), and retroactively records your existing
+architecture as ADRs — so the knowledge base starts warm, not empty.
+
+## The daily workflow
+
+| Command | What it does |
+|---|---|
+| `/feature <desc>` | Researches the codebase (and web when useful) *before* writing code, writes a checkbox plan to `docs/plans/`, implements with TDD, verifies end-to-end, documents in `docs/features/`. |
+| `/fix <bug>` | Reproduce first, root-cause (not symptom-patch), failing test → fix, document Symptom/Root cause/Fix/Verification/Prevention in `docs/fixes/`. |
+| `/decide <choice>` | Numbered ADR with context, options, decision, consequences. Supersede — never delete — old decisions. |
+| `/phase status` | Cross-checks the current phase checklist against reality (do claimed tests actually pass?). |
+| `/phase next <name>` | Phase-gate closeout: verify acceptance criteria, get operator sign-off, open the next phase. |
+
+## CLI reference
+
+```bash
+npx eng-skills init [dir]   # scaffold (default: current directory)
+  --force                   # overwrite existing files
+  --dry-run                 # print what would happen, write nothing
+```
+
+## Design principles (and their sources)
+
+- **"Give Claude a check it can run."** Without a runnable check, "looks done" is the
+  agent's only stop signal. The stop-gate is that check for documentation; the
+  templates' Verification sections demand evidence (real command output), not
+  assertions. — [Claude Code best practices](https://code.claude.com/docs/en/best-practices)
+- **Hooks for zero-exception rules, CLAUDE.md for judgment calls.** Anything that
+  must happen every time is a hook; CLAUDE.md carries the judgment-dependent
+  conventions. — [Hooks reference](https://code.claude.com/docs/en/hooks)
+- **Research before code.** `/feature` front-loads codebase + web research so the
+  plan is grounded in what exists, not what the model remembers.
+- **Keep CLAUDE.md small.** It loads into every session; every line costs context.
+  `/onboard` targets ~120 lines. Long-form knowledge goes in `docs/` where it's
+  read on demand.
+- **ADRs are agent memory.** Superseded decisions are marked, never deleted — the
+  decision log is how session N+1 avoids re-litigating what session N settled.
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+// eng-skills — scaffold battle-tested Claude Code engineering conventions.
+// Usage: npx eng-skills init [dir] [--force] [--dry-run]
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const TEMPLATES = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'templates');
+
+const argv = process.argv.slice(2);
+const flags = new Set(argv.filter((a) => a.startsWith('--')));
+const positional = argv.filter((a) => !a.startsWith('--'));
+const command = positional[0] || 'init';
+const FORCE = flags.has('--force');
+const DRY = flags.has('--dry-run');
+
+if (flags.has('--help') || command === 'help') {
+  console.log(`
+eng-skills — scaffold Claude Code engineering conventions into a repo
+
+Usage:
+  npx eng-skills init [dir]     scaffold into dir (default: current directory)
+
+Options:
+  --force      overwrite files that already exist (default: skip them)
+  --dry-run    show what would be written without writing anything
+  --help       this message
+
+What it sets up:
+  CLAUDE.md                 protocol + TODO(onboard) markers Claude fills in
+  docs/                     features/ fixes/ decisions/ phases/ plans/ specs/ + templates
+  .claude/hooks/            pre-edit reminder, post-edit changelog, stop-gate, bash guard
+  .claude/commands/         /onboard /feature /fix /decide /phase
+  .claude/settings.json     hook wiring (merged into an existing file safely)
+
+After installing, open Claude Code in the repo and run /onboard.
+`);
+  process.exit(0);
+}
+
+if (command !== 'init') {
+  console.error(`Unknown command "${command}". Try: npx eng-skills init`);
+  process.exit(1);
+}
+
+const target = path.resolve(positional[1] || '.');
+const today = new Date().toISOString().slice(0, 10);
+
+function projectName() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(target, 'package.json'), 'utf8'));
+    if (pkg.name) return pkg.name;
+  } catch {}
+  return path.basename(target);
+}
+
+const VARS = { PROJECT_NAME: projectName(), DATE: today };
+const fill = (s) => s.replace(/\{\{(\w+)\}\}/g, (m, k) => VARS[k] ?? m);
+
+const written = [];
+const skipped = [];
+const merged = [];
+
+function writeFile(rel, content) {
+  const dest = path.join(target, rel);
+  if (fs.existsSync(dest) && !FORCE) {
+    skipped.push(rel);
+    return;
+  }
+  written.push(rel);
+  if (DRY) return;
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, content);
+}
+
+function copyTemplate(srcRel, destRel = srcRel) {
+  writeFile(destRel, fill(fs.readFileSync(path.join(TEMPLATES, srcRel), 'utf8')));
+}
+
+/** Merge our hook wiring into an existing .claude/settings.json without clobbering. */
+function mergeSettings() {
+  const rel = path.join('.claude', 'settings.json');
+  const dest = path.join(target, rel);
+  const ours = JSON.parse(fs.readFileSync(path.join(TEMPLATES, 'claude', 'settings.json'), 'utf8'));
+
+  if (!fs.existsSync(dest)) {
+    writeFile(rel, JSON.stringify(ours, null, 2) + '\n');
+    return;
+  }
+
+  let existing;
+  try {
+    existing = JSON.parse(fs.readFileSync(dest, 'utf8'));
+  } catch {
+    console.error(`  !  ${rel} exists but is not valid JSON — leaving it alone.`);
+    console.error(`     Add the hook wiring manually (see templates in the eng-skills package).`);
+    skipped.push(rel);
+    return;
+  }
+
+  existing.hooks ||= {};
+  let changed = false;
+  for (const [event, entries] of Object.entries(ours.hooks)) {
+    existing.hooks[event] ||= [];
+    for (const entry of entries) {
+      const sig = JSON.stringify(entry.hooks.map((h) => h.command));
+      const already = existing.hooks[event].some(
+        (e) => JSON.stringify((e.hooks || []).map((h) => h.command)) === sig,
+      );
+      if (!already) {
+        existing.hooks[event].push(entry);
+        changed = true;
+      }
+    }
+  }
+  if (changed) {
+    merged.push(rel);
+    if (!DRY) fs.writeFileSync(dest, JSON.stringify(existing, null, 2) + '\n');
+  } else {
+    skipped.push(rel + ' (hooks already wired)');
+  }
+}
+
+/** Append the enforced docs-protocol section to an existing CLAUDE.md. */
+function installClaudeMd() {
+  const dest = path.join(target, 'CLAUDE.md');
+  const template = fill(fs.readFileSync(path.join(TEMPLATES, 'CLAUDE.md'), 'utf8'));
+
+  if (!fs.existsSync(dest)) {
+    writeFile('CLAUDE.md', template);
+    return;
+  }
+  const existing = fs.readFileSync(dest, 'utf8');
+  if (existing.includes('Documentation protocol (ENFORCED BY HOOKS)')) {
+    skipped.push('CLAUDE.md (protocol section already present)');
+    return;
+  }
+  const marker = '## 📋 Documentation protocol (ENFORCED BY HOOKS)';
+  const start = template.indexOf(marker);
+  const end = template.indexOf('## Phase roadmap');
+  const section = template.slice(start, end === -1 ? undefined : end).trimEnd();
+  merged.push('CLAUDE.md (appended docs-protocol section)');
+  if (!DRY) fs.writeFileSync(dest, existing.trimEnd() + '\n\n' + section + '\n');
+}
+
+function ensureGitignore() {
+  const dest = path.join(target, '.gitignore');
+  const line = '.claude/.docs-state/';
+  const existing = fs.existsSync(dest) ? fs.readFileSync(dest, 'utf8') : '';
+  if (existing.includes(line)) return;
+  merged.push('.gitignore (+ .claude/.docs-state/)');
+  if (!DRY) fs.writeFileSync(dest, existing + (existing && !existing.endsWith('\n') ? '\n' : '') + line + '\n');
+}
+
+console.log(`\neng-skills init → ${target}${DRY ? '  (dry run)' : ''}\n`);
+
+// Hooks + commands
+for (const f of ['lib.mjs', 'pre-edit.mjs', 'post-edit.mjs', 'stop-gate.mjs', 'guard.mjs']) {
+  copyTemplate(path.join('claude', 'hooks', f), path.join('.claude', 'hooks', f));
+}
+for (const f of ['onboard.md', 'feature.md', 'fix.md', 'decide.md', 'phase.md']) {
+  copyTemplate(path.join('claude', 'commands', f), path.join('.claude', 'commands', f));
+}
+mergeSettings();
+
+// Knowledge base
+copyTemplate(path.join('docs', 'README.md'));
+copyTemplate(path.join('docs', 'CHANGELOG-AUTO.md'));
+for (const f of ['feature.md', 'fix.md', 'decision.md', 'phase.md']) {
+  copyTemplate(path.join('docs', '_templates', f));
+}
+copyTemplate(path.join('docs', 'decisions', '0001-record-architecture-decisions.md'));
+copyTemplate(path.join('docs', 'phases', 'phase-0-foundation.md'));
+for (const d of ['features', 'fixes', 'plans', 'specs']) {
+  writeFile(path.join('docs', d, '.gitkeep'), '');
+}
+
+installClaudeMd();
+ensureGitignore();
+
+for (const f of written) console.log(`  +  ${f}`);
+for (const f of merged) console.log(`  ~  ${f}`);
+for (const f of skipped) console.log(`  =  ${f} (exists, skipped)`);
+
+console.log(`
+Done. Next steps:
+  1. cd ${path.relative(process.cwd(), target) || '.'} && claude
+  2. Run /onboard — Claude researches this codebase and fills in CLAUDE.md.
+  3. Build things with /feature, fix things with /fix, record choices with /decide.
+
+The stop-gate hook now blocks any turn that changes code without updating docs/.
+Verify hooks are active with /hooks inside Claude Code.
+`);

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "eng-skills",
+  "version": "0.1.0",
+  "description": "Scaffold battle-tested Claude Code engineering conventions into any repo: enforced docs protocol (features/fixes/decisions/phases), pre/post/stop hooks, research-first slash commands, and a CLAUDE.md that Claude fills in by reading your codebase.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "agent",
+    "scaffold",
+    "adr",
+    "documentation",
+    "hooks",
+    "best-practices"
+  ],
+  "license": "MIT",
+  "author": "Vidit Parashar <viditsharma818@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/viditparashar96/eng-skills.git"
+  },
+  "bugs": "https://github.com/viditparashar96/eng-skills/issues",
+  "homepage": "https://github.com/viditparashar96/eng-skills#readme",
+  "type": "module",
+  "bin": {
+    "eng-skills": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs"
+  }
+}

package/templates/CLAUDE.md

@@ -0,0 +1,60 @@
+# {{PROJECT_NAME}}
+
+<!-- TODO(onboard): One-paragraph mission. State the defining constraint of this
+project and point at the authoritative requirement sources. Run /onboard to have
+Claude research the codebase and fill every TODO(onboard) in this file. -->
+
+> ⚠️ <!-- TODO(onboard): the single biggest risk/constraint contributors must never violate. -->
+
+## Stack
+
+<!-- TODO(onboard): One bullet per package/app/module, plus an infra line
+(DB, queues, docker). Keep it to what an agent needs to navigate, not a sales pitch. -->
+
+## Commands
+
+```bash
+# TODO(onboard): the canonical dev commands — install, run, test, lint, migrate.
+```
+
+## Hard invariants (NEVER violate)
+
+<!-- TODO(onboard): a numbered list of absolute rules, e.g. security constraints,
+"never edit generated files", "all writes go through X". Keep them few and bold. -->
+
+## 📋 Documentation protocol (ENFORCED BY HOOKS)
+
+This repo runs three hooks (`.claude/hooks/`, configured in `.claude/settings.json`):
+
+- **pre-edit** (PreToolUse): reminds about this protocol on the first code edit of a turn.
+- **post-edit** (PostToolUse): appends every tracked edit to `docs/CHANGELOG-AUTO.md` (never hand-edit that file).
+- **stop-gate** (Stop): **blocks the turn from ending** if you changed source files without updating `docs/`.
+
+**Therefore, every turn that touches code MUST also update docs.**
+
+| You did… | Write/Update |
+|----------|--------------|
+| Implemented a feature/module | `docs/features/<phase>-<name>.md` (template: `docs/_templates/feature.md`) |
+| Fixed a bug | `docs/fixes/YYYY-MM-DD-<slug>.md` (template: `fix.md`) |
+| Made an architectural/trade-off decision | `docs/decisions/NNNN-<title>.md` (template: `decision.md`) |
+| Any code-touching turn | tick/append progress in the **current** `docs/phases/phase-N-*.md` |
+
+Notes:
+- `docs/CHANGELOG-AUTO.md` is machine-written — never edit it by hand.
+- If the Stop hook blocks you, it's working as designed: write the missing doc, then finish.
+- If hooks don't fire at all, the workspace may be untrusted — verify with `/hooks`.
+
+## Phase roadmap
+
+<!-- TODO(onboard): bullet list of phases, one marked `← CURRENT`, each pointing
+at its docs/phases/phase-N-*.md. Pause for operator review at each phase boundary. -->
+
+- Phase 0 — foundation ← CURRENT (`docs/phases/phase-0-foundation.md`)
+
+## Conventions
+
+- Research before building: for any non-trivial feature, use `/feature` — it researches the codebase (and the web when useful) and writes a short plan before writing code.
+- TDD for logic; build/boot verification for scaffolding.
+- Frequent, small conventional commits (`feat:` / `fix:` / `docs:` / `chore:`), one logical change each.
+- Small focused files; generated contracts are regenerated, never hand-copied.
+- Record trade-off decisions as ADRs in `docs/decisions/` (use `/decide`).

package/templates/claude/commands/decide.md

@@ -0,0 +1,12 @@
+---
+description: Record an Architecture Decision Record (ADR) in docs/decisions/
+argument-hint: <decision to record>
+---
+
+Record an ADR for: **$ARGUMENTS**
+
+1. Find the next number: list `docs/decisions/` and take the highest `NNNN` + 1 (zero-padded to 4 digits).
+2. If the decision hasn't been made yet: lay out the real options with honest pros/cons, recommend one, and ask the user to choose before writing `Status: accepted`.
+3. Write `docs/decisions/NNNN-<slug>.md` from `docs/_templates/decision.md` — Context, Options considered, Decision, Consequences.
+4. If this supersedes an earlier ADR, update that ADR's status line to `superseded by [[NNNN]]`.
+5. Link the ADR from the current `docs/phases/` doc's notes section.

package/templates/claude/commands/feature.md

@@ -0,0 +1,30 @@
+---
+description: Research-first feature workflow — research, plan, implement, verify, document
+argument-hint: <feature description>
+---
+
+Build the following feature using the research-first workflow: **$ARGUMENTS**
+
+## 1. Research (before any code)
+
+- Search the codebase for everything the feature touches: existing modules to reuse, conventions to follow, contracts (API schemas, types, DB models) to extend.
+- Read the relevant docs: `docs/features/` for related features, `docs/decisions/` for constraints already decided, the current `docs/phases/` doc.
+- If the feature involves an external library/API or a non-obvious technique, do a web search for current best practice — do not rely on memory for API details.
+- If requirements are ambiguous in a way that changes the design, ask the user now, not after implementing.
+
+## 2. Plan
+
+Write a short plan to `docs/plans/YYYY-MM-DD-<slug>.md`: goal, approach, files to create/change as checkboxes (`- [ ]`), test strategy. For a small feature this can be 15 lines; don't pad it. If the plan involves a real trade-off decision, record it as an ADR (`/decide`).
+
+## 3. Implement
+
+Work through the plan's checkboxes, ticking them as you go. TDD for logic. Follow the codebase's existing style, not your defaults.
+
+## 4. Verify
+
+Run the project's tests and build/typecheck. For user-facing behavior, exercise the feature end-to-end (run the app, hit the endpoint, drive the UI) — not just tests. Paste real output as evidence.
+
+## 5. Document (required — the Stop hook enforces this)
+
+- Write `docs/features/<phase>-<slug>.md` from `docs/_templates/feature.md`.
+- Tick progress in the current `docs/phases/phase-N-*.md` with a dated entry.

package/templates/claude/commands/fix.md

@@ -0,0 +1,22 @@
+---
+description: Root-cause a bug, fix it, prove the fix, and document it
+argument-hint: <bug description or error output>
+---
+
+Fix the following bug: **$ARGUMENTS**
+
+## 1. Reproduce & root-cause
+
+Reproduce the bug first (failing test, curl, script). Then find the *root cause* — trace the actual failure, don't patch the symptom. Check `docs/fixes/` for related past fixes before starting; the same class of bug may have history.
+
+## 2. Fix
+
+Write a failing test that captures the bug, then make it pass with the smallest correct change. If the root cause reveals a design flaw, note it — fix the bug now, record the design issue as an ADR or follow-up rather than scope-creeping.
+
+## 3. Verify
+
+Run the reproduction again and the full relevant test suite. Paste real output.
+
+## 4. Document (required — the Stop hook enforces this)
+
+Write `docs/fixes/YYYY-MM-DD-<slug>.md` from `docs/_templates/fix.md` — Symptom, Root cause, Fix, Verification, Prevention. Tick the current `docs/phases/` doc.

package/templates/claude/commands/onboard.md

@@ -0,0 +1,35 @@
+---
+description: Research this codebase and fill in CLAUDE.md + seed the docs knowledge base
+---
+
+You are onboarding this repository into the eng-skills workflow. The scaffold left
+`TODO(onboard)` markers in `CLAUDE.md`. Your job is to replace every one of them
+with researched, accurate content — not guesses.
+
+## Steps
+
+1. **Research the codebase thoroughly.** Read the manifest files (package.json,
+   pyproject.toml, go.mod, Cargo.toml, …), lockfiles' package manager, CI config,
+   docker/compose files, existing README/docs, and the top-level source layout.
+   For monorepos, map every package/app. Identify: tech stack, how to install/run/
+   test/lint, architecture boundaries, generated-vs-source files, and anything
+   dangerous (migrations, deploy scripts, secrets handling).
+
+2. **Fill in `CLAUDE.md`.** Replace each `TODO(onboard)` marker:
+   - Mission paragraph: what the project is and its defining constraint.
+   - Warning callout: the single biggest thing an agent must never break.
+   - Stack: one bullet per package/module + infra line.
+   - Commands: the *canonical* dev commands, verified against the manifests (don't invent scripts that don't exist).
+   - Hard invariants: 3–7 absolute rules derived from what you found (e.g. "never edit `src/generated/**`").
+   - Phase roadmap: if the project has a clear direction (roadmap file, milestones, TODOs), sketch phases; otherwise leave Phase 0 as CURRENT.
+   Keep CLAUDE.md under ~120 lines — it is loaded into every session; every line costs context.
+
+3. **Seed the knowledge base.** If this is an existing codebase (not a fresh repo):
+   - Write `docs/decisions/0002-<slug>.md`-style ADRs for 2–4 major *existing* architectural decisions you can infer (framework choice, data layer, auth approach) — mark them `accepted`, dated today, noting they were recorded retroactively.
+   - Update `docs/phases/phase-0-foundation.md`: tick the onboard task, add a dated log entry.
+
+4. **Verify.** Run the test/build command you documented in Commands to confirm it actually works. If it fails, document the real state honestly rather than an aspirational one.
+
+5. **Report.** Summarize what you filled in and anything you were unsure about so the human can correct it.
+
+Do NOT modify source code during onboarding — this is a documentation-only pass.

package/templates/claude/commands/phase.md

@@ -0,0 +1,9 @@
+---
+description: Review current phase progress, or close it out and open the next one
+argument-hint: [status | next <name>]
+---
+
+Phase management: **$ARGUMENTS**
+
+- **`status`** (or no argument): read the current `docs/phases/phase-N-*.md`, cross-check its checkboxes against reality (do the features/tests it claims actually exist and pass?), and report honest progress: done, in flight, blocked.
+- **`next <name>`**: close out the current phase — verify all acceptance criteria are ticked and true (run the tests), mark it `complete`, then create `docs/phases/phase-N+1-<name>.md` from `docs/_templates/phase.md` and update the Phase roadmap in `CLAUDE.md` to move the `← CURRENT` marker. Phase boundaries are review gates: summarize what shipped and ask the operator to confirm before starting work in the new phase.

package/templates/claude/hooks/guard.mjs

@@ -0,0 +1,32 @@
+// PreToolUse (Bash): deny obviously destructive commands and secret access.
+// Hooks fire even under --dangerously-skip-permissions, so this holds in
+// unattended runs. Deny-list only — everything else passes through untouched.
+import { readEvent } from './lib.mjs';
+
+const ev = readEvent();
+const cmd = String(ev.tool_input?.command || '');
+
+const RULES = [
+  [/\brm\s+(-[a-z]*[rf][a-z]*\s+)+.*(\/|\*|~|\$HOME)/i, 'recursive/forced rm on a broad path'],
+  [/\bgit\s+push\s+.*--force(?!-with-lease)/, 'force push (use --force-with-lease if truly needed)'],
+  [/\bgit\s+reset\s+--hard\b/, 'hard reset discards uncommitted work — stash first or ask the user'],
+  [/\bDROP\s+(TABLE|DATABASE|SCHEMA)\b/i, 'destructive SQL'],
+  [/(^|[\s/])\.env(\.[\w.]+)?\b.*(cat|cp|curl|nc |mail|post)|((cat|cp|curl)\s+[^|;]*\.env\b)/i, 'reading/exfiltrating .env secrets via shell'],
+  [/~\/\.(ssh|aws|gnupg)\b/, 'accessing credential directories'],
+];
+
+for (const [re, why] of RULES) {
+  if (re.test(cmd)) {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason: `Blocked by eng-skills guard: ${why}. If this is genuinely needed, ask the user to run it themselves or adjust .claude/hooks/guard.mjs.`,
+        },
+      }),
+    );
+    process.exit(0);
+  }
+}
+process.exit(0);

package/templates/claude/hooks/lib.mjs

@@ -0,0 +1,91 @@
+// Shared helpers for eng-skills hooks. Zero dependencies — plain Node.
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+export const PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+export const STATE_DIR = path.join(PROJECT_DIR, '.claude', '.docs-state');
+
+/** Parse the hook event JSON that Claude Code pipes to stdin. */
+export function readEvent() {
+  try {
+    return JSON.parse(fs.readFileSync(0, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/** Repo-relative path for display. */
+export function relPath(fp) {
+  if (!fp) return '';
+  const abs = path.resolve(fp);
+  const root = path.resolve(PROJECT_DIR) + path.sep;
+  return abs.startsWith(root) ? abs.slice(root.length) : fp;
+}
+
+/**
+ * Classify an edited file:
+ *  - 'ignored' — infra noise that should count as neither code nor docs
+ *  - 'docs'    — the tracked knowledge base (docs/**, CLAUDE.md)
+ *  - 'code'    — everything else
+ */
+export function classify(fp) {
+  const rel = relPath(fp).replaceAll('\\', '/');
+  if (!rel) return 'ignored';
+  const base = path.basename(rel);
+
+  if (
+    rel.startsWith('.git/') ||
+    rel.startsWith('.claude/') ||
+    rel.includes('node_modules/') ||
+    rel === 'docs/CHANGELOG-AUTO.md' ||
+    base.startsWith('.')
+  ) {
+    return 'ignored';
+  }
+  // Agent docs/config counts as documentation.
+  if (rel.startsWith('docs/') || base === 'CLAUDE.md') return 'docs';
+  return 'code';
+}
+
+const DEFAULT_STATE = { codeChanged: false, docsChanged: false, reminded: false };
+
+function stateFile(sessionId) {
+  const sid = String(sessionId || 'unknown').slice(0, 16);
+  return path.join(STATE_DIR, `${sid}.json`);
+}
+
+export function readState(sessionId) {
+  try {
+    return { ...DEFAULT_STATE, ...JSON.parse(fs.readFileSync(stateFile(sessionId), 'utf8')) };
+  } catch {
+    return { ...DEFAULT_STATE };
+  }
+}
+
+export function writeState(sessionId, state) {
+  try {
+    fs.mkdirSync(STATE_DIR, { recursive: true });
+    fs.writeFileSync(stateFile(sessionId), JSON.stringify(state));
+  } catch {
+    // State is best-effort; never break the agent over it.
+  }
+}
+
+/** Best-effort "+added/-deleted" git diff stat for one file. */
+export function diffStat(fp) {
+  const rel = relPath(fp);
+  try {
+    const run = (args) =>
+      execFileSync('git', args, { cwd: PROJECT_DIR, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const out = run(['diff', '--numstat', '--', rel]) || run(['diff', '--cached', '--numstat', '--', rel]);
+    const m = out.trim().split('\n')[0]?.match(/^(\d+|-)\s+(\d+|-)/);
+    if (m) return `+${m[1]}/-${m[2]}`;
+    // Untracked file — no diff yet.
+    const status = run(['status', '--porcelain', '--', rel]);
+    if (status.startsWith('??')) return 'new/?';
+    return '?/?';
+  } catch {
+    return '?/?';
+  }
+}

package/templates/claude/hooks/post-edit.mjs

@@ -0,0 +1,28 @@
+// PostToolUse (Edit|Write|MultiEdit): append every tracked edit to
+// docs/CHANGELOG-AUTO.md and record code/docs activity for the Stop gate.
+import fs from 'node:fs';
+import path from 'node:path';
+import { readEvent, readState, writeState, classify, relPath, diffStat, PROJECT_DIR } from './lib.mjs';
+
+const ev = readEvent();
+const fp = ev.tool_input?.file_path;
+const kind = classify(fp);
+
+if (kind !== 'ignored') {
+  const logFile = path.join(PROJECT_DIR, 'docs', 'CHANGELOG-AUTO.md');
+  try {
+    const row = `| ${new Date().toISOString()} | ${String(ev.session_id || '').slice(0, 8)} | ${
+      ev.tool_name || '?'
+    } | \`${relPath(fp)}\` | ${diffStat(fp)} |\n`;
+    fs.mkdirSync(path.dirname(logFile), { recursive: true });
+    fs.appendFileSync(logFile, row);
+  } catch {
+    // Logging is best-effort.
+  }
+
+  const st = readState(ev.session_id);
+  if (kind === 'code') st.codeChanged = true;
+  if (kind === 'docs') st.docsChanged = true;
+  writeState(ev.session_id, st);
+}
+process.exit(0);

package/templates/claude/hooks/pre-edit.mjs

@@ -0,0 +1,23 @@
+// PreToolUse (Edit|Write|MultiEdit): on the first code edit of a turn,
+// remind Claude about the docs protocol. Never blocks.
+import { readEvent, readState, writeState, classify } from './lib.mjs';
+
+const ev = readEvent();
+const fp = ev.tool_input?.file_path;
+if (classify(fp) === 'code') {
+  const st = readState(ev.session_id);
+  if (!st.reminded) {
+    st.reminded = true;
+    writeState(ev.session_id, st);
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          additionalContext:
+            'Docs protocol: you are editing source code this turn. Before ending the turn, create/update the matching entry under docs/ (features/, fixes/, or decisions/ — templates in docs/_templates/) and tick progress in the current docs/phases/ doc. The Stop hook will block the turn otherwise.',
+        },
+      }),
+    );
+  }
+}
+process.exit(0);

package/templates/claude/hooks/stop-gate.mjs

@@ -0,0 +1,25 @@
+// Stop: block the turn from ending if source files changed but docs/ did not.
+// This is the enforcement half of the docs protocol in CLAUDE.md.
+import { readEvent, readState, writeState } from './lib.mjs';
+
+const ev = readEvent();
+
+// Loop guard: if we already blocked once this turn, let it end.
+if (ev.stop_hook_active) process.exit(0);
+
+const st = readState(ev.session_id);
+
+if (st.codeChanged && !st.docsChanged) {
+  process.stdout.write(
+    JSON.stringify({
+      decision: 'block',
+      reason:
+        'You changed source files this turn but did not update docs/. Per the CLAUDE.md docs protocol: create or update the matching entry (docs/features/ for a feature, docs/fixes/ for a bug fix, docs/decisions/ for an architectural decision — templates in docs/_templates/) AND tick progress in the current docs/phases/ doc, then finish.',
+    }),
+  );
+  process.exit(0);
+}
+
+// Clean turn — reset state for the next one.
+writeState(ev.session_id, { codeChanged: false, docsChanged: false, reminded: false });
+process.exit(0);

package/templates/claude/settings.json

@@ -0,0 +1,45 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/pre-edit.mjs\""
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard.mjs\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit.mjs\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/stop-gate.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/docs/CHANGELOG-AUTO.md

@@ -0,0 +1,8 @@
+# CHANGELOG-AUTO
+
+> ⚠️ **Machine-written file.** Every row below is appended automatically by the
+> post-edit hook (`.claude/hooks/post-edit.mjs`) whenever Claude Code edits a
+> tracked file. Never edit this file by hand.
+
+| timestamp (UTC) | session | tool | file | ±lines |
+|---|---|---|---|---|

package/templates/docs/README.md

@@ -0,0 +1,22 @@
+# docs/ — the project knowledge base
+
+This directory is the project's tracked knowledge base. It is **enforced by hooks**:
+you cannot end a Claude Code turn that changed source code without updating
+something here.
+
+| Path | What it is | Who writes it |
+|------|------------|---------------|
+| `features/` | One doc per implemented feature (`<phase>-<name>.md`) | you (Claude) |
+| `fixes/` | One doc per bug fix (`YYYY-MM-DD-<slug>.md`) | you (Claude) |
+| `decisions/` | Architecture Decision Records (`NNNN-<title>.md`) | you (Claude) |
+| `phases/` | Living per-phase progress checklists (`phase-N-<name>.md`) | you (Claude) |
+| `plans/` | Implementation plans (`YYYY-MM-DD-<name>.md`) | planning workflow |
+| `specs/` | Approved design specs (`YYYY-MM-DD-<name>-design.md`) | design workflow |
+| `_templates/` | Copy-from templates for all of the above | eng-skills (don't edit casually) |
+| `CHANGELOG-AUTO.md` | Append-only, machine-written edit log | the post-edit hook (**never by hand**) |
+
+Cross-link docs with `[[wiki-style]]` links so phases ↔ features ↔ fixes ↔ decisions
+stay navigable.
+
+**The rule:** after implementing or fixing anything, write the matching doc
+**before the turn ends.**

package/templates/docs/_templates/decision.md

@@ -0,0 +1,17 @@
+# NNNN — <title>
+
+**Date:** YYYY-MM-DD · **Status:** proposed | accepted | superseded by [[NNNN]]
+
+## Context
+<The forces at play: requirements, constraints, what problem this decides.>
+
+## Options considered
+1. **<Option A>** — pros / cons
+2. **<Option B>** — pros / cons
+3. **<Option C>** — pros / cons
+
+## Decision
+<The choice made.>
+
+## Consequences
+<What becomes easier/harder. Follow-ups. What this commits us to.>

package/templates/docs/_templates/feature.md

@@ -0,0 +1,21 @@
+# Feature — <name>
+
+**Phase:** <N> · **Date:** YYYY-MM-DD · **Status:** implemented | partial
+
+## What it does
+<One-paragraph summary of the capability.>
+
+## How to use it
+<Entry points: endpoints, events, functions, CLI. Example request/payload.>
+
+## Contract touchpoints
+<APIs, events, DB models, or types this feature touches.>
+
+## Dependencies
+<Packages/modules/services this relies on.>
+
+## Tests
+<Where the tests live and what they assert.>
+
+## Notes / follow-ups
+<Known gaps, deferred work, links to related [[docs]].>

package/templates/docs/_templates/fix.md

@@ -0,0 +1,18 @@
+# Fix — <slug>
+
+**Date:** YYYY-MM-DD · **Phase:** <N> · **Severity:** low | med | high
+
+## Symptom
+<What was observed. Error messages, repro steps.>
+
+## Root cause
+<The actual underlying cause, not just the surface symptom.>
+
+## Fix
+<What changed and why it resolves the root cause. Files touched.>
+
+## Verification
+<Command(s) run + observed output proving the fix works.>
+
+## Prevention
+<Test added / guard added so this can't regress. Links to [[docs]].>

package/templates/docs/_templates/phase.md

@@ -0,0 +1,17 @@
+# Phase <N> — <name>
+
+**Status:** not started | in progress | complete · **Plan:** [[docs/plans/...]]
+
+## Goal
+<One sentence.>
+
+## Acceptance criteria
+- [ ] <criterion 1>
+- [ ] <criterion 2>
+
+## Task progress
+- [ ] Task 1 — <name>
+- [ ] Task 2 — <name>
+
+## Notes / decisions made during the phase
+<Running log. Link [[decisions]] and [[features]].>

package/templates/docs/decisions/0001-record-architecture-decisions.md

@@ -0,0 +1,24 @@
+# 0001 — Record architecture decisions
+
+**Date:** {{DATE}} · **Status:** accepted
+
+## Context
+This project is built with Claude Code. Agent sessions are ephemeral: context is
+lost between sessions, and the reasoning behind a choice evaporates unless it is
+written down where the next session will find it. We need a durable, low-friction
+record of significant architectural and trade-off decisions.
+
+## Options considered
+1. **No records** — zero friction, but every future session (human or agent) re-litigates old decisions and repeats mistakes.
+2. **Decisions embedded in code comments** — close to the code, but scattered, unsearchable as a set, and invisible to planning.
+3. **Architecture Decision Records in `docs/decisions/`** — one numbered file per decision with context, options, decision, consequences. Searchable, linkable, cheap.
+
+## Decision
+We record every significant decision as an ADR in `docs/decisions/NNNN-<title>.md`,
+using `docs/_templates/decision.md`. The docs-protocol hooks enforce that decisions
+made while coding get written down in the same turn.
+
+## Consequences
+Future sessions can read *why*, not just *what*. Superseded decisions are marked,
+not deleted, preserving history. The set of ADRs becomes the project's long-term
+memory alongside `CLAUDE.md`.

package/templates/docs/phases/phase-0-foundation.md

@@ -0,0 +1,18 @@
+# Phase 0 — foundation
+
+**Status:** in progress · **Plan:** —
+
+## Goal
+Establish the eng-skills workflow in this repo: hooks live, CLAUDE.md filled in, first real work documented.
+
+## Acceptance criteria
+- [ ] `/onboard` run — CLAUDE.md has no remaining `TODO(onboard)` markers
+- [ ] Hooks verified firing (check `/hooks` inside Claude Code)
+- [ ] First feature/fix documented under `docs/`
+
+## Task progress
+- [x] Task 0 — scaffold installed via `npx eng-skills init` ({{DATE}})
+- [ ] Task 1 — run `/onboard`
+
+## Notes / decisions made during the phase
+See [[0001-record-architecture-decisions]].