@firatcand/forge 0.1.0

package/bin/forge.js

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+
+import { checkbox, input, confirm } from '@inquirer/prompts';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import path from 'path';
+import { execSync } from 'child_process';
+
+import { detectTools, installToTool } from '../lib/tools.js';
+import { COMPANIONS, installCompanion } from '../lib/companions.js';
+import { FORGE_ROOT, getPackageVersion } from '../lib/paths.js';
+
+function showHelp() {
+  console.log(`
+${chalk.bold('🔨 forge')} — A lightweight framework for shipping software products with AI coding agents
+
+${chalk.bold('Usage:')}
+  npx @firatcand/forge                  Run interactive setup (default)
+  npx @firatcand/forge install          Install forge skills + agents only
+  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
+  /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)
+  /ingest-spec    Validate spec docs
+  /decompose      spec → phases.yaml
+  /setup-repo     GitHub repo + workflows + branch protection
+  /push-to-linear Linear project + cycles + issues
+  /pickup-task    Claim next task, create worktree
+  /plan-task      Plan mode for task
+  /implement      Execute plan
+  /review         Multi-agent review
+  /qa             Tests + browser checks
+  /codex          Second-opinion review via Codex CLI
+  /ship           Push branch, open PR
+  /learn          Capture learning
+  /phase-gate     Advance phase ceremony
+  /retro          Phase retrospective
+
+${chalk.dim('More: https://github.com/firatcand/forge')}
+`);
+}
+
+async function runInteractiveSetup() {
+  console.log(chalk.bold('\n🔨 forge') + chalk.dim(` v${getPackageVersion()}`));
+  console.log(chalk.dim('A lightweight framework for shipping software products with AI coding agents\n'));
+
+  console.log(chalk.bold('Detecting installed AI coding tools...'));
+  const detected = detectTools();
+
+  if (detected.length === 0) {
+    console.log(chalk.red('\n  ⚠️  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);
+  }
+
+  for (const tool of detected) {
+    console.log(chalk.green('  ✓') + ' ' + tool.name + chalk.dim(' (' + tool.dir + ')'));
+  }
+  console.log();
+
+  let selectedTools;
+  if (detected.length === 1) {
+    selectedTools = [detected[0].key];
+    console.log(chalk.dim(`Installing to ${detected[0].name} (only tool detected).\n`));
+  } else {
+    selectedTools = await checkbox({
+      message: 'Install forge skills + agents to:',
+      choices: detected.map(t => ({
+        value: t.key,
+        name: t.name,
+        checked: true,
+      })),
+      validate: (answer) => answer.length > 0 || 'Select at least one tool.',
+    });
+  }
+
+  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}`);
+  }
+
+  console.log();
+  const wantsCompanions = await confirm({
+    message: 'Install founder-skills companions? These extend /draft-prd, /draft-spec, /draft-design, and /review with deeper domain expertise.',
+    default: true,
+  });
+
+  if (wantsCompanions) {
+    const selectedCompanions = await checkbox({
+      message: 'Choose which companions to install (Space to select, Enter to confirm):',
+      choices: COMPANIONS.map(c => ({
+        value: c.value,
+        name: `${c.name} ${chalk.dim(`(${c.description})`)}`,
+        checked: c.recommended,
+      })),
+    });
+
+    if (selectedCompanions.length > 0) {
+      console.log(chalk.bold(`\n📦 Installing ${selectedCompanions.length} companion(s) via npx skills...\n`));
+      for (const slug of selectedCompanions) {
+        try {
+          await installCompanion(slug, selectedTools);
+          console.log(chalk.green('  ✓') + ` ${slug}`);
+        } catch (err) {
+          console.log(chalk.yellow('  ⚠️') + ` ${slug} — ${err.message}`);
+        }
+      }
+    }
+  }
+
+  console.log(chalk.bold.green('\n✅ Forge installed successfully\n'));
+  console.log(chalk.bold('Next steps:'));
+  console.log('  1. ' + chalk.cyan('cd into a project directory'));
+  console.log('  2. ' + chalk.cyan('npx @firatcand/forge init') + ' — initialize project structure');
+  console.log('  3. Open your AI coding tool (claude, codex)');
+  console.log('  4. Run ' + chalk.cyan('/forge') + ' to start the lifecycle\n');
+  console.log(chalk.dim('Docs: https://github.com/firatcand/forge#quickstart\n'));
+}
+
+async function commandInstall() {
+  console.log(chalk.bold('\n🔨 forge install\n'));
+
+  const detected = detectTools();
+  if (detected.length === 0) {
+    console.log(chalk.red('No supported tools detected.'));
+    process.exit(1);
+  }
+
+  const selectedTools = detected.length === 1
+    ? [detected[0].key]
+    : await checkbox({
+        message: 'Install to:',
+        choices: detected.map(t => ({ value: t.key, name: t.name, checked: true })),
+        validate: (a) => a.length > 0 || 'Select at least one.',
+      });
+
+  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}`);
+  }
+
+  console.log(chalk.bold.green('\n✅ Done\n'));
+}
+
+async function commandCompanions() {
+  console.log(chalk.bold('\n🔨 forge companions\n'));
+
+  const detected = detectTools();
+  if (detected.length === 0) {
+    console.log(chalk.red('No supported tools detected.'));
+    process.exit(1);
+  }
+
+  const selectedCompanions = await checkbox({
+    message: 'Choose which founder-skills companions to install:',
+    choices: COMPANIONS.map(c => ({
+      value: c.value,
+      name: `${c.name} ${chalk.dim(`(${c.description})`)}`,
+      checked: c.recommended,
+    })),
+    validate: (a) => a.length > 0 || 'Select at least one.',
+  });
+
+  const selectedTools = detected.length === 1
+    ? [detected[0].key]
+    : await checkbox({
+        message: 'Install companions to:',
+        choices: detected.map(t => ({ value: t.key, name: t.name, checked: true })),
+        validate: (a) => a.length > 0 || 'Select at least one.',
+      });
+
+  for (const slug of selectedCompanions) {
+    try {
+      await installCompanion(slug, selectedTools);
+      console.log(chalk.green('  ✓') + ` ${slug}`);
+    } catch (err) {
+      console.log(chalk.yellow('  ⚠️') + ` ${slug} — ${err.message}`);
+    }
+  }
+
+  console.log(chalk.bold.green('\n✅ Done\n'));
+}
+
+async function commandInit(projectNameArg) {
+  console.log(chalk.bold('\n🔨 forge init\n'));
+
+  const cwd = process.cwd();
+
+  if (await fs.pathExists(path.join(cwd, 'CLAUDE.md'))) {
+    const overwrite = await confirm({
+      message: 'CLAUDE.md already exists. Overwrite?',
+      default: false,
+    });
+    if (!overwrite) {
+      console.log(chalk.dim('Cancelled.\n'));
+      process.exit(0);
+    }
+  }
+
+  const projectName = projectNameArg || await input({
+    message: 'Project name:',
+    default: path.basename(cwd),
+  });
+
+  const initGit = await fs.pathExists(path.join(cwd, '.git'))
+    ? false
+    : await confirm({ message: 'Initialize git repo?', default: true });
+
+  console.log(chalk.bold('\n📁 Creating directory structure...'));
+  await fs.ensureDir(path.join(cwd, 'spec'));
+  await fs.ensureDir(path.join(cwd, 'plans', 'tasks'));
+  await fs.ensureDir(path.join(cwd, 'docs', 'learnings'));
+  await fs.ensureDir(path.join(cwd, 'docs', 'retros'));
+  console.log(chalk.green('  ✓') + ' spec/, plans/, docs/{learnings,retros}/');
+
+  console.log(chalk.bold('\n📄 Copying templates...'));
+  const templatesDir = path.join(FORGE_ROOT, 'templates');
+
+  const claudeTemplate = await fs.readFile(
+    path.join(templatesDir, 'CLAUDE.project.template.md'),
+    'utf-8'
+  );
+  await fs.writeFile(
+    path.join(cwd, 'CLAUDE.md'),
+    claudeTemplate.replaceAll('{{PROJECT_NAME}}', projectName)
+  );
+  console.log(chalk.green('  ✓') + ' CLAUDE.md');
+
+  const criticalPath = path.join(cwd, 'CRITICAL.md');
+  let writeCritical = true;
+  if (await fs.pathExists(criticalPath)) {
+    writeCritical = await confirm({
+      message: 'CRITICAL.md already exists. Overwrite?',
+      default: false,
+    });
+  }
+  if (writeCritical) {
+    await fs.copy(
+      path.join(templatesDir, 'CRITICAL.template.md'),
+      criticalPath,
+      { overwrite: true }
+    );
+    console.log(chalk.green('  ✓') + ' CRITICAL.md');
+  } else {
+    console.log(chalk.dim('  - CRITICAL.md (kept existing)'));
+  }
+
+  const projectTemplates = path.join(cwd, 'templates');
+  let copyTemplates = true;
+  if (await fs.pathExists(projectTemplates)) {
+    copyTemplates = await confirm({
+      message: 'templates/ already exists. Refresh from forge templates? (your edits will be overwritten)',
+      default: false,
+    });
+  }
+  if (copyTemplates) {
+    const skipList = new Set(['CLAUDE.project.template.md', 'CRITICAL.template.md']);
+    await fs.ensureDir(projectTemplates);
+    const entries = await fs.readdir(templatesDir);
+    for (const entry of entries) {
+      if (skipList.has(entry)) continue;
+      await fs.copy(
+        path.join(templatesDir, entry),
+        path.join(projectTemplates, entry),
+        { overwrite: true }
+      );
+    }
+    console.log(chalk.green('  ✓') + ' templates/ (BRIEF, PRD, SPEC, DESIGN, phases, retro, learning + github-workflows/)');
+  } else {
+    console.log(chalk.dim('  - templates/ (kept existing)'));
+  }
+
+  if (!await fs.pathExists(path.join(cwd, '.env.example'))) {
+    await fs.writeFile(
+      path.join(cwd, '.env.example'),
+      '# Environment variables — populate based on spec/SPEC.md\n# Copy to .env (gitignored) for local development\n'
+    );
+    console.log(chalk.green('  ✓') + ' .env.example');
+  }
+
+  const gitignorePath = path.join(cwd, '.gitignore');
+  const forgeIgnoreLines = [
+    '# Forge defaults',
+    '.env',
+    '.env.local',
+    '.env.production',
+    'node_modules/',
+    '*.log',
+    '.DS_Store',
+  ];
+  let existing = '';
+  if (await fs.pathExists(gitignorePath)) {
+    existing = await fs.readFile(gitignorePath, 'utf-8');
+  }
+  if (!existing.includes('# Forge defaults')) {
+    await fs.writeFile(gitignorePath, existing + '\n' + forgeIgnoreLines.join('\n') + '\n');
+    console.log(chalk.green('  ✓') + ' .gitignore (forge defaults appended)');
+  }
+
+  if (initGit) {
+    try {
+      execSync('git init', { cwd, stdio: 'ignore' });
+      console.log(chalk.green('  ✓') + ' git initialized');
+    } catch (err) {
+      console.log(chalk.yellow('  ⚠️') + ' git init failed (is git installed?)');
+    }
+  }
+
+  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');
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  try {
+    switch (command) {
+      case 'install':
+        await commandInstall();
+        break;
+      case 'companions':
+        await commandCompanions();
+        break;
+      case 'init':
+        await commandInit(args[1]);
+        break;
+      case '-h':
+      case '--help':
+      case 'help':
+        showHelp();
+        break;
+      case '-v':
+      case '--version':
+        console.log(getPackageVersion());
+        break;
+      case undefined:
+        await runInteractiveSetup();
+        break;
+      default:
+        console.log(chalk.red(`Unknown command: ${command}\n`));
+        showHelp();
+        process.exit(1);
+    }
+  } catch (err) {
+    if (err.name === 'ExitPromptError') {
+      console.log(chalk.dim('\nCancelled.\n'));
+      process.exit(0);
+    }
+    console.error(chalk.red('\n❌ Error:'), err.message);
+    if (process.env.DEBUG) console.error(err.stack);
+    process.exit(1);
+  }
+}
+
+main();

package/lib/companions.js

@@ -0,0 +1,67 @@
+import { spawnSync } from 'child_process';
+
+export const COMPANIONS = [
+  {
+    value: 'product-spec',
+    name: 'product-spec',
+    description: 'powers /draft-prd',
+    sourceUrl: 'https://github.com/firatcand/founder-skills/tree/main/skills/product-spec',
+    recommended: true,
+  },
+  {
+    value: 'software-architect',
+    name: 'software-architect',
+    description: 'powers /draft-spec',
+    sourceUrl: 'https://github.com/firatcand/founder-skills/tree/main/skills/software-architect',
+    recommended: true,
+  },
+  {
+    value: 'ux-design',
+    name: 'ux-design',
+    description: 'powers /draft-design',
+    sourceUrl: 'https://github.com/firatcand/founder-skills/tree/main/skills/ux-design',
+    recommended: false,
+  },
+  {
+    value: 'ui-design',
+    name: 'ui-design',
+    description: 'powers /review for UI tasks',
+    sourceUrl: 'https://github.com/firatcand/founder-skills/tree/main/skills/ui-design',
+    recommended: false,
+  },
+];
+
+const TOOL_KEY_TO_AGENT_ID = {
+  claude: 'claude-code',
+  codex: 'codex',
+  cursor: 'cursor',
+  gemini: 'gemini-cli',
+};
+
+export async function installCompanion(slug, targetTools) {
+  const companion = COMPANIONS.find(c => c.value === slug);
+  if (!companion) {
+    throw new Error(`Unknown companion: ${slug}`);
+  }
+
+  const agentIds = (targetTools ?? [])
+    .map(key => TOOL_KEY_TO_AGENT_ID[key])
+    .filter(Boolean);
+
+  const args = ['-y', 'skills', 'add', companion.sourceUrl, '--global', '--yes'];
+  if (agentIds.length > 0) {
+    args.push('--agent', ...agentIds);
+  }
+
+  const result = spawnSync('npx', args, {
+    stdio: 'pipe',
+    encoding: 'utf-8',
+  });
+
+  if (result.status !== 0) {
+    throw new Error(
+      result.stderr?.split('\n')[0] ||
+      `npx skills failed (exit code ${result.status})`
+    );
+  }
+}

package/lib/github-helpers.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# github-helpers.sh — gh CLI wrappers used by /setup-repo.
+#
+# Source this file: `source "${FORGE_DIR}/lib/github-helpers.sh"`
+
+set -euo pipefail
+
+# ──────────────────────────────────────────────
+# Logging
+# ──────────────────────────────────────────────
+_log()  { printf '\033[1;35m[gh]\033[0m %s\n' "$*" >&2; }
+_warn() { printf '\033[1;33m[gh]\033[0m %s\n' "$*" >&2; }
+_err()  { printf '\033[1;31m[gh]\033[0m %s\n' "$*" >&2; }
+
+# ──────────────────────────────────────────────
+# gh_check_auth
+# Verifies that gh CLI is installed and authenticated.
+# Returns 0 if ready, 1 otherwise.
+# ──────────────────────────────────────────────
+gh_check_auth() {
+  if ! command -v gh >/dev/null 2>&1; then
+    _err "gh CLI not installed. https://cli.github.com/"
+    return 1
+  fi
+
+  if ! gh auth status >/dev/null 2>&1; then
+    _err "gh CLI not authenticated. Run: gh auth login"
+    return 1
+  fi
+
+  _log "gh CLI ready"
+}
+
+# ──────────────────────────────────────────────
+# gh_create_repo NAME [PRIVACY=private]
+# Creates a GitHub repo from current directory and sets origin remote.
+# Skips creation if origin remote already configured.
+# ──────────────────────────────────────────────
+gh_create_repo() {
+  local name="${1:?name required}"
+  local privacy="${2:-private}"
+
+  if git remote get-url origin >/dev/null 2>&1; then
+    _warn "origin remote already configured: $(git remote get-url origin)"
+    return 0
+  fi
+
+  _log "Creating repo: ${name} (${privacy})"
+  gh repo create "${name}" "--${privacy}" --source=. --remote=origin
+}
+
+# ──────────────────────────────────────────────
+# gh_protect_branch BRANCH [REQUIRE_REVIEWS=1] [REQUIRE_CHECKS_CSV=test]
+# Sets branch protection: require PR review, require status checks, no
+# direct pushes, no force pushes.
+# ──────────────────────────────────────────────
+gh_protect_branch() {
+  local branch="${1:?branch required}"
+  local require_reviews="${2:-1}"
+  local require_checks="${3:-test}"
+
+  local repo
+  repo=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
+
+  _log "Protecting ${repo}:${branch}"
+
+  local checks_json
+  checks_json=$(printf '%s\n' "${require_checks}" | tr ',' '\n' | jq -R . | jq -sc '{strict: true, contexts: .}')
+
+  local payload
+  payload=$(jq -n \
+    --argjson reviews "${require_reviews}" \
+    --argjson checks "${checks_json}" \
+    '{required_status_checks: $checks,
+      enforce_admins: true,
+      required_pull_request_reviews: {required_approving_review_count: $reviews},
+      restrictions: null,
+      allow_force_pushes: false,
+      allow_deletions: false}')
+
+  gh api -X PUT \
+    "repos/${repo}/branches/${branch}/protection" \
+    -H "Accept: application/vnd.github+json" \
+    --input - <<<"${payload}" >/dev/null
+
+  _log "✓ ${branch} protected"
+}
+
+# ──────────────────────────────────────────────
+# gh_create_environment NAME [REQUIRE_APPROVAL=false]
+# Creates a GitHub Environment. Set REQUIRE_APPROVAL=true to gate deploys.
+# ──────────────────────────────────────────────
+gh_create_environment() {
+  local name="${1:?name required}"
+  local require_approval="${2:-false}"
+
+  local repo
+  repo=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
+
+  _log "Creating environment: ${name}"
+
+  local reviewers='[]'
+  if [[ "${require_approval}" == "true" ]]; then
+    local user_id
+    user_id=$(gh api user -q '.id')
+    reviewers=$(jq -nc --argjson id "${user_id}" '[{type: "User", id: $id}]')
+  fi
+
+  local payload
+  payload=$(jq -n --argjson reviewers "${reviewers}" \
+    '{wait_timer: 0, reviewers: $reviewers, deployment_branch_policy: null}')
+
+  gh api -X PUT \
+    "repos/${repo}/environments/${name}" \
+    -H "Accept: application/vnd.github+json" \
+    --input - <<<"${payload}" >/dev/null
+
+  _log "✓ environment ${name} (approval: ${require_approval})"
+}
+
+# ──────────────────────────────────────────────
+# gh_set_secret KEY VALUE
+# Sets a repo-level GitHub Actions secret. Reads VALUE from arg or stdin.
+# ──────────────────────────────────────────────
+gh_set_secret() {
+  local key="${1:?key required}"
+  local value="${2:-}"
+
+  if [[ -z "${value}" ]]; then
+    if [[ -t 0 ]]; then
+      _err "VALUE not provided (arg or stdin)"
+      return 1
+    fi
+    value=$(cat)
+  fi
+
+  printf '%s' "${value}" | gh secret set "${key}"
+  _log "✓ secret ${key} set"
+}
+
+# ──────────────────────────────────────────────
+# gh_set_oauth_token VALUE
+# Convenience: sets CLAUDE_CODE_OAUTH_TOKEN as a repo secret.
+# ──────────────────────────────────────────────
+gh_set_oauth_token() {
+  local token="${1:?token required}"
+  gh_set_secret CLAUDE_CODE_OAUTH_TOKEN "${token}"
+}