forge-workflow 0.0.5 → 0.0.7

package/lib/agents/README.md

@@ -23,8 +23,21 @@ Each plugin file must follow this structure:
   "homepage": "https://...",  // OPTIONAL: Agent's homepage URL
   "capabilities": {           // OPTIONAL: Agent capabilities
     "commands": true,         // Supports commands
+    "rules": true,            // Supports rules/instructions
     "skills": true,           // Supports skills
-    "hooks": false            // Supports git hooks
+    "mcp": true,              // Supports MCP servers
+    "contextMode": true,      // Supports context isolation/modes
+    "hooks": {                // Supports hooks and blocking hooks
+      "blocking": false
+    }
+  },
+  "support": {                // OPTIONAL: Support quality metadata
+    "status": "supported",    // first-class | supported | compatibility | deprecated | unsupported
+    "surface": "cli-first",   // cli-first | editor-native | desktop-app | web-app | terminal-native | hybrid
+    "install": {
+      "required": true,       // Requires installation or setup
+      "repairRequired": false  // Can be repaired in place instead of reinstalled
+    }
   },
   "directories": {            // REQUIRED: Directory structure (at least one)
     "commands": ".your-agent/commands",
@@ -58,9 +71,27 @@ Each plugin file must follow this structure:
 - **description**: Short description of the agent
 - **homepage**: URL to agent's official website
 - **capabilities**: Object defining what the agent supports
+- **support**: Support tier and enforcement metadata
 - **files**: Important configuration file paths
 - **setup**: Installation and setup instructions
 
+### Normalized Capability Metadata
+
+`PluginManager` exposes a normalized capability block on each loaded plugin at `normalizedCapabilities`:
+
+- `nativeSurface`
+- `supportStatus`
+- `commands`
+- `rules`
+- `skills`
+- `mcp`
+- `contextMode`
+- `hooks.blocking`
+- `install.required`
+- `install.repairRequired`
+
+Legacy `capabilities.hooks: true/false` values are still accepted and normalized to `hooks.blocking`.
+
 ## Supported Agents
 
 Currently supported AI coding agents:
@@ -122,6 +153,8 @@ The PluginManager automatically validates all plugins on load:
 - **Type checking**: Fields must have correct types
 - **Unique IDs**: No duplicate plugin IDs allowed
 - **JSON syntax**: Files must be valid JSON
+- **Support metadata**: `support.status` must be one of `first-class`, `supported`, `compatibility`, `deprecated`, or `unsupported`
+- **Capability metadata**: `capabilities.hooks.blocking`, `capabilities.mcp`, `capabilities.contextMode`, and the other support flags must be booleans when present
 
 Run tests to validate your plugin:
 
@@ -129,6 +162,17 @@ Run tests to validate your plugin:
 bun test test/plugins/
 ```
 
+### Parity Drift Validation
+
+`node scripts/check-agents.js` now validates more than command sync. It also checks parity-critical support claims:
+
+- invalid enforcement metadata under `support` and `capabilities`
+- plugins that claim command support without a Forge sync adapter
+- command directory declarations that do not match the sync adapter output path
+- `rules` or `skills` capabilities declared without a scaffold path in `directories`
+
+This is the guardrail for keeping agent support honest as vendor integrations evolve.
+
 ## Community Contributions
 
 We welcome community contributions for new AI coding agents!
@@ -191,6 +235,7 @@ Common validation errors:
 - `missing required field "id"`: Add the id field
 - `"directories" must be an object`: Ensure directories is an object, not array
 - `"version" must be a string`: Version must be in "x.y.z" format
+- `"support.status" must be one of ...`: Use a supported status value
 - `Plugin with ID "x" already exists`: Choose a unique ID
 
 ## License

package/lib/agents/cline.plugin.json

@@ -6,17 +6,24 @@
   "homepage": "https://github.com/cline/cline",
   "capabilities": {
     "commands": true,
-    "skills": true,
+    "skills": false,
     "hooks": false
   },
   "directories": {
-    "workflows": ".cline/workflows",
-    "skills": ".cline/skills/forge-workflow"
+    "workflows": ".cline/workflows"
   },
   "files": {
     "rootConfig": ".clinerules"
   },
+  "support": {
+    "status": "deprecated",
+    "surface": "editor-native",
+    "install": {
+      "required": false,
+      "repairRequired": false
+    }
+  },
   "setup": {
-    "createSkill": true
+    "copyCommands": true
   }
 }

package/lib/agents/codex.plugin.json

@@ -6,7 +6,7 @@
   "homepage": "https://github.com/openai/codex",
   "capabilities": {
     "commands": true,
-    "skills": false,
+    "skills": true,
     "hooks": false
   },
   "directories": {
@@ -14,6 +14,6 @@
   },
   "setup": {
     "copyRules": false,
-    "createSkill": false
+    "createSkill": true
   }
 }

package/lib/agents/copilot.plugin.json

@@ -2,23 +2,23 @@
   "id": "copilot",
   "name": "GitHub Copilot",
   "version": "1.0.0",
-  "description": "GitHub's AI assistant",
+  "description": "GitHub's AI assistant with native instructions and prompts",
   "homepage": "https://github.com/features/copilot",
   "capabilities": {
     "commands": true,
-    "skills": true,
+    "skills": false,
     "hooks": false
   },
   "directories": {
     "prompts": ".github/prompts",
-    "instructions": ".github/instructions",
-    "skills": ".github/skills/forge-workflow"
+    "instructions": ".github/instructions"
   },
   "files": {
     "rootConfig": ".github/copilot-instructions.md"
   },
   "setup": {
     "needsConversion": true,
-    "promptFormat": true
+    "promptFormat": true,
+    "customSetup": "copilot"
   }
 }

package/lib/agents/cursor.plugin.json

@@ -2,7 +2,7 @@
   "id": "cursor",
   "name": "Cursor",
   "version": "1.0.0",
-  "description": "AI-first code editor",
+  "description": "AI-first code editor with native rules and skills",
   "homepage": "https://cursor.sh",
   "capabilities": {
     "commands": true,

package/lib/agents/kilocode.plugin.json

@@ -2,7 +2,7 @@
   "id": "kilocode",
   "name": "Kilo Code",
   "version": "1.0.0",
-  "description": "VS Code extension",
+  "description": "VS Code extension with native workflows, rules, and skills",
   "homepage": "https://marketplace.visualstudio.com/items?itemName=kilo-code",
   "capabilities": {
     "commands": true,

package/lib/agents/opencode.plugin.json

@@ -2,19 +2,22 @@
   "id": "opencode",
   "name": "OpenCode",
   "version": "1.0.0",
-  "description": "Open-source agent",
+  "description": "Open-source agent with native config and agent definitions",
   "homepage": "https://opencode.ai",
   "capabilities": {
     "commands": true,
-    "skills": true,
+    "skills": false,
     "hooks": false
   },
   "directories": {
     "commands": ".opencode/commands",
-    "skills": ".opencode/skills/forge-workflow"
+    "agents": ".opencode/agents"
+  },
+  "files": {
+    "rootConfig": "opencode.json"
   },
   "setup": {
     "copyCommands": true,
-    "createSkill": true
+    "customSetup": "opencode"
   }
 }

package/lib/agents/roo.plugin.json

@@ -6,16 +6,23 @@
   "homepage": "https://github.com/roocode/roo",
   "capabilities": {
     "commands": true,
-    "skills": true,
+    "skills": false,
     "hooks": false
   },
   "directories": {
-    "commands": ".roo/commands",
-    "skills": ".roo/skills/forge-workflow"
+    "commands": ".roo/commands"
   },
   "files": {
     "rootConfig": ".roorules"
   },
+  "support": {
+    "status": "deprecated",
+    "surface": "editor-native",
+    "install": {
+      "required": false,
+      "repairRequired": false
+    }
+  },
   "setup": {
     "copyCommands": true,
     "needsConversion": true

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);
 }
 
 /**
@@ -943,7 +950,7 @@ Update documentation at relevant stages (not deferred to end):
 - Security considerations (OWASP analysis)
 
 ### During /plan (Stage 3)
-- Create implementation plan in \`.claude/plans/<feature-slug>.md\`
+- Create implementation plan in \`docs/plans/<feature-slug>.md\`
 - Document test scenarios
 - Identify affected files
 
@@ -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);
 }
 
 /**
@@ -1271,7 +1319,7 @@ Focus on:
 - Research with web search for best practices
 - Document findings in \`docs/plans/<feature-slug>-design.md\`
 - Include security analysis (OWASP Top 10)
-- Create detailed plan in \`.claude/plans/<feature-slug>.md\`
+- Create detailed plan in \`docs/plans/<feature-slug>.md\`
 - Break down into TDD cycles (RED-GREEN-REFACTOR)
 - Identify files to create/modify
 

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,
+};