@firatcand/forge 0.1.0 → 0.2.1

package/README.md

@@ -1,3 +1,4 @@
+![banner](forge-cover-v1--horizon-banner-3x1@2x.png)
 # 🔨 Forge
 
 > A lightweight Claude Code framework that takes you from idea to production with structure, not friction.
@@ -8,7 +9,7 @@ Forge is for solo founders and small teams who want to ship real products with C
 
 Forge ships:
 
-- **21 slash commands** covering the full product lifecycle from raw idea to production
+- **21 skills** covering the full product lifecycle from raw idea to production (typed as slash commands in Claude Code; invoked by description in Codex CLI — see [Cross-tool support](#cross-tool-support))
 - **12 specialist subagents** — frontend, backend, db, qa, security, devops, design, plus orchestrators
 - **13 templates** for PRD, SPEC, DESIGN, phases.yaml, GitHub workflows, and more
 - **8 best practices baked in** — Boil the Lake, Iron Law of Investigation, Compound Learning, Test-or-die, Multi-model Second Opinion, and more
@@ -44,6 +45,8 @@ PROD  ← /phase-gate phase-3 ← (manual PR dev → main)
 
 ~90-120 minutes from raw idea to first task ready to implement.
 
+> The `/`-prefixed names above are the Claude Code experience — typed slash commands. In other hosts (Codex CLI, Cursor, Gemini CLI), the same skills are available but invoked differently. See [Cross-tool support](#cross-tool-support) below.
+
 ## Install
 
 One command. No git clone, no setup script.
@@ -69,9 +72,9 @@ npx @firatcand/forge
 mkdir my-product && cd my-product
 npx @firatcand/forge init
 
-# Open your AI coding tool and run /forge
-claude       # or: codex, cursor, gemini
-> /forge          # Socratic Q&A → spec/BRIEF.md
+# Open your AI coding tool — see Cross-tool support below for per-host invocation
+claude
+> /forge          # discovery interview → spec/BRIEF.md
 > /draft-prd      # → spec/PRD.md
 > /draft-spec     # → spec/SPEC.md
 > /decompose      # → plans/phases.yaml
@@ -80,31 +83,41 @@ claude       # or: codex, cursor, gemini
 > /pickup-task    # claim first task, worktree created
 ```
 
+In Codex CLI, the same skills are installed but Codex doesn't expose user-defined slash commands — invoke them by description instead, e.g. `Run forge's discovery interview for my project idea: ...`. Codex's model picks the skill up from `~/.codex/skills/forge/SKILL.md`.
+
 [Full quick start →](docs/QUICKSTART.md)
 
 ## Other commands
 
 ```bash
 npx @firatcand/forge install      # Install/reinstall forge skills + agents only
+npx @firatcand/forge doctor       # Audit installed skills + agents per detected tool
 npx @firatcand/forge init [name]  # Initialize a project in current directory
 npx @firatcand/forge companions   # Install founder-skills companions only
 npx @firatcand/forge --help       # Show all commands
 npx @firatcand/forge --version    # Show version
 ```
 
+If a slash command stops triggering in one of your AI tools (e.g. you installed Codex CLI after running forge for the first time), run `npx @firatcand/forge doctor` to see exactly what's installed where, then `npx @firatcand/forge install` to sync.
+
 ## Cross-tool support
 
-Forge works with:
-- ✅ Claude Code (`~/.claude/`)
-- ✅ Codex CLI (`~/.codex/`)
-- ✅ Cursor (`~/.cursor/`)
-- ✅ Gemini CLI (`~/.gemini/`)
+The installer detects which tools you have and installs forge skills + subagents into each. **The skills land in every host, but how you invoke them differs by host.**
+
+| Host       | Install path                          | How to invoke a forge skill                                  | Status                |
+|------------|---------------------------------------|--------------------------------------------------------------|-----------------------|
+| Claude Code | `~/.claude/skills/`, `~/.claude/agents/` | Typed slash commands: `/forge`, `/draft-prd`, …            | ✅ Verified            |
+| Codex CLI  | `~/.codex/skills/`, `~/.codex/subagents/` | Natural language — Codex doesn't expose user slash commands. Ask the model: "Run forge's discovery interview for …" | ✅ Skills load; no `/forge` syntax |
+| Cursor     | `~/.cursor/skills/`, `~/.cursor/agents/`   | Unverified — invocation mechanism not yet tested by maintainer | ⚠️ Unverified          |
+| Gemini CLI | `~/.gemini/extensions/`                | Unverified — uses Gemini's `extensions` format, may need manual config | ⚠️ Unverified          |
+
+If you're on Codex/Cursor/Gemini and `/forge` doesn't trigger, that's expected — try the natural-language form. Run `npx @firatcand/forge doctor` to confirm the skills are physically present at the expected paths.
 
-The installer detects which tools you have and installs to all of them by default. You can choose specific tools during setup.
+If you discover the right invocation pattern for Cursor or Gemini and it differs from natural language, please open an issue or PR — the maintainer is actively looking for confirmation on those two.
 
 ## Why "forge"?
 
-Forge is what you do when you have raw material (an idea) and want a finished tool (a product). The process is heat, pressure, shape, repeat. The framework's namesake skill `/forge` applies Socratic pressure to your raw idea until structure emerges.
+Forge is what you do when you have raw material (an idea) and want a finished tool (a product). The process is heat, pressure, shape, repeat. The framework's namesake skill `/forge` is a discovery interview that applies pressure to your raw idea until structure emerges.
 
 ## Inspiration
 
@@ -123,7 +136,7 @@ What forge adds:
 
 ## Status
 
-Forge is **v1.0** — used in production by the maintainer for solo founder workflows. Stable enough to depend on, raw enough that you'll find sharp edges. Issues and PRs welcome.
+Forge is **v0.2.1** — used in production by the maintainer for solo founder workflows. Stable enough to depend on, raw enough that you'll find sharp edges. Issues and PRs welcome.
 
 ## License
 

package/bin/forge.js

@@ -4,12 +4,28 @@ import { checkbox, input, confirm } from '@inquirer/prompts';
 import chalk from 'chalk';
 import fs from 'fs-extra';
 import path from 'path';
+import os from 'os';
 import { execSync } from 'child_process';
 
-import { detectTools, installToTool } from '../lib/tools.js';
+import { detectTools, installToTool, auditTool } from '../lib/tools.js';
 import { COMPANIONS, installCompanion } from '../lib/companions.js';
 import { FORGE_ROOT, getPackageVersion } from '../lib/paths.js';
 
+function tildify(p) {
+  if (!p) return p;
+  const home = os.homedir();
+  return p.startsWith(home) ? '~' + p.slice(home.length) : p;
+}
+
+function formatInstallSummary(tool, result) {
+  const parts = [`${result.skillsCount} skills → ${tildify(result.skillsTarget)}`];
+  if (result.agentsTarget) {
+    const agentLabel = tool.key === 'codex' ? 'subagents' : 'agents';
+    parts.push(`${result.agentsCount} ${agentLabel} → ${tildify(result.agentsTarget)}`);
+  }
+  return `${tool.name} — ${parts.join(', ')}`;
+}
+
 function showHelp() {
   console.log(`
 ${chalk.bold('🔨 forge')} — A lightweight framework for shipping software products with AI coding agents
@@ -17,13 +33,15 @@ ${chalk.bold('🔨 forge')} — A lightweight framework for shipping software pr
 ${chalk.bold('Usage:')}
   npx @firatcand/forge                  Run interactive setup (default)
   npx @firatcand/forge install          Install forge skills + agents only
+  npx @firatcand/forge doctor           Audit installed skills + agents per tool
   npx @firatcand/forge init [name]      Initialize a forge project in current directory
   npx @firatcand/forge companions       Install founder-skills companions
   npx @firatcand/forge --version        Show version
   npx @firatcand/forge --help           Show this help
 
 ${chalk.bold('Skills (use inside your AI coding tool):')}
-  /forge          Socratic ideation → BRIEF.md
+${chalk.dim(`  Claude Code: type the / name. Codex CLI: ask in natural language ("run forge's discovery interview").`)}
+  /forge          Discovery interview → BRIEF.md
   /draft-prd      Generate PRD.md from BRIEF.md
   /draft-spec     Generate SPEC.md from PRD.md
   /draft-design   Generate DESIGN.md from PRD.md (optional)
@@ -84,8 +102,8 @@ async function runInteractiveSetup() {
   console.log(chalk.bold('\n📦 Installing forge skills (21) and agents (12)...\n'));
   for (const toolKey of selectedTools) {
     const tool = detected.find(t => t.key === toolKey);
-    await installToTool(tool, FORGE_ROOT);
-    console.log(chalk.green('  ✓') + ` Installed to ${tool.name}`);
+    const result = await installToTool(tool, FORGE_ROOT);
+    console.log(chalk.green('  ✓') + ' ' + formatInstallSummary(tool, result));
   }
 
   console.log();
@@ -145,13 +163,82 @@ async function commandInstall() {
 
   for (const toolKey of selectedTools) {
     const tool = detected.find(t => t.key === toolKey);
-    await installToTool(tool, FORGE_ROOT);
-    console.log(chalk.green('  ✓') + ` Installed to ${tool.name}`);
+    const result = await installToTool(tool, FORGE_ROOT);
+    console.log(chalk.green('  ✓') + ' ' + formatInstallSummary(tool, result));
   }
 
   console.log(chalk.bold.green('\n✅ Done\n'));
 }
 
+async function commandDoctor() {
+  console.log(chalk.bold('\n🔨 forge doctor\n'));
+
+  const detected = detectTools();
+  if (detected.length === 0) {
+    console.log(chalk.red('  ⚠️  No supported AI coding tools detected.'));
+    console.log(chalk.dim('  Install one of: Claude Code, Codex CLI, Cursor, Gemini CLI'));
+    console.log(chalk.dim('  Then re-run: npx @firatcand/forge\n'));
+    process.exit(1);
+  }
+
+  let anyDrift = false;
+  for (const tool of detected) {
+    const audit = await auditTool(tool, FORGE_ROOT);
+    const agentLabelWord = tool.key === 'codex' ? 'subagents' : 'agents';
+
+    const skillsStaleSuffix = audit.staleSkills.length > 0
+      ? chalk.yellow(` (${audit.staleSkills.length} stale)`)
+      : '';
+    const skillsLabel = `${audit.installedSkills.length}/${audit.expectedSkills.length} skills${skillsStaleSuffix}`;
+
+    let agentsLabel = null;
+    if (audit.agentsTarget) {
+      const agentsStaleSuffix = audit.staleAgents.length > 0
+        ? chalk.yellow(` (${audit.staleAgents.length} stale)`)
+        : '';
+      agentsLabel = `${audit.installedAgents.length}/${audit.expectedAgents.length} ${agentLabelWord}${agentsStaleSuffix}`;
+    }
+
+    const toolDrift =
+      audit.missingSkills.length > 0 ||
+      audit.missingAgents.length > 0 ||
+      audit.staleSkills.length > 0 ||
+      audit.staleAgents.length > 0;
+
+    const statusIcon = toolDrift ? chalk.yellow('  ⚠') : chalk.green('  ✓');
+    const counts = agentsLabel ? `${skillsLabel}, ${agentsLabel}` : skillsLabel;
+    console.log(`${statusIcon} ${tool.name} — ${counts}`);
+    console.log(chalk.dim(`     skills:  ${tildify(audit.skillsTarget)}`));
+    if (audit.agentsTarget) {
+      console.log(chalk.dim(`     ${agentLabelWord}:  ${tildify(audit.agentsTarget)}`));
+    }
+
+    if (audit.missingSkills.length > 0) {
+      console.log(chalk.yellow(`     missing skills: ${audit.missingSkills.join(', ')}`));
+    }
+    if (audit.staleSkills.length > 0) {
+      console.log(chalk.yellow(`     stale skills:   ${audit.staleSkills.join(', ')}`));
+    }
+    if (audit.missingAgents.length > 0) {
+      console.log(chalk.yellow(`     missing ${agentLabelWord}: ${audit.missingAgents.join(', ')}`));
+    }
+    if (audit.staleAgents.length > 0) {
+      console.log(chalk.yellow(`     stale ${agentLabelWord}:   ${audit.staleAgents.join(', ')}`));
+    }
+
+    if (toolDrift) anyDrift = true;
+  }
+
+  console.log();
+  if (anyDrift) {
+    console.log(chalk.yellow('Some tools have missing or stale forge skills/agents.'));
+    console.log(chalk.dim('Run: ') + chalk.cyan('npx @firatcand/forge install') + chalk.dim(' to sync.\n'));
+    process.exit(1);
+  }
+
+  console.log(chalk.bold.green('✅ All detected tools are in sync\n'));
+}
+
 async function commandCompanions() {
   console.log(chalk.bold('\n🔨 forge companions\n'));
 
@@ -319,7 +406,7 @@ async function commandInit(projectNameArg) {
   console.log(chalk.bold.green('\n✅ Project initialized\n'));
   console.log(chalk.bold('Next:'));
   console.log('  Open your AI coding tool: ' + chalk.cyan('claude') + ' or ' + chalk.cyan('codex'));
-  console.log('  Run: ' + chalk.cyan('/forge') + ' (Socratic ideation → BRIEF.md)\n');
+  console.log('  Run: ' + chalk.cyan('/forge') + ' (discovery interview → BRIEF.md)\n');
 }
 
 async function main() {
@@ -331,6 +418,9 @@ async function main() {
       case 'install':
         await commandInstall();
         break;
+      case 'doctor':
+        await commandDoctor();
+        break;
       case 'companions':
         await commandCompanions();
         break;

package/lib/tools.js

@@ -1,7 +1,38 @@
 import path from 'path';
 import os from 'os';
+import crypto from 'crypto';
 import fs from 'fs-extra';
 
+const HASH_IGNORE = new Set(['.DS_Store', 'Thumbs.db', '.git']);
+
+async function hashEntry(entryPath) {
+  let stat;
+  try {
+    stat = await fs.stat(entryPath);
+  } catch {
+    return null;
+  }
+  if (stat.isFile()) {
+    const buf = await fs.readFile(entryPath);
+    return crypto.createHash('sha256').update(buf).digest('hex');
+  }
+  if (stat.isDirectory()) {
+    const entries = (await fs.readdir(entryPath))
+      .filter(name => !HASH_IGNORE.has(name))
+      .sort();
+    const hash = crypto.createHash('sha256');
+    for (const name of entries) {
+      const childHash = await hashEntry(path.join(entryPath, name));
+      if (childHash === null) continue;
+      hash.update(name);
+      hash.update('\0');
+      hash.update(childHash);
+    }
+    return hash.digest('hex');
+  }
+  return null;
+}
+
 const TOOL_DEFINITIONS = [
   {
     key: 'claude',
@@ -53,6 +84,7 @@ export async function installToTool(tool, forgeRoot) {
     await fs.copy(src, dst, { overwrite: true, errorOnExist: false });
   }
 
+  let agentsCount = 0;
   if (agentsTarget) {
     const agentsSource = path.join(forgeRoot, 'agents');
     if (await fs.pathExists(agentsSource)) {
@@ -63,6 +95,76 @@ export async function installToTool(tool, forgeRoot) {
         await fs.remove(dst);
         await fs.copy(src, dst, { overwrite: true, errorOnExist: false });
       }
+      agentsCount = agents.length;
     }
   }
+
+  return {
+    skillsCount: skills.length,
+    agentsCount,
+    skillsTarget,
+    agentsTarget,
+  };
+}
+
+export async function listExpectedSkills(forgeRoot) {
+  return fs.readdir(path.join(forgeRoot, 'skills'));
+}
+
+export async function listExpectedAgents(forgeRoot) {
+  const agentsSource = path.join(forgeRoot, 'agents');
+  if (!(await fs.pathExists(agentsSource))) return [];
+  return fs.readdir(agentsSource);
+}
+
+async function diffByContent(names, sourceDir, targetDir) {
+  const stale = [];
+  for (const name of names) {
+    const sourceHash = await hashEntry(path.join(sourceDir, name));
+    const targetHash = await hashEntry(path.join(targetDir, name));
+    if (sourceHash !== targetHash) stale.push(name);
+  }
+  return stale;
+}
+
+export async function auditTool(tool, forgeRoot) {
+  const expectedSkills = await listExpectedSkills(forgeRoot);
+  const skillsTarget = path.join(tool.dir, tool.skillsDir);
+  const skillsSource = path.join(forgeRoot, 'skills');
+  const skillsInstalled = (await fs.pathExists(skillsTarget))
+    ? new Set(await fs.readdir(skillsTarget))
+    : new Set();
+  const installedSkills = expectedSkills.filter(s => skillsInstalled.has(s));
+  const missingSkills = expectedSkills.filter(s => !skillsInstalled.has(s));
+  const staleSkills = await diffByContent(installedSkills, skillsSource, skillsTarget);
+
+  let agentsTarget = null;
+  let expectedAgents = [];
+  let installedAgents = [];
+  let missingAgents = [];
+  let staleAgents = [];
+  if (tool.agentsDir) {
+    agentsTarget = path.join(tool.dir, tool.agentsDir);
+    const agentsSource = path.join(forgeRoot, 'agents');
+    expectedAgents = await listExpectedAgents(forgeRoot);
+    const agentsInstalled = (await fs.pathExists(agentsTarget))
+      ? new Set(await fs.readdir(agentsTarget))
+      : new Set();
+    installedAgents = expectedAgents.filter(a => agentsInstalled.has(a));
+    missingAgents = expectedAgents.filter(a => !agentsInstalled.has(a));
+    staleAgents = await diffByContent(installedAgents, agentsSource, agentsTarget);
+  }
+
+  return {
+    skillsTarget,
+    expectedSkills,
+    installedSkills,
+    missingSkills,
+    staleSkills,
+    agentsTarget,
+    expectedAgents,
+    installedAgents,
+    missingAgents,
+    staleAgents,
+  };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firatcand/forge",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "A lightweight framework for shipping software products from idea to production with AI coding agents (Claude Code, Codex CLI, Cursor, Gemini)",
   "type": "module",
   "bin": {

package/skills/forge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: forge
-description: Apply Socratic pressure to a raw idea and produce a validated project BRIEF. Heavy ceremony — 6 forcing questions. The required first command for any new forge project.
+description: Run forge's discovery interview over a raw idea and produce a validated project BRIEF. Heavy ceremony — 6 forcing questions. The required first command for any new forge project.
 tools: Read, Write, Edit, Bash(git*)
 ---
 
@@ -71,7 +71,7 @@ BRIEF written to spec/BRIEF.md
 Gate 1 — review the brief. To proceed:
   • /draft-prd to generate the PRD
   • Edit spec/BRIEF.md directly for fixes
-  • /forge --refine [section] to re-Socratic a weak section
+  • /forge --refine [section] to re-interview a weak section
 ```
 
 ## --refine mode

package/templates/CLAUDE.project.template.md

@@ -22,7 +22,7 @@
 - New API routes must have input validation
 - See `spec/` for full conventions
 
-## Forge principles (auto-applied — see ~/.forge/ETHOS.md)
+## Forge principles (auto-applied — see [Forge ETHOS.md](https://github.com/firatcand/forge/blob/main/ETHOS.md))
 1. Boil the Lake — refuse weak inputs
 2. Iron Law of Investigation — no fixes without RCA
 3. Confusion Protocol — clarify, don't guess