specweave 0.1.9 → 0.3.0

package/src/adapters/gemini/adapter.ts

@@ -0,0 +1,298 @@
+/**
+ * Gemini CLI Adapter
+ *
+ * Semi-automation adapter for Google Gemini CLI.
+ * Uses universal AGENTS.md file for instructions.
+ *
+ * Gemini CLI features:
+ * - Open-source AI agent (Apache 2.0)
+ * - 1M token context window
+ * - ReAct loop with built-in tools
+ * - MCP (Model Context Protocol) support
+ * - Agent mode for multi-file tasks
+ */
+
+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 GeminiAdapter extends AdapterBase {
+  name = 'gemini';
+  description = 'Gemini CLI adapter - Semi-automation with AGENTS.md and agent mode';
+  automationLevel = 'semi' as const;
+
+  /**
+   * Detect if Gemini CLI is available
+   *
+   * Checks for:
+   * - gemini command in PATH
+   * - .gemini/ directory exists
+   * - AGENTS.md file exists (previously configured)
+   */
+  async detect(): Promise<boolean> {
+    const hasGeminiCLI = await this.commandExists('gemini');
+    const hasGeminiDir = await this.fileExists('.gemini');
+    const hasAgentsMd = await this.fileExists('AGENTS.md');
+
+    return hasGeminiCLI || hasGeminiDir || hasAgentsMd;
+  }
+
+  /**
+   * Get files to install for Gemini adapter
+   */
+  getFiles(): AdapterFile[] {
+    return [
+      {
+        sourcePath: 'AGENTS.md',
+        targetPath: 'AGENTS.md',
+        description: 'Universal SpecWeave instructions (works with all AI tools)'
+      },
+      {
+        sourcePath: 'README.md',
+        targetPath: '.gemini/README.md',
+        description: 'Gemini adapter documentation'
+      }
+    ];
+  }
+
+  /**
+   * Install Gemini adapter
+   */
+  async install(options: AdapterOptions): Promise<void> {
+    console.log('\n📦 Installing Gemini CLI Adapter (Semi-Automation)\n');
+
+    // Ensure .gemini directory exists
+    const geminiDir = path.join(options.projectPath, '.gemini');
+    await fs.ensureDir(geminiDir);
+
+    // 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(geminiDir, 'README.md'));
+    }
+
+    console.log('\n✨ Gemini adapter installed!');
+    console.log('\n📋 Files created:');
+    console.log('   - AGENTS.md (universal instructions)');
+    console.log('   - .gemini/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 Gemini adapter
+   */
+  getInstructions(): string {
+    return `
+================================================================
+      Gemini CLI Adapter - Semi-Automation
+================================================================
+
+Your project is now configured for Gemini CLI with SEMI-automation!
+
+WHAT THIS PROVIDES:
+
+- AGENTS.md (Universal Instructions)
+  - Works with Gemini CLI AND other tools
+  - Auto-generated from actual skills/agents
+  - SpecWeave structure and workflows
+  - 1M token context window support
+
+- Agent Mode Integration
+  - Multi-file task handling
+  - ReAct loop with built-in tools
+  - MCP support for extensibility
+
+QUICK START:
+
+1. Install Gemini CLI (if not already installed):
+
+   npm install -g @google-cloud/gemini-cli
+
+2. Authenticate:
+
+   gemini auth
+
+3. Create your first feature:
+
+   gemini "Read AGENTS.md and create increment for user authentication"
+
+   Gemini 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
+   - Use agent mode for multi-file operations
+
+4. Continue development:
+
+   gemini "Implement task T001 from increment 0001"
+   gemini "Run tests for increment 0001"
+   gemini "Review and fix any issues"
+
+HOW TO USE:
+
+Gemini CLI reads AGENTS.md automatically when you reference it:
+
+\`\`\`bash
+# Explicit reference (recommended):
+gemini "Read AGENTS.md and [your request]"
+
+# Natural language:
+gemini "Create a new feature following SpecWeave structure"
+
+# With context:
+gemini "Following the PM role in AGENTS.md, create requirements for payments"
+\`\`\`
+
+CONTEXT LOADING (70%+ Token Savings):
+
+CRITICAL: Tell Gemini to read context-manifest.yaml first!
+
+\`\`\`bash
+gemini "Read context-manifest.yaml from increment 0001, load only those files, then implement task T001"
+\`\`\`
+
+**Why this matters**:
+- Gemini has 1M token context window
+- But loading everything wastes tokens
+- Context manifests = precise, efficient loading
+
+FEATURES:
+
+✅ 1M Token Context Window
+   - Can handle large specifications
+   - Read entire codebase if needed
+
+✅ Agent Mode
+   - Multi-file task completion
+   - Automatic planning and execution
+   - Interactive approval before changes
+
+✅ Built-in Tools
+   - File operations
+   - Shell commands
+   - Google Search grounding
+   - Web fetching
+
+✅ MCP Support
+   - Extend with custom integrations
+   - Local or remote MCP servers
+
+✅ Free Tier
+   - Gemini 2.5 Pro included
+   - 60 requests/minute
+   - 1,000 requests/day
+
+EXAMPLE WORKFLOWS:
+
+1. **Create Feature**:
+   \`\`\`bash
+   gemini "Read AGENTS.md. Create increment 0002 for payment processing with Stripe. Follow SpecWeave structure: spec.md (PM role), plan.md (Architect role), tasks.md"
+   \`\`\`
+
+2. **Implement Task**:
+   \`\`\`bash
+   gemini "Read increment 0002, implement task T001 (Setup Stripe SDK)"
+   \`\`\`
+
+3. **Fix Bug**:
+   \`\`\`bash
+   gemini "Read AGENTS.md and increment 0001. Fix authentication bug in login endpoint. Update tests."
+   \`\`\`
+
+4. **Review Code**:
+   \`\`\`bash
+   gemini "Adopt Tech Lead role from AGENTS.md. Review code in src/auth/ and provide feedback"
+   \`\`\`
+
+TIPS & TRICKS:
+
+1. **Always Reference AGENTS.md**
+   - Ensures Gemini understands SpecWeave structure
+   - Provides role definitions (PM, Architect, etc.)
+
+2. **Use Agent Mode**
+   - For complex, multi-file tasks
+   - Gemini proposes plan before execution
+   - You approve changes
+
+3. **Leverage 1M Context Window**
+   - Can load large specs
+   - But still use context manifests for efficiency
+
+4. **MCP Integration**
+   - Connect to your tools (JIRA, GitHub, etc.)
+   - See: https://modelcontextprotocol.io/
+
+5. **Check Gemini Documentation**
+   - \`gemini --help\`
+   - https://developers.google.com/gemini-code-assist/docs/gemini-cli
+
+COMPARISON:
+
+| Feature | Claude Code | Gemini CLI |
+|---------|-------------|------------|
+| **Automation** | Full | Semi |
+| **Skills** | Native | Via AGENTS.md |
+| **Agents** | Native | Via AGENTS.md |
+| **Context Window** | 200k | 1M (5x larger!) |
+| **Cost** | Paid | Free tier available |
+| **Open Source** | No | Yes (Apache 2.0) |
+
+LIMITATIONS:
+
+- No native skills/agents (manual role adoption via AGENTS.md)
+- No hooks (can't auto-update docs on events)
+- Requires explicit instruction referencing
+- CLI-only (no IDE integration yet)
+
+But still VERY powerful with 1M context and agent mode!
+
+DOCUMENTATION:
+
+- AGENTS.md: Universal SpecWeave instructions (READ THIS!)
+- SPECWEAVE.md: Complete framework documentation
+- .gemini/README.md: Gemini adapter guide
+- https://developers.google.com/gemini-code-assist/docs/gemini-cli
+
+You're ready to build with SpecWeave on Gemini CLI!
+
+Pro tip: Leverage the 1M token context window for large specifications,
+but always use context manifests for efficiency!
+    `;
+  }
+}

package/src/adapters/generic/adapter.ts

@@ -1,21 +1,21 @@
 /**
  * Generic Adapter
  *
- * Manual workflow adapter that works with ANY AI tool.
- * Provides step-by-step instructions for using SpecWeave without tool-specific features.
+ * Universal adapter that works with ANY AI tool.
+ * All AI tools can read AGENTS.md (universal standard) for workflow instructions.
  *
  * This adapter ensures 100% compatibility - works with ChatGPT web, Claude web,
  * Gemini, or literally ANY AI that can read markdown and follow instructions.
  */
 
 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 GenericAdapter extends AdapterBase {
   name = 'generic';
-  description = 'Generic adapter - Manual workflow for ANY AI tool (ChatGPT, Gemini, etc.)';
+  description = 'Generic adapter - AGENTS.md works with ANY AI tool (ChatGPT, Gemini, etc.)';
   automationLevel = 'manual' as const;
 
   /**
@@ -31,34 +31,22 @@ export class GenericAdapter extends AdapterBase {
 
   /**
    * Get files to install for Generic adapter
+   *
+   * Note: Any AI tool can read AGENTS.md (universal standard).
+   * No additional files needed.
    */
   getFiles(): AdapterFile[] {
-    return [
-      {
-        sourcePath: 'SPECWEAVE-MANUAL.md',
-        targetPath: 'SPECWEAVE-MANUAL.md',
-        description: 'Complete manual workflow guide for ANY AI tool'
-      },
-      {
-        sourcePath: 'README.md',
-        targetPath: '.specweave/adapters/generic/README.md',
-        description: 'Generic adapter documentation'
-      }
-    ];
+    return [];
   }
 
   /**
    * Install Generic adapter
    */
   async install(options: AdapterOptions): Promise<void> {
-    console.log('\n📦 Installing Generic Adapter (Manual Workflow)\n');
-
-    // Generic adapter is simple - just copy manual guide
-    await super.install(options);
+    console.log('\n📦 Configuring for Universal AI Tool Compatibility\n');
 
-    console.log('\n✨ Generic adapter installed!');
-    console.log('\n📋 Files created:');
-    console.log('   - SPECWEAVE-MANUAL.md (complete manual workflow guide)');
+    // No files to install - any AI can read AGENTS.md
+    console.log('✅ AGENTS.md works with any AI tool (ChatGPT, Gemini, Claude web, etc.)');
   }
 
   /**
@@ -74,35 +62,49 @@ export class GenericAdapter extends AdapterBase {
   getInstructions(): string {
     return `
 ================================================================
-        Generic Adapter - Manual Workflow
+        Generic Adapter - Universal Compatibility
 ================================================================
 
 Your project is now configured for ANY AI tool!
 
 WHAT THIS PROVIDES:
 
-- SPECWEAVE-MANUAL.md (Complete Manual Guide)
-  - Step-by-step instructions for creating increments
-  - Templates you can copy-paste to any AI
-  - Workflow guidance (no tool dependencies)
-  - Works with LITERALLY any AI
+- AGENTS.md (Universal Standard)
+  - Any AI tool can read this file
+  - Contains all workflow instructions
+  - Project structure and templates
+  - Following agents.md standard (https://agents.md/)
 
 - 100% Compatibility
   - ChatGPT (web), Claude (web), Gemini
-  - Any AI that can read text
+  - Any AI that can read markdown
+
+HOW TO USE AGENTS.MD WITH ANY AI:
+
+Method 1: Copy-Paste Workflow (ChatGPT web, Claude web, etc.)
+1. Open AGENTS.md in your browser/editor
+2. Copy relevant section (e.g., "Creating a Feature Increment")
+3. Paste into AI chat (ChatGPT, Claude web, Gemini, etc.)
+4. Ask AI to follow the instructions
+5. AI generates content (spec.md, plan.md, etc.)
+6. Copy AI's response, save to files
+
+Method 2: File System Access (AI with file access)
+1. AI automatically reads AGENTS.md
+2. Ask: "Create increment for user authentication"
+3. AI follows AGENTS.md workflow
+4. AI creates files directly
 
 UNDERSTANDING "MANUAL":
 
 Manual = You Orchestrate, AI Executes
 
 Example workflow:
-1. You read SPECWEAVE-MANUAL.md (Step 1: Create Folder)
-2. You run: mkdir -p .specweave/increments/0001-auth
-3. You read Step 2: Create spec.md
-4. You copy template from manual, paste to AI (ChatGPT)
-5. AI generates spec.md content
-6. You copy AI's response, save to spec.md file
-7. Repeat for plan.md, tasks.md, etc.
+1. Read AGENTS.md section "Creating a Feature Increment"
+2. Copy instructions to ChatGPT
+3. ChatGPT generates spec.md content
+4. Save content to .specweave/increments/0001-auth/spec.md
+5. Repeat for plan.md, tasks.md
 
 Manual does not mean harder - just means YOU control each step (no automation).
 Benefit: Works with ANY AI tool!
@@ -110,13 +112,13 @@ Benefit: Works with ANY AI tool!
 COMPARISON:
 
 Claude Code (Full): "create increment" -> Done in 30 seconds (auto)
-Cursor (Semi): "create increment" -> Done in 5 minutes (.cursorrules)
-Copilot (Basic): Create files manually, Copilot suggests content
-Generic (Manual): Follow SPECWEAVE-MANUAL.md step-by-step (30-60 min)
+Cursor (Semi): "create increment" -> Done in 5 minutes (reads AGENTS.md)
+Copilot (Basic): Reads AGENTS.md, suggests content as you type
+Generic (Manual): Copy AGENTS.md instructions to any AI (10-30 min)
 
 Trade-off: Speed vs Compatibility
-- Claude Code: Fast, but only works with Claude Code
-- Generic: Slower, but works with EVERY AI tool!
+- Claude Code: Fast, but requires Claude Code CLI
+- Generic: Slower, but works with EVERY AI tool (even web-based)!
 
 WHEN TO USE:
 
@@ -127,33 +129,35 @@ Use Generic adapter if:
 - Simple projects where automation isn't critical
 
 Consider alternatives if:
-- You want automation -> Use Claude Code (full) or Cursor (semi)
-- You have file system access -> Use Copilot at minimum
+- You want automation -> Use Claude Code (full)
+- You have CLI access -> Use Cursor (semi) or Copilot (basic)
 - Large projects -> Manual workflow becomes tedious
 
 QUICK START:
 
-1. Open SPECWEAVE-MANUAL.md
-   Read the complete manual workflow guide
+1. Open AGENTS.md
+   Read the "Common Workflows" section
+
+2. Copy workflow to your AI tool:
+   - "Creating a Feature Increment" section
+   - Paste into ChatGPT/Claude/Gemini
 
-2. Follow step-by-step for your first feature
-   - Step 1: Create increment folder
-   - Step 2: Create spec.md (copy template, paste to AI, save)
-   - Step 3: Create plan.md (copy template, paste to AI, save)
-   - Step 4: Create tasks.md (copy template, paste to AI, save)
+3. Follow AI's guidance:
+   - AI generates spec.md content (copy & save)
+   - AI generates plan.md content (copy & save)
+   - AI generates tasks.md content (copy & save)
 
-3. Use any AI tool you prefer
+4. Use any AI tool you prefer:
    ChatGPT, Claude web, Gemini, Perplexity, etc.
 
 DOCUMENTATION:
 
-- SPECWEAVE-MANUAL.md: Complete step-by-step guide (READ THIS FIRST!)
-- SPECWEAVE.md: Complete technical documentation
+- AGENTS.md: Universal workflow instructions (works with any AI!)
 - .specweave/docs/: Project documentation
 
 You're ready to build with SpecWeave using ANY AI tool!
 
-Remember: Generic = Manual = Copy-paste workflow, but 100% compatible!
+Remember: AGENTS.md is the universal standard - it works everywhere!
     `;
   }
 }

package/src/adapters/registry.yaml

@@ -9,21 +9,23 @@ last_updated: 2025-10-27
 
 adapters:
   - name: claude
-    description: "Claude Code adapter - Full automation with skills, agents, hooks"
+    description: "Claude Code - NATIVE/BASELINE (no adapter needed!). Full automation with skills, agents, hooks"
     automation_level: full
-    status: active
+    status: native
     directory: claude
     features:
+      - Native skills, agents, hooks (no approximation needed)
       - Skills auto-activate (specweave-detector, skill-router, etc.)
       - Agents coordinate (PM, Architect, DevOps, QA, Security)
       - Hooks auto-update docs (post-task-completion, etc.)
-      - Slash commands (/create-increment, /review-docs, etc.)
-      - Best experience, most features
+      - Slash commands (/create-increment, /sync-docs, etc.)
+      - Best experience, most features - THE BASELINE!
     requirements:
       - Claude Code CLI installed
       - Node.js >= 18.0.0
     market_share: 10%
-    priority: P1
+    priority: P0
+    note: "Claude is the native experience - adapters exist to approximate these capabilities for other tools"
 
   - name: cursor
     description: "Cursor adapter - Semi-automation with .cursorrules and @ shortcuts"
@@ -32,7 +34,7 @@ adapters:
     directory: cursor
     features:
       - .cursorrules with SpecWeave workflow instructions
-      - @ context shortcuts (@increments, @docs, @strategy)
+      - "@ context shortcuts (@increments, @docs, @strategy)"
       - Composer multi-file editing support
       - Good experience, semi-automated
     requirements:
@@ -73,6 +75,41 @@ adapters:
     market_share: 20%
     priority: P1
 
+  - name: gemini
+    description: "Gemini CLI adapter - Semi-automation with AGENTS.md and agent mode"
+    automation_level: semi
+    status: active
+    directory: gemini
+    features:
+      - AGENTS.md universal instructions
+      - 1M token context window (5x larger than Claude!)
+      - Agent mode for multi-file tasks
+      - MCP (Model Context Protocol) support
+      - Free tier available (60 req/min, 1K req/day)
+      - Open source (Apache 2.0)
+    requirements:
+      - Gemini CLI installed
+      - Node.js >= 18.0.0
+    market_share: 10%
+    priority: P1
+
+  - name: codex
+    description: "OpenAI Codex adapter - Semi-automation with AGENTS.md and GPT-5-Codex"
+    automation_level: semi
+    status: active
+    directory: codex
+    features:
+      - AGENTS.md universal instructions
+      - GPT-5-Codex optimized for engineering
+      - Multiple access points (CLI + Web + IDE + GitHub + iOS)
+      - Task-based isolated execution
+      - File operations and test execution
+    requirements:
+      - ChatGPT Plus/Pro/Business/Enterprise
+      - Node.js >= 18.0.0
+    market_share: 20%
+    priority: P1
+
 # Future adapters (P2/P3)
 future_adapters:
   - name: windsurf
@@ -81,46 +118,70 @@ future_adapters:
     status: planned
     priority: P2
 
-  - name: gemini
-    description: "Google Gemini adapter (if requested by community)"
-    automation_level: basic
-    status: planned
-    priority: P3
-
 # Adapter capabilities comparison
 capabilities:
   skills:
     claude: full
-    cursor: partial
-    copilot: none
-    generic: none
+    cursor: via_agents_md
+    copilot: via_agents_md
+    gemini: via_agents_md
+    codex: via_agents_md
+    generic: via_agents_md
 
   agents:
     claude: full
-    cursor: manual
-    copilot: manual
-    generic: manual
+    cursor: via_agents_md
+    copilot: via_agents_md
+    gemini: via_agents_md
+    codex: via_agents_md
+    generic: via_agents_md
 
   hooks:
     claude: full
     cursor: none
     copilot: none
+    gemini: none
+    codex: none
     generic: none
 
-  slash_commands:
-    claude: native
-    cursor: via_cursorrules
-    copilot: via_instructions
-    generic: via_markdown_guide
+  instruction_file:
+    claude: .claude/skills + agents
+    cursor: AGENTS.md
+    copilot: AGENTS.md
+    gemini: AGENTS.md
+    codex: AGENTS.md
+    generic: AGENTS.md
 
   context_manifests:
     claude: auto_load
     cursor: manual_reference
     copilot: manual_reference
+    gemini: manual_reference
+    codex: manual_reference
     generic: manual_copy_paste
 
 # Target market coverage
 market_coverage:
-  claude_only: 10%
-  with_all_adapters: 100%
+  claude: 10%
+  cursor: 30%
+  copilot: 35%
+  gemini: 10%
+  codex: 20%
+  generic: 5%
+  total: 110% # Overlapping users
+  unique_coverage: 100%
   goal: "Make SpecWeave accessible to ALL developers"
+
+# Universal AGENTS.md
+universal_standard:
+  file: AGENTS.md
+  purpose: "Single source of truth for all adapters (except Claude which has native support)"
+  replaces:
+    - .cursorrules (Cursor)
+    - .github/copilot/instructions.md (Copilot)
+    - Multiple tool-specific files
+  benefits:
+    - Single file to maintain
+    - Works across ALL tools
+    - Auto-generated from actual skills/agents
+    - Follows agents.md standard