forge-workflow 0.0.10 → 0.1.0-beta.2

package/lib/agents-config.js

@@ -1,6 +1,14 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
+const { renderRulesForHarness } = require('./rules-sync');
+const { getPackageRoot } = require('./package-root');
+
+// Forge package root — the canonical `rules/` manifest lives here and is the
+// single source for every harness's native rule files. On-disk under npm/npx;
+// resolved to the extracted embed dir inside a compiled binary via getPackageRoot.
+const PACKAGE_ROOT = path.join(__dirname, '..');
+
 /**
  * Generate universal AGENTS.md file that works with all supported AI agents
  * @param {string} projectPath - Path to the project root
@@ -68,25 +76,6 @@ 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
@@ -95,14 +84,13 @@ function createConditionalWriter(overwrite) {
 function generateAgentsMdContent(meta) {
   return `# Forge Workflow Framework
 
-This project uses the **Forge 7-Stage TDD Workflow** for development.
+This project uses the **Forge TDD Workflow Template** for development. The commands are composable building blocks, not a mandatory fixed ladder.
 
 ## Supported AI Agents
 
-This workflow works with all major AI coding agents:
+Forge currently supports Claude Code, Codex, and Cursor. Hermes support is planned.
 - **Claude Code** - Native custom slash commands, skills
-- **GitHub Copilot** - Enterprise support, multi-editor, MCP
-- **Kilo Code** - Auto failure recovery, managed indexing
+- **Codex** - OpenAI's CLI agent, skills-based workflow
 - **Cursor** - IDE-integrated, native Plan/Ask/Debug modes
 
 ## Quick Start
@@ -113,7 +101,7 @@ ${meta.testCommand}  # Run tests
 ${meta.buildCommand} # Build project
 \`\`\`
 
-## Forge 7-Stage TDD Workflow
+## Forge TDD Workflow Template
 
 ### Utility: /status
 Check current context and active work
@@ -121,14 +109,14 @@ Check current context and active work
 - Check Beads issues (if installed) for active work
 - Identify current workflow stage
 
-### Stage 1: /plan
+### /plan
 Create implementation plan
 - Research with web search (parallel-ai MCP recommended)
-- Document findings in \`docs/plans/<feature-slug>-design.md\`
+- Document findings in \`docs/work/YYYY-MM-DD-<feature-slug>/plan.md\`
 - Include decision rationale and security considerations
 - Generate plan, create Beads issue, break into TDD cycles
 
-### Stage 2: /dev
+### /dev
 TDD development (RED-GREEN-REFACTOR)
 - **RED**: Write failing test FIRST
 - **GREEN**: Implement minimal code to pass
@@ -136,7 +124,7 @@ TDD development (RED-GREEN-REFACTOR)
 - Commit after each cycle
 - Push regularly to remote
 
-### Stage 3: /validate
+### /validate
 Validation and quality gates
 - Type checking${meta.language === 'TypeScript' ? ' (TypeScript strict mode)' : ''}
 - Linting (ESLint)
@@ -144,14 +132,14 @@ Validation and quality gates
 - Test suite (all tests must pass)
 - Code coverage verification
 
-### Stage 4: /ship
+### /ship
 Create pull request
 - Generate PR body with context
 - Reference Beads issues
 - Include test coverage metrics
 - Link to research and plan documents
 
-### Stage 5: /review
+### /review
 Address ALL PR feedback
 - GitHub Actions failures
 - Code review comments
@@ -159,15 +147,9 @@ Address ALL PR feedback
 - Security scan results
 - Resolve all threads before merge
 
-### Stage 6: /premerge
-Merge and cleanup
-- Update documentation
-- Merge pull request (squash commits)
-- Delete feature branch
-- Archive completed work
-- Close Beads issues
+> **Pre-merge gate** (not a numbered stage): before merge, finish docs on the feature branch, confirm CI is green, and hand off the PR. This gate is embedded in the \`/ship\` and \`/review\` stages, not a standalone command.
 
-### Stage 7: /verify
+### /verify
 Final documentation cross-check
 - Verify all docs updated correctly
 - Check for broken links
@@ -230,8 +212,8 @@ forge close <id>                         # Complete
 forge sync                               # Sync Beads state
 \`\`\`
 
-Use \`bd\` directly only for capabilities Forge does not wrap yet, such as
-\`bd init\`, \`bd comments\`, \`bd dep\`, and \`bd dolt\`.
+Use \`forge issue\` subcommands for everything else, such as
+\`forge issue comment\`, \`forge issue dep\`, and \`forge issue stats\`.
 
 ## Git Workflow
 
@@ -260,10 +242,7 @@ git commit -m "refactor: extract helpers"      # REFACTOR
 
 While this universal AGENTS.md works with all agents, you can optionally enable agent-specific enhancements:
 
-- **GitHub Copilot**: \`.github/copilot-instructions.md\` + path-specific instructions
 - **Cursor**: \`.cursor/rules/*.mdc\` + native modes
-- **OpenCode**: \`opencode.json\` + custom agents
-- **Kilo**: \`.kilocode/workflows\`, \`.kilocode/rules\`, \`.kilocode/skills\`
 
 Generate with: \`bunx forge setup --agent=<name>\`
 
@@ -278,371 +257,6 @@ For questions or issues with Forge workflow, see project documentation or GitHub
 `;
 }
 
-/**
- * Generate GitHub Copilot 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)
- * @returns {Promise<void>}
- */
-async function generateCopilotConfig(projectPath, options = {}) {
-  const { overwrite = false } = options;
-
-  // Detect project metadata
-  const projectMeta = await detectProjectMetadata(projectPath);
-
-  // Create .github directory structure
-  const githubDir = path.join(projectPath, '.github');
-  const instructionsDir = path.join(githubDir, 'instructions');
-  const promptsDir = path.join(githubDir, 'prompts');
-
-  await fs.promises.mkdir(instructionsDir, { recursive: true });
-  await fs.promises.mkdir(promptsDir, { recursive: true });
-
-  const writeConfigFile = createConditionalWriter(overwrite);
-
-  // 1. Create .github/copilot-instructions.md
-  const copilotInstructionsPath = path.join(githubDir, 'copilot-instructions.md');
-  const copilotInstructionsContent = generateCopilotInstructionsContent(projectMeta);
-  await writeConfigFile(copilotInstructionsPath, copilotInstructionsContent);
-
-  // 2. Create .github/instructions/typescript.instructions.md
-  const tsInstructionsPath = path.join(instructionsDir, 'typescript.instructions.md');
-  const tsInstructionsContent = generateTypeScriptInstructionsContent();
-  await writeConfigFile(tsInstructionsPath, tsInstructionsContent);
-
-  // 3. Create .github/instructions/testing.instructions.md
-  const testInstructionsPath = path.join(instructionsDir, 'testing.instructions.md');
-  const testInstructionsContent = generateTestingInstructionsContent();
-  await writeConfigFile(testInstructionsPath, testInstructionsContent);
-
-  // 4. Create .github/prompts/red.prompt.md
-  const redPromptPath = path.join(promptsDir, 'red.prompt.md');
-  const redPromptContent = generateRedPromptContent();
-  await writeConfigFile(redPromptPath, redPromptContent);
-
-  // 5. Create .github/prompts/green.prompt.md
-  const greenPromptPath = path.join(promptsDir, 'green.prompt.md');
-  const greenPromptContent = generateGreenPromptContent();
-  await writeConfigFile(greenPromptPath, greenPromptContent);
-}
-
-/**
- * Generate .github/copilot-instructions.md content
- */
-function generateCopilotInstructionsContent(meta) {
-  const packageManager = meta.testCommand?.includes('bun') ? 'bun' : 'npm';
-
-  return `# Forge Workflow Framework
-
-This project uses the **Forge 7-Stage TDD Workflow** for development with GitHub Copilot.
-
-## Quick Start
-
-\`\`\`bash
-${packageManager} install      # Install dependencies
-${meta.testCommand}            # Run tests
-${meta.buildCommand}           # Build project
-\`\`\`
-
-## Tech Stack
-
-${meta.language ? `- **Language**: ${meta.language} (strict mode enabled)` : '- **Language**: JavaScript'}
-- **Package Manager**: ${packageManager}
-- **Testing**: TDD-first approach (tests before implementation)
-- **Security**: OWASP Top 10 compliance required
-- **Version Control**: Git with conventional commits
-
-## Forge 7-Stage TDD Workflow
-
-### Utility: /status
-Check current context and active work
-- Review git status and recent commits
-- Check Beads issues (if installed) for active work
-- Identify current workflow stage
-
-### Stage 1: /plan
-Create implementation plan
-- Research with web search
-- Document findings in \`docs/plans/<feature-slug>-design.md\`
-- **Security**: Identify OWASP Top 10 considerations
-- Generate plan, create Beads issue, break into TDD cycles
-
-### Stage 2: /dev
-**TDD development (RED-GREEN-REFACTOR)**
-- **RED**: Write failing test FIRST
-- **GREEN**: Implement minimal code to pass
-- **REFACTOR**: Clean up and optimize
-- Commit after each cycle
-- Push regularly to remote
-
-### Stage 3: /validate
-Validation and quality gates
-- Type checking${meta.language === 'TypeScript' ? ' (TypeScript strict mode)' : ''}
-- Linting (ESLint - no errors allowed)
-- Security scanning (npm audit, OWASP checks)
-- Test suite (all tests must pass)
-- Code coverage verification (80%+ required)
-
-### Stage 4: /ship
-Create pull request
-- Generate PR body with context
-- Reference Beads issues
-- Include test coverage metrics
-- Link to research and plan documents
-
-### Stage 5: /review
-Address ALL PR feedback
-- GitHub Actions failures
-- Code review comments
-- AI review tools (Greptile, CodeRabbit if configured)
-- Security scan results
-- **IMPORTANT**: Resolve all comment threads before merge
-
-### Stage 6: /premerge
-Merge and cleanup
-- Update documentation
-- Merge pull request (squash commits only)
-- Delete feature branch
-- Archive completed work
-- Close Beads issues
-
-### Stage 7: /verify
-Final documentation cross-check
-- Verify all docs updated correctly
-- Check for broken links
-- Validate code examples
-- Ensure consistency across documentation
-
-## Core Principles
-
-### 1. TDD-First Development (MANDATORY)
-- Tests written UPFRONT in RED-GREEN-REFACTOR cycles
-- **NO implementation without failing test first**
-- Commit after each GREEN cycle
-- Maintain high code coverage (80%+ minimum)
-
-### 2. Research-First Approach
-- All features start with comprehensive research
-- Use web search for best practices and security analysis
-- Document findings before implementation
-- **Include OWASP Top 10 analysis for security-critical features**
-
-### 3. Security Built-In
-- **OWASP Top 10** analysis for every new feature:
-  - A01: Broken Access Control
-  - A02: Cryptographic Failures
-  - A03: Injection
-  - A04: Insecure Design
-  - A05: Security Misconfiguration
-  - A06: Vulnerable and Outdated Components
-  - A07: Identification and Authentication Failures
-  - A08: Software and Data Integrity Failures
-  - A09: Security Logging and Monitoring Failures
-  - A10: Server-Side Request Forgery (SSRF)
-- Security test scenarios identified upfront
-- Automated scans + manual review
-- Input validation and sanitization
-
-### 4. Documentation Progressive
-- Updated at relevant stages (not deferred to end)
-- Cross-checked at /verify stage
-- Never accumulate documentation debt
-- Keep README, docs/, and inline comments synchronized
-
-## Git Workflow
-
-**Branch naming**:
-- \`feat/<feature-slug>\` - New features
-- \`fix/<bug-slug>\` - Bug fixes
-- \`docs/<doc-slug>\` - Documentation updates
-
-**Commit pattern** (conventional commits):
-\`\`\`bash
-git commit -m "test: add validation tests"     # RED phase
-git commit -m "feat: implement validation"     # GREEN phase
-git commit -m "refactor: extract helpers"      # REFACTOR phase
-\`\`\`
-
-**Pre-commit hooks** (automatic via Lefthook):
-- TDD enforcement (source files must have tests)
-- Interactive prompts (option to unstage, continue, or abort)
-
-**Pre-push hooks** (automatic):
-- Branch protection (blocks direct push to main/master)
-- ESLint check (blocks on errors)
-- Test suite (all tests must pass)
-
-## MCP Servers (Enhanced Capabilities)
-
-Configure these MCP servers in \`.mcp.json\`:
-
-- **github**: Repository integration (usually built-in)
-- **parallel-ai**: Web research and data enrichment
-- **context7**: Up-to-date library documentation
-
-## Issue Tracking with Beads
-
-Use **Forge's Beads wrapper** for persistent tracking across sessions:
-
-\`\`\`bash
-forge create "Feature name"                # Create issue
-forge claim <id>                           # Claim work
-forge update <id> --append-notes "Progress" # Add notes
-forge close <id>                           # Complete
-forge sync                                 # Sync Beads state
-\`\`\`
-
-Use \`bd\` directly only for capabilities Forge does not wrap yet, such as
-\`bd init\`, \`bd comments\`, \`bd dep\`, and \`bd dolt\`.
-
-## Code Quality Standards
-
-${meta.language === 'TypeScript' ? `
-### TypeScript
-- Strict mode enabled (\`strict: true\` in tsconfig.json)
-- No \`any\` types without explicit justification
-- Prefer interfaces over types for object shapes
-- Use const assertions for literal types
-` : ''}
-
-### Testing
-- TDD-first: Write failing test BEFORE implementation
-- Use descriptive test names ("it should...")
-- Arrange-Act-Assert pattern
-- Mock external dependencies
-- Test edge cases and error scenarios
-
-### Security
-- Validate all user input
-- Sanitize output to prevent XSS
-- Use parameterized queries (prevent SQL injection)
-- Implement proper authentication and authorization
-- Never commit secrets or credentials
-
-## Additional Resources
-
-- **Workflow Guide**: \`AGENTS.md\`
-- **Architecture**: \`docs/ARCHITECTURE.md\`
-- **Configuration**: \`docs/CONFIGURATION.md\`
-`;
-}
-
-/**
- * Generate .github/instructions/typescript.instructions.md content
- */
-function generateTypeScriptInstructionsContent() {
-  return `---
-applyTo: "**/*.ts"
----
-
-# TypeScript Guidelines
-
-When working with TypeScript files in this project:
-
-## Type Safety
-- **strict mode is enabled** - No shortcuts with types
-- Avoid \`any\` type - Use \`unknown\` and type guards instead
-- Prefer interfaces over type aliases for object shapes
-- Use const assertions for literal types
-
-## Code Style
-- Use explicit return types for public functions
-- Leverage type inference for local variables
-- Use utility types (\`Partial\`, \`Pick\`, \`Omit\`, etc.) appropriately
-- Document complex types with JSDoc comments
-
-## Common Patterns
-- Use discriminated unions for state management
-- Prefer \`readonly\` for immutable data
-- Use \`unknown\` instead of \`any\` for truly unknown types
-- Leverage template literal types for string validation
-
-## Error Handling
-- Create custom error types for domain-specific errors
-- Use type guards to narrow error types
-- Always type catch clauses (\`catch (error: unknown)\`)
-`;
-}
-
-/**
- * Generate .github/instructions/testing.instructions.md content
- */
-function generateTestingInstructionsContent() {
-  return `---
-applyTo: "**/*.test.ts"
----
-
-# Testing Guidelines
-
-When writing tests in this project:
-
-## TDD-First Approach
-- **Write failing test BEFORE implementation** (RED phase)
-- Run test to confirm it fails for the right reason
-- Implement minimal code to make test pass (GREEN phase)
-- Refactor while keeping tests green (REFACTOR phase)
-
-## Test Structure
-- Use descriptive test names: "it should [expected behavior] when [condition]"
-- Follow Arrange-Act-Assert pattern:
-  - **Arrange**: Set up test data and preconditions
-  - **Act**: Execute the code under test
-  - **Assert**: Verify the expected outcome
-
-## Best Practices
-- One assertion per test (or closely related assertions)
-- Test edge cases and error scenarios
-- Mock external dependencies (APIs, databases, file system)
-- Use fixtures for complex test data
-- Keep tests fast and independent
-
-## Coverage
-- Aim for 80%+ code coverage
-- Focus on testing behavior, not implementation details
-- Test public interfaces, not private methods
-- Include integration tests for critical paths
-
-## Security Testing
-- Test input validation and sanitization
-- Verify authentication and authorization
-- Test error messages don't leak sensitive data
-- Include security-specific test cases for OWASP Top 10
-`;
-}
-
-/**
- * Generate .github/prompts/red.prompt.md content
- */
-function generateRedPromptContent() {
-  return `Write a failing test for the following requirement.
-
-Follow TDD red-green-refactor cycle:
-- Test should fail initially (RED phase)
-- Use descriptive test name
-- Follow Arrange-Act-Assert pattern
-- Test one behavior per test case
-
-Do NOT implement the feature yet - only write the test.
-`;
-}
-
-/**
- * Generate .github/prompts/green.prompt.md content
- */
-function generateGreenPromptContent() {
-  return `Implement minimal code to make the failing test pass.
-
-Follow TDD principles:
-- Write only enough code to pass the test (GREEN phase)
-- Keep implementation simple and focused
-- Don't add features not covered by tests
-- Ensure all tests pass
-
-Refactoring comes after this step - focus on making it work first.
-`;
-}
-
 /**
  * Generate Cursor configuration files
  * @param {string} projectPath - Path to the project root
@@ -653,768 +267,17 @@ Refactoring comes after this step - focus on making it work first.
 async function generateCursorConfig(projectPath, options = {}) {
   const { overwrite = false } = options;
 
-  // Detect project metadata
-  const projectMeta = await detectProjectMetadata(projectPath);
-
-  // Create .cursor/rules directory structure
-  const cursorDir = path.join(projectPath, '.cursor');
-  const rulesDir = path.join(cursorDir, 'rules');
-
-  await fs.promises.mkdir(rulesDir, { recursive: true });
-
-  const writeConfigFile = createConditionalWriter(overwrite);
-
-  // 1. Create .cursor/rules/forge-workflow.mdc
-  const workflowPath = path.join(rulesDir, 'forge-workflow.mdc');
-  const workflowContent = generateCursorWorkflowContent(projectMeta);
-  await writeConfigFile(workflowPath, workflowContent);
-
-  // 2. Create .cursor/rules/tdd-enforcement.mdc
-  const tddPath = path.join(rulesDir, 'tdd-enforcement.mdc');
-  const tddContent = generateCursorTddContent();
-  await writeConfigFile(tddPath, tddContent);
-
-  // 3. Create .cursor/rules/security-scanning.mdc
-  const securityPath = path.join(rulesDir, 'security-scanning.mdc');
-  const securityContent = generateCursorSecurityContent();
-  await writeConfigFile(securityPath, securityContent);
-
-  // 4. Create .cursor/rules/documentation.mdc
-  const docsPath = path.join(rulesDir, 'documentation.mdc');
-  const docsContent = generateCursorDocumentationContent();
-  await writeConfigFile(docsPath, docsContent);
-}
-
-/**
- * Generate .cursor/rules/forge-workflow.mdc content
- */
-function generateCursorWorkflowContent(meta) {
-  const packageManager = meta.testCommand?.includes('bun') ? 'bun' : 'npm';
-
-  return `---
-description: "When working with Forge workflow stages"
-alwaysApply: true
----
-
-# Forge 7-Stage TDD Workflow
-
-Always follow these stages in order:
-
-## Utility: /status
-Check current context and active work
-- Review git status and recent commits
-- Check Beads issues (if installed) for active work
-- Identify current workflow stage
-
-## Stage 1: /plan
-Create implementation plan
-- Research with parallel-ai
-- Document findings in \`docs/plans/<feature-slug>-design.md\`
-- **Security**: OWASP Top 10 analysis
-- Generate plan, create Beads issue, break into TDD cycles
-
-## Stage 2: /dev
-**TDD development (RED-GREEN-REFACTOR)**
-- **RED**: Write failing test FIRST
-- **GREEN**: Implement minimal code to pass
-- **REFACTOR**: Clean up and optimize
-- Commit after each cycle
-- Push regularly to remote
-
-## Stage 3: /validate
-Validation (type/lint/tests/security)
-- Type checking${meta.language === 'TypeScript' ? ' (TypeScript strict mode)' : ''}
-- Linting (ESLint - no errors)
-- Security scanning (npm audit, OWASP)
-- Test suite (all tests must pass)
-- Code coverage (80%+ required)
-
-## Stage 4: /ship
-Create PR with documentation
-- Generate PR body with context
-- Reference Beads issues
-- Include test coverage metrics
-- Link to research and plan documents
-
-## Stage 5: /review
-Address ALL PR feedback
-- GitHub Actions failures
-- Code review comments
-- AI review tools (Greptile, CodeRabbit)
-- Security scan results
-- **IMPORTANT**: Resolve all comment threads
-
-## Stage 6: /premerge
-Update docs, merge PR, cleanup
-- Update documentation
-- Merge pull request (squash commits only)
-- Delete feature branch
-- Archive completed work
-- Close Beads issues
-
-## Stage 7: /verify
-Final documentation verification
-- Verify all docs updated correctly
-- Check for broken links
-- Validate code examples
-- Ensure consistency across documentation
-
-## TDD Requirements
-
-**MANDATORY - No implementation without failing test**:
-- Write test FIRST (RED phase)
-- Implement minimal code to pass (GREEN phase)
-- Refactor and commit (REFACTOR phase)
-- No code changes without corresponding tests
-
-## Tech Stack
-
-${meta.language ? `- **Language**: ${meta.language}` : '- **Language**: JavaScript'}
-- **Package Manager**: ${packageManager}
-- **Testing**: TDD-first approach (tests before implementation)
-- **Security**: OWASP Top 10 compliance
-- **Version Control**: Git with conventional commits
-
-## Cursor Native Modes
-
-Leverage Cursor's built-in modes:
-- **Agent Mode** (default): Full tools for implementation
-- **Ask Mode**: Read-only exploration and learning
-- **Plan Mode** (Shift+Tab): Create plans before coding
-- **Debug Mode**: Specialized bug hunting with instrumentation
-
-Use Plan Mode for complex features and architectural decisions.
-`;
-}
-
-/**
- * Generate .cursor/rules/tdd-enforcement.mdc content
- */
-function generateCursorTddContent() {
-  return `---
-description: "TDD patterns and enforcement"
-globs: ["**/*.ts", "**/*.js", "**/*.test.ts", "**/*.test.js"]
----
-
-# TDD Enforcement
-
-## RED-GREEN-REFACTOR Cycle
-
-### RED Phase (Write Failing Test)
-1. **Write test FIRST** - Before any implementation
-2. Run test to confirm it fails for the right reason
-3. Commit: \`git commit -m "test: add [feature] tests (RED)"\`
-
-### GREEN Phase (Make Test Pass)
-1. **Write minimal code** to make the test pass
-2. Keep implementation simple and focused
-3. Don't add features not covered by tests
-4. Commit: \`git commit -m "feat: implement [feature] (GREEN)"\`
-
-### REFACTOR Phase (Clean Up)
-1. Improve code while keeping tests green
-2. Extract helpers, remove duplication
-3. Optimize performance if needed
-4. Commit: \`git commit -m "refactor: [description]"\`
-
-## Test Structure
-
-### Naming Convention
-\`\`\`javascript
-test('should [expected behavior] when [condition]', async () => {
-  // Arrange: Set up test data
-  // Act: Execute code under test
-  // Assert: Verify outcome
-});
-\`\`\`
-
-### Best Practices
-- One assertion per test (or closely related assertions)
-- Test edge cases and error scenarios
-- Mock external dependencies (APIs, databases, file system)
-- Use fixtures for complex test data
-- Keep tests fast and independent
-
-## Coverage Requirements
-- Minimum 80% code coverage
-- Focus on testing behavior, not implementation
-- Test public interfaces, not private methods
-- Include integration tests for critical paths
-
-## Security Testing
-- Test input validation and sanitization
-- Verify authentication and authorization
-- Test error messages don't leak sensitive data
-- Include security-specific test cases for OWASP Top 10
-`;
-}
-
-/**
- * Generate .cursor/rules/security-scanning.mdc content
- */
-function generateCursorSecurityContent() {
-  return `---
-description: "OWASP Top 10 security checks"
----
-
-# Security Scanning Guidelines
-
-## OWASP Top 10 (2021)
-
-For every new feature, analyze these security risks:
-
-### A01: Broken Access Control
-- Verify authorization checks on all protected resources
-- Test that users can't access data they shouldn't
-- Implement principle of least privilege
-
-### A02: Cryptographic Failures
-- Never store passwords in plaintext
-- Use strong encryption algorithms (AES-256, RSA-2048+)
-- Protect data in transit (HTTPS, TLS 1.2+)
-- Secure key management
-
-### A03: Injection
-- **SQL Injection**: Use parameterized queries
-- **XSS**: Sanitize output, use Content Security Policy
-- **Command Injection**: Validate and sanitize all inputs
-- Never concatenate user input into commands or queries
-
-### A04: Insecure Design
-- Security requirements defined upfront
-- Threat modeling for new features
-- Defense in depth (multiple security layers)
-- Secure defaults
-
-### A05: Security Misconfiguration
-- Remove default credentials
-- Disable unnecessary features and services
-- Keep dependencies up to date
-- Implement security headers
-
-### A06: Vulnerable and Outdated Components
-- Regular dependency audits (\`npm audit\`)
-- Update dependencies promptly
-- Use Software Composition Analysis (SCA) tools
-- Monitor security advisories
-
-### A07: Identification and Authentication Failures
-- Implement multi-factor authentication where appropriate
-- Secure password storage (bcrypt, Argon2)
-- Protect against brute force attacks (rate limiting)
-- Secure session management
-
-### A08: Software and Data Integrity Failures
-- Verify digital signatures
-- Use integrity checks for critical data
-- Implement code signing
-- Secure CI/CD pipelines
-
-### A09: Security Logging and Monitoring Failures
-- Log all security-relevant events
-- Protect logs from tampering
-- Implement alerting for suspicious activity
-- Regular log review
-
-### A10: Server-Side Request Forgery (SSRF)
-- Validate and sanitize all URLs
-- Use allowlists for external requests
-- Disable unnecessary protocols
-- Network segmentation
-
-## Security Testing Checklist
-
-For each feature:
-- [ ] Input validation implemented and tested
-- [ ] Output sanitization verified
-- [ ] Authentication and authorization tested
-- [ ] Error messages don't leak sensitive data
-- [ ] Dependencies scanned for vulnerabilities
-- [ ] Security test cases added to test suite
-- [ ] OWASP Top 10 risks analyzed
-`;
-}
-
-/**
- * Generate .cursor/rules/documentation.mdc content
- */
-function generateCursorDocumentationContent() {
-  return `---
-description: "Progressive documentation standards"
----
-
-# Documentation Standards
-
-## Progressive Documentation
-
-Update documentation at relevant stages (not deferred to end):
-
-### During /plan (Stage 1)
-- Document findings in \`docs/plans/<feature-slug>-design.md\`
-- Include decision rationale
-- Document alternatives considered
-- Security considerations (OWASP analysis)
-
-### During /plan (Stage 3)
-- Create implementation plan in \`docs/plans/<feature-slug>.md\`
-- Document test scenarios
-- Identify affected files
-
-### During /dev (Stage 4)
-- Add inline code comments for complex logic
-- Update JSDoc/TSDoc for public APIs
-- Keep comments synchronized with code changes
-
-### During /ship (Stage 6)
-- Update README if user-facing changes
-- Update CHANGELOG with conventional commit summary
-- Document breaking changes
-- Add migration guide if needed
-
-### During /verify (Stage 7)
-- Cross-check all documentation updated
-- Validate code examples still work
-- Check for broken internal links
-- Ensure terminology consistency
-
-## Documentation Types
-
-### Code Comments
-- **What to comment**: Why, not what
-- Document non-obvious decisions
-- Explain complex algorithms
-- Note security considerations
-- Reference tickets/issues for context
-
-### API Documentation
-- Use JSDoc/TSDoc for public APIs
-- Include parameter types and return types
-- Provide usage examples
-- Document error conditions
-- List breaking changes in version updates
-
-### README Updates
-- Keep Quick Start section current
-- Update feature list
-- Maintain installation instructions
-- Document configuration options
-- Include troubleshooting section
-
-## Documentation Quality
-
-### Consistency
-- Use consistent terminology across docs
-- Follow project style guide
-- Maintain consistent formatting
-- Use same voice and tone
-
-### Clarity
-- Write for your audience (developers, users, etc.)
-- Use examples liberally
-- Avoid jargon without explanation
-- Keep sentences short and clear
-
-### Maintainability
-- Link to code where appropriate
-- Use relative links for internal docs
-- Keep docs close to the code they describe
-- Remove outdated documentation promptly
-`;
-}
-
-/**
- * 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)
- * @returns {Promise<void>}
- */
-async function generateKiloConfig(projectPath, options = {}) {
-  const { overwrite = false } = options;
-
-  // Detect project metadata
-  const projectMeta = await detectProjectMetadata(projectPath);
-
-  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');
-
-  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 .kilocode/workflows/forge-workflow.md content
- */
-function generateKiloWorkflowContent(meta) {
-  const packageManager = meta.testCommand?.includes('bun') ? 'bun' : 'npm';
-
-  return `---
-description: "Forge workflow for Kilo Code"
----
-
-# Forge Workflow Framework - Kilo Code
-
-This project uses the **Forge 7-Stage TDD Workflow** with Kilo Code native workflows.
-
-## Quick Start
-
-\`\`\`bash
-${packageManager} install      # Install dependencies
-${meta.testCommand}            # Run tests
-${meta.buildCommand}           # Build project
-\`\`\`
-
-## Native Kilo Surface
-
-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.
-
-## Forge 7-Stage TDD Workflow
-
-### Utility: /status
-Check current context and active work
-- Review git status and recent commits
-- Check Beads issues (if installed)
-
-### Stage 1: /plan
-Create implementation plan
-- Research with web search
-- Document findings in \`docs/plans/<feature-slug>-design.md\`
-- Security: OWASP Top 10 analysis
-- Generate plan, create Beads issue, break into TDD cycles
-
-### Stage 2: /dev
-**TDD development (RED-GREEN-REFACTOR)**
-- **RED**: Write failing test FIRST
-- **GREEN**: Implement minimal code to pass
-- **REFACTOR**: Clean up and optimize
-- Commit after each cycle
-
-### Stage 3: /validate
-Validation (type/lint/tests/security)
-- Type checking${meta.language === 'TypeScript' ? ' (TypeScript strict mode)' : ''}
-- Linting (ESLint)
-- Security scanning
-- Test suite (all tests must pass)
-- Code coverage (80%+ required)
-
-### Stage 4: /ship
-Create pull request
-- Generate PR body with context
-- Reference Beads issues
-- Include test coverage metrics
-
-### Stage 5: /review
-Address ALL PR feedback
-- GitHub Actions failures
-- Code review comments
-- AI review tools
-- Resolve all comment threads
-
-### Stage 6: /premerge
-Merge and cleanup
-- Update documentation
-- Merge PR (squash commits)
-- Delete feature branch
-- Close Beads issues
-
-### Stage 7: /verify
-Final documentation verification
-- Verify all docs updated
-- Check for broken links
-- Validate code examples
-`;
-}
-
-/**
- * Generate .kilocode/rules/workflow.md content
- */
-function generateKiloRulesContent(meta) {
-  const packageManager = meta.testCommand?.includes('bun') ? 'bun' : 'npm';
-
-  return `---
-description: "Forge workflow rules for Kilo Code"
----
-
-# Forge Workflow Rules
-
-- 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.
-
-## Environment
-
-- 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\`
-`;
-}
-
-/**
- * Generate OpenCode 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)
- * @returns {Promise<void>}
- */
-async function generateOpenCodeConfig(projectPath, options = {}) {
-  const { overwrite = false } = options;
-
-  // Detect project metadata
-  const projectMeta = await detectProjectMetadata(projectPath);
-
-  // Create .opencode/agents directory
-  const opencodeDir = path.join(projectPath, '.opencode');
-  const agentsDir = path.join(opencodeDir, 'agents');
-  await fs.promises.mkdir(agentsDir, { recursive: true });
-
-  const writeConfigFile = createConditionalWriter(overwrite);
-
-  // 1. Create opencode.json
-  const opencodeJsonPath = path.join(projectPath, 'opencode.json');
-  const opencodeJsonContent = generateOpenCodeJsonContent(projectMeta);
-  await writeConfigFile(opencodeJsonPath, opencodeJsonContent);
-
-  // 2. Create .opencode/agents/plan-review.md
-  const planAgentPath = path.join(agentsDir, 'plan-review.md');
-  const planAgentContent = generateOpenCodePlanAgentContent();
-  await writeConfigFile(planAgentPath, planAgentContent);
-
-  // 3. Create .opencode/agents/tdd-build.md
-  const buildAgentPath = path.join(agentsDir, 'tdd-build.md');
-  const buildAgentContent = generateOpenCodeBuildAgentContent();
-  await writeConfigFile(buildAgentPath, buildAgentContent);
-}
-
-/**
- * Generate opencode.json content
- */
-function generateOpenCodeJsonContent(_meta) {
-  return JSON.stringify({
-    "$schema": "https://opencode.ai/config.json",
-    "agent": {
-      "build": {
-        "mode": "primary",
-        "model": "anthropic/claude-sonnet-4-20250514",
-        "tools": {
-          "write": true,
-          "edit": true,
-          "bash": true
-        }
-      },
-      "plan": {
-        "mode": "primary",
-        "model": "anthropic/claude-haiku-4-20250514",
-        "tools": {
-          "write": false,
-          "edit": false,
-          "bash": false
-        }
-      }
-    },
-    "mcp_servers": {
-      "parallel-ai": {
-        "type": "stdio",
-        "command": "npx",
-        "args": ["-y", "@parallel-ai/mcp-server"],
-        "env": {
-          "API_KEY": "${env:PARALLEL_AI_TOKEN}"
-        }
-      },
-      "context7": {
-        "type": "stdio",
-        "command": "npx",
-        "args": ["-y", "@context7/mcp-server"]
-      }
-    }
-  }, null, 2);
-}
-
-/**
- * Generate .opencode/agents/plan-review.md content
- */
-function generateOpenCodePlanAgentContent() {
-  return `---
-description: Read-only planning and analysis
-mode: subagent
-model: anthropic/claude-sonnet-4-20250514
-temperature: 0.1
-tools:
-  write: false
-  edit: false
-  bash: false
----
-
-# Planning & Review Agent
-
-You are in **planning mode** for the Forge 7-Stage TDD Workflow.
-
-## Your Role
-
-Focus on:
-- Understanding requirements thoroughly
-- Researching existing patterns in the codebase
-- Creating detailed implementation plans
-- Identifying test scenarios upfront
-- Analyzing OWASP Top 10 security considerations
-- **NO code changes allowed** - planning only
-
-## Forge Planning Stages
-
-### Stage 1: /plan
-- 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 \`docs/plans/<feature-slug>.md\`
-- Break down into TDD cycles (RED-GREEN-REFACTOR)
-- Identify files to create/modify
-
-## Output Format
-
-Your plan should include:
-1. **Requirements Summary** - What needs to be built
-2. **Test Scenarios** - All tests to write (RED phase)
-3. **Implementation Steps** - Minimal code to pass tests (GREEN phase)
-4. **Security Analysis** - OWASP Top 10 relevant risks
-5. **Files Affected** - List of files to create/modify
-6. **Verification** - How to test end-to-end
-
-**Remember**: You are read-only. No code changes. Planning only.
-`;
-}
-
-/**
- * Generate .opencode/agents/tdd-build.md content
- */
-function generateOpenCodeBuildAgentContent() {
-  return `---
-description: TDD implementation with full tools
-mode: primary
-model: anthropic/claude-sonnet-4-20250514
-temperature: 0
-tools:
-  write: true
-  edit: true
-  bash: true
----
-
-# TDD Build Agent
-
-You are in **implementation mode** for the Forge 7-Stage TDD Workflow.
-
-## MANDATORY TDD Process
-
-**RED-GREEN-REFACTOR** - No exceptions:
-
-### RED Phase
-1. Write failing test FIRST
-2. Run test to confirm it fails for the right reason
-3. Commit: \`git commit -m "test: add [feature] tests (RED)"\`
-
-### GREEN Phase
-1. Write minimal code to make the test pass
-2. Keep implementation simple
-3. Don't add features not covered by tests
-4. Commit: \`git commit -m "feat: implement [feature] (GREEN)"\`
-
-### REFACTOR Phase
-1. Clean up code while keeping tests green
-2. Extract helpers, remove duplication
-3. Commit: \`git commit -m "refactor: [description]"\`
-
-## Forge Development Stages
-
-### Stage 2: /dev
-Implement features using TDD:
-- Follow RED-GREEN-REFACTOR for each feature
-- Commit after each GREEN cycle
-- Push regularly to remote
-
-### Stage 3: /validate
-Validate before creating PR:
-- Type checking (TypeScript strict mode)
-- Linting (ESLint - no errors)
-- Security scanning (npm audit)
-- Test suite (all must pass)
-- Code coverage (80%+ required)
-
-## Security
-
-For every feature, check OWASP Top 10:
-- Input validation
-- Output sanitization
-- Authentication/Authorization
-- Cryptography
-- Dependency vulnerabilities
-
-## Quality Standards
-
-- Tests written BEFORE implementation
-- 80%+ code coverage
-- No ESLint errors
-- Security vulnerabilities addressed
-- Documentation updated progressively
-`;
+  // Cursor rule CONTENT is not hand-authored here. It is rendered from the
+  // canonical `rules/<name>.md` manifest. Cursor is the only harness with a native
+  // rule surface; Claude/Codex/Hermes receive the same policy via their AGENTS.md
+  // instruction projection (no always-on `.claude/rules/*` files are generated).
+  // See lib/rules-sync.js and docs/reference/AGENT_SKILL_PARITY.md.
+  renderRulesForHarness({
+    sourceRoot: getPackageRoot(PACKAGE_ROOT),
+    targetRoot: projectPath,
+    harness: 'cursor',
+    overwrite,
+  });
 }
 
 /**
@@ -1502,7 +365,7 @@ Forge supports multiple AI agents through a three-tier architecture:
 - \`parallel-ai\` - Web search and research
 - \`github\` - GitHub API integration
 
-**Compatibility**: ✅ Growing (Claude Code, GitHub Copilot, Cursor, OpenCode support MCP)
+**Compatibility**: ✅ Growing (Claude Code, Codex, and Cursor support MCP)
 
 ## Universal vs Agent-Specific
 
@@ -1548,11 +411,9 @@ This ensures:
 \`\`\`
 project/
 ├── AGENTS.md              # Universal commands (all agents)
-├── .mcp.json              # MCP servers (Claude, Copilot, Cursor, OpenCode)
+├── .mcp.json              # MCP servers (Claude, Codex, Cursor)
 ├── .claude/
 │   └── skills/            # Claude-specific skills
-├── .github/
-│   └── copilot-instructions.md  # Copilot-specific instructions
 └── .cursor/
     └── rules/             # Cursor-specific rules
 \`\`\`
@@ -1691,7 +552,7 @@ bunx forge setup --profile=team --interactive
 /validate                    # Run all checks
 /ship                     # Create PR
 /review                   # Address feedback
-/premerge          # Merge after approval
+/verify                   # Post-merge verify (pre-merge gate runs in /ship + /review)
 \`\`\`
 
 ## Configuration Options
@@ -1868,9 +729,8 @@ function generateMcpSetupContent() {
 
 **Supported Agents**:
 - ✅ Claude Code
-- ✅ GitHub Copilot (VS Code extension)
+- ✅ Codex
 - ✅ Cursor
-- ✅ OpenCode
 
 ## Quick Start
 
@@ -1883,9 +743,8 @@ Choose one of the supported agents above.
 Each agent has a different configuration location:
 
 **Claude Code**: \`.mcp.json\` in project root
-**GitHub Copilot**: \`.mcp.json\` in project root (VS Code)
+**Codex**: \`~/.codex/config.toml\` under \`mcp_servers\`
 **Cursor**: \`.cursor/mcp.json\`
-**OpenCode**: \`opencode.json\` under \`mcp_servers\`
 
 ### 3. Add Forge-Recommended Servers
 
@@ -1943,9 +802,6 @@ Copy the configuration for your agent from the examples below.
 
 **Purpose**: GitHub repository access, issues, PRs, code search
 
-**Setup for GitHub Copilot** (built-in):
-- No configuration needed, included by default in VS Code extension
-
 **Setup for Claude Code**:
 \`\`\`json
 {
@@ -1994,25 +850,6 @@ Copy the configuration for your agent from the examples below.
 
 **Environment Variables**: Set in \`.env\` or shell profile
 
-### GitHub Copilot
-
-**File**: \`.mcp.json\` in project root (VS Code)
-
-**Example**:
-\`\`\`json
-{
-  "mcpServers": {
-    "context7": {
-      "type": "local",
-      "command": "npx",
-      "args": ["-y", "@context7/mcp-server"]
-    }
-  }
-}
-\`\`\`
-
-**Note**: GitHub MCP server is built-in, no config needed
-
 ### Cursor
 
 **File**: \`.cursor/mcp.json\`
@@ -2039,31 +876,6 @@ Copy the configuration for your agent from the examples below.
 
 **Note**: Cursor supports both STDIO and HTTP MCP servers
 
-### OpenCode
-
-**File**: \`opencode.json\` (add under \`mcp_servers\`)
-
-**Example**:
-\`\`\`json
-{
-  "mcp_servers": {
-    "parallel-ai": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@parallel-ai/mcp-server"],
-      "env": {
-        "API_KEY": "\${env:PARALLEL_AI_TOKEN}"
-      }
-    },
-    "context7": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@context7/mcp-server"]
-    }
-  }
-}
-\`\`\`
-
 ## Setup with Forge
 
 Forge can automatically configure MCP servers during setup:
@@ -2074,7 +886,7 @@ bunx forge setup --mcp
 
 # Agent-specific setup with MCP
 bunx forge setup --agent=claude --mcp
-bunx forge setup --agent=copilot --mcp
+bunx forge setup --agent=codex --mcp
 bunx forge setup --agent=cursor --mcp
 \`\`\`
 
@@ -2109,12 +921,6 @@ Test MCP setup:
 # Should use parallel-ai automatically
 \`\`\`
 
-**GitHub Copilot**:
-\`\`\`bash
-# In VS Code, ask Copilot: "What's the latest TypeScript syntax?"
-# Should fetch from context7
-\`\`\`
-
 **Cursor**:
 \`\`\`bash
 # In Cursor, use Agent mode: "Research authentication best practices"
@@ -2156,10 +962,7 @@ Choose based on server documentation.
 module.exports = {
   detectProjectMetadata,
   generateAgentsMd,
-  generateCopilotConfig,
   generateCursorConfig,
-  generateKiloConfig,
-  generateOpenCodeConfig,
   generateArchitectureDoc,
   generateConfigurationDoc,
   generateMcpSetupDoc