specweave 0.1.9 → 0.3.1

package/src/adapters/claude-md-generator.ts

@@ -0,0 +1,311 @@
+/**
+ * CLAUDE.md Generator
+ *
+ * Generates CLAUDE.md - the PRIMARY instruction file for Claude Code.
+ *
+ * CRITICAL:
+ * - Claude Code ONLY reads CLAUDE.md (NOT AGENTS.md)
+ * - This is the native/baseline implementation (skills, agents, hooks, slash commands)
+ * - Claude Code is NOT an adapter - it's the gold standard that others try to approximate
+ *
+ * This generator creates a quick reference that lists what's actually installed,
+ * so when we add new agents/skills, CLAUDE.md stays in sync automatically.
+ */
+
+import { DocGenerator } from './doc-generator.js';
+import * as path from 'path';
+import fs from 'fs-extra';
+import { getDirname } from '../utils/esm-helpers.js';
+
+const __dirname = getDirname(import.meta.url);
+
+export interface ClaudeMdOptions {
+  projectName: string;
+  projectPath: string;
+  templatePath?: string;
+}
+
+/**
+ * Generate CLAUDE.md with dynamic agent/skill sections
+ */
+export class ClaudeMdGenerator {
+  private docGen: DocGenerator;
+
+  constructor(
+    skillsDir?: string,
+    agentsDir?: string,
+    commandsDir?: string
+  ) {
+    this.docGen = new DocGenerator(skillsDir, agentsDir, commandsDir);
+  }
+
+  /**
+   * Generate complete CLAUDE.md content
+   */
+  async generate(options: ClaudeMdOptions): Promise<string> {
+    // Read template
+    const templatePath = options.templatePath ||
+      path.join(__dirname, '../templates/CLAUDE.md.template');
+
+    if (!await fs.pathExists(templatePath)) {
+      throw new Error(`CLAUDE.md template not found at: ${templatePath}`);
+    }
+
+    let content = await fs.readFile(templatePath, 'utf-8');
+
+    // Replace placeholders
+    content = content.replace(/\{PROJECT_NAME\}/g, options.projectName);
+
+    // Replace dynamic sections
+    content = await this.replaceDynamicSections(content);
+
+    return content;
+  }
+
+  /**
+   * Replace dynamic sections in template
+   */
+  private async replaceDynamicSections(content: string): Promise<string> {
+    // Extract actual skills and agents
+    const skills = await this.docGen.extractSkills();
+    const agents = await this.docGen.extractAgents();
+    const commands = await this.docGen.extractCommands();
+
+    // Replace agents section (lines 226-243 in template)
+    content = this.replaceAgentsSection(content, agents);
+
+    // Replace skills section (lines 248-278 in template)
+    content = this.replaceSkillsSection(content, skills);
+
+    // Replace commands section if needed
+    content = this.replaceCommandsSection(content, commands);
+
+    return content;
+  }
+
+  /**
+   * Generate dynamic agents section
+   */
+  private replaceAgentsSection(content: string, agents: any[]): string {
+    const agentsTable = this.generateAgentsTable(agents);
+
+    // Find the agents section and replace it
+    // Look for "## Agents (Activate Automatically)" section
+    const agentsSectionRegex = /## Agents \(Activate Automatically\)[\s\S]*?(?=\n## |$)/;
+
+    const agentsSection = `## Agents (Activate Automatically)
+
+**Strategic Agents** (pre-installed & ready to use):
+
+${agentsTable}
+
+**All ${agents.length} agents are pre-installed** - Claude uses the right one based on your request!
+
+**See**: \`.claude/agents/\` for complete list
+
+---
+`;
+
+    if (agentsSectionRegex.test(content)) {
+      return content.replace(agentsSectionRegex, agentsSection);
+    }
+
+    return content;
+  }
+
+  /**
+   * Generate agents table
+   */
+  private generateAgentsTable(agents: any[]): string {
+    let table = '| Agent | Purpose | Activates When |\n';
+    table += '|-------|---------|----------------|\n';
+
+    for (const agent of agents) {
+      const activation = this.getAgentActivation(agent.name);
+      table += `| \`${agent.name}\` | ${agent.description} | ${activation} |\n`;
+    }
+
+    return table;
+  }
+
+  /**
+   * Get agent activation guidance
+   */
+  private getAgentActivation(agentName: string): string {
+    const activations: Record<string, string> = {
+      'pm': 'Planning features',
+      'architect': 'Technical design',
+      'security': 'Security review',
+      'qa-lead': 'Testing',
+      'devops': 'Deployment needed',
+      'tech-lead': 'Code review',
+      'sre': 'Troubleshooting',
+      'docs-writer': 'Writing docs',
+      'performance': 'Optimization needed',
+      'frontend': 'Frontend development',
+      'nodejs-backend': 'Node.js backend',
+      'python-backend': 'Python backend',
+      'nextjs': 'Next.js development',
+      'dotnet-backend': '.NET development'
+    };
+
+    return activations[agentName] || 'Specialized tasks';
+  }
+
+  /**
+   * Generate dynamic skills section
+   */
+  private replaceSkillsSection(content: string, skills: any[]): string {
+    const skillsTable = this.generateSkillsTable(skills);
+
+    // Find the skills section and replace it
+    const skillsSectionRegex = /## Skills \(Activate Automatically\)[\s\S]*?(?=\n## |$)/;
+
+    const skillsSection = `## Skills (Activate Automatically)
+
+**Framework Skills** (always available):
+
+${this.generateFrameworkSkillsTable(skills)}
+
+**Technology Skills** (all pre-installed):
+
+${this.generateTechSkillsTable(skills)}
+
+**Integration Skills** (all pre-installed):
+
+${this.generateIntegrationSkillsTable(skills)}
+
+**See**: \`.claude/skills/\` for complete list of ${skills.length}+ skills!
+
+---
+`;
+
+    if (skillsSectionRegex.test(content)) {
+      return content.replace(skillsSectionRegex, skillsSection);
+    }
+
+    return content;
+  }
+
+  /**
+   * Generate framework skills table
+   */
+  private generateFrameworkSkillsTable(skills: any[]): string {
+    const frameworkSkills = skills.filter(s =>
+      ['specweave-detector', 'increment-planner', 'context-loader', 'skill-router',
+       'spec-driven-debugging', 'spec-driven-brainstorming', 'brownfield-analyzer'].includes(s.name)
+    );
+
+    let table = '| Skill | Purpose | Activates When |\n';
+    table += '|-------|---------|----------------|\n';
+
+    for (const skill of frameworkSkills) {
+      const activation = this.getSkillActivation(skill.name);
+      table += `| \`${skill.name}\` | ${this.truncate(skill.description, 60)} | ${activation} |\n`;
+    }
+
+    return table;
+  }
+
+  /**
+   * Generate tech skills table
+   */
+  private generateTechSkillsTable(skills: any[]): string {
+    const techSkills = skills.filter(s =>
+      ['nodejs-backend', 'python-backend', 'nextjs', 'frontend', 'dotnet-backend',
+       'e2e-playwright'].includes(s.name)
+    );
+
+    let table = '| Skill | Purpose | Activates When |\n';
+    table += '|-------|---------|----------------|\n';
+
+    for (const skill of techSkills) {
+      const activation = this.getSkillActivation(skill.name);
+      table += `| \`${skill.name}\` | ${this.truncate(skill.description, 60)} | ${activation} |\n`;
+    }
+
+    return table;
+  }
+
+  /**
+   * Generate integration skills table
+   */
+  private generateIntegrationSkillsTable(skills: any[]): string {
+    const integrationSkills = skills.filter(s =>
+      ['jira-sync', 'github-sync', 'ado-sync', 'hetzner-provisioner',
+       'cost-optimizer', 'figma-mcp-connector'].includes(s.name)
+    );
+
+    let table = '| Skill | Purpose | Activates When |\n';
+    table += '|-------|---------|----------------|\n';
+
+    for (const skill of integrationSkills) {
+      const activation = this.getSkillActivation(skill.name);
+      table += `| \`${skill.name}\` | ${this.truncate(skill.description, 60)} | ${activation} |\n`;
+    }
+
+    return table;
+  }
+
+  /**
+   * Get skill activation guidance
+   */
+  private getSkillActivation(skillName: string): string {
+    const activations: Record<string, string> = {
+      'specweave-detector': 'User asks about SpecWeave',
+      'increment-planner': '/pi or feature planning',
+      'context-loader': 'Working on increments',
+      'skill-router': 'Ambiguous requests',
+      'spec-driven-debugging': 'Bug or test failure',
+      'spec-driven-brainstorming': 'Brainstorm or refine idea',
+      'nodejs-backend': 'Node.js backend',
+      'python-backend': 'Python backend',
+      'nextjs': 'Next.js',
+      'frontend': 'Frontend',
+      'dotnet-backend': '.NET',
+      'jira-sync': 'JIRA integration',
+      'github-sync': 'GitHub integration',
+      'ado-sync': 'Azure DevOps sync',
+      'hetzner-provisioner': 'Hetzner deployment',
+      'cost-optimizer': 'Cost optimization',
+      'e2e-playwright': 'E2E testing'
+    };
+
+    return activations[skillName] || 'Specialized tasks';
+  }
+
+  /**
+   * Generate skills table
+   */
+  private generateSkillsTable(skills: any[]): string {
+    let table = '| Skill | Description |\n';
+    table += '|-------|-------------|\n';
+
+    for (const skill of skills.slice(0, 20)) { // Top 20 skills
+      table += `| \`${skill.name}\` | ${this.truncate(skill.description, 80)} |\n`;
+    }
+
+    if (skills.length > 20) {
+      table += `| _...and ${skills.length - 20} more_ | See \`.claude/skills/\` |\n`;
+    }
+
+    return table;
+  }
+
+  /**
+   * Replace commands section
+   */
+  private replaceCommandsSection(content: string, commands: any[]): string {
+    // Commands are already listed in the template, but we could make them dynamic too
+    // For now, we'll skip this since commands are explicitly documented
+    return content;
+  }
+
+  /**
+   * Truncate text to max length
+   */
+  private truncate(text: string, maxLength: number): string {
+    if (text.length <= maxLength) return text;
+    return text.substring(0, maxLength - 3) + '...';
+  }
+}

package/src/adapters/codex/README.md

@@ -0,0 +1,105 @@
+# OpenAI Codex Adapter
+
+**Automation Level**: Semi (Good experience with GPT-5-Codex and multiple access points)
+
+## Overview
+
+The Codex adapter provides **semi-automation** for SpecWeave using OpenAI's Codex (ChatGPT Code Interpreter/Codex CLI) with **AGENTS.md** as the universal instruction file.
+
+## Key Features
+
+- **GPT-5-Codex Model**: Optimized for engineering tasks
+- **Multiple Access Points**: CLI, Web, IDE, GitHub, iOS app
+- **Task-Based Execution**: Isolated environments per task
+- **File Operations**: Read, write, execute commands
+- **Test Execution**: Run tests and validate implementations
+- **Real-Time Progress**: Monitor task execution (1-30 min/task)
+
+## Installation
+
+```bash
+# Install Codex CLI (requires ChatGPT Plus/Pro/Business/Enterprise)
+npm install -g openai-codex-cli
+
+# Initialize SpecWeave project with Codex adapter
+npx specweave init my-project --adapter codex
+```
+
+## How It Works
+
+### Option 1: Codex CLI (Fastest)
+```bash
+codex "Read AGENTS.md and create increment for user authentication"
+```
+
+### Option 2: ChatGPT Web (Most Accessible)
+1. Upload AGENTS.md file
+2. Say: "Create increment for user authentication following SpecWeave"
+3. Copy generated content to files
+
+### Option 3: IDE Integration
+Use Codex in your IDE (VS Code, JetBrains) with AGENTS.md reference
+
+## Universal AGENTS.md
+
+Instead of tool-specific files, SpecWeave uses **AGENTS.md** that works with ALL tools:
+
+- ✅ Codex (OpenAI)
+- ✅ Gemini CLI
+- ✅ Cursor
+- ✅ GitHub Copilot
+- ✅ ANY AI tool
+
+**Single source of truth** = easier maintenance!
+
+## Example Workflows
+
+### Create Feature (CLI)
+```bash
+codex "Read AGENTS.md. Create increment 0002 for payment processing with Stripe."
+```
+
+### Create Feature (Web)
+1. Upload AGENTS.md to ChatGPT
+2. Say: "Create increment for payment processing"
+3. Download generated files
+
+### Implement Task
+```bash
+codex "Read increment 0002, implement task T001"
+```
+
+### Fix Bug with Tests
+```bash
+codex "Read AGENTS.md and increment 0001. Fix auth bug. Run tests."
+```
+
+## Comparison with Claude Code
+
+| Feature | Claude Code | Codex |
+|---------|-------------|-------|
+| **Automation** | Full | Semi |
+| **Skills** | Native | Via AGENTS.md |
+| **Agents** | Native | Via AGENTS.md |
+| **Access Points** | CLI only | CLI + Web + IDE + GitHub + iOS |
+| **Model** | Sonnet 4.5 | GPT-5-Codex |
+| **Task Isolation** | No | Yes (isolated per task) |
+| **Hooks** | Yes | No |
+
+## Plans & Pricing
+
+- **ChatGPT Plus**: $20/month (Codex included)
+- **ChatGPT Pro**: $200/month (unlimited, faster)
+- **Business/Enterprise**: Custom pricing
+
+## Links
+
+- [OpenAI Codex](https://openai.com/codex/)
+- [ChatGPT Features](https://chatgpt.com/features/codex)
+- [SpecWeave Website](https://spec-weave.com)
+
+---
+
+**Status**: Active (v0.2.0+)
+**Market Share**: ~20% (OpenAI users)
+**Priority**: P1 (high impact - most accessible AI tool)