create-cadmo 0.1.0 → 0.2.0

package/README.md

@@ -13,5 +13,7 @@ Drops into the current directory, never overwriting anything:
 - `cadmo/spec.md` — the rules, in the client's language, criteria first
 - `cadmo/plan.md` — the internal route: tasks, constraints, how to validate
 - `cadmo/decision.md` — architecture decisions with a "when to reconsider" trigger
+- `cadmo/spec-drift.mjs` + a ready CI workflow — **specs must change with the code they watch** (the drift guard)
+- `.claude/commands/cadmo-*.md` — `/cadmo-gate`, `/cadmo-spec`, `/cadmo-done` slash commands (when Claude Code is detected, or `--claude`)
 
-The method, docs and protocols: **https://github.com/tiagotorres91/cadmo** · **https://cadmo.dev**
+The method, docs and protocols: **https://github.com/tiagotorres91/cadmo**

package/index.js

@@ -1,44 +1,95 @@
-#!/usr/bin/env node
-/*
- * create-cadmo — scaffold the Cadmo method into the current project.
- * No dependencies. Never overwrites an existing file.
- * https://github.com/tiagotorres91/cadmo
- */
-const fs = require('fs');
-const path = require('path');
-
-const here = (...p) => path.join(__dirname, 'templates', ...p);
-const cwd = process.cwd();
-
-const FILES = [
-  // [source in package, destination in project]
-  ['AGENTS.md', 'AGENTS.md'],
-  ['value-gate.md', path.join('cadmo', 'value-gate.md')],
-  ['spec.md', path.join('cadmo', 'spec.md')],
-  ['plan.md', path.join('cadmo', 'plan.md')],
-  ['decision.md', path.join('cadmo', 'decision.md')],
-];
-
-console.log('\n  Cadmo — write it down before you build it.\n');
-
-let placed = 0, skipped = 0;
-for (const [src, dest] of FILES) {
-  const target = path.join(cwd, dest);
-  if (fs.existsSync(target)) {
-    console.log(`  = kept      ${dest} (already exists — not touched)`);
-    skipped++;
-    continue;
-  }
-  fs.mkdirSync(path.dirname(target), { recursive: true });
-  fs.copyFileSync(here(src), target);
-  console.log(`  + created   ${dest}`);
-  placed++;
-}
-
-console.log(`\n  ${placed} file(s) created, ${skipped} kept.\n`);
-console.log('  Next steps:');
-console.log('  1. Fill in AGENTS.md — the local map your AI pair reads first');
-console.log('     (using CLAUDE.md? link or rename it — same idea).');
-console.log('  2. For your next relevant feature: cadmo/value-gate.md (5 lines, before any spec).');
-console.log('  3. For any 3+ step task: copy cadmo/plan.md — acceptance criteria before code.');
-console.log('\n  The method in one page: https://github.com/tiagotorres91/cadmo\n');
+#!/usr/bin/env node
+/*
+ * create-cadmo — scaffold the Cadmo method into the current project.
+ * No dependencies. Never overwrites an existing file.
+ * https://github.com/tiagotorres91/cadmo
+ */
+const fs = require('fs');
+const path = require('path');
+
+const args = process.argv.slice(2);
+const DRY = args.includes('--dry-run');
+const FORCE_CLAUDE = args.includes('--claude');
+const NO_CLAUDE = args.includes('--no-claude');
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+  create-cadmo — drop the Cadmo method into the current project.
+
+  Usage: npm create cadmo [-- --dry-run] [-- --claude | --no-claude]
+
+    --dry-run     show what would be created, create nothing
+    --claude      also install Claude Code slash commands (/cadmo-gate, /cadmo-spec, /cadmo-done)
+    --no-claude   skip the Claude Code commands even if CLAUDE.md/.claude is detected
+
+  Creates (never overwrites):
+    AGENTS.md                       the local map your AI pair reads first
+    cadmo/value-gate.md             5 lines before any spec: is it worth building?
+    cadmo/spec.md                   the rules, client language, criteria first
+    cadmo/plan.md                   the internal route: tasks, constraints, validation
+    cadmo/decision.md               ADR with a "when to reconsider" trigger
+    cadmo/spec-drift.mjs            the drift guard: specs must change with the code they watch
+    cadmo/spec-drift-workflow.yml   ready CI workflow (move into .github/workflows/)
+    .claude/commands/cadmo-*.md     (when Claude Code is detected, or --claude)
+
+  The method in one page: https://github.com/tiagotorres91/cadmo
+`);
+  process.exit(0);
+}
+
+const here = (...p) => path.join(__dirname, 'templates', ...p);
+const cwd = process.cwd();
+
+const FILES = [
+  ['AGENTS.md', 'AGENTS.md'],
+  ['value-gate.md', path.join('cadmo', 'value-gate.md')],
+  ['spec.md', path.join('cadmo', 'spec.md')],
+  ['plan.md', path.join('cadmo', 'plan.md')],
+  ['decision.md', path.join('cadmo', 'decision.md')],
+  ['spec-drift.mjs', path.join('cadmo', 'spec-drift.mjs')],
+  ['spec-drift-workflow.yml', path.join('cadmo', 'spec-drift-workflow.yml')],
+];
+
+const hasClaude = FORCE_CLAUDE || (!NO_CLAUDE &&
+  (fs.existsSync(path.join(cwd, 'CLAUDE.md')) || fs.existsSync(path.join(cwd, '.claude'))));
+
+const CLAUDE_FILES = [
+  [path.join('claude-commands', 'cadmo-gate.md'), path.join('.claude', 'commands', 'cadmo-gate.md')],
+  [path.join('claude-commands', 'cadmo-spec.md'), path.join('.claude', 'commands', 'cadmo-spec.md')],
+  [path.join('claude-commands', 'cadmo-done.md'), path.join('.claude', 'commands', 'cadmo-done.md')],
+];
+
+const plan = hasClaude ? FILES.concat(CLAUDE_FILES) : FILES;
+
+console.log(`\n  Cadmo — write it down before you build it.${DRY ? '  (dry run)' : ''}\n`);
+
+let placed = 0, skipped = 0;
+for (const [src, dest] of plan) {
+  const target = path.join(cwd, dest);
+  if (fs.existsSync(target)) {
+    console.log(`  = kept      ${dest} (already exists — not touched)`);
+    skipped++;
+    continue;
+  }
+  if (DRY) {
+    console.log(`  ~ would create ${dest}`);
+  } else {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(here(src), target);
+    console.log(`  + created   ${dest}`);
+  }
+  placed++;
+}
+
+console.log(`\n  ${placed} file(s) ${DRY ? 'would be created' : 'created'}, ${skipped} kept.\n`);
+if (!hasClaude && !NO_CLAUDE) {
+  console.log('  (No CLAUDE.md/.claude detected — run with --claude to also install /cadmo-* slash commands.)');
+}
+console.log('  Next steps:');
+console.log('  1. Fill in AGENTS.md — the local map your AI pair reads first');
+console.log('     (using CLAUDE.md? link or rename it — same idea).');
+console.log('  2. For your next relevant feature: cadmo/value-gate.md (5 lines, before any spec).');
+console.log('  3. For any 3+ step task: copy cadmo/plan.md — acceptance criteria before code.');
+console.log('  4. Turn on the drift guard: move cadmo/spec-drift-workflow.yml to .github/workflows/');
+console.log('     and add a `watches:` front matter to your first spec.');
+console.log('\n  The method in one page: https://github.com/tiagotorres91/cadmo\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cadmo",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Scaffold the Cadmo method into your project \u2014 a right-sized method for building software with AI as your pair.",
   "keywords": [
     "cadmo",
@@ -13,7 +13,7 @@
     "claude",
     "scaffold"
   ],
-  "homepage": "https://cadmo.dev",
+  "homepage": "https://github.com/tiagotorres91/cadmo",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/tiagotorres91/cadmo.git"
@@ -30,5 +30,8 @@
   },
   "engines": {
     "node": ">=16"
+  },
+  "scripts": {
+    "test": "node --test"
   }
 }

package/templates/claude-commands/cadmo-done.md

@@ -0,0 +1,17 @@
+# /cadmo-done — the definition of done, checked honestly
+
+Run the definition of done for: **$ARGUMENTS** (or the work we just finished).
+
+Check each item **against evidence, not memory** — run the commands, don't assume:
+
+- [ ] Build/tests pass — run them now and show me the output
+- [ ] **Tested functionally** — the real flow (browser, curl, CLI run), not just linters
+- [ ] Validated in staging before production (when there is one)
+- [ ] Acceptance criteria from the spec/plan — checked one by one, quoted
+- [ ] Spec updated if a rule changed (same commit) — run `node cadmo/spec-drift.mjs --base origin/main` if present
+- [ ] Anything untested? Say it explicitly: "I didn't test X"
+- [ ] Touched auth/input/data/secrets? → flag that an adversarial security pass is due before shipping
+
+Then the **process check** (the choreography, not the code): was there a plan before execution? criteria before code? If any answer is no, say so plainly — this checklist exists to be failed honestly, not passed cosmetically.
+
+Finish with a verdict: **ready to ship** / **ready except <items>** / **not ready because <items>**.

package/templates/claude-commands/cadmo-gate.md

@@ -0,0 +1,13 @@
+# /cadmo-gate — open a value gate
+
+Open a value gate for: **$ARGUMENTS**
+
+Work with me (the human) to fill the five lines — copy `cadmo/value-gate.md` next to the demand, then:
+
+1. **Problem (measurable):** ask me what hurts today; push for a number (time lost, error rate, money).
+2. **Why this solution:** make me compare against at least one cheaper alternative (a rule? a process change? doing nothing?).
+3. **Success metric (business):** a number that will prove value after delivery — reject "it works" as a metric.
+4. **Data readiness:** check the actual sources (tables, exports, APIs) — 🟢/🟡/🔴 with the caveat named.
+5. **Verdict:** recommend GO / NO-GO / defer, with one sentence of reasoning — but the verdict is mine to make.
+
+Keep it to ~5 lines of content. If the work is trivial (a fix, a tweak), tell me it doesn't need a gate and stop.

package/templates/claude-commands/cadmo-spec.md

@@ -0,0 +1,13 @@
+# /cadmo-spec — write the spec, criteria first
+
+Write the spec for: **$ARGUMENTS**
+
+Use `cadmo/spec.md` as the skeleton. Rules:
+
+1. **Goal in the client's language** — 2-5 lines a non-developer validates. No jargon.
+2. **Acceptance criteria before anything else** — each one observable and specific. For critical ones (money, data, integrations, security) use EARS: *"WHEN <trigger>, THE SYSTEM SHALL <behavior>"* — they become tests almost word for word.
+3. **Out of scope** — name what this does NOT cover.
+4. **Impact on stable specs** — which existing documented rules will absorb this on delivery. If this spec should be *watched* against code, add the `watches:` front matter (see `cadmo/spec-drift.mjs`).
+5. Then pair it with a plan (`cadmo/plan.md`) — technical route, tasks, how to validate. Don't repeat the criteria there.
+
+Stop after the spec and ask me to validate it **before** writing any code. If it changes money, data or an external integration, remind me the client (or their proxy) validates it first.

package/templates/spec-drift-workflow.yml

@@ -0,0 +1,19 @@
+# Example workflow — copy to .github/workflows/spec-drift.yml in your project.
+# Fails a PR when a file watched by a spec changes and the spec doesn't change with it.
+# Escape hatch (audited, never silent): write "spec-drift: skip — <reason>" in the PR body.
+name: spec-drift
+on:
+  pull_request:
+jobs:
+  drift:
+    if: "${{ !contains(github.event.pull_request.body, 'spec-drift: skip') }}"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: specs must change with the code they govern
+        run: node cadmo/spec-drift.mjs --base origin/${{ github.base_ref }}

package/templates/spec-drift.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/*
+ * spec-drift — the rule that keeps documentation honest:
+ * a spec declares which files implement it; if those files change and the spec
+ * doesn't change in the same diff, the check fails.
+ *
+ * No dependencies. How it works:
+ *   1. Scans the repo for .md files with a `watches:` list in their front matter.
+ *   2. Diffs the current branch against --base (default: origin/main).
+ *   3. For each spec: if a watched file changed and the spec didn't → DRIFT.
+ *
+ * Usage:
+ *   node spec-drift.mjs [--base origin/main] [--dir .]
+ *
+ * Spec front matter example:
+ *   ---
+ *   watches:
+ *     - src/billing/**
+ *     - api/invoices.py
+ *   ---
+ *
+ * Escape hatch (audited, not silent): if a change genuinely doesn't alter any
+ * documented rule, say so where reviewers can see it — e.g. run the CI step
+ * only when the PR body does NOT contain "spec-drift: skip — <reason>".
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const args = process.argv.slice(2);
+function opt(name, fallback) {
+  const i = args.indexOf(name);
+  return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
+}
+const BASE = opt('--base', 'origin/main');
+const ROOT = path.resolve(opt('--dir', '.'));
+
+// --- collect specs that declare `watches:` in front matter ---
+function* mdFiles(dir) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.name.startsWith('.') || e.name === 'node_modules') continue;
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) yield* mdFiles(p);
+    else if (e.name.endsWith('.md')) yield p;
+  }
+}
+
+function parseWatches(file) {
+  const text = fs.readFileSync(file, 'utf8');
+  if (!text.startsWith('---')) return null;
+  const end = text.indexOf('\n---', 3);
+  if (end < 0) return null;
+  const fm = text.slice(3, end);
+  const lines = fm.split('\n');
+  const watches = [];
+  let inWatches = false;
+  for (const line of lines) {
+    if (/^watches:\s*$/.test(line)) { inWatches = true; continue; }
+    if (inWatches) {
+      const m = line.match(/^\s+-\s+(.+?)\s*$/);
+      if (m) watches.push(m[1].replace(/^["']|["']$/g, ''));
+      else if (!/^\s/.test(line)) inWatches = false;
+    }
+  }
+  return watches.length ? watches : null;
+}
+
+// --- minimal glob → regex (supports ** and *) ---
+function globToRegex(glob) {
+  // zero-backslash implementation: escape specials via char classes, never via backslash
+  const BS = String.fromCharCode(92);
+  let esc = '';
+  for (const ch of glob) {
+    if (ch === '*' || ch === '/') esc += ch;
+    else if ('.+^$(){}|[]?'.includes(ch) || ch === BS) esc += BS + ch;
+    else esc += ch;
+  }
+  esc = esc.split('**').join('__DSTAR__');
+  esc = esc.split('*').join('[^/]*');
+  esc = esc.split('__DSTAR__').join('.*');
+  return new RegExp('^' + esc + '$');
+}
+
+// --- changed files vs base ---
+let changed;
+try {
+  changed = execFileSync('git', ['diff', '--name-only', `${BASE}...HEAD`], { cwd: ROOT, encoding: 'utf8' })
+    .split('\n').filter(Boolean);
+} catch (e) {
+  console.error(`spec-drift: cannot diff against ${BASE} — ${e.message}`);
+  process.exit(2);
+}
+
+const specs = [];
+for (const f of mdFiles(ROOT)) {
+  const watches = parseWatches(f);
+  if (watches) specs.push({ spec: path.relative(ROOT, f).split(String.fromCharCode(92)).join('/'), watches });
+}
+
+if (!specs.length) {
+  console.log('spec-drift: no specs with a `watches:` front matter found — nothing to check.');
+  process.exit(0);
+}
+
+const changedSet = new Set(changed);
+let drift = 0;
+for (const { spec, watches } of specs) {
+  const regexes = watches.map(globToRegex);
+  const hits = changed.filter(c => regexes.some(r => r.test(c)));
+  if (hits.length && !changedSet.has(spec)) {
+    drift++;
+    console.error(`DRIFT: ${hits.join(', ')} changed, but ${spec} (which watches ${watches.join(', ')}) did not change in this diff.`);
+  }
+}
+
+if (drift) {
+  console.error(`\nspec-drift: ${drift} spec(s) out of sync. Update the spec in the same change — or state why no documented rule changed (visibly, where reviewers can see it).`);
+  process.exit(1);
+}
+console.log(`spec-drift: ${specs.length} spec(s) checked against ${changed.length} changed file(s) — in sync ✓`);