forge-workflow 0.0.6 → 0.0.8

package/.cursorrules

@@ -0,0 +1,149 @@
+# Forge - 7-Stage TDD Workflow
+
+A TDD-first workflow for AI coding agents. Ship features with confidence.
+
+## Commands (7 Stages)
+
+| Stage | Command | Description |
+|-------|---------|-------------|
+| utility | `/status` | Check current context, active work, recent completions |
+| 1 | `/plan` | Design intent Q&A → research → branch + task list |
+| 2 | `/dev` | Subagent-driven TDD per task (spec + quality review) |
+| 3 | `/validate` | Validation (type/lint/security/tests) |
+| 4 | `/ship` | Create PR with full documentation |
+| 5 | `/review` | Address ALL PR feedback |
+| 6 | `/premerge` | Complete docs on feature branch, hand off PR to user |
+| 7 | `/verify` | Post-merge health check (CI on main) |
+
+## Workflow Flow
+
+```
+/plan → /dev → /validate → /ship → /review → /premerge → /verify
+```
+
+## Core Principles
+
+- **TDD-First**: Write tests BEFORE implementation (RED-GREEN-REFACTOR)
+- **Design-First**: One-question-at-a-time Q&A captures design intent upfront
+- **HARD-GATEs**: Every stage exit has explicit pass criteria — run the commands, show the output
+- **Security Built-In**: OWASP Top 10 analysis for every feature
+
+## Prerequisites
+
+- Git, GitHub CLI (`gh`)
+- Beads (recommended): `bun add -g @beads/bd && bd init`
+
+## Quick Start
+
+1. `/status` - Check where you are
+2. `/plan <feature-slug>` - Design intent → research → branch + task list
+3. `/dev` - Implement with TDD
+4. `/validate` - Validate everything
+5. `/ship` - Create PR
+6. `/review <pr-number>` - Address all feedback
+7. `/premerge <pr-number>` - Docs + hand off to user
+
+## Stage Details
+
+### Utility: Status (`/status`)
+
+Check current context before starting work:
+- Active issues (via Beads if installed)
+- Recent completions
+- Current branch state
+
+### 1. Plan (`/plan <feature-slug>`)
+
+Three phases:
+- **Phase 1**: Design intent Q&A (one-question-at-a-time with user)
+- **Phase 2**: Technical research (web + codebase, OWASP Top 10)
+- **Phase 3**: Create branch + task list (TDD-ordered)
+
+### 2. Development (`/dev`)
+
+Subagent-driven TDD per task:
+- Implementer subagent: RED-GREEN-REFACTOR enforced by HARD-GATE
+- Spec compliance reviewer: checks every task
+- Code quality reviewer: checks after spec compliance
+- Decision gate: 7-dimension scoring when spec gap found
+
+### 3. Validate (`/validate`)
+
+Validate everything (HARD-GATE exit — fresh output required):
+- Type checking
+- Linting (0 errors, 0 warnings)
+- All tests passing
+- Security scan (OWASP Top 10)
+
+### 4. Ship (`/ship`)
+
+Create pull request:
+- Push branch
+- Create PR with design doc reference
+- Link to Beads issue
+
+### 5. Review (`/review <pr-number>`)
+
+Address ALL feedback:
+- GitHub Actions failures
+- Greptile inline comments (reply + resolve each)
+- SonarCloud issues
+- Other CI/CD tool feedback
+
+### 6. Premerge (`/premerge <pr-number>`)
+
+Complete docs and hand off (NEVER merges):
+- Update CLAUDE.md, AGENTS.md, GEMINI.md, README as needed
+- Commit docs to feature branch
+- Hand off PR URL to user for merge
+
+### 7. Verify (`/verify`)
+
+Post-merge health check:
+- CI on main: all checks green
+- Close Beads issue
+- Confirm merge landed
+
+## Directory Structure
+
+```
+your-project/
+├── AGENTS.md                    # Universal (Windsurf, Cursor, Kilo, OpenCode, Cline, Roo, Aider)
+├── CLAUDE.md                    # Claude Code
+├── GEMINI.md                    # Google Antigravity
+├── .cursorrules                 # Cursor
+│
+├── .claude/commands/            # Claude Code commands
+└── docs/
+    ├── plans/
+    │   ├── YYYY-MM-DD-<slug>-design.md
+    │   └── YYYY-MM-DD-<slug>-tasks.md
+    └── TOOLCHAIN.md
+```
+
+## Supported Agents
+
+This workflow works with ALL major AI coding agents:
+
+| Agent | Instructions | Commands |
+|-------|-------------|----------|
+| Claude Code | CLAUDE.md | .claude/commands/ |
+| Google Antigravity | GEMINI.md | .agent/workflows/ |
+| Cursor | .cursorrules | .cursor/rules/ |
+| Windsurf | AGENTS.md | .windsurf/workflows/ |
+| Kilo Code | AGENTS.md | .kilocode/workflows/ |
+| OpenCode | AGENTS.md | .opencode/commands/ |
+| Cline | AGENTS.md | - |
+| Roo Code | AGENTS.md | .roo/commands/ |
+| Continue | AGENTS.md | .continue/prompts/ |
+| GitHub Copilot | .github/copilot-instructions.md | .github/prompts/ |
+| Aider | AGENTS.md (via .aider.conf.yml) | In-chat |
+| Codex CLI | AGENTS.md | In-chat |
+
+## License
+
+MIT
+
+---
+
+See `AGENTS.md` for the complete workflow guide.

package/bin/forge.js

@@ -51,7 +51,9 @@ const { scaffoldGithubBeadsSync } = require('../lib/setup');
 const { copyEssentialDocs } = require('../lib/docs-copy');
 const { listTopics, getTopicContent } = require('../lib/docs-command');
 const { resetSoft, resetHard, reinstall } = require('../lib/reset');
-const { loadCommands } = require('../lib/commands/_registry');
+const { loadCommands, executeCommand } = require('../lib/commands/_registry');
+const { enforceStageEntry } = require('../lib/workflow/enforce-stage');
+const { normalizeStageId } = require('../lib/workflow/stages');
 
 // Load enhanced onboarding modules
 const contextMerge = require(path.join(packageDir, 'lib', 'context-merge'));
@@ -2539,6 +2541,13 @@ function parseFlags() {
     sync: false,      // Scaffold Beads GitHub sync workflows (--sync)
   };
 
+  // Issue passthrough commands delegate all flags to bd.
+  // Skip global parsing so flags like --type, -p, --help reach the handler intact.
+  const issuePassthroughCommands = ['create', 'update', 'claim', 'close', 'show', 'list', 'ready', 'issue'];
+  if (issuePassthroughCommands.includes(args[0])) {
+    return flags;
+  }
+
   for (let i = 0; i < args.length;) {
     const arg = args[i];
 
@@ -4159,13 +4168,29 @@ async function main() {
 
   // Registry command dispatch — auto-discovered commands take priority
   if (registry.commands.has(command)) {
-    const cmd = registry.commands.get(command);
     try {
-      const result = await cmd.handler(args.slice(1), flags, projectRoot);
+      const result = await executeCommand(
+        registry.commands,
+        command,
+        args.slice(1),
+        flags,
+        projectRoot,
+        {
+          enforceStage: (context) => enforceStageEntry({
+            commandName: context.commandName,
+            args: context.args,
+            flags: context.flags,
+            projectRoot: context.projectRoot,
+          }),
+        }
+      );
       if (result && !result.success) {
         console.error(result.error || result.message || 'Command failed');
         process.exit(1);
       }
+      if (result && typeof result.output === 'string' && result.output.length > 0) {
+        process.stdout.write(result.output.endsWith('\n') ? result.output : `${result.output}\n`);
+      }
     } catch (err) {
       console.error(`Error running '${command}':`, err.message);
       process.exit(1);
@@ -4173,6 +4198,21 @@ async function main() {
     return;
   }
 
+  const stageId = normalizeStageId(command);
+  if (stageId) {
+    try {
+      await enforceStageEntry({
+        commandName: stageId,
+        args: args.slice(1),
+        flags,
+        projectRoot,
+      });
+    } catch (err) {
+      console.error(`Error running '${command}':`, err.message);
+      process.exit(1);
+    }
+  }
+
   if (command === 'setup') {
     // Determine agents to install
     let selectedAgents = determineSelectedAgents(flags);

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