forge-workflow 0.0.6 → 0.0.7

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/_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/commands-reset.js

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * @module commands-reset
+ *
+ * Reset agent command files to match the canonical source (commands/*.md or .claude/commands/*.md).
+ * Rebuilds adapted files via sync-commands and optionally writes them.
+ *
+ * Used by `forge commands reset [--dry-run] [--all] [command-name]`.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  syncCommands,
+  contentHash,
+  resolveCanonicalCommandsDir,
+  writeSyncManifest,
+} = require('../../scripts/sync-commands.js');
+
+function validateCommandName(commandName) {
+  if (commandName && !/^[a-z0-9-]+$/.test(commandName)) {
+    return [`Invalid command name: "${commandName}" - only lowercase letters, numbers, and hyphens allowed`];
+  }
+
+  return [];
+}
+
+function ensureCanonicalCommandExists(repoRoot, canonicalDir, commandName) {
+  if (!commandName) {
+    return [];
+  }
+
+  if (fs.existsSync(path.join(canonicalDir, `${commandName}.md`))) {
+    return [];
+  }
+
+  const canonicalLabel = path.relative(repoRoot, canonicalDir).replaceAll('\\', '/');
+  return [`Command not found: ${canonicalLabel}/${commandName}.md`];
+}
+
+function filterPlannedEntries(entries, commandName, all) {
+  if (commandName && all !== true) {
+    return entries.filter(entry =>
+      entry.filename.replaceAll('.prompt.md', '').replaceAll('.md', '') === commandName ||
+      entry.dir.includes(`/${commandName}/`)
+    );
+  }
+
+  return entries;
+}
+
+function recordEntryResult(entry, reset, skipped, dryRun) {
+  const relativeFile = path.join(entry.dir, entry.filename);
+
+  if (dryRun) {
+    if (fs.existsSync(entry.filePath)) {
+      const existing = fs.readFileSync(entry.filePath, 'utf8');
+      if (contentHash(existing) === contentHash(entry.content)) {
+        skipped.push({ agent: entry.agent, file: relativeFile });
+      } else {
+        reset.push({ agent: entry.agent, file: relativeFile });
+      }
+    } else {
+      reset.push({ agent: entry.agent, file: relativeFile });
+    }
+    return;
+  }
+
+  const targetDir = path.dirname(entry.filePath);
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  if (fs.existsSync(entry.filePath)) {
+    const existing = fs.readFileSync(entry.filePath, 'utf8');
+    if (contentHash(existing) === contentHash(entry.content)) {
+      skipped.push({ agent: entry.agent, file: relativeFile });
+      return;
+    }
+  }
+
+  fs.writeFileSync(entry.filePath, entry.content);
+  reset.push({ agent: entry.agent, file: relativeFile });
+}
+
+function resetCommands({ repoRoot, commandName, all, dryRun }) {
+  const errors = [];
+  const reset = [];
+  const skipped = [];
+
+  errors.push(...validateCommandName(commandName));
+  if (errors.length > 0) {
+    return { reset, skipped, errors };
+  }
+
+  const canonicalDir = resolveCanonicalCommandsDir(repoRoot);
+  if (!canonicalDir) {
+    errors.push('Canonical source directory not found: commands/ or .claude/commands/');
+    return { reset, skipped, errors };
+  }
+
+  errors.push(...ensureCanonicalCommandExists(repoRoot, canonicalDir, commandName));
+  if (errors.length > 0) {
+    return { reset, skipped, errors };
+  }
+
+  const result = syncCommands({ dryRun: true, check: false, repoRoot, canonicalDir });
+  if (!result.planned || result.planned.length === 0) {
+    return { reset, skipped, errors };
+  }
+
+  const entries = filterPlannedEntries(result.planned, commandName, all);
+  for (const entry of entries) {
+    recordEntryResult(entry, reset, skipped, dryRun);
+  }
+
+  if (!dryRun) {
+    // Refresh the manifest using the full expected sync set without rewriting
+    // unrelated command files that were intentionally excluded from this reset.
+    writeSyncManifest(repoRoot, result.planned);
+  }
+
+  return { reset, skipped, errors };
+}
+
+module.exports = {
+  name: 'commands-reset',
+  description: 'Reset generated agent command files to canonical content',
+  handler: async (args, flags, repoRoot) => {
+    const commandName = args.find(arg => !arg.startsWith('-'));
+    const result = resetCommands({
+      repoRoot,
+      commandName,
+      all: Boolean(flags.all),
+      dryRun: Boolean(flags.dryRun),
+    });
+
+    if (result.errors.length > 0) {
+      return { success: false, error: result.errors.join('; ') };
+    }
+
+    return { success: true, ...result };
+  },
+  resetCommands,
+  resolveCanonicalCommandsDir,
+};

package/lib/commands/dev.js

@@ -558,6 +558,32 @@ function verifyTaskCompletion(taskTitle, ownedFiles, opts = {}) {
 }
 
 module.exports = {
+	name: 'dev',
+	description: 'Run the TDD development stage with phase guidance',
+	handler: async (args, flags = {}) => {
+		const featureName = args[0] || 'feature';
+		const phaseInput = flags.phase || args[1];
+		const phase = typeof phaseInput === 'string' ? phaseInput.toUpperCase() : undefined;
+		if (phase && !['RED', 'GREEN', 'REFACTOR'].includes(phase)) {
+			return {
+				success: false,
+				error: `Invalid phase '${phaseInput}'. Valid phases: red, green, refactor`,
+			};
+		}
+
+		const result = await executeDev(featureName, phase ? { phase } : {});
+		if (!result.success) {
+			return result;
+		}
+
+		const lines = [`TDD Phase: ${result.phase || result.detectedPhase}`];
+		if (result.guidance) lines.push('', result.guidance);
+
+		return {
+			...result,
+			output: lines.join('\n'),
+		};
+	},
 	detectTDDPhase,
 	identifyFilePairs,
 	runTests,

package/lib/commands/plan.js

@@ -680,6 +680,24 @@ async function executePlan(featureName) { // NOSONAR S3776
 }
 
 module.exports = {
+	name: 'plan',
+	description: 'Create implementation plan from researched feature context',
+	handler: async (args) => {
+		const result = await executePlan(args[0]);
+		if (!result.success) {
+			return result;
+		}
+
+		const lines = [`Plan created: ${result.summary || result.branchName || args[0]}`];
+		if (result.beadsIssueId) lines.push(`Beads: ${result.beadsIssueId}`);
+		if (result.branchName) lines.push(`Branch: ${result.branchName}`);
+		if (result.nextCommand) lines.push(`Next: ${result.nextCommand}`);
+
+		return {
+			...result,
+			output: lines.join('\n'),
+		};
+	},
 	readResearchDoc,
 	detectScope,
 	createBeadsIssue,