@johanesimm/fundamentum 0.1.0 → 0.2.0

package/README.md

@@ -13,11 +13,12 @@
 npx @johanesimm/fundamentum
 ```
 
-That's it — the installer asks whether to install **globally** (every
-project) or into the **current project**, copies the skills into the
-right `.claude/skills/` folder, and you're done. Restart Claude Code,
-then say *"Initialize this project documentation-first"* to kick off
-`blueprint`. Full walkthrough in [Installation](#installation) below.
+The installer asks **which coding agent you use** (Claude Code, Codex,
+Cursor, Gemini CLI, Copilot, …), then installs the skills the way that
+agent expects and preconfigures them for it — no repeated "which tool?"
+questions later. Restart your agent, then say *"Initialize this project
+documentation-first"* to kick off `blueprint`. Full walkthrough in
+[Installation](#installation) below.
 
 ------------------------------------------------------------------------
 
@@ -110,7 +111,7 @@ jump straight to one phase, provided its inputs already exist.
 ### The `npx` installer (recommended)
 
 **Prerequisites:** [Node.js](https://nodejs.org) 18+ (gives you `npx`)
-and [Claude Code](https://claude.com/claude-code).
+and a supported coding agent.
 
 **Step 1 — run the installer.** No global install needed; `npx` fetches
 and runs it on the fly:
@@ -119,33 +120,49 @@ and runs it on the fly:
 npx @johanesimm/fundamentum
 ```
 
-**Step 2 — choose where the skills go.** You'll be asked:
+**Step 2 — pick your agent (asked first).** Your choice decides where
+the skills go *and* preconfigures `primer` to write the right
+agent-context file — so nothing re-asks "which tool?" later:
 
 ```
 Fundamentum — installing: blueprint, excavate, primer
 
-Where should these skills go?
-  1) Global   ~/.claude/skills      (available in every project)
-  2) Project  ./.claude/skills      (this repo only)
-Choose [1/2]:
+Which coding agent do you use?
+  1) Claude Code    (native skills)
+  2) Codex          (wires into AGENTS.md)
+  3) Cursor         (wires into AGENTS.md)
+  4) Gemini CLI     (wires into GEMINI.md)
+  5) GitHub Copilot (wires into .github/copilot-instructions.md)
+  6) Other / generic (wires into AGENTS.md)
+Choose [1-6]:
 ```
 
-- **Global** → the skills work in *every* project on your machine.
-- **Project** → installed only into the repo you're currently in
-  (`./.claude/skills/`); commit them to share with your team.
+How each agent is installed:
 
-**Step 3 — done.** It copies the folders and confirms:
+| Agent | Skills land in | How it's used |
+|---|---|---|
+| **Claude Code** | `.claude/skills/` (asks **global** vs **project**) | invoked natively as skills |
+| **Codex / Cursor / Gemini / Copilot / Other** | `.fundamentum/skills/` (this project) | a pointer block is added to that agent's instructions file (`AGENTS.md` / `GEMINI.md` / `copilot-instructions.md`) telling it to follow the workflows |
+
+For Claude Code you then choose **global** (every project) or
+**project** (this repo only). Non-Claude agents are always wired into
+the current project.
+
+**Step 3 — done.** It copies the folders, wires things up, and confirms
+— e.g. for Codex:
 
 ```
-  ✓ blueprint → ~/.claude/skills/blueprint
-  ✓ excavate  → ~/.claude/skills/excavate
-  ✓ primer    → ~/.claude/skills/primer
+  ✓ blueprint → ./.fundamentum/skills/blueprint
+  ✓ excavate  → ./.fundamentum/skills/excavate
+  ✓ primer    → ./.fundamentum/skills/primer
 
-Done. Installed 3 skill(s) into the global directory.
-Restart Claude Code (or start a new session) to pick them up.
+Done. Installed 3 skill(s) for Codex.
+Wired into: ./AGENTS.md
+primer is preconfigured to write AGENTS.md — it won't ask which agent.
 ```
 
-**Step 4 — use them.** Restart Claude Code, then just ask:
+**Step 4 — use them.** Restart your agent (or start a new session),
+then just ask:
 
 | Say this | Runs |
 |---|---|
@@ -156,12 +173,14 @@ Restart Claude Code (or start a new session) to pick them up.
 ### More installer options
 
 ```bash
-npx @johanesimm/fundamentum add primer   # install just one skill (space-separate for several)
-npx @johanesimm/fundamentum --global     # skip the prompt: install for every project
-npx @johanesimm/fundamentum --project    # skip the prompt: install into ./.claude/skills
-npx @johanesimm/fundamentum --force      # overwrite existing skills without asking
-npx @johanesimm/fundamentum list         # show which skills are bundled
-npx @johanesimm/fundamentum --help       # full usage
+npx @johanesimm/fundamentum --agent claude          # skip the agent prompt
+npx @johanesimm/fundamentum --agent codex           # wire into ./AGENTS.md
+npx @johanesimm/fundamentum add primer              # install just one skill (space-separate for several)
+npx @johanesimm/fundamentum --agent claude --global # Claude: install for every project
+npx @johanesimm/fundamentum --agent claude --project # Claude: install into ./.claude/skills
+npx @johanesimm/fundamentum --force                 # overwrite existing skills without asking
+npx @johanesimm/fundamentum list                    # show which skills are bundled
+npx @johanesimm/fundamentum --help                  # full usage
 ```
 
 ### Run without npm (from source)

package/bin/cli.mjs

@@ -1,9 +1,20 @@
 #!/usr/bin/env node
-// Fundamentum skill installer — copies the bundled skills into a Claude Code
-// skills directory (global ~/.claude/skills or project ./.claude/skills).
-// Zero dependencies: uses only the Node standard library.
+// Fundamentum skill installer.
+//
+// Asks which coding agent you use, then installs the skills the way that
+// agent expects:
+//   - Claude Code  -> copies invokable skills into ~/.claude/skills or
+//                     ./.claude/skills (native SKILL.md skills).
+//   - Other agents -> copies the skill folders into ./.fundamentum/skills and
+//                     wires a pointer block into that agent's instructions
+//                     file (AGENTS.md / GEMINI.md / copilot-instructions.md),
+//                     since those tools have no skill runtime.
+// The chosen agent is baked into the installed `primer` skill so it never
+// re-asks which agent-context file to generate.
+//
+// Zero dependencies: Node standard library only.
 
-import { readdir, cp, mkdir } from 'node:fs/promises';
+import { readdir, cp, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
@@ -14,27 +25,41 @@ import process from 'node:process';
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(HERE, '..'); // package root — where the skill folders live
 
-const HELP = `fundamentum — install documentation-first Claude Code skills
+// agent key -> how to install + which context file `primer` should write.
+const AGENTS = {
+  claude: { label: 'Claude Code', file: 'CLAUDE.md', native: true },
+  codex: { label: 'Codex', file: 'AGENTS.md', native: false },
+  cursor: { label: 'Cursor', file: 'AGENTS.md', native: false },
+  gemini: { label: 'Gemini CLI', file: 'GEMINI.md', native: false },
+  copilot: { label: 'GitHub Copilot', file: '.github/copilot-instructions.md', native: false },
+  other: { label: 'Other / generic', file: 'AGENTS.md', native: false },
+};
+const AGENT_ORDER = ['claude', 'codex', 'cursor', 'gemini', 'copilot', 'other'];
+const NONCLAUDE_SKILLS_DIR = '.fundamentum/skills'; // relative to the project root
+
+const HELP = `fundamentum — install documentation-first coding-agent skills
 
 Usage:
-  npx fundamentum [add] [skills...] [options]
-  npx fundamentum list
+  npx @johanesimm/fundamentum [add] [skills...] [options]
+  npx @johanesimm/fundamentum list
 
 Arguments:
-  skills...            Names of skills to install (default: all bundled skills)
+  skills...              Skills to install (default: all bundled skills)
 
 Options:
-  -g, --global        Install into ~/.claude/skills (every project)
-  -p, --project       Install into ./.claude/skills (this repo only)
-  -f, --force         Overwrite an existing skill without asking
-  -h, --help          Show this help
+  --agent <name>         claude | codex | cursor | gemini | copilot | other
+  -g, --global           Claude Code only: install into ~/.claude/skills
+  -p, --project          Install into the current project
+  -f, --force            Overwrite existing skills without asking
+  -h, --help             Show this help
 
-With no --global/--project flag, you'll be asked which one.
+With no --agent, you'll be asked which agent you use (asked first).
+Non-Claude agents are always installed into the current project.
 
 Examples:
-  npx fundamentum                 # install all skills, ask scope
-  npx fundamentum add primer -g   # install just 'primer' globally
-  npx fundamentum --project       # install all into this repo
+  npx @johanesimm/fundamentum                       # ask everything
+  npx @johanesimm/fundamentum --agent claude -g     # Claude, global, no prompts
+  npx @johanesimm/fundamentum --agent codex         # wire into ./AGENTS.md
 `;
 
 /** Discover bundled skills = top-level dirs that contain a SKILL.md. */
@@ -51,35 +76,102 @@ async function discoverSkills() {
 
 function parseArgs(argv) {
   const args = [...argv];
-  // optional leading verb
   if (['add', 'install', 'i'].includes(args[0])) args.shift();
   const flags = new Set();
   const names = [];
-  for (const a of args) {
+  let agent = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
     if (a === '-h' || a === '--help') flags.add('help');
     else if (a === '-g' || a === '--global') flags.add('global');
     else if (a === '-p' || a === '--project') flags.add('project');
     else if (a === '-f' || a === '--force') flags.add('force');
+    else if (a === '--agent') agent = (args[++i] || '').toLowerCase();
+    else if (a.startsWith('--agent=')) agent = a.slice('--agent='.length).toLowerCase();
     else if (a.startsWith('-')) throw new Error(`Unknown option: ${a}`);
     else names.push(a);
   }
-  return { flags, names, verb: argv[0] };
+  return { flags, names, agent, verb: argv[0] };
 }
 
-async function main() {
-  const { flags, names, verb } = parseArgs(process.argv.slice(2));
+/** The note the installer injects into the installed primer/SKILL.md. */
+function preconfiguredNote(agentKey) {
+  const { label, file } = AGENTS[agentKey];
+  return (
+    `> **Installer-preconfigured target: \`${file}\` (${label}).** The agent ` +
+    `was chosen at install time — do NOT ask "which tool?"; write ` +
+    `\`${file}\` directly. Only generate additional tools' files if the ` +
+    `user explicitly asks.`
+  );
+}
+
+/** Rewrite the placeholder in an installed primer so it skips its interview. */
+async function preconfigurePrimer(primerDir, agentKey) {
+  const file = join(primerDir, 'SKILL.md');
+  if (!existsSync(file)) return;
+  const src = await readFile(file, 'utf8');
+  const marker = '<!-- FUNDAMENTUM_PRECONFIGURED_TARGET -->';
+  if (!src.includes(marker)) return;
+  await writeFile(file, src.replace(marker, preconfiguredNote(agentKey)), 'utf8');
+}
+
+/** Build the pointer block wired into a non-Claude agent's instructions file. */
+function pointerBlock(skills, agentKey) {
+  const { file } = AGENTS[agentKey];
+  const lines = [
+    '<!-- fundamentum:start -->',
+    '## Fundamentum documentation workflows',
+    '',
+    `Installed at \`${NONCLAUDE_SKILLS_DIR}/\` (paths below are relative to the`,
+    'project root). When asked to scaffold or write project documentation,',
+    'follow the matching workflow file to completion:',
+    '',
+  ];
+  const desc = {
+    blueprint: 'New project, documentation-first',
+    excavate: 'Existing codebase — document what is built + plan the gap',
+    primer: `Generate this project's agent-context file (writes \`${file}\`)`,
+  };
+  for (const s of skills) {
+    lines.push(`- ${desc[s] || s} → \`${NONCLAUDE_SKILLS_DIR}/${s}/SKILL.md\``);
+  }
+  lines.push('<!-- fundamentum:end -->');
+  return lines.join('\n');
+}
 
-  if (flags.has('help')) {
-    process.stdout.write(HELP);
-    return;
+/** Create/replace the fundamentum pointer block in an instructions file. */
+async function wirePointer(projectRoot, agentKey, skills) {
+  const rel = AGENTS[agentKey].file;
+  const dest = join(projectRoot, rel);
+  await mkdir(dirname(dest), { recursive: true });
+  const block = pointerBlock(skills, agentKey);
+  let body = existsSync(dest) ? await readFile(dest, 'utf8') : '';
+  const start = '<!-- fundamentum:start -->';
+  const end = '<!-- fundamentum:end -->';
+  const si = body.indexOf(start);
+  const ei = body.indexOf(end);
+  if (si !== -1 && ei !== -1) {
+    body = body.slice(0, si) + block + body.slice(ei + end.length); // replace in place
+  } else {
+    if (body && !body.endsWith('\n')) body += '\n';
+    body += (body ? '\n' : '') + block + '\n';
   }
+  await writeFile(dest, body, 'utf8');
+  return dest;
+}
+
+async function main() {
+  const { flags, names, agent: agentFlag, verb } = parseArgs(process.argv.slice(2));
+
+  if (flags.has('help')) return void process.stdout.write(HELP);
 
   const available = await discoverSkills();
   if (available.length === 0) throw new Error(`No skills found in ${ROOT}`);
 
   if (verb === 'list') {
-    process.stdout.write(`Bundled skills:\n${available.map((s) => `  - ${s}`).join('\n')}\n`);
-    return;
+    return void process.stdout.write(
+      `Bundled skills:\n${available.map((s) => `  - ${s}`).join('\n')}\n`,
+    );
   }
 
   // Which skills?
@@ -87,49 +179,66 @@ async function main() {
   if (names.length) {
     const unknown = names.filter((n) => !available.includes(n));
     if (unknown.length) {
-      throw new Error(
-        `Unknown skill(s): ${unknown.join(', ')}\nAvailable: ${available.join(', ')}`,
-      );
+      throw new Error(`Unknown skill(s): ${unknown.join(', ')}\nAvailable: ${available.join(', ')}`);
     }
     selected = names;
   }
 
-  // Interactive prompts share one readline instance.
   const interactive = process.stdin.isTTY && process.stdout.isTTY;
   const rl = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
 
   try {
-    // Scope: global vs project.
+    // 1) Agent — asked FIRST.
+    let agent = agentFlag;
+    if (agent && !AGENTS[agent]) {
+      throw new Error(`Unknown agent: ${agent}\nChoose one of: ${AGENT_ORDER.join(', ')}`);
+    }
+    if (!agent) {
+      if (!rl) throw new Error('Non-interactive shell: pass --agent <name>.');
+      process.stdout.write(`\nFundamentum — installing: ${selected.join(', ')}\n\nWhich coding agent do you use?\n`);
+      AGENT_ORDER.forEach((k, i) => {
+        const tag = AGENTS[k].native ? 'native skills' : `wires into ${AGENTS[k].file}`;
+        process.stdout.write(`  ${i + 1}) ${AGENTS[k].label.padEnd(15)} (${tag})\n`);
+      });
+      const ans = (await rl.question('Choose [1-6]: ')).trim().toLowerCase();
+      agent = AGENT_ORDER[Number(ans) - 1] || AGENT_ORDER.find((k) => k.startsWith(ans) || AGENTS[k].label.toLowerCase().startsWith(ans));
+      if (!agent) throw new Error('No agent chosen. Aborting.');
+    }
+    const meta = AGENTS[agent];
+
+    // 2) Location.
     let scope;
-    if (flags.has('global')) scope = 'global';
-    else if (flags.has('project')) scope = 'project';
-    else if (rl) {
-      process.stdout.write(
-        `\nFundamentum — installing: ${selected.join(', ')}\n\n` +
-          `Where should these skills go?\n` +
-          `  1) Global   ${join(homedir(), '.claude', 'skills')}   (available in every project)\n` +
-          `  2) Project  ${join(process.cwd(), '.claude', 'skills')}   (this repo only)\n`,
-      );
-      const ans = (await rl.question('Choose [1/2]: ')).trim();
-      scope = ans === '2' || ans.toLowerCase().startsWith('p') ? 'project' : ans === '1' || ans.toLowerCase().startsWith('g') ? 'global' : null;
-      if (!scope) throw new Error('No scope chosen. Aborting.');
+    let targetBase;
+    if (meta.native) {
+      if (flags.has('global')) scope = 'global';
+      else if (flags.has('project')) scope = 'project';
+      else if (rl) {
+        process.stdout.write(
+          `\n${meta.label} skills — where to?\n` +
+            `  1) Global   ${join(homedir(), '.claude', 'skills')}   (every project)\n` +
+            `  2) Project  ${join(process.cwd(), '.claude', 'skills')}   (this repo only)\n`,
+        );
+        const ans = (await rl.question('Choose [1/2]: ')).trim().toLowerCase();
+        scope = ans === '2' || ans.startsWith('p') ? 'project' : ans === '1' || ans.startsWith('g') ? 'global' : null;
+        if (!scope) throw new Error('No location chosen. Aborting.');
+      } else {
+        throw new Error('Non-interactive shell: pass --global or --project.');
+      }
+      targetBase = scope === 'global' ? join(homedir(), '.claude', 'skills') : join(process.cwd(), '.claude', 'skills');
     } else {
-      throw new Error('Non-interactive shell: pass --global or --project.');
+      // Non-Claude agents wire into a project instructions file — always project.
+      scope = 'project';
+      targetBase = join(process.cwd(), ...NONCLAUDE_SKILLS_DIR.split('/'));
     }
 
-    const targetBase =
-      scope === 'global'
-        ? join(homedir(), '.claude', 'skills')
-        : join(process.cwd(), '.claude', 'skills');
-
     await mkdir(targetBase, { recursive: true });
 
+    // 3) Copy skills.
     const force = flags.has('force');
     const installed = [];
     for (const name of selected) {
       const src = join(ROOT, name);
       const dest = join(targetBase, name);
-
       if (existsSync(dest) && !force) {
         if (rl) {
           const ans = (await rl.question(`  ${dest} exists. Overwrite? [y/N]: `)).trim().toLowerCase();
@@ -142,19 +251,30 @@ async function main() {
           continue;
         }
       }
-
       await cp(src, dest, { recursive: true, force: true });
+      if (name === 'primer') await preconfigurePrimer(dest, agent);
       installed.push(name);
       process.stdout.write(`  ✓ ${name} → ${dest}\n`);
     }
 
-    if (installed.length) {
+    if (!installed.length) return void process.stdout.write('\nNothing installed.\n');
+
+    // 4) Wire the pointer for non-Claude agents.
+    let wired = null;
+    if (!meta.native) wired = await wirePointer(process.cwd(), agent, installed);
+
+    // 5) Summary.
+    process.stdout.write(`\nDone. Installed ${installed.length} skill(s) for ${meta.label}.\n`);
+    if (meta.native) {
+      process.stdout.write(`Location: ${targetBase} (${scope}).\nRestart Claude Code (or start a new session) to pick them up.\n`);
+    } else {
       process.stdout.write(
-        `\nDone. Installed ${installed.length} skill(s) into the ${scope} directory.\n` +
-          `Restart Claude Code (or start a new session) to pick them up.\n`,
+        `Skills:  ${targetBase}\nWired into: ${wired}\n` +
+          `${meta.label} reads that file, so it will follow the workflows from there.\n`,
       );
-    } else {
-      process.stdout.write(`\nNothing installed.\n`);
+    }
+    if (installed.includes('primer')) {
+      process.stdout.write(`\nprimer is preconfigured to write ${meta.file} — it won't ask which agent.\n`);
     }
   } finally {
     rl?.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johanesimm/fundamentum",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Documentation-first Claude Code skill suite (blueprint / excavate / primer) with a one-command installer.",
   "type": "module",
   "author": "Johanes <johanesimm95@gmail.com>",

package/primer/SKILL.md

@@ -25,6 +25,15 @@ generated file, do not guess.
 
 ## Phase 0 — Pick the target file(s)
 
+<!-- FUNDAMENTUM_PRECONFIGURED_TARGET -->
+<!-- The installer rewrites the line above when you choose your agent at
+     install time. If it still shows as a bare comment, this copy was
+     installed manually — run the interview below as normal. -->
+
+If the line above was replaced with a "preconfigured target" note, obey
+it and **skip the question** — the agent was already chosen at install
+time; just write that file. Otherwise:
+
 Ask (AskUserQuestion) before anything else: **"Do you use an agentic
 coding assistant, and which one(s)?"** Map the answer to filename(s):