forge-workflow 0.0.2 → 0.0.4

package/lib/plugin-catalog.js

@@ -24,10 +24,10 @@ const STAGES = Object.freeze({
   RESEARCH: 'research',
   PLAN: 'plan',
   DEV: 'dev',
-  CHECK: 'check',
+  VALIDATE: 'validate',
   SHIP: 'ship',
   REVIEW: 'review',
-  MERGE: 'merge',
+  PREMERGE: 'premerge',
 });
 
 const BUDGET_MODES = Object.freeze({
@@ -101,16 +101,6 @@ const CATALOG = Object.freeze({
     detectWhen: [],
     install: { method: 'npm', cmd: 'bun add -g @beads/bd' },
   },
-  openspec: {
-    name: 'OpenSpec',
-    type: 'cli',
-    tier: 'free',
-    stage: 'plan',
-    description: 'Spec-driven development proposals',
-    detectWhen: [],
-    install: { method: 'npm', cmd: 'bun add -g @fission-ai/openspec' },
-  },
-
   // ── Dev ──
   'typescript-lsp': {
     name: 'TypeScript LSP',
@@ -155,7 +145,7 @@ const CATALOG = Object.freeze({
     name: 'ESLint',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'JavaScript/TypeScript linting',
     detectWhen: ['file:eslint.config.js', 'dep:eslint'],
     install: { method: 'npm', cmd: 'bun add -D eslint', dev: true },
@@ -164,7 +154,7 @@ const CATALOG = Object.freeze({
     name: 'Biome',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Fast formatter and linter',
     detectWhen: ['file:biome.json'],
     install: { method: 'npm', cmd: 'bun add -D @biomejs/biome', dev: true },
@@ -173,7 +163,7 @@ const CATALOG = Object.freeze({
     name: 'Prettier',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Opinionated code formatter',
     detectWhen: ['file:.prettierrc'],
     install: { method: 'npm', cmd: 'bun add -D prettier', dev: true },
@@ -182,7 +172,7 @@ const CATALOG = Object.freeze({
     name: 'ESLint Security Plugin',
     type: 'config',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Security-focused ESLint rules',
     detectWhen: ['dep:express', 'dep:fastify'],
     install: { method: 'npm', cmd: 'bun add -D eslint-plugin-security', dev: true },
@@ -191,7 +181,7 @@ const CATALOG = Object.freeze({
     name: 'SonarCloud Analysis',
     type: 'skill',
     tier: 'free-public',
-    stage: 'check',
+    stage: 'validate',
     description: 'Code quality and security analysis via SonarCloud REST API',
     detectWhen: [],
     install: {
@@ -204,7 +194,7 @@ const CATALOG = Object.freeze({
     name: 'Sonar Scanner',
     type: 'cli',
     tier: 'free-public',
-    stage: 'check',
+    stage: 'validate',
     description: 'SonarCloud/SonarQube CLI scanner',
     detectWhen: ['file:sonar-project.properties'],
     install: { method: 'npm', cmd: 'bun add -D sonarqube-scanner', dev: true },
@@ -214,7 +204,7 @@ const CATALOG = Object.freeze({
     name: 'CodeQL',
     type: 'cli',
     tier: 'free-public',
-    stage: 'check',
+    stage: 'validate',
     description: 'Semantic code analysis by GitHub',
     detectWhen: [],
     install: { method: 'binary', cmd: 'GitHub-provided (github.com/github/codeql-action)' },
@@ -224,7 +214,7 @@ const CATALOG = Object.freeze({
     name: 'npm audit',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Dependency vulnerability scanning',
     detectWhen: [],
     install: { method: 'npm', cmd: 'built-in (bun pm audit)' },
@@ -233,7 +223,7 @@ const CATALOG = Object.freeze({
     name: 'Vitest',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Vite-native test runner',
     detectWhen: ['dep:vitest', 'file:vitest.config.ts'],
     install: { method: 'npm', cmd: 'bun add -D vitest', dev: true },
@@ -242,7 +232,7 @@ const CATALOG = Object.freeze({
     name: 'Jest',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Delightful JavaScript testing',
     detectWhen: ['dep:jest', 'file:jest.config.js'],
     install: { method: 'npm', cmd: 'bun add -D jest', dev: true },
@@ -251,7 +241,7 @@ const CATALOG = Object.freeze({
     name: 'Playwright',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'End-to-end browser testing',
     detectWhen: ['dep:@playwright/test'],
     install: { method: 'npm', cmd: 'bun add -D @playwright/test', dev: true },
@@ -260,7 +250,7 @@ const CATALOG = Object.freeze({
     name: 'c8',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Native V8 code coverage',
     detectWhen: [],
     install: { method: 'npm', cmd: 'bun add -D c8', dev: true },
@@ -269,7 +259,7 @@ const CATALOG = Object.freeze({
     name: 'Stryker',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Mutation testing for JavaScript',
     detectWhen: [],
     install: { method: 'npm', cmd: 'bun add -D @stryker-mutator/core', dev: true },
@@ -278,7 +268,7 @@ const CATALOG = Object.freeze({
     name: 'Oxlint',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Blazing-fast Rust-based linter',
     detectWhen: [],
     install: { method: 'npm', cmd: 'bun add -D oxlint', dev: true },
@@ -341,7 +331,7 @@ const CATALOG = Object.freeze({
     name: 'Changesets',
     type: 'cli',
     tier: 'free',
-    stage: 'merge',
+    stage: 'premerge',
     description: 'Versioning and changelog management',
     detectWhen: ['file:package.json'],
     install: { method: 'npm', cmd: 'bun add -D @changesets/cli', dev: true },
@@ -350,7 +340,7 @@ const CATALOG = Object.freeze({
     name: 'Release Please',
     type: 'config',
     tier: 'free',
-    stage: 'merge',
+    stage: 'premerge',
     description: 'Automated release PRs by Google',
     detectWhen: [],
     install: { method: 'config', cmd: 'GitHub Action (google-github-actions/release-please-action)' },

package/lib/setup-action-log.js

@@ -0,0 +1,139 @@
+/**
+ * Centralized action log for setup operations.
+ *
+ * Collects file-level actions (created, skipped, merged, etc.) during
+ * `forge setup` so the CLI can display a structured summary at the end.
+ *
+ * @module setup-action-log
+ */
+
+/** Map of directory prefixes to human-readable agent names. */
+const AGENT_PREFIXES = {
+  '.claude/': 'Claude Code',
+  '.cursor/': 'Cursor',
+  '.windsurf/': 'Windsurf',
+  '.cline/': 'Cline',
+  '.codex/': 'Codex',
+  '.opencode/': 'OpenCode',
+  '.kilocode/': 'Kilocode',
+  '.roo/': 'Roo Code',
+  '.github/prompts/': 'GitHub Copilot'
+};
+
+/**
+ * Detect the agent name from a file path.
+ *
+ * @param {string} filePath - Relative file path (e.g. `.claude/settings.json`)
+ * @returns {string} Agent name or `'General'` if no agent prefix matches
+ */
+function detectAgent(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  for (const [prefix, name] of Object.entries(AGENT_PREFIXES)) {
+    if (normalized.startsWith(prefix)) {
+      return name;
+    }
+  }
+  return 'General';
+}
+
+/**
+ * Strip the agent directory prefix from a file path.
+ *
+ * @param {string} filePath - Relative file path
+ * @returns {string} Path with the leading agent directory removed
+ */
+function stripAgentPrefix(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  for (const prefix of Object.keys(AGENT_PREFIXES)) {
+    if (normalized.startsWith(prefix)) {
+      return normalized.slice(prefix.length);
+    }
+  }
+  return normalized;
+}
+
+class SetupActionLog {
+  constructor() {
+    /** @type {Array<{file: string, action: string, detail: string|null}>} */
+    this.actions = [];
+  }
+
+  /**
+   * Record a setup action.
+   *
+   * @param {string} file   - Relative file path that was acted on
+   * @param {string} action - One of: created, skipped, merged, conflict, removed, force-created
+   * @param {string|null} [detail=null] - Optional human-readable detail
+   */
+  add(file, action, detail = null) {
+    this.actions.push({ file, action, detail });
+  }
+
+  /**
+   * Get counts grouped by action type.
+   *
+   * @returns {Record<string, number>} e.g. `{ created: 4, skipped: 2 }`
+   */
+  getSummary() {
+    const counts = {};
+    for (const { action } of this.actions) {
+      counts[action] = (counts[action] || 0) + 1;
+    }
+    return counts;
+  }
+
+  /**
+   * Get the full ordered list of actions.
+   *
+   * @returns {Array<{file: string, action: string, detail: string|null}>}
+   */
+  getVerbose() {
+    return this.actions;
+  }
+
+  /**
+   * Group files by detected agent name.
+   *
+   * Each agent key maps to an object whose keys are action types and whose
+   * values are arrays of file paths (with the agent prefix stripped).
+   *
+   * @returns {Record<string, Record<string, string[]>>}
+   */
+  getAgentSummary() {
+    const agents = {};
+    for (const { file, action } of this.actions) {
+      const agent = detectAgent(file);
+      const stripped = stripAgentPrefix(file);
+
+      if (!agents[agent]) {
+        agents[agent] = {};
+      }
+      if (!agents[agent][action]) {
+        agents[agent][action] = [];
+      }
+      agents[agent][action].push(stripped);
+    }
+    return agents;
+  }
+
+  /**
+   * Filter actions by type.
+   *
+   * @param {string} action - The action type to filter on
+   * @returns {Array<{file: string, action: string, detail: string|null}>}
+   */
+  getByAction(action) {
+    return this.actions.filter(a => a.action === action);
+  }
+
+  /**
+   * Total number of recorded actions.
+   *
+   * @returns {number}
+   */
+  get length() {
+    return this.actions.length;
+  }
+}
+
+module.exports = { SetupActionLog };

package/lib/setup-summary-renderer.js

@@ -0,0 +1,106 @@
+/**
+ * Renders a clean summary from SetupActionLog data.
+ *
+ * Default mode: 3-line concise output.
+ * Verbose mode: file-by-file detail grouped by agent.
+ *
+ * @module setup-summary-renderer
+ */
+
+/**
+ * Capitalize the first letter of a string.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+function capitalize(str) {
+  if (!str) return str;
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Render setup summary as a string.
+ *
+ * @param {import('./setup-action-log').SetupActionLog} actionLog - The populated action log
+ * @param {string[]} agentNames - List of configured agent slugs (e.g. ['claude', 'cursor'])
+ * @param {boolean} verbose - Whether to show file-by-file detail
+ * @returns {string} The formatted summary output
+ */
+function renderSetupSummary(actionLog, agentNames, verbose) {
+  if (verbose) {
+    return renderVerbose(actionLog, agentNames);
+  }
+  return renderDefault(actionLog, agentNames);
+}
+
+/**
+ * Render the default 3-line concise summary.
+ *
+ * @param {import('./setup-action-log').SetupActionLog} actionLog
+ * @param {string[]} agentNames
+ * @returns {string}
+ */
+function renderDefault(actionLog, agentNames) {
+  const agentCount = agentNames.length;
+  const agentLabel = agentCount === 1 ? '1 agent' : `${agentCount} agents`;
+  const agentList = agentNames.length > 0 ? ` (${agentNames.join(', ')})` : '';
+
+  const summary = actionLog.getSummary();
+
+  // Build counts line — only include non-zero actions
+  const displayOrder = ['created', 'skipped', 'merged', 'force-created', 'updated', 'conflict', 'removed'];
+  const parts = [];
+  for (const action of displayOrder) {
+    if (summary[action] && summary[action] > 0) {
+      parts.push(`${capitalize(action)}: ${summary[action]} ${summary[action] === 1 ? 'file' : 'files'}`);
+    }
+  }
+  // Include any actions not in displayOrder
+  for (const [action, count] of Object.entries(summary)) {
+    if (!displayOrder.includes(action) && count > 0) {
+      parts.push(`${capitalize(action)}: ${count} ${count === 1 ? 'file' : 'files'}`);
+    }
+  }
+
+  const lines = [];
+  lines.push(`Forge setup complete — ${agentLabel} configured${agentList}`);
+
+  if (parts.length > 0) {
+    lines.push(`  ${parts.join(' | ')}`);
+  } else {
+    lines.push('  0 files changed');
+  }
+
+  lines.push('  Run forge setup --verbose to see all files');
+
+  return lines.join('\n');
+}
+
+/**
+ * Render verbose file-by-file output grouped by agent.
+ *
+ * @param {import('./setup-action-log').SetupActionLog} actionLog
+ * @param {string[]} _agentNames - Not used in verbose (agents come from log data)
+ * @returns {string}
+ */
+function renderVerbose(actionLog, _agentNames) {
+  const agentSummary = actionLog.getAgentSummary();
+  const lines = [];
+
+  for (const [agent, actions] of Object.entries(agentSummary)) {
+    for (const [action, files] of Object.entries(actions)) {
+      const fileCount = files.length;
+      const fileLabel = fileCount === 1 ? '1 file' : `${fileCount} files`;
+      const fileList = files.join(', ');
+      lines.push(`${agent}: ${fileList} (${fileLabel}) [${action}]`);
+    }
+  }
+
+  if (lines.length === 0) {
+    return 'No file operations recorded.';
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { renderSetupSummary };

package/lib/setup.js

@@ -109,10 +109,84 @@ async function markStepComplete(projectPath, stepName) {
   await saveSetupState(projectPath, state);
 }
 
+/**
+ * Scaffold GitHub-Beads sync files into a target project.
+ * Copies workflow, config, and mapping template — never overwrites existing files.
+ *
+ * @param {string} projectPath - Target project root
+ * @param {string} pkgDir - Forge package directory (source of template files)
+ * @returns {Promise<{created: string[], skipped: string[]}>}
+ */
+async function scaffoldGithubBeadsSync(projectPath, pkgDir) {
+  const created = [];
+  const skipped = [];
+
+  // Sync script modules that workflows depend on at runtime
+  const syncScripts = [
+    'config.mjs', 'mapping.mjs', 'comment.mjs', 'github-api.mjs',
+    'sanitize.mjs', 'run-bd.mjs', 'label-mapper.mjs', 'index.mjs',
+    'reverse-sync.mjs', 'reverse-sync-cli.mjs',
+  ];
+
+  const files = [
+    // Phase 1: GitHub → Beads
+    {
+      src: path.join(pkgDir, '.github', 'workflows', 'github-to-beads.yml'),
+      dest: path.join('.github', 'workflows', 'github-to-beads.yml'),
+    },
+    // Phase 2: Beads → GitHub
+    {
+      src: path.join(pkgDir, '.github', 'workflows', 'beads-to-github.yml'),
+      dest: path.join('.github', 'workflows', 'beads-to-github.yml'),
+    },
+    {
+      src: path.join(pkgDir, 'scripts', 'github-beads-sync.config.json'),
+      dest: path.join('scripts', 'github-beads-sync.config.json'),
+    },
+    {
+      src: null, // generated in-place (empty mapping template)
+      dest: path.join('.github', 'beads-mapping.json'),
+      content: '{}',
+    },
+    // Sync script modules
+    ...syncScripts.map((name) => ({
+      src: path.join(pkgDir, 'scripts', 'github-beads-sync', name),
+      dest: path.join('scripts', 'github-beads-sync', name),
+    })),
+  ];
+
+  for (const file of files) {
+    const destPath = path.join(projectPath, file.dest);
+
+    // Never overwrite existing files — preserve user customizations
+    if (fs.existsSync(destPath)) {
+      skipped.push(file.dest);
+      continue;
+    }
+
+    // Ensure parent directory exists
+    const destDir = path.dirname(destPath);
+    await fs.promises.mkdir(destDir, { recursive: true });
+
+    if (file.src) {
+      // Copy from template
+      await fs.promises.copyFile(file.src, destPath);
+    } else {
+      // Write generated content
+      await fs.promises.writeFile(destPath, file.content, 'utf-8');
+    }
+
+    created.push(file.dest);
+  }
+
+  return { created, skipped };
+}
+
 module.exports = {
   saveSetupState,
   loadSetupState,
   isSetupComplete,
   getNextStep,
-  markStepComplete
+  markStepComplete,
+  scaffoldGithubBeadsSync
 };

package/lib/workflow-profiles.js

@@ -12,29 +12,26 @@
 const PROFILES = {
   critical: {
     name: 'Critical (Maximum Rigor)',
-    stages: ['/status', '/research', '/plan', '/dev', '/validate', '/ship', '/review', '/merge', '/verify'],
+    stages: ['/status', '/plan', '/dev', '/validate', '/ship', '/review', '/premerge', '/verify'],
     tdd: 'strict',
     research: 'required',
-    openspec: 'required-strategic',
     description: 'Security, auth, payments, data integrity, breaking changes',
     keywords: ['auth', 'security', 'payment', 'crypto', 'password', 'token', 'session', 'data-migration', 'breaking']
   },
 
   standard: {
     name: 'Standard (Full Workflow)',
-    stages: ['/status', '/plan', '/dev', '/validate', '/ship', '/merge'],
+    stages: ['/status', '/plan', '/dev', '/validate', '/ship', '/review', '/premerge'],
     tdd: 'required',
     research: 'optional',
-    openspec: 'strategic',
     description: 'Most features and non-critical enhancements'
   },
 
   simple: {
     name: 'Simple (Streamlined)',
-    stages: ['/dev', '/validate', '/ship', '/merge'],
+    stages: ['/dev', '/validate', '/ship', '/premerge'],
     tdd: 'recommended',
     research: 'skip',
-    openspec: 'no',
     description: 'UI tweaks, small improvements, minor fixes'
   },
 
@@ -43,26 +40,23 @@ const PROFILES = {
     stages: ['/dev', '/validate', '/ship'],
     tdd: 'required',  // Must reproduce bug
     research: 'skip',
-    openspec: 'no',
     description: 'Production bugs, urgent fixes',
     keywords: ['urgent', 'production', 'emergency', 'hotfix', 'critical']
   },
 
   docs: {
     name: 'Docs (Documentation Only)',
-    stages: ['/verify', '/ship', '/merge'],
+    stages: ['/verify', '/ship', '/premerge'],
     tdd: 'no',
     research: 'no',
-    openspec: 'no',
     description: 'Documentation updates, README changes'
   },
 
   refactor: {
     name: 'Refactor (Behavior-Preserving)',
-    stages: ['/plan', '/dev', '/validate', '/ship', '/merge'],
+    stages: ['/plan', '/dev', '/validate', '/ship', '/premerge'],
     tdd: 'strict',  // Must preserve behavior
     research: 'optional',
-    openspec: 'architectural',
     description: 'Code cleanup, optimization, behavior-preserving improvements'
   }
 };

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "forge-workflow",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "7-stage TDD workflow for ALL AI coding agents (Claude, Cursor, Cline, OpenCode, Copilot, Kilo Code, Roo Code, Codex)",
   "bin": {
     "forge": "bin/forge.js",
-    "forge-validate": "bin/forge-validate.js"
+    "forge-preflight": "bin/forge-preflight.js"
   },
   "workspaces": [
     "packages/*"
@@ -15,9 +15,8 @@
     "test:all": "bun run test:setup && bun test",
     "test:coverage": "c8 --check-coverage bun test",
     "typecheck": "echo 'No TypeScript in project - skipping type check'",
-    "lint": "eslint .",
+    "lint": "eslint . --max-warnings 0",
     "check": "bash scripts/validate.sh",
-    "postinstall": "node ./bin/forge.js",
     "prepare": "lefthook install || echo 'Note: lefthook not installed. Git hooks disabled. Run: bun add -d lefthook'",
     "setup": "node ./bin/forge.js setup",
     "help": "node ./bin/forge.js --help",
@@ -39,7 +38,7 @@
     "@commitlint/config-conventional": "^20.4.1",
     "@eslint/js": "^10.0.1",
     "@microsoft/eslint-formatter-sarif": "^3.1.0",
-    "@stryker-mutator/core": "^9.5.1",
+    "@stryker-mutator/core": "^9.6.0",
     "c8": "^11.0.0",
     "eslint": "^10.0.2",
     "globals": "^17.3.0",
@@ -76,12 +75,21 @@
   "files": [
     "bin/",
     "lib/",
+    "skills/",
     ".claude/commands/",
     ".claude/rules/",
     ".claude/scripts/",
-    ".forge/hooks/",
+    ".claude/skills/",
+    ".cursor/",
+    ".cline/",
+    ".roo/",
+    ".codex/",
+    ".kilocode/",
+    ".opencode/",
+    ".github/prompts/",
     ".github/PLUGIN_TEMPLATE.json",
-    "docs/",
+    ".forge/hooks/",
+    "docs/*.md",
     "install.sh",
     "lefthook.yml",
     "AGENTS.md",
@@ -89,10 +97,12 @@
     ".mcp.json.example"
   ],
   "dependencies": {
+    "@babel/parser": "^7.29.2",
     "fastest-levenshtein": "^1.0.16"
   },
   "overrides": {
     "eslint": "^10.0.2",
+    "flatted": "3.4.2",
     "minimatch": "10.2.4"
   },
   "c8": {