specweave 0.1.9 → 0.3.0

package/src/adapters/codex/adapter.ts

@@ -0,0 +1,333 @@
+/**
+ * Codex Adapter (OpenAI)
+ *
+ * Semi-automation adapter for OpenAI Codex (ChatGPT Code Interpreter/Codex CLI).
+ * Uses universal AGENTS.md file for instructions.
+ *
+ * Codex features:
+ * - Works in CLI, IDE, web, GitHub, iOS app
+ * - GPT-5-Codex optimized for engineering tasks
+ * - File read/write operations
+ * - Test execution and validation
+ * - Task-based isolated environments
+ */
+
+import * as path from 'path';
+import fs from 'fs-extra';
+import { AdapterBase } from '../adapter-base.js';
+import { AdapterOptions, AdapterFile } from '../adapter-interface.js';
+import { AgentsMdGenerator } from '../agents-md-generator.js';
+import { getDirname } from '../../utils/esm-helpers.js';
+
+const __dirname = getDirname(import.meta.url);
+
+export class CodexAdapter extends AdapterBase {
+  name = 'codex';
+  description = 'OpenAI Codex adapter - Semi-automation with AGENTS.md and task-based execution';
+  automationLevel = 'semi' as const;
+
+  /**
+   * Detect if Codex is available
+   *
+   * Checks for:
+   * - codex command in PATH (Codex CLI)
+   * - .codex/ directory exists
+   * - AGENTS.md file exists (previously configured)
+   */
+  async detect(): Promise<boolean> {
+    const hasCodexCLI = await this.commandExists('codex');
+    const hasCodexDir = await this.fileExists('.codex');
+    const hasAgentsMd = await this.fileExists('AGENTS.md');
+
+    return hasCodexCLI || hasCodexDir || hasAgentsMd;
+  }
+
+  /**
+   * Get files to install for Codex adapter
+   */
+  getFiles(): AdapterFile[] {
+    return [
+      {
+        sourcePath: 'AGENTS.md',
+        targetPath: 'AGENTS.md',
+        description: 'Universal SpecWeave instructions (works with all AI tools)'
+      },
+      {
+        sourcePath: 'README.md',
+        targetPath: '.codex/README.md',
+        description: 'Codex adapter documentation'
+      }
+    ];
+  }
+
+  /**
+   * Install Codex adapter
+   */
+  async install(options: AdapterOptions): Promise<void> {
+    console.log('\n📦 Installing OpenAI Codex Adapter (Semi-Automation)\n');
+
+    // Ensure .codex directory exists
+    const codexDir = path.join(options.projectPath, '.codex');
+    await fs.ensureDir(codexDir);
+
+    // Generate AGENTS.md
+    const agentsMdPath = path.join(options.projectPath, 'AGENTS.md');
+    await this.generateAgentsMd(agentsMdPath, options);
+
+    // Copy README
+    const readmePath = path.join(__dirname, 'README.md');
+    if (await fs.pathExists(readmePath)) {
+      await fs.copy(readmePath, path.join(codexDir, 'README.md'));
+    }
+
+    console.log('\n✨ Codex adapter installed!');
+    console.log('\n📋 Files created:');
+    console.log('   - AGENTS.md (universal instructions)');
+    console.log('   - .codex/README.md (adapter documentation)');
+  }
+
+  /**
+   * Generate AGENTS.md file
+   */
+  private async generateAgentsMd(targetPath: string, options: AdapterOptions): Promise<void> {
+    const generator = new AgentsMdGenerator(
+      path.join(__dirname, '../../skills'),
+      path.join(__dirname, '../../agents'),
+      path.join(__dirname, '../../commands')
+    );
+
+    const content = await generator.generate({
+      projectName: options.projectName,
+      projectPath: options.projectPath
+    });
+
+    await fs.writeFile(targetPath, content);
+    console.log('  ✅ AGENTS.md - Universal SpecWeave instructions');
+  }
+
+  /**
+   * Post-installation instructions
+   */
+  async postInstall(options: AdapterOptions): Promise<void> {
+    console.log(this.getInstructions());
+  }
+
+  /**
+   * Get usage instructions for Codex adapter
+   */
+  getInstructions(): string {
+    return `
+================================================================
+      OpenAI Codex Adapter - Semi-Automation
+================================================================
+
+Your project is now configured for OpenAI Codex with SEMI-automation!
+
+WHAT THIS PROVIDES:
+
+- AGENTS.md (Universal Instructions)
+  - Works with Codex CLI, ChatGPT web, and IDEs
+  - Auto-generated from actual skills/agents
+  - SpecWeave structure and workflows
+  - GPT-5-Codex optimized guidance
+
+- Task-Based Execution
+  - Isolated environments per task
+  - File read/write operations
+  - Test execution and validation
+
+QUICK START:
+
+**Option 1: Codex CLI** (Fastest)
+
+1. Install Codex CLI:
+
+   # Included with ChatGPT Plus, Pro, Business, Enterprise
+   npm install -g openai-codex-cli
+
+2. Create your first feature:
+
+   codex "Read AGENTS.md and create increment for user authentication"
+
+   Codex will:
+   - Read AGENTS.md for SpecWeave context
+   - Adopt PM role: Create spec.md (WHAT/WHY)
+   - Adopt Architect role: Create plan.md (HOW)
+   - Create tasks.md
+   - Execute in isolated environment
+
+**Option 2: ChatGPT Web** (Most Accessible)
+
+1. Open ChatGPT (Plus/Pro/Business/Enterprise)
+
+2. Upload AGENTS.md file
+
+3. Say:
+   "I'm using SpecWeave framework. Create increment for user authentication."
+
+4. Copy generated content to files:
+   - spec.md
+   - plan.md
+   - tasks.md
+
+**Option 3: IDE Integration** (If available in your IDE)
+
+Use Codex integration in your IDE (VS Code, JetBrains, etc.)
+Reference AGENTS.md for SpecWeave structure.
+
+HOW TO USE:
+
+**With Codex CLI**:
+\`\`\`bash
+# Explicit reference (recommended):
+codex "Read AGENTS.md and [your request]"
+
+# Natural language:
+codex "Create a new feature following SpecWeave structure"
+
+# With context:
+codex "Following the PM role in AGENTS.md, create requirements for payments"
+\`\`\`
+
+**With ChatGPT Web**:
+1. Upload AGENTS.md at start of conversation
+2. Reference it: "Following AGENTS.md, create increment for..."
+3. Download or copy-paste generated files
+
+CONTEXT LOADING (70%+ Token Savings):
+
+CRITICAL: Tell Codex to read context-manifest.yaml first!
+
+\`\`\`bash
+# CLI:
+codex "Read context-manifest.yaml from increment 0001, load only those files, then implement task T001"
+
+# Web:
+# 1. Upload context-manifest.yaml
+# 2. Upload only files listed in manifest
+# 3. Request task implementation
+\`\`\`
+
+FEATURES:
+
+✅ GPT-5-Codex Model
+   - Optimized for engineering tasks
+   - Trained on complex, real-world projects
+   - Code generation, debugging, refactoring
+
+✅ Task-Based Execution
+   - Each task in isolated environment
+   - Real-time progress monitoring
+   - Verifiable evidence (citations, logs)
+
+✅ File Operations
+   - Read and edit files
+   - Run commands (tests, linters, type checkers)
+   - Create new files and directories
+
+✅ Multiple Access Points
+   - CLI (fastest)
+   - Web (most accessible)
+   - IDE (most integrated)
+   - GitHub (for PRs)
+   - iOS app (mobile)
+
+✅ Test Execution
+   - Run test harnesses
+   - Validate implementations
+   - Ensure quality
+
+EXAMPLE WORKFLOWS:
+
+1. **Create Feature (CLI)**:
+   \`\`\`bash
+   codex "Read AGENTS.md. Create increment 0002 for payment processing with Stripe. Follow SpecWeave structure."
+   \`\`\`
+
+2. **Create Feature (Web)**:
+   - Upload AGENTS.md
+   - Say: "Create increment for payment processing"
+   - Download generated files
+
+3. **Implement Task**:
+   \`\`\`bash
+   codex "Read increment 0002, implement task T001 (Setup Stripe SDK)"
+   \`\`\`
+
+4. **Fix Bug**:
+   \`\`\`bash
+   codex "Read AGENTS.md and increment 0001. Fix authentication bug. Run tests."
+   \`\`\`
+
+5. **Code Review**:
+   \`\`\`bash
+   codex "Adopt Tech Lead role from AGENTS.md. Review src/auth/ code."
+   \`\`\`
+
+TIPS & TRICKS:
+
+1. **Always Reference AGENTS.md**
+   - CLI: Explicit in command
+   - Web: Upload at conversation start
+
+2. **Use Task-Based Approach**
+   - Break work into tasks (T001, T002, etc.)
+   - Each task runs in isolated environment
+   - Easier to track and validate
+
+3. **Monitor Progress**
+   - CLI shows real-time progress (1-30 minutes per task)
+   - Web shows thinking process
+   - Review citations and logs
+
+4. **Leverage Multiple Access Points**
+   - CLI for speed
+   - Web for accessibility
+   - IDE for integration
+
+5. **Validate with Tests**
+   - Codex can run tests automatically
+   - Verify implementations work
+
+COMPARISON:
+
+| Feature | Claude Code | Codex |
+|---------|-------------|-------|
+| **Automation** | Full | Semi |
+| **Skills** | Native | Via AGENTS.md |
+| **Agents** | Native | Via AGENTS.md |
+| **Access** | CLI only | CLI + Web + IDE + GitHub + iOS |
+| **Model** | Sonnet 4.5 | GPT-5-Codex |
+| **Task Isolation** | No | Yes (isolated environments) |
+
+LIMITATIONS:
+
+- No native skills/agents (manual role adoption via AGENTS.md)
+- No hooks (can't auto-update docs on events)
+- Tasks run 1-30 minutes (not instant)
+- Requires ChatGPT Plus/Pro/Business/Enterprise
+
+But very powerful with GPT-5-Codex and multiple access points!
+
+PLANS & PRICING:
+
+- **ChatGPT Plus**: $20/month (includes Codex CLI + Web)
+- **ChatGPT Pro**: $200/month (unlimited, faster)
+- **Business/Enterprise**: Custom pricing
+
+Free trial may be available - check OpenAI website.
+
+DOCUMENTATION:
+
+- AGENTS.md: Universal SpecWeave instructions (READ THIS!)
+- SPECWEAVE.md: Complete framework documentation
+- .codex/README.md: Codex adapter guide
+- https://openai.com/codex/
+
+You're ready to build with SpecWeave on OpenAI Codex!
+
+Pro tip: Use CLI for speed, Web for accessibility, and always
+reference AGENTS.md for SpecWeave structure!
+    `;
+  }
+}

package/src/adapters/copilot/adapter.ts

@@ -2,73 +2,52 @@
  * GitHub Copilot Adapter
  *
  * Basic automation adapter for GitHub Copilot.
- * Provides workspace instructions that Copilot reads for context and suggestions.
+ * Copilot automatically reads AGENTS.md (universal standard) for context and suggestions.
  *
- * Since GitHub Copilot has limited configuration (workspace instructions only),
- * this adapter focuses on clear, structured guidance that Copilot can use
- * to provide better code suggestions and completions.
+ * This adapter requires no additional files - Copilot reads AGENTS.md automatically.
  */
 
 import * as path from 'path';
-import * as fs from 'fs-extra';
-import { AdapterBase } from '../adapter-base';
-import { AdapterOptions, AdapterFile } from '../adapter-interface';
+import fs from 'fs-extra';
+import { AdapterBase } from '../adapter-base.js';
+import { AdapterOptions, AdapterFile } from '../adapter-interface.js';
 
 export class CopilotAdapter extends AdapterBase {
   name = 'copilot';
-  description = 'GitHub Copilot adapter - Basic automation with workspace instructions';
+  description = 'GitHub Copilot adapter - Basic automation with AGENTS.md';
   automationLevel = 'basic' as const;
 
   /**
    * Detect if GitHub Copilot is available
    *
-   * Checks for:
-   * - .github/copilot/instructions.md exists
-   * - VS Code with Copilot extension
+   * Note: Detection is best-effort since Copilot might be installed
+   * but we can't detect it reliably. This adapter is safe to use
+   * as a fallback since Copilot reads AGENTS.md (universal standard).
    */
   async detect(): Promise<boolean> {
-    const hasInstructions = await this.fileExists('.github/copilot/instructions.md');
-    const hasGitHubDir = await this.fileExists('.github');
-
-    // Check for VS Code Copilot extension (best effort)
-    // This is approximate - Copilot might be installed but we can't detect reliably
-    return hasInstructions || hasGitHubDir;
+    // Always return false to make this a manual selection
+    // Users can explicitly choose Copilot adapter if they want
+    return false;
   }
 
   /**
    * Get files to install for Copilot adapter
+   *
+   * Note: Copilot automatically reads AGENTS.md (universal standard).
+   * No additional files needed.
    */
   getFiles(): AdapterFile[] {
-    return [
-      {
-        sourcePath: '.github/copilot/instructions.md',
-        targetPath: '.github/copilot/instructions.md',
-        description: 'GitHub Copilot workspace instructions'
-      },
-      {
-        sourcePath: 'README.md',
-        targetPath: '.github/copilot/README.md',
-        description: 'Copilot adapter documentation'
-      }
-    ];
+    return [];
   }
 
   /**
    * Install Copilot adapter
    */
   async install(options: AdapterOptions): Promise<void> {
-    console.log('\n📦 Installing GitHub Copilot Adapter (Basic Automation)\n');
-
-    // Ensure .github/copilot directory exists
-    const copilotDir = path.join(options.projectPath, '.github', 'copilot');
-    await fs.ensureDir(copilotDir);
-
-    // Copy files
-    await super.install(options);
+    console.log('\n📦 Configuring GitHub Copilot (Basic Automation)\n');
 
-    console.log('\n✨ Copilot adapter installed!');
-    console.log('\n📋 Files created:');
-    console.log('   - .github/copilot/instructions.md (workspace guidance)');
+    // No files to install - Copilot reads AGENTS.md automatically
+    console.log('✅ Copilot will automatically read AGENTS.md');
   }
 
   /**
@@ -91,14 +70,14 @@ Your project is now configured for GitHub Copilot!
 
 WHAT THIS PROVIDES:
 
-- Workspace Instructions (.github/copilot/instructions.md)
-  - Project overview (SpecWeave framework)
-  - Workflow guidance (creating increments)
-  - Context manifest explanation
-  - File structure reference
+- AGENTS.md (Universal Standard)
+  - Copilot automatically reads this file
+  - Contains all workflow instructions
+  - Project structure and templates
+  - Following agents.md standard (https://agents.md/)
 
 - Better Code Suggestions
-  - Copilot reads workspace instructions
+  - Copilot reads AGENTS.md for context
   - Suggests code following SpecWeave patterns
   - Understands project structure
 
@@ -108,26 +87,22 @@ Claude Code (Full Automation):
 - Native skills (auto-activate)
 - Native agents (separate context windows)
 - Native hooks (auto-update docs)
-- Slash commands
+- Slash commands (/inc, /do, /done)
 
 Cursor (Semi-Automation):
-- Simulated skills (.cursorrules)
-- Simulated agents (manual roles)
+- Reads AGENTS.md for workflow
 - @ context shortcuts
+- Composer multi-file editing
 
 Copilot (Basic Automation - This Adapter):
-- Workspace instructions only
+- Reads AGENTS.md automatically
 - Better code suggestions
 - No skills, agents, hooks, or commands
 - Manual workflow with AI assistance
 
-HOW WE BRIDGE THE GAP:
+HOW COPILOT USES AGENTS.MD:
 
-GitHub Copilot doesn't support custom commands or complex
-workflows. But it DOES read workspace instructions to provide
-better code suggestions.
-
-We provide clear instructions that teach Copilot about:
+GitHub Copilot automatically reads AGENTS.md to understand:
 - SpecWeave structure (.specweave/ folders)
 - File naming conventions (spec.md, plan.md, tasks.md)
 - Context manifests (what files to reference)
@@ -137,12 +112,11 @@ Result: Copilot suggests code that fits SpecWeave patterns!
 
 HOW TO USE SPECWEAVE WITH COPILOT:
 
-1. Copilot reads workspace instructions automatically
+1. Copilot reads AGENTS.md automatically
    - No action needed - just open project in VS Code
    - Copilot will suggest code following SpecWeave patterns
 
 2. Create increments manually:
-
    mkdir -p .specweave/increments/0001-user-auth
 
 3. Reference context manifests:
@@ -157,20 +131,19 @@ HOW TO USE SPECWEAVE WITH COPILOT:
 
 5. Use Copilot inline suggestions:
    Start typing in spec.md → Copilot suggests content
-   Following SpecWeave patterns from instructions.md
+   Following SpecWeave patterns from AGENTS.md
 
 WORKFLOW EXAMPLE:
 
 Creating a Feature:
 
 1. Create increment folder:
-
    mkdir -p .specweave/increments/0002-payments
    cd .specweave/increments/0002-payments
 
 2. Create spec.md:
    - Open file, start typing frontmatter
-   - Copilot suggests SpecWeave structure
+   - Copilot suggests SpecWeave structure (from AGENTS.md)
    - Fill in user stories, acceptance criteria
 
 3. Create plan.md:
@@ -191,14 +164,12 @@ LIMITATIONS (vs Claude Code & Cursor):
 - Completely manual workflow
 
 But Copilot still provides helpful suggestions!
-- Understands SpecWeave structure from instructions
+- Understands SpecWeave structure from AGENTS.md
 - Suggests code following project patterns
 
 DOCUMENTATION:
 
-- SPECWEAVE.md: Complete development guide
-- .github/copilot/instructions.md: Workspace instructions
-- .github/copilot/README.md: Copilot adapter guide
+- AGENTS.md: Universal workflow instructions (Copilot reads this!)
 - .specweave/docs/: Project documentation
 
 You're ready to build with SpecWeave on GitHub Copilot!

package/src/adapters/cursor/README.md

@@ -21,7 +21,6 @@ A skill is a specialized capability that activates automatically when relevant.
 
 ## increment-planner Skill
 When user says "create increment":
-1. Read .specweave/config.yaml
 2. Auto-increment number
 3. Create spec.md (act as PM role)
 4. Create plan.md (act as Architect role)
@@ -126,7 +125,6 @@ npx specweave init my-project --adapter cursor
 **User**: "Create increment for user authentication"
 
 **Cursor** (following .cursorrules):
-1. ✅ Read .specweave/config.yaml
 2. ✅ Find next increment number (0003)
 3. ✅ Create folder: `.specweave/increments/0003-user-authentication/`
 4. ✅ Act as PM: Create spec.md (WHAT/WHY, user stories, acceptance criteria)