create-cadmo 0.0.1 → 0.1.0

package/README.md

@@ -1,11 +1,17 @@
-# create-cadmo
-
-Scaffold the **Cadmo** method into your project — a right-sized method for building software with AI as your pair.
-
-```bash
-npm create cadmo
-```
-
-The method, docs and templates: **https://github.com/tiagotorres91/cadmo** · **https://cadmo.dev**
-
-> This is an early placeholder reserving the name. The scaffolder (`cadmo init` — drops `AGENTS.md`, the value gate, spec/plan templates into your project) is on the roadmap.
+# create-cadmo
+
+Scaffold the **Cadmo** method into your project — a right-sized method for building software with AI as your pair.
+
+```bash
+npm create cadmo
+```
+
+Drops into the current directory, never overwriting anything:
+
+- `AGENTS.md` — the local map your AI pair reads first (it will offer to fill it in for you)
+- `cadmo/value-gate.md` — 5 lines before any spec: is it worth building?
+- `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
+
+The method, docs and protocols: **https://github.com/tiagotorres91/cadmo** · **https://cadmo.dev**

package/index.js

@@ -0,0 +1,44 @@
+#!/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');

package/package.json

@@ -1,26 +1,34 @@
-{
-  "name": "create-cadmo",
-  "version": "0.0.1",
-  "description": "Scaffold the Cadmo method into your project — a right-sized method for building software with AI as your pair.",
-  "keywords": [
-    "cadmo",
-    "create-cadmo",
-    "spec-driven-development",
-    "ai",
-    "methodology",
-    "framework",
-    "agents",
-    "claude",
-    "scaffold"
-  ],
-  "homepage": "https://cadmo.dev",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/tiagotorres91/cadmo.git"
-  },
-  "author": "Tiago Torres (B2B Soluções em TI)",
-  "license": "MIT",
-  "files": [
-    "README.md"
-  ]
-}
+{
+  "name": "create-cadmo",
+  "version": "0.1.0",
+  "description": "Scaffold the Cadmo method into your project \u2014 a right-sized method for building software with AI as your pair.",
+  "keywords": [
+    "cadmo",
+    "create-cadmo",
+    "spec-driven-development",
+    "ai",
+    "methodology",
+    "framework",
+    "agents",
+    "claude",
+    "scaffold"
+  ],
+  "homepage": "https://cadmo.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tiagotorres91/cadmo.git"
+  },
+  "author": "Tiago Torres",
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "templates/",
+    "README.md"
+  ],
+  "bin": {
+    "create-cadmo": "index.js"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}

package/templates/AGENTS.md

@@ -0,0 +1,31 @@
+# AGENTS.md — <project name>
+
+> Drop this at the root of your project so any AI pair works the Cadmo way from the first message.
+> This is the *local map*: what this project is, where things live, and how to verify. The method
+> itself is in AGENTS.md at the Cadmo repo; this file is the project-specific instance.
+>
+> **AI pair reading this while it still has `<placeholders>`:** your first job is to fill it —
+> scan the repository (structure, package files, scripts, CI) and propose the map to your human:
+> what the project is, where specs/plans should live, and the actual verify commands. Then remove
+> this paragraph.
+
+## What this project is
+<one paragraph: the product, the client/owner, the stack>
+
+## Where things live
+- Specs / decisions: <path>
+- Plans: <path>
+- Demands / task board: <where>
+
+## How to verify (the harness — run before saying "done")
+- Build/type-check: `<command>`
+- Tests: `<command>`
+- End-to-end / smoke: `<command>`
+- Staging URL: <url>  ·  Production: <url>
+
+## Gates
+- Plan approved before building; production ships only with explicit human approval.
+- <any project-specific rule or gotcha>
+
+## The method
+Opening choreography, definition of done, the layers — see the Cadmo method (link).

package/templates/decision.md

@@ -0,0 +1,20 @@
+# ADR — <short title of the decision>
+
+**Status:** accepted · **Date:** <YYYY-MM-DD> · **Deciders:** <who>
+
+## Context
+The forces at play: the problem, the constraints, what makes this decision necessary now (3–6 lines).
+
+## Decision
+What was decided, stated as a full sentence ("We will…").
+
+## Alternatives considered
+- **<Alternative A>** — why not: …
+- **<Alternative B>** — why not: …
+(Real alternatives you weighed — this section is what saves the re-investigation in six months.)
+
+## Consequences
+What becomes easier, what becomes harder, what debt is knowingly taken on.
+
+## When to reconsider
+The trigger that should reopen this decision (a scale threshold, a price change, a vendor event) — a decision without a reconsider-trigger quietly becomes dogma.

package/templates/plan.md

@@ -0,0 +1,21 @@
+# <Demand name> — plan (internal)
+
+Pairs with `spec.md` (acceptance criteria live there — don't repeat them).
+
+## Objective
+What changes in the world when this is done (1–3 lines).
+
+## Investigation (optional)
+What was tried/considered before and why it was discarded (3–6 lines) — avoids re-investigating dead ends.
+
+## Context & constraints
+Current state, decisions already made, what NOT to change.
+
+## Technical plan
+Files/tables/endpoints touched; approach; alternatives discarded.
+
+## Tasks
+- [ ] Small, verifiable (status kept here — any session resumes without getting lost)
+
+## How to validate
+Commands/flows that prove the acceptance criteria (build, tests, e2e, real manual flow).

package/templates/spec.md

@@ -0,0 +1,24 @@
+# Spec — <name>
+
+**Status:** draft — awaiting validation (<who>)  ·  **Demand:** <link/id>
+
+## Goal & context
+The business problem and what changes in the world (2–5 lines, in the client's language).
+(Relevant work already passed the value gate — its success metric becomes an acceptance criterion here.)
+
+## Acceptance criteria
+- [ ] Simple ones in free form
+- [ ] Critical ones (money / data / integration / security) in EARS:
+      WHEN <trigger>, THE SYSTEM SHALL <behavior>
+
+## Data (AI features only)
+Source, owner, access, quality/bias, corpus refresh plan.
+
+## Risks (critical or AI demands only)
+Risk → response. For AI: corpus drift, provider API change, cost, regulation.
+
+## Out of scope
+What this delivery does NOT cover (controlled expectations).
+
+## Impact on stable specs
+Which sections of the system/domain specs will be updated on delivery (the absorption).

package/templates/value-gate.md

@@ -0,0 +1,12 @@
+# Value gate — <demand name>
+
+Fill this in *before* writing a spec, for anything relevant (a new feature, module, project).
+Trivial work and routine fixes skip this.
+
+**Problem (measurable):** what hurts today, in numbers when possible.
+**Why this solution:** AI vs a rule vs a process vs doing nothing — why this path.
+**Success metric (business):** the number that will prove value — not "it works", but "reduced X", "freed Y hours", "raised Z".
+**Data readiness:** 🟢 data exists, accessible, reliable · 🟡 exists with caveats (which?) · 🔴 doesn't exist → resolve *before* specifying.
+**Verdict:** GO / NO-GO / defer (why).
+
+<!-- At close, come back and record: did the metric materialize? -->