forge-workflow 0.0.6 → 0.0.8

package/lib/agents-config.js

@@ -68,6 +68,25 @@ async function detectProjectMetadata(projectPath) {
   return meta;
 }
 
+/**
+ * Write a file unless it already exists, unless overwrite is enabled.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ * @param {boolean} overwrite
+ * @returns {Promise<void>}
+ */
+async function writeIfNeeded(filePath, content, overwrite = false) {
+  const exists = await fs.promises.access(filePath).then(() => true).catch(() => false);
+  if (!exists || overwrite) {
+    await fs.promises.writeFile(filePath, content, 'utf-8');
+  }
+}
+
+function createConditionalWriter(overwrite) {
+  return (filePath, content) => writeIfNeeded(filePath, content, overwrite);
+}
+
 /**
  * Generate AGENTS.md content
  * @param {Object} meta - Project metadata
@@ -241,7 +260,7 @@ While this universal AGENTS.md works with all agents, you can optionally enable
 - **GitHub Copilot**: \`.github/copilot-instructions.md\` + path-specific instructions
 - **Cursor**: \`.cursor/rules/*.mdc\` + native modes
 - **OpenCode**: \`opencode.json\` + custom agents
-- **Kilo**: \`.kilo.md\` + built-in commands
+- **Kilo**: \`.kilocode/workflows\`, \`.kilocode/rules\`, \`.kilocode/skills\`
 
 Generate with: \`bunx forge setup --agent=<name>\`
 
@@ -277,38 +296,32 @@ async function generateCopilotConfig(projectPath, options = {}) {
   await fs.promises.mkdir(instructionsDir, { recursive: true });
   await fs.promises.mkdir(promptsDir, { recursive: true });
 
-  // Helper to write file if it doesn't exist or overwrite is true
-  const writeIfNeeded = async (filePath, content) => {
-    const exists = await fs.promises.access(filePath).then(() => true).catch(() => false);
-    if (!exists || overwrite) {
-      await fs.promises.writeFile(filePath, content, 'utf-8');
-    }
-  };
+  const writeConfigFile = createConditionalWriter(overwrite);
 
   // 1. Create .github/copilot-instructions.md
   const copilotInstructionsPath = path.join(githubDir, 'copilot-instructions.md');
   const copilotInstructionsContent = generateCopilotInstructionsContent(projectMeta);
-  await writeIfNeeded(copilotInstructionsPath, copilotInstructionsContent);
+  await writeConfigFile(copilotInstructionsPath, copilotInstructionsContent);
 
   // 2. Create .github/instructions/typescript.instructions.md
   const tsInstructionsPath = path.join(instructionsDir, 'typescript.instructions.md');
   const tsInstructionsContent = generateTypeScriptInstructionsContent();
-  await writeIfNeeded(tsInstructionsPath, tsInstructionsContent);
+  await writeConfigFile(tsInstructionsPath, tsInstructionsContent);
 
   // 3. Create .github/instructions/testing.instructions.md
   const testInstructionsPath = path.join(instructionsDir, 'testing.instructions.md');
   const testInstructionsContent = generateTestingInstructionsContent();
-  await writeIfNeeded(testInstructionsPath, testInstructionsContent);
+  await writeConfigFile(testInstructionsPath, testInstructionsContent);
 
   // 4. Create .github/prompts/red.prompt.md
   const redPromptPath = path.join(promptsDir, 'red.prompt.md');
   const redPromptContent = generateRedPromptContent();
-  await writeIfNeeded(redPromptPath, redPromptContent);
+  await writeConfigFile(redPromptPath, redPromptContent);
 
   // 5. Create .github/prompts/green.prompt.md
   const greenPromptPath = path.join(promptsDir, 'green.prompt.md');
   const greenPromptContent = generateGreenPromptContent();
-  await writeIfNeeded(greenPromptPath, greenPromptContent);
+  await writeConfigFile(greenPromptPath, greenPromptContent);
 }
 
 /**
@@ -643,33 +656,27 @@ async function generateCursorConfig(projectPath, options = {}) {
 
   await fs.promises.mkdir(rulesDir, { recursive: true });
 
-  // Helper to write file if it doesn't exist or overwrite is true
-  const writeIfNeeded = async (filePath, content) => {
-    const exists = await fs.promises.access(filePath).then(() => true).catch(() => false);
-    if (!exists || overwrite) {
-      await fs.promises.writeFile(filePath, content, 'utf-8');
-    }
-  };
+  const writeConfigFile = createConditionalWriter(overwrite);
 
   // 1. Create .cursor/rules/forge-workflow.mdc
   const workflowPath = path.join(rulesDir, 'forge-workflow.mdc');
   const workflowContent = generateCursorWorkflowContent(projectMeta);
-  await writeIfNeeded(workflowPath, workflowContent);
+  await writeConfigFile(workflowPath, workflowContent);
 
   // 2. Create .cursor/rules/tdd-enforcement.mdc
   const tddPath = path.join(rulesDir, 'tdd-enforcement.mdc');
   const tddContent = generateCursorTddContent();
-  await writeIfNeeded(tddPath, tddContent);
+  await writeConfigFile(tddPath, tddContent);
 
   // 3. Create .cursor/rules/security-scanning.mdc
   const securityPath = path.join(rulesDir, 'security-scanning.mdc');
   const securityContent = generateCursorSecurityContent();
-  await writeIfNeeded(securityPath, securityContent);
+  await writeConfigFile(securityPath, securityContent);
 
   // 4. Create .cursor/rules/documentation.mdc
   const docsPath = path.join(rulesDir, 'documentation.mdc');
   const docsContent = generateCursorDocumentationContent();
-  await writeIfNeeded(docsPath, docsContent);
+  await writeConfigFile(docsPath, docsContent);
 }
 
 /**
@@ -1010,7 +1017,7 @@ Update documentation at relevant stages (not deferred to end):
 }
 
 /**
- * Generate Kilo Code configuration file
+ * Generate Kilo Code configuration files
  * @param {string} projectPath - Path to the project root
  * @param {Object} options - Generation options
  * @param {boolean} options.overwrite - Whether to overwrite existing files (default: false)
@@ -1022,29 +1029,45 @@ async function generateKiloConfig(projectPath, options = {}) {
   // Detect project metadata
   const projectMeta = await detectProjectMetadata(projectPath);
 
-  const kiloMdPath = path.join(projectPath, '.kilo.md');
-
-  // Check if file exists
-  const exists = await fs.promises.access(kiloMdPath).then(() => true).catch(() => false);
-  if (exists && !overwrite) {
-    return; // Don't overwrite
-  }
+  const kilocodeDir = path.join(projectPath, '.kilocode');
+  const workflowsDir = path.join(kilocodeDir, 'workflows');
+  const rulesDir = path.join(kilocodeDir, 'rules');
+  const skillsDir = path.join(kilocodeDir, 'skills', 'forge-workflow');
 
-  // Generate .kilo.md content (plain markdown, no frontmatter)
-  const content = generateKiloMdContent(projectMeta);
-
-  await fs.promises.writeFile(kiloMdPath, content, 'utf-8');
+  await fs.promises.mkdir(workflowsDir, { recursive: true });
+  await fs.promises.mkdir(rulesDir, { recursive: true });
+  await fs.promises.mkdir(skillsDir, { recursive: true });
+
+  await writeIfNeeded(
+    path.join(workflowsDir, 'forge-workflow.md'),
+    generateKiloWorkflowContent(projectMeta),
+    overwrite
+  );
+  await writeIfNeeded(
+    path.join(rulesDir, 'workflow.md'),
+    generateKiloRulesContent(projectMeta),
+    overwrite
+  );
+  await writeIfNeeded(
+    path.join(skillsDir, 'SKILL.md'),
+    generateKiloSkillContent(projectMeta),
+    overwrite
+  );
 }
 
 /**
- * Generate .kilo.md content
+ * Generate .kilocode/workflows/forge-workflow.md content
  */
-function generateKiloMdContent(meta) {
+function generateKiloWorkflowContent(meta) {
   const packageManager = meta.testCommand?.includes('bun') ? 'bun' : 'npm';
 
-  return `# Forge Workflow Framework - Kilo Code
+  return `---
+description: "Forge workflow for Kilo Code"
+---
 
-This project uses the **Forge 7-Stage TDD Workflow** with Kilo Code.
+# Forge Workflow Framework - Kilo Code
+
+This project uses the **Forge 7-Stage TDD Workflow** with Kilo Code native workflows.
 
 ## Quick Start
 
@@ -1054,12 +1077,12 @@ ${meta.testCommand}            # Run tests
 ${meta.buildCommand}           # Build project
 \`\`\`
 
-## Kilo Built-in Commands
+## Native Kilo Surface
 
-Kilo Code provides built-in commands:
-- \`/plan\` - Create implementation plans (similar to Forge Stage 3)
-- \`/deploy\` - Deploy to production
-- \`/review\` - Code review assistance
+Kilo Code uses native workflows, rules, and skills. Forge generates:
+- \`.kilocode/workflows/forge-workflow.md\`
+- \`.kilocode/rules/workflow.md\`
+- \`.kilocode/skills/forge-workflow/SKILL.md\`
 
 These complement the Forge workflow stages below.
 
@@ -1117,36 +1140,67 @@ Final documentation verification
 - Verify all docs updated
 - Check for broken links
 - Validate code examples
+`;
+}
 
-## TDD Requirements
+/**
+ * Generate .kilocode/rules/workflow.md content
+ */
+function generateKiloRulesContent(meta) {
+  const packageManager = meta.testCommand?.includes('bun') ? 'bun' : 'npm';
 
-**MANDATORY**:
-- Write test FIRST (RED phase)
-- Implement minimal code to pass (GREEN phase)
-- Refactor and commit (REFACTOR phase)
-- No code changes without corresponding tests
+  return `---
+description: "Forge workflow rules for Kilo Code"
+---
 
-## Tech Stack
+# Forge Workflow Rules
 
-${meta.language ? `- **Language**: ${meta.language}` : '- **Language**: JavaScript'}
-- **Package Manager**: ${packageManager}
-- **Testing**: TDD-first approach
-- **Security**: OWASP Top 10 compliance
-- **Version Control**: Git with conventional commits
+- Use Forge as the source of truth for stage order and hard stops.
+- Run \`forge <stage>\` before continuing any workflow stage.
+- Treat \`.kilocode/workflows\` as the canonical workflow surface.
+- Keep \`AGENTS.md\` as shared context, not the workflow authority.
+- If Forge blocks a stage, fix the prerequisite or provide an explicit override payload.
 
-## Security
+## Environment
 
-For every new feature, analyze OWASP Top 10:
-- A01: Broken Access Control
-- A02: Cryptographic Failures
-- A03: Injection
-- A04: Insecure Design
-- A05: Security Misconfiguration
-- A06: Vulnerable and Outdated Components
-- A07: Authentication Failures
-- A08: Software and Data Integrity Failures
-- A09: Security Logging and Monitoring Failures
-- A10: Server-Side Request Forgery (SSRF)
+- Package manager: ${packageManager}
+- Language: ${meta.language ? meta.language : 'JavaScript'}
+`;
+}
+
+/**
+ * Generate .kilocode/skills/forge-workflow/SKILL.md content
+ */
+function generateKiloSkillContent(meta) {
+  const packageManager = meta.testCommand?.includes('bun') ? 'bun' : 'npm';
+
+  return `---
+name: forge-workflow
+description: Forge stage adapter for Kilo Code
+---
+
+# Forge Workflow Skill
+
+Before starting any stage, invoke \`forge <stage>\` so Forge can enforce stage order, prerequisites, and overrides.
+If Forge blocks the stage, stop and resolve it first.
+
+## Workflow Context
+
+- Package manager: ${packageManager}
+- Language: ${meta.language ? meta.language : 'JavaScript'}
+- Canonical workflow surface: \`.kilocode/workflows/forge-workflow.md\`
+- Shared context: \`AGENTS.md\`
+
+## Supported Stages
+
+- \`/status\`
+- \`/plan\`
+- \`/dev\`
+- \`/validate\`
+- \`/ship\`
+- \`/review\`
+- \`/premerge\`
+- \`/verify\`
 `;
 }
 
@@ -1168,28 +1222,22 @@ async function generateOpenCodeConfig(projectPath, options = {}) {
   const agentsDir = path.join(opencodeDir, 'agents');
   await fs.promises.mkdir(agentsDir, { recursive: true });
 
-  // Helper to write file if it doesn't exist or overwrite is true
-  const writeIfNeeded = async (filePath, content) => {
-    const exists = await fs.promises.access(filePath).then(() => true).catch(() => false);
-    if (!exists || overwrite) {
-      await fs.promises.writeFile(filePath, content, 'utf-8');
-    }
-  };
+  const writeConfigFile = createConditionalWriter(overwrite);
 
   // 1. Create opencode.json
   const opencodeJsonPath = path.join(projectPath, 'opencode.json');
   const opencodeJsonContent = generateOpenCodeJsonContent(projectMeta);
-  await writeIfNeeded(opencodeJsonPath, opencodeJsonContent);
+  await writeConfigFile(opencodeJsonPath, opencodeJsonContent);
 
   // 2. Create .opencode/agents/plan-review.md
   const planAgentPath = path.join(agentsDir, 'plan-review.md');
   const planAgentContent = generateOpenCodePlanAgentContent();
-  await writeIfNeeded(planAgentPath, planAgentContent);
+  await writeConfigFile(planAgentPath, planAgentContent);
 
   // 3. Create .opencode/agents/tdd-build.md
   const buildAgentPath = path.join(agentsDir, 'tdd-build.md');
   const buildAgentContent = generateOpenCodeBuildAgentContent();
-  await writeIfNeeded(buildAgentPath, buildAgentContent);
+  await writeConfigFile(buildAgentPath, buildAgentContent);
 }
 
 /**

package/lib/codex-skills.js

@@ -0,0 +1,50 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+function injectForgeAdapter(content, commandName) {
+  const adapter = [
+    '> Forge stage adapter',
+    '',
+    `Before executing this workflow, invoke \`forge ${commandName}\` so Forge can enforce stage order, runtime prerequisites, and override rules.`,
+    'If Forge blocks the stage or asks for an explicit override payload, stop and resolve that first.',
+    '',
+  ].join('\n');
+
+  const match = content.match(/^(---\r?\n[\s\S]*?\r?\n---\r?\n?)([\s\S]*)$/);
+  if (!match) {
+    return `${adapter}\n${content}`;
+  }
+
+  return `${match[1]}\n${adapter}${match[2]}`;
+}
+
+function listCodexSkillEntries(sourceRoot) {
+  const skillsDir = path.join(sourceRoot, '.codex', 'skills');
+
+  if (!fs.existsSync(skillsDir)) {
+    return [];
+  }
+
+  return fs.readdirSync(skillsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+    .map((commandName) => {
+      const sourceFile = path.join(skillsDir, commandName, 'SKILL.md');
+      if (!fs.existsSync(sourceFile)) {
+        return null;
+      }
+
+      return {
+        commandName,
+        dir: `.codex/skills/${commandName}/`,
+        filename: 'SKILL.md',
+        content: injectForgeAdapter(fs.readFileSync(sourceFile, 'utf8'), commandName),
+      };
+    })
+    .filter(Boolean);
+}
+
+module.exports = {
+  listCodexSkillEntries,
+};

package/lib/commands/_issue.js

@@ -0,0 +1,172 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+const SUBCOMMANDS = {
+  create: {
+    description: 'Create a Beads issue via Forge',
+    usage: 'forge create [title] [bd-create-flags]',
+    helpCommand: 'create',
+    buildBdArgs: (args) => ['create', ...args],
+  },
+  update: {
+    description: 'Update a Beads issue via Forge',
+    usage: 'forge update <id...> [bd-update-flags]',
+    helpCommand: 'update',
+    buildBdArgs: (args) => ['update', ...args],
+  },
+  claim: {
+    description: 'Claim a Beads issue via Forge',
+    usage: 'forge claim <id> [bd-update-flags]',
+    helpCommand: 'update',
+    buildBdArgs: (args) => {
+      const [issueId, ...rest] = args;
+      if (!issueId) {
+        return { error: 'Missing issue id. Usage: forge claim <id> [bd-update-flags]' };
+      }
+      return ['update', issueId, '--claim', ...rest];
+    },
+  },
+  close: {
+    description: 'Close a Beads issue via Forge',
+    usage: 'forge close <id...> [bd-close-flags]',
+    helpCommand: 'close',
+    buildBdArgs: (args) => ['close', ...args],
+  },
+  show: {
+    description: 'Show a Beads issue via Forge',
+    usage: 'forge show <id> [bd-show-flags]',
+    helpCommand: 'show',
+    buildBdArgs: (args) => ['show', ...args],
+  },
+  list: {
+    description: 'List Beads issues via Forge',
+    usage: 'forge list [bd-list-flags]',
+    helpCommand: 'list',
+    buildBdArgs: (args) => ['list', ...args],
+  },
+  ready: {
+    description: 'Show ready Beads issues via Forge',
+    usage: 'forge ready [bd-ready-flags]',
+    helpCommand: 'ready',
+    buildBdArgs: (args) => ['ready', ...args],
+  },
+};
+
+function normalizeArgs(args = []) {
+  return args.filter(arg => arg !== '--');
+}
+
+function getExecOptions(projectRoot) {
+  return {
+    cwd: projectRoot,
+    stdio: 'inherit',
+  };
+}
+
+function formatIssueHelp() {
+  const lines = [
+    'Usage: forge issue <subcommand> [...]',
+    '',
+    'Supported subcommands:',
+  ];
+
+  for (const [name, spec] of Object.entries(SUBCOMMANDS)) {
+    lines.push(`  ${name.padEnd(6)} ${spec.description}`);
+  }
+
+  lines.push('');
+  lines.push('Examples:');
+  lines.push('  forge create --title "Add feature" --type feature');
+  lines.push('  forge claim forge-abc');
+  lines.push('  forge update forge-abc --priority 1');
+  lines.push('  forge close forge-abc --reason "Done"');
+  lines.push('  forge issue show forge-abc --json');
+
+  return lines.join('\n');
+}
+
+function extractErrorMessage(error) {
+  if (error?.code === 'ENOENT') {
+    return 'Beads (bd) command not found. Install or initialize Beads before using Forge issue commands.';
+  }
+
+  // With stdio: 'inherit', error.stderr and error.stdout are always null.
+  // Only error.message is available for diagnostics.
+  return error?.message?.trim() || 'Beads command failed';
+}
+
+function buildBdArgs(subcommand, rawArgs) {
+  const spec = SUBCOMMANDS[subcommand];
+  if (!spec) {
+    return { error: `Unknown issue subcommand '${subcommand}'.\n\n${formatIssueHelp()}` };
+  }
+
+  const args = normalizeArgs(rawArgs);
+  if (args.includes('--help') || args.includes('-h')) {
+    return [spec.helpCommand, '--help'];
+  }
+
+  return spec.buildBdArgs(args);
+}
+
+async function runIssueSubcommand(subcommand, args, projectRoot, opts = {}) {
+  const exec = opts._exec || execFileSync;
+  const bdArgs = buildBdArgs(subcommand, args);
+
+  if (!Array.isArray(bdArgs)) {
+    return { success: false, error: bdArgs.error };
+  }
+
+  try {
+    exec('bd', bdArgs, getExecOptions(projectRoot));
+    return { success: true, subcommand };
+  } catch (error) {
+    return {
+      success: false,
+      error: extractErrorMessage(error),
+    };
+  }
+}
+
+function makeAliasCommand(subcommand) {
+  const spec = SUBCOMMANDS[subcommand];
+  if (!spec) {
+    throw new Error(`Unknown issue subcommand '${subcommand}'`);
+  }
+
+  return {
+    name: subcommand,
+    description: spec.description,
+    usage: spec.usage,
+    flags: {},
+    handler: async (args, _flags, projectRoot, opts = {}) =>
+      runIssueSubcommand(subcommand, args, projectRoot, opts),
+  };
+}
+
+function createIssueCommand() {
+  return {
+    name: 'issue',
+    description: 'Manage Beads issues through the Forge command surface',
+    usage: 'forge issue <create|update|claim|close|show|list|ready> [...]',
+    flags: {},
+    handler: async (args, _flags, projectRoot, opts = {}) => {
+      const [subcommand, ...rest] = normalizeArgs(args);
+
+      if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+        return { success: true, output: formatIssueHelp() };
+      }
+
+      return runIssueSubcommand(subcommand, rest, projectRoot, opts);
+    },
+  };
+}
+
+module.exports = {
+  SUBCOMMANDS,
+  buildBdArgs,
+  createIssueCommand,
+  makeAliasCommand,
+  runIssueSubcommand,
+};

package/lib/commands/_registry.js

@@ -11,6 +11,7 @@
 
 const { existsSync, readdirSync } = require('node:fs');
 const path = require('node:path');
+const { normalizeStageId } = require('../workflow/stages');
 
 /**
  * @typedef {Object} CommandModule
@@ -131,4 +132,42 @@ function buildHelp(commands) {
   return lines.join('\n');
 }
 
-module.exports = { loadCommands, validateCommand };
+function isStageCommand(commandName) {
+  return normalizeStageId(commandName) !== null;
+}
+
+async function executeCommand(commands, commandName, args, flags, projectRoot, options = {}) {
+  const command = commands.get(commandName);
+  if (!command) {
+    return { success: false, error: `Unknown command: ${commandName}` };
+  }
+
+  try {
+    if (typeof options.enforceStage === 'function' && isStageCommand(commandName)) {
+      const enforcement = await options.enforceStage({
+        commandName,
+        args,
+        flags,
+        projectRoot,
+        command,
+      });
+
+      if (enforcement?.allowed === false) {
+        return {
+          success: false,
+          error: enforcement.error ?? `Stage ${commandName} is blocked.`,
+          enforcement,
+        };
+      }
+    }
+
+    return await command.handler(args, flags, projectRoot);
+  } catch (err) {
+    return {
+      success: false,
+      error: err?.message ?? `Failed to execute ${commandName}`,
+    };
+  }
+}
+
+module.exports = { loadCommands, validateCommand, executeCommand };

package/lib/commands/claim.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const { makeAliasCommand } = require('./_issue');
+
+module.exports = makeAliasCommand('claim');

package/lib/commands/close.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const { makeAliasCommand } = require('./_issue');
+
+module.exports = makeAliasCommand('close');