specweave 0.6.8 → 0.7.0

package/src/adapters/codex/adapter.ts

@@ -1,333 +0,0 @@
-/**
- * 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/cursor/.cursor/context/docs-context.md

@@ -1,62 +0,0 @@
-# @docs - Architecture Documentation Context
-
-This file is loaded when you type `@docs` in Cursor.
-
-## What This Provides
-
-Quick access to architecture documentation:
-- System design (HLD)
-- ADRs (Architecture Decision Records)
-- Component diagrams (C4 Model)
-- Data models (ER diagrams)
-
-## Usage
-
-```
-@docs show me the system architecture
-@docs what ADRs exist for authentication?
-@docs explain the data model
-```
-
-## Files Loaded
-
-When `@docs` is used, Cursor should load:
-
-```
-.specweave/docs/internal/architecture/
-├── system-design.md           # HLD
-├── adr/                       # Architecture Decision Records
-│   ├── 0001-tech-stack.md
-│   ├── 0002-database-choice.md
-│   └── ...
-├── diagrams/                  # C4 diagrams
-│   ├── system-context.mmd     # C4 Level 1
-│   ├── system-container.mmd   # C4 Level 2
-│   └── {module}/              # C4 Level 3 (component)
-└── data-models/               # ER diagrams
-    └── schema.sql
-```
-
-## Context Precision
-
-**Don't load everything!**
-
-If working on specific module (e.g., authentication):
-1. Check context-manifest.yaml
-2. Load ONLY auth-related docs:
-   ```
-   .specweave/docs/internal/architecture/auth/
-   ├── design.md
-   ├── adr/0005-auth-method.md
-   └── diagrams/auth-flow.mmd
-   ```
-
-## Example Workflow
-
-User: `@docs show authentication architecture`
-
-You:
-1. Load .specweave/docs/internal/architecture/auth/
-2. Load ADRs related to auth (ADR-0005, ADR-0012)
-3. Load auth diagrams
-4. Summarize: "Authentication uses OAuth2 (ADR-0005), JWT tokens stored in httpOnly cookies (ADR-0012). See auth-flow.mmd for sequence diagram."

package/src/adapters/cursor/.cursor/context/increments-context.md

@@ -1,71 +0,0 @@
-# @increments - Current Increment Context
-
-This file is loaded when you type `@increments` in Cursor.
-
-## What This Provides
-
-Quick access to the current increment's:
-- spec.md (WHAT and WHY)
-- plan.md (HOW)
-- tasks.md (implementation steps)
-- context-manifest.yaml (what context to load)
-
-## Usage
-
-```
-@increments show me what we're working on
-@increments what's the current task?
-@increments load the spec for this feature
-```
-
-## Files Loaded
-
-When `@increments` is used, Cursor should load:
-
-1. **Current increment folder** (most recent in-progress):
-   ```
-   .specweave/increments/####-feature-name/
-   ├── spec.md
-   ├── plan.md
-   ├── tasks.md
-   └── context-manifest.yaml
-   ```
-
-2. **How to find current increment**:
-   ```bash
-   # List all increments
-   ls -la .specweave/increments/
-
-   # Find in-progress increments
-   grep -r "status: in-progress" .specweave/increments/*/spec.md
-   ```
-
-3. **Load order**:
-   - context-manifest.yaml (to know what else to load)
-   - spec.md (business requirements)
-   - plan.md (technical design)
-   - tasks.md (current task status)
-
-## Context Manifest Critical
-
-**ALWAYS read context-manifest.yaml first!**
-
-It tells you which additional files to load:
-```yaml
-spec_sections:
-  - .specweave/docs/internal/strategy/auth/spec.md
-documentation:
-  - .specweave/docs/internal/architecture/auth-design.md
-```
-
-Then load ONLY those files (70%+ token savings).
-
-## Example Workflow
-
-User: `@increments what's the current feature?`
-
-You:
-1. Find most recent in-progress increment
-2. Read spec.md → See it's user authentication
-3. Read tasks.md → See we're on T003 (OAuth2 implementation)
-4. Respond: "Working on user authentication (increment 0002). Currently on task T003: Implement OAuth2 flow."

package/src/adapters/cursor/.cursor/context/strategy-context.md

@@ -1,73 +0,0 @@
-# @strategy - Business Strategy Context
-
-This file is loaded when you type `@strategy` in Cursor.
-
-## What This Provides
-
-Quick access to business strategy documentation:
-- Product vision and goals
-- Business requirements (technology-agnostic)
-- User stories and acceptance criteria
-- PRDs (Product Requirements Documents)
-
-## Usage
-
-```
-@strategy what's the product vision?
-@strategy show me authentication requirements
-@strategy what are the success criteria?
-```
-
-## Files Loaded
-
-When `@strategy` is used, Cursor should load:
-
-```
-.specweave/docs/internal/strategy/
-├── {module}/                  # Module-specific strategy
-│   ├── overview.md            # Product vision
-│   ├── requirements.md        # FR/NFR (tech-agnostic)
-│   ├── user-stories.md        # All user stories
-│   └── success-criteria.md    # KPIs, metrics
-```
-
-## Context Precision
-
-**Don't load everything!**
-
-If working on authentication module:
-1. Load ONLY auth strategy:
-   ```
-   .specweave/docs/internal/strategy/auth/
-   ├── overview.md
-   ├── requirements.md
-   ├── user-stories.md
-   └── success-criteria.md
-   ```
-
-## Technology-Agnostic Requirements
-
-**Critical**: Strategy docs are technology-agnostic (WHAT/WHY, not HOW).
-
-**Good (technology-agnostic)**:
-```markdown
-## FR-001: User Authentication
-Users must be able to securely authenticate with their email and password.
-```
-
-**Bad (too technical)**:
-```markdown
-## FR-001: User Authentication
-Users authenticate via JWT tokens stored in httpOnly cookies with bcrypt password hashing.
-```
-
-The technical details go in architecture docs (@docs), not strategy.
-
-## Example Workflow
-
-User: `@strategy what are the authentication requirements?`
-
-You:
-1. Load .specweave/docs/internal/strategy/auth/requirements.md
-2. Read functional and non-functional requirements
-3. Summarize: "FR-001: Email/password auth. FR-002: Social login (Google, GitHub). NFR-001: < 2s login response time. NFR-002: 99.9% uptime."

package/src/adapters/cursor/.cursor/context/tests-context.md

@@ -1,89 +0,0 @@
-# @tests - Test Strategy Context
-
-This file is loaded when you type `@tests` in Cursor.
-
-## What This Provides
-
-Quick access to test documentation:
-- Test strategy (E2E, unit, integration)
-- Test coverage matrix (TC-0001 → test files)
-- Test cases (YAML format for skills)
-- Acceptance criteria validation
-
-## Usage
-
-```
-@tests show me test strategy
-@tests what tests exist for authentication?
-@tests map TC-0001 to test file
-```
-
-## Files Loaded
-
-When `@tests` is used, Cursor should load:
-
-```
-.specweave/increments/####-feature/tests.md    # Test strategy
-tests/                                          # Actual test code
-├── e2e/                                        # Playwright E2E tests
-│   └── auth.spec.ts
-├── unit/                                       # Unit tests
-│   └── auth-utils.test.ts
-└── integration/                                # Integration tests
-    └── auth-api.test.ts
-```
-
-## Test Coverage Matrix
-
-**tests.md contains mapping: TC-0001 → test file**
-
-Example:
-```markdown
-| TC ID   | Acceptance Criteria     | Test Type | Location               | Priority |
-|---------|-------------------------|-----------|------------------------|----------|
-| TC-0001 | Valid login redirects   | E2E       | tests/e2e/auth.spec.ts | P1       |
-| TC-0002 | Invalid password errors | E2E       | tests/e2e/auth.spec.ts | P1       |
-```
-
-## Four Levels of Test Cases
-
-### Level 1: Specification (TC-0001 in spec.md)
-```markdown
-- [ ] **TC-0001**: Valid credentials → redirect to dashboard
-```
-
-### Level 2: Feature Test Strategy (tests.md)
-Mapping TC-0001 to test implementation
-
-### Level 3: Skill Test Cases (for SpecWeave skills)
-YAML format in src/skills/{name}/test-cases/
-
-### Level 4: Code Tests (Playwright, Jest, etc.)
-```typescript
-test('TC-0001: Valid Login Flow', async ({ page }) => {
-  // Implementation
-});
-```
-
-## Context Precision
-
-**Load test strategy for current increment only**
-
-If working on auth increment:
-```
-.specweave/increments/0002-user-auth/tests.md
-tests/e2e/auth.spec.ts
-tests/unit/auth-utils.test.ts
-```
-
-Don't load ALL tests from ALL increments.
-
-## Example Workflow
-
-User: `@tests what's the test coverage for authentication?`
-
-You:
-1. Load .specweave/increments/0002-user-auth/tests.md
-2. Read test coverage matrix
-3. Load referenced test files (auth.spec.ts)
-4. Summarize: "TC-0001 to TC-0008 covered. 8/8 E2E tests in auth.spec.ts. All P1 tests passing."