specweave 0.1.9 → 0.3.1

package/src/adapters/cursor/adapter.ts

@@ -2,20 +2,20 @@
  * Cursor Adapter
  *
  * Semi-automation adapter for Cursor editor.
- * Provides workflow instructions via .cursorrules and @ context shortcuts.
+ * Provides @ context shortcuts for quick context injection.
  *
- * Since Cursor doesn't natively support Claude Code's skills/agents/hooks,
- * this adapter teaches Cursor HOW TO BEHAVE LIKE it has these capabilities.
+ * Cursor automatically reads AGENTS.md (universal standard) for workflow instructions.
+ * This adapter only installs Cursor-specific features (@ shortcuts).
  */
 
 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 CursorAdapter extends AdapterBase {
   name = 'cursor';
-  description = 'Cursor adapter - Semi-automation with .cursorrules and @ context shortcuts';
+  description = 'Cursor adapter - Semi-automation with AGENTS.md and @ context shortcuts';
   automationLevel = 'semi' as const;
 
   /**
@@ -24,26 +24,22 @@ export class CursorAdapter extends AdapterBase {
    * Checks for:
    * - cursor command in PATH
    * - .cursor/ directory exists
-   * - .cursorrules file exists
    */
   async detect(): Promise<boolean> {
     const hasCursorCLI = await this.commandExists('cursor');
     const hasCursorDir = await this.fileExists('.cursor');
-    const hasCursorRules = await this.fileExists('.cursorrules');
 
-    return hasCursorCLI || hasCursorDir || hasCursorRules;
+    return hasCursorCLI || hasCursorDir;
   }
 
   /**
    * Get files to install for Cursor adapter
+   *
+   * Note: Cursor automatically reads AGENTS.md (universal standard).
+   * This adapter only installs Cursor-specific @ context shortcuts.
    */
   getFiles(): AdapterFile[] {
     return [
-      {
-        sourcePath: '.cursorrules',
-        targetPath: '.cursorrules',
-        description: 'Cursor workflow instructions (how to act like skills/agents)'
-      },
       {
         sourcePath: '.cursor/context/increments-context.md',
         targetPath: '.cursor/context/increments-context.md',
@@ -88,8 +84,7 @@ export class CursorAdapter extends AdapterBase {
 
     console.log('\n✨ Cursor adapter installed!');
     console.log('\n📋 Files created:');
-    console.log('   - .cursorrules (workflow instructions)');
-    console.log('   - .cursor/context/ (@ shortcuts)');
+    console.log('   - .cursor/context/ (@ shortcuts for quick context injection)');
   }
 
   /**
@@ -112,11 +107,13 @@ Your project is now configured for Cursor with SEMI-automation!
 
 WHAT THIS PROVIDES:
 
-- .cursorrules (Workflow Instructions)
-  - Teaches Cursor HOW to act like Claude Code skills/agents
-  - Step-by-step workflow for creating increments
-  - Context loading strategy (70%+ token savings)
-  - Increment lifecycle management
+- AGENTS.md (Universal Standard)
+  - Cursor automatically reads this file
+  - Contains all workflow instructions
+  - Defines agent roles (PM, Architect, etc.)
+  - Defines skill capabilities (increment-planner, context-loader, etc.)
+  - Project structure and templates
+  - Following agents.md standard (https://agents.md/)
 
 - @ Context Shortcuts (Quick Access)
   - @increments - Load current increment files
@@ -134,72 +131,30 @@ Claude Code (Full Automation):
 - Native skills (auto-activate)
 - Native agents (separate context windows)
 - Native hooks (auto-update docs)
-- Slash commands (/create-increment)
+- Slash commands (/inc, /do, /done)
 
 Cursor (Semi-Automation - This Adapter):
-- Simulated skills (via .cursorrules instructions)
-- Simulated agents (manual role invocation)
+- Reads AGENTS.md for workflow instructions
+- Manual role adoption (say "act as PM")
 - No hooks (manual doc updates)
-- Simulated commands (via workflow instructions)
-
-HOW WE BRIDGE THE GAP:
-
-Anthropic's standards (skills, agents, MCP) provide superior
-results. For Cursor, we provide "implementation guides"
-that teach Cursor's AI how to BEHAVE LIKE it has these
-capabilities, even without native support.
-
-Example: .cursorrules says:
-"When user requests feature, act like 'increment-planner' skill:
- 1. Read context-manifest.yaml
- 2. Load only files listed there
- 3. Invoke PM role: Create spec.md
- 4. Invoke Architect role: Create plan.md"
-
-HOW TO "IMPLEMENT" SKILLS IN CURSOR:
-
-What is a SpecWeave Skill?
-A skill is a specialized capability that activates when needed.
-
-In Claude Code: Skills are native (.claude/skills/)
-In Cursor: You simulate by reading relevant files
-
-Example: increment-planner skill
-
-Claude Code (automatic):
-  User: "create increment for auth"
-  → increment-planner skill activates automatically
-
-Cursor (manual simulation):
-  User: "create increment for auth"
-  → You read .cursorrules
-  → Follow workflow: read config → create spec → create plan
-  → Act like increment-planner by following those steps
-
-HOW TO "IMPLEMENT" AGENTS IN CURSOR:
-
-What is a SpecWeave Agent?
-An agent is a specialized role (PM, Architect, DevOps, etc.)
-with separate context window.
-
-In Claude Code: Agents have separate context windows
-In Cursor: You adopt the role's perspective
-
-Example: PM agent
+- Manual workflows (follow AGENTS.md steps)
 
-Claude Code (automatic):
-  Task({ subagent_type: "pm", prompt: "create spec" })
-  → PM agent with separate context window
+HOW CURSOR USES AGENTS.MD:
 
-Cursor (manual simulation):
-  User: "act as PM agent and create spec"
-  → You adopt PM perspective:
-    - Focus on WHAT and WHY (not HOW)
-    - Technology-agnostic requirements
-    - User stories and acceptance criteria
-  → Create spec.md following PM role
+Cursor automatically reads AGENTS.md to understand:
+1. Project structure (.specweave/ folders)
+2. How to create increments (spec.md, plan.md, tasks.md)
+3. Agent roles (PM defines WHAT/WHY, Architect designs HOW)
+4. Skill workflows (increment-planner, context-loader, etc.)
+5. Context manifests (70%+ token savings)
+6. Templates and examples
 
-Pro Tip: .cursorrules defines each role's responsibilities
+When you say "create increment for auth":
+→ Cursor reads AGENTS.md
+→ Follows the workflow described there
+→ Creates spec.md (adopting PM role)
+→ Creates plan.md (adopting Architect role)
+→ Creates tasks.md
 
 QUICK START:
 
@@ -209,10 +164,10 @@ QUICK START:
    "Create increment for user authentication"
 
    Cursor will:
-   - Read .cursorrules for workflow
+   - Read AGENTS.md for workflow
    - Ask clarifying questions
-   - Create spec.md (acting as PM)
-   - Create plan.md (acting as Architect)
+   - Create spec.md (acting as PM from AGENTS.md)
+   - Create plan.md (acting as Architect from AGENTS.md)
    - Create tasks.md
 
 3. Use @ shortcuts for context:
@@ -227,7 +182,7 @@ CONTEXT LOADING (70%+ Token Savings):
 
 CRITICAL: Always read context-manifest.yaml first!
 
-.cursorrules teaches Cursor:
+AGENTS.md teaches Cursor:
 1. Look for .specweave/increments/####/context-manifest.yaml
 2. ONLY load files listed in manifest
 3. Don't load all specs (wastes tokens)
@@ -252,17 +207,16 @@ But still VERY good experience with Composer + @ shortcuts!
 
 DOCUMENTATION:
 
-- SPECWEAVE.md: Complete development guide
-- .cursorrules: Workflow instructions (READ THIS!)
+- AGENTS.md: Universal workflow instructions (Cursor reads this!)
 - .cursor/README.md: Cursor-specific documentation
 - .specweave/docs/: Project documentation
 
 You're ready to build with SpecWeave on Cursor!
 
-Pro tip: Say "act as [role]" to simulate agents:
-- "act as PM and create spec"
-- "act as Architect and design system"
-- "act as DevOps and create infrastructure"
+Pro tip: Say "act as [role]" to follow AGENTS.md patterns:
+- "act as PM and create spec" (AGENTS.md defines PM role)
+- "act as Architect and design system" (AGENTS.md defines Architect role)
+- "act as DevOps and create infrastructure" (AGENTS.md defines DevOps role)
     `;
   }
 }

package/src/adapters/doc-generator.ts

@@ -0,0 +1,331 @@
+/**
+ * Documentation Generator for Adapters
+ *
+ * Generates markdown documentation from actual skills/agents/commands
+ * for use in adapter instruction files (.cursorrules, instructions.md, etc.)
+ */
+
+import fs from 'fs-extra';
+import * as path from 'path';
+import * as YAML from 'yaml';
+import { getDirname } from '../utils/esm-helpers.js';
+
+const __dirname = getDirname(import.meta.url);
+
+interface SkillMetadata {
+  name: string;
+  description: string;
+  location: string;
+}
+
+interface AgentMetadata {
+  name: string;
+  role: string;
+  description: string;
+  location: string;
+}
+
+interface CommandMetadata {
+  name: string;
+  description: string;
+  location: string;
+}
+
+/**
+ * Documentation Generator
+ */
+export class DocGenerator {
+  private skillsDir: string;
+  private agentsDir: string;
+  private commandsDir: string;
+
+  constructor(
+    skillsDir: string = path.join(__dirname, '../skills'),
+    agentsDir: string = path.join(__dirname, '../agents'),
+    commandsDir: string = path.join(__dirname, '../commands')
+  ) {
+    this.skillsDir = skillsDir;
+    this.agentsDir = agentsDir;
+    this.commandsDir = commandsDir;
+  }
+
+  /**
+   * Extract skills metadata from SKILL.md files
+   */
+  async extractSkills(): Promise<SkillMetadata[]> {
+    const skills: SkillMetadata[] = [];
+
+    if (!await fs.pathExists(this.skillsDir)) {
+      return skills;
+    }
+
+    const skillFolders = await fs.readdir(this.skillsDir);
+
+    for (const folder of skillFolders) {
+      const skillPath = path.join(this.skillsDir, folder);
+      const skillFile = path.join(skillPath, 'SKILL.md');
+
+      if (await fs.pathExists(skillFile)) {
+        const content = await fs.readFile(skillFile, 'utf-8');
+        const metadata = this.extractYAMLFrontmatter(content);
+
+        if (metadata && metadata.name && metadata.description) {
+          skills.push({
+            name: metadata.name,
+            description: metadata.description,
+            location: `.claude/skills/${folder}/SKILL.md`
+          });
+        }
+      }
+    }
+
+    return skills.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  /**
+   * Extract agents metadata from AGENT.md files
+   */
+  async extractAgents(): Promise<AgentMetadata[]> {
+    const agents: AgentMetadata[] = [];
+
+    if (!await fs.pathExists(this.agentsDir)) {
+      return agents;
+    }
+
+    const agentFolders = await fs.readdir(this.agentsDir);
+
+    for (const folder of agentFolders) {
+      const agentPath = path.join(this.agentsDir, folder);
+      const agentFile = path.join(agentPath, 'AGENT.md');
+
+      if (await fs.pathExists(agentFile)) {
+        const content = await fs.readFile(agentFile, 'utf-8');
+
+        // Extract role from content (look for "# [Role]" heading)
+        const roleMatch = content.match(/^#\s+(.+?)$/m);
+        const role = roleMatch ? roleMatch[1].trim() : folder;
+
+        // Extract description (first paragraph after frontmatter)
+        const descriptionMatch = content.match(/---\n[\s\S]*?---\n\n(.+?)(?:\n\n|$)/);
+        const description = descriptionMatch ? descriptionMatch[1].trim() : `${role} agent`;
+
+        agents.push({
+          name: folder,
+          role: role,
+          description: description,
+          location: `.claude/agents/${folder}/AGENT.md`
+        });
+      }
+    }
+
+    return agents.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  /**
+   * Extract commands metadata from .md files
+   */
+  async extractCommands(): Promise<CommandMetadata[]> {
+    const commands: CommandMetadata[] = [];
+
+    if (!await fs.pathExists(this.commandsDir)) {
+      return commands;
+    }
+
+    const commandFiles = await fs.readdir(this.commandsDir);
+
+    for (const file of commandFiles) {
+      if (file.endsWith('.md') && file !== 'README.md') {
+        const commandPath = path.join(this.commandsDir, file);
+        const content = await fs.readFile(commandPath, 'utf-8');
+
+        // Extract description from first paragraph
+        const descriptionMatch = content.match(/^(.+?)(?:\n\n|$)/);
+        const description = descriptionMatch ? descriptionMatch[1].trim() : '';
+
+        const commandName = file.replace('.md', '');
+
+        commands.push({
+          name: commandName,
+          description: description,
+          location: `.claude/commands/${file}`
+        });
+      }
+    }
+
+    return commands.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  /**
+   * Generate skills documentation for Cursor .cursorrules
+   */
+  async generateSkillsDocForCursor(): Promise<string> {
+    const skills = await this.extractSkills();
+
+    let doc = '## Available Skills (Read SKILL.md when task matches)\n\n';
+    doc += 'SpecWeave skills are specialized capabilities. In Claude Code, they auto-activate.\n';
+    doc += 'In Cursor, you simulate by reading the skill file and following its workflow.\n\n';
+
+    for (const skill of skills) {
+      doc += `### ${skill.name}\n`;
+      doc += `**File**: \`${skill.location}\`\n`;
+      doc += `**Description**: ${skill.description}\n`;
+      doc += `**How to use**: Read the SKILL.md file and follow the workflow described\n\n`;
+    }
+
+    return doc;
+  }
+
+  /**
+   * Generate agents documentation for Cursor .cursorrules
+   */
+  async generateAgentsDocForCursor(): Promise<string> {
+    const agents = await this.extractAgents();
+
+    let doc = '## Agent Roles (Adopt role when specialized expertise needed)\n\n';
+    doc += 'SpecWeave agents are specialized roles. In Claude Code, they have separate contexts.\n';
+    doc += 'In Cursor, you adopt the role\'s perspective and responsibilities.\n\n';
+
+    for (const agent of agents) {
+      doc += `### ${agent.role}\n`;
+      doc += `**File**: \`${agent.location}\`\n`;
+      doc += `**Description**: ${agent.description}\n`;
+      doc += `**When to adopt**: Say "Adopting ${agent.role} role..." and follow AGENT.md guidance\n\n`;
+    }
+
+    return doc;
+  }
+
+  /**
+   * Generate skills documentation for Copilot instructions.md
+   */
+  async generateSkillsDocForCopilot(): Promise<string> {
+    const skills = await this.extractSkills();
+
+    let doc = '## Available Capabilities (SpecWeave Skills)\n\n';
+    doc += 'The project uses these specialized capabilities:\n\n';
+
+    for (const skill of skills) {
+      doc += `- **${skill.name}**: ${skill.description}\n`;
+    }
+
+    doc += '\n_Note: These are defined in `.claude/skills/` but work as documentation for code suggestions._\n\n';
+
+    return doc;
+  }
+
+  /**
+   * Generate agents documentation for Copilot instructions.md
+   */
+  async generateAgentsDocForCopilot(): Promise<string> {
+    const agents = await this.extractAgents();
+
+    let doc = '## Project Roles (SpecWeave Agents)\n\n';
+    doc += 'Code in this project follows these role-based patterns:\n\n';
+
+    for (const agent of agents) {
+      doc += `- **${agent.role}**: ${agent.description}\n`;
+    }
+
+    doc += '\n_Note: These are defined in `.claude/agents/` but inform code patterns and suggestions._\n\n';
+
+    return doc;
+  }
+
+  /**
+   * Generate complete manual workflow for generic adapter
+   */
+  async generateManualWorkflow(): Promise<string> {
+    const skills = await this.extractSkills();
+    const agents = await this.extractAgents();
+    const commands = await this.extractCommands();
+
+    let doc = '# SpecWeave Manual Workflow Guide\n\n';
+    doc += '_For use with ANY AI tool (ChatGPT, Claude web, Gemini, etc.)_\n\n';
+    doc += '---\n\n';
+
+    doc += '## What is SpecWeave?\n\n';
+    doc += 'SpecWeave is a spec-driven development framework where specifications are the source of truth.\n';
+    doc += 'This manual shows you how to use SpecWeave WITHOUT specialized tools (works with ANY AI).\n\n';
+
+    doc += '## Available Capabilities\n\n';
+    doc += 'While you can\'t auto-activate these like Claude Code, you can reference them:\n\n';
+
+    doc += '### Skills\n\n';
+    for (const skill of skills.slice(0, 10)) { // Top 10 skills
+      doc += `- **${skill.name}**: ${skill.description}\n`;
+    }
+    doc += `\n_...and ${skills.length - 10} more in \`.claude/skills/\`_\n\n`;
+
+    doc += '### Roles\n\n';
+    for (const agent of agents) {
+      doc += `- **${agent.role}**: ${agent.description}\n`;
+    }
+    doc += '\n';
+
+    doc += '## Step-by-Step: Creating a Feature\n\n';
+    doc += '### Step 1: Create Increment Folder\n\n';
+    doc += '```bash\n';
+    doc += 'mkdir -p .specweave/increments/0001-feature-name\n';
+    doc += '```\n\n';
+
+    doc += '### Step 2: Create spec.md (Act as Product Manager)\n\n';
+    doc += '_Copy this template to your AI and ask it to fill it out:_\n\n';
+    doc += '```markdown\n';
+    doc += '---\n';
+    doc += 'increment: 0001-feature-name\n';
+    doc += 'title: "Feature Title"\n';
+    doc += 'priority: P1\n';
+    doc += 'status: planned\n';
+    doc += '---\n\n';
+    doc += '# Increment 0001: Feature Name\n\n';
+    doc += '## Overview\n';
+    doc += '[Problem and solution]\n\n';
+    doc += '## User Stories\n';
+    doc += '[User stories with acceptance criteria]\n';
+    doc += '```\n\n';
+
+    doc += '### Step 3: Create plan.md (Act as Architect)\n\n';
+    doc += '_Copy this template to your AI:_\n\n';
+    doc += '```markdown\n';
+    doc += '# Technical Plan: Feature Name\n\n';
+    doc += '## Architecture\n';
+    doc += '[Component design]\n\n';
+    doc += '## Data Model\n';
+    doc += '[Database schema]\n';
+    doc += '```\n\n';
+
+    doc += '### Step 4: Create tasks.md\n\n';
+    doc += '```markdown\n';
+    doc += '# Implementation Tasks\n\n';
+    doc += '- [ ] T001: Task 1\n';
+    doc += '- [ ] T002: Task 2\n';
+    doc += '```\n\n';
+
+    doc += '### Step 5: Create context-manifest.yaml\n\n';
+    doc += '```yaml\n';
+    doc += 'spec_sections:\n';
+    doc += '  - .specweave/docs/internal/strategy/relevant-spec.md\n';
+    doc += 'documentation:\n';
+    doc += '  - .specweave/docs/internal/architecture/relevant-design.md\n';
+    doc += '```\n\n';
+
+    doc += '## Complete Workflow Reference\n\n';
+    doc += 'For detailed guidance, see SPECWEAVE.md in the project root.\n\n';
+
+    return doc;
+  }
+
+  /**
+   * Extract YAML frontmatter from markdown content
+   */
+  private extractYAMLFrontmatter(content: string): any {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) return null;
+
+    try {
+      return YAML.parse(match[1]);
+    } catch (error) {
+      return null;
+    }
+  }
+}

package/src/adapters/gemini/README.md

@@ -0,0 +1,97 @@
+# Gemini CLI Adapter
+
+**Automation Level**: Semi (Good experience with 1M context window and agent mode)
+
+## Overview
+
+The Gemini CLI adapter provides **semi-automation** for SpecWeave using Google's open-source Gemini CLI tool with **AGENTS.md** as the universal instruction file.
+
+## Key Features
+
+- **1M Token Context Window**: Handle massive specifications
+- **Agent Mode**: Multi-file task completion with approval workflow
+- **MCP Support**: Model Context Protocol for extensibility
+- **Built-in Tools**: File operations, shell commands, Google Search, web fetching
+- **Free Tier**: Gemini 2.5 Pro included (60 req/min, 1K req/day)
+- **Open Source**: Apache 2.0 license
+
+## Installation
+
+```bash
+# Install Gemini CLI
+npm install -g @google-cloud/gemini-cli
+
+# Authenticate
+gemini auth
+
+# Initialize SpecWeave project with Gemini adapter
+npx specweave init my-project --adapter gemini
+```
+
+## How It Works
+
+Gemini CLI reads **AGENTS.md** (universal instruction file) for SpecWeave context:
+
+```bash
+gemini "Read AGENTS.md and create increment for user authentication"
+```
+
+Gemini will:
+1. Read AGENTS.md for project structure and roles
+2. Adopt PM role: Create spec.md (WHAT/WHY)
+3. Adopt Architect role: Create plan.md (HOW)
+4. Create tasks.md (implementation checklist)
+5. Use agent mode for multi-file operations
+
+## Universal AGENTS.md
+
+Instead of tool-specific files (.cursorrules, copilot instructions), SpecWeave uses **AGENTS.md** that works with ALL tools:
+
+- ✅ Gemini CLI
+- ✅ Codex (OpenAI)
+- ✅ Cursor
+- ✅ GitHub Copilot
+- ✅ ANY AI tool
+
+**Single source of truth** = easier maintenance!
+
+## Example Workflows
+
+### Create Feature
+```bash
+gemini "Read AGENTS.md. Create increment 0002 for payment processing with Stripe."
+```
+
+### Implement Task
+```bash
+gemini "Read increment 0002, implement task T001"
+```
+
+### Context Loading (70%+ Token Savings)
+```bash
+gemini "Read context-manifest.yaml from increment 0001, load only those files, then implement T001"
+```
+
+## Comparison with Claude Code
+
+| Feature | Claude Code | Gemini CLI |
+|---------|-------------|------------|
+| **Automation** | Full | Semi |
+| **Context** | 200k tokens | 1M tokens (5x!) |
+| **Skills** | Native | Via AGENTS.md |
+| **Agents** | Native (separate contexts) | Via AGENTS.md (manual adoption) |
+| **Hooks** | Yes (auto-update) | No (manual) |
+| **Cost** | Paid | Free tier available |
+| **Open Source** | No | Yes (Apache 2.0) |
+
+## Links
+
+- [Gemini CLI Documentation](https://developers.google.com/gemini-code-assist/docs/gemini-cli)
+- [GitHub Repository](https://github.com/google-gemini/gemini-cli)
+- [SpecWeave Website](https://spec-weave.com)
+
+---
+
+**Status**: Active (v0.2.0+)
+**Market Share**: Growing (Google's AI coding tool)
+**Priority**: P1 (high impact - 1M context window!)