specweave 0.6.8 → 0.7.0

package/src/adapters/README.md

@@ -1,275 +0,0 @@
-# SpecWeave Adapters
-
-**Version**: 0.2.0 (Multi-Tool Support)
-
-## Overview
-
-SpecWeave adapters enable the framework to work with **ANY AI coding tool**, not just Claude Code. This directory contains all adapter implementations that provide tool-specific enhancements while maintaining a tool-agnostic core.
-
-## Architecture
-
-```
-SpecWeave
-├── Core (Tool-Agnostic)
-│   └── .specweave/              # Plain Markdown + YAML
-│       ├── increments/
-│       └── docs/
-│
-└── Adapters (Optional)
-    ├── Claude                    # Full automation (native)
-    │   ├── .claude/skills/
-    │   ├── .claude/agents/
-    │   └── .claude/hooks/
-    │
-    ├── Cursor                    # Partial automation
-    │   ├── .cursorrules (legacy)
-    │   └── AGENTS.md
-    │
-    └── Generic                   # Limited features
-        └── AGENTS.md             # Works with Copilot, ChatGPT, Gemini
-```
-
-## Available Adapters
-
-| Adapter | Automation | Tools | Status |
-|---------|------------|-------|--------|
-| **Claude** | Full (skills, agents, hooks) | Claude Code | ✅ Active |
-| **Cursor** | Partial (AGENTS.md, team commands, less reliable) | Cursor | ✅ Active |
-| **Generic** | Limited (AGENTS.md, no hooks, manual workflow) | Copilot, ChatGPT, Gemini, etc. | ✅ Active |
-
-**Total Market Coverage**: 100% (works with ANY AI tool)
-
-**Note**: Claude Code is the only fully reliable option. Others have reduced features and reliability.
-
-## Adapter Interface
-
-All adapters implement the `IAdapter` interface defined in `adapter-interface.ts`:
-
-```typescript
-interface IAdapter {
-  name: string;
-  description: string;
-  automationLevel: 'full' | 'semi' | 'basic' | 'manual';
-
-  detect(): Promise<boolean>;
-  checkRequirements(): Promise<RequirementsResult>;
-  getFiles(): AdapterFile[];
-  install(options: AdapterOptions): Promise<void>;
-  postInstall(options: AdapterOptions): Promise<void>;
-  getInstructions(): string;
-}
-```
-
-## How Adapters Work
-
-### 1. Claude Adapter (Full Automation)
-
-**Files Installed**:
-- `.claude/skills/` - Auto-activating skills (specweave-detector, skill-router, etc.)
-- `.claude/agents/` - Specialized agents (PM, Architect, DevOps, QA, Security)
-- `.claude/commands/` - Slash commands (/create-increment, /sync-docs, etc.)
-- `.claude/hooks/` - Auto-update hooks (post-task-completion, etc.)
-
-**Features**:
-- Skills auto-activate based on user requests
-- Agents coordinate complex workflows
-- Hooks auto-update documentation
-- Slash commands for quick actions
-- Best-in-class experience
-
-**Detection**: Checks for Claude Code CLI
-
----
-
-### 2. Cursor Adapter (Semi-Automation)
-
-**Files Installed**:
-- `.cursorrules` - Workflow instructions for Cursor AI
-- `.cursor/context/` - Context shortcut files
-
-**Features**:
-- @ shortcuts: `@increments`, `@docs`, `@strategy`
-- Composer multi-file editing guided by .cursorrules
-- Context manifests work via manual reference
-
-**Workflow Instructions** (in .cursorrules):
-```markdown
-# SpecWeave Configuration for Cursor
-
-## When user requests a feature:
-1. Check if increment exists in `.specweave/increments/####-name/`
-2. If not, create: spec.md, plan.md, tasks.md
-
-## Context Loading (70%+ Token Reduction)
-**CRITICAL**: Always read `context-manifest.yaml` first!
-Only load files listed in manifest.
-```
-
-**Detection**: Checks for Cursor editor process or .cursor/ directory
-
----
-
-### 3. Generic Adapter (Limited Features)
-
-**Files Installed**:
-- `AGENTS.md` - Universal instruction file for all AI tools
-
-**Features**:
-- Works with Copilot, ChatGPT, Gemini, and ANY AI tool
-- AGENTS.md format (https://agents.md/)
-- No automation (manual workflow)
-- No hooks (manual living docs sync)
-- High context usage
-
-**Manual Guide** (SPECWEAVE.md):
-```markdown
-# SpecWeave Manual Workflow
-
-## Step 1: Create Feature
-```bash
-mkdir -p .specweave/increments/0001-feature-name
-```
-
-## Step 2: Create spec.md
-[Detailed template and instructions]
-
-## Step 3: Load Context
-Copy files listed in `context-manifest.yaml` to your AI chat.
-```
-
-**Detection**: Always returns `true` (universal fallback)
-
----
-
-## Command Mechanism
-
-**Critical Insight**: Commands work differently across tools.
-
-### Claude Code (Native Slash Commands)
-- User types `/create-increment "user auth"` in Claude chat
-- Command file in `.claude/commands/create-increment.md` is loaded
-- Command executes with full context
-
-### Cursor (Instruction-Based)
-- User types: "create increment for user auth"
-- Cursor reads `.cursorrules` which contains workflow instructions
-- AI follows instructions step-by-step
-
-### Generic / Copilot / ChatGPT (AGENTS.md)
-- All tools read `AGENTS.md` (universal standard)
-- Copilot reads it automatically in VS Code
-- ChatGPT/Gemini: User copies sections to chat
-- Manual workflow with AI assistance
-
-**Pattern**: AGENTS.md is the universal instruction format. Only Claude Code uses native plugins (.claude/).
-
-## Installation
-
-### For Users (Select Adapter)
-
-```bash
-# Auto-detect tool and install appropriate adapter
-npx specweave init my-project
-
-# Or specify adapter explicitly
-npx specweave init my-project --adapter claude
-npx specweave init my-project --adapter cursor
-npx specweave init my-project --adapter generic  # For Copilot, ChatGPT, Gemini
-```
-
-### For Developers (Install All Adapters)
-
-```bash
-# Install all adapters to SpecWeave framework
-npm run install:adapters
-```
-
-## Adding New Adapters
-
-To add support for a new tool:
-
-1. **Create adapter directory**: `src/adapters/your-tool/`
-2. **Create adapter class**: `src/adapters/your-tool/adapter.ts`
-3. **Implement IAdapter interface**
-4. **Add template files**: Tool-specific instruction files
-5. **Add to registry**: Update `registry.yaml`
-6. **Add test cases**: Minimum 3 test cases
-7. **Update CLI**: Add detection logic
-
-**Example**:
-```typescript
-// src/adapters/windsurf/adapter.ts
-import { AdapterBase } from '../adapter-base';
-
-export class WindsurfAdapter extends AdapterBase {
-  name = 'windsurf';
-  description = 'Windsurf adapter with semi-automation';
-  automationLevel = 'semi' as const;
-
-  async detect(): Promise<boolean> {
-    // Check if Windsurf is installed
-    return this.commandExists('windsurf');
-  }
-
-  getFiles(): AdapterFile[] {
-    return [
-      {
-        sourcePath: '.windsurfrules',
-        targetPath: '.windsurfrules',
-        description: 'Windsurf workflow instructions'
-      }
-    ];
-  }
-
-  getInstructions(): string {
-    return `
-# Windsurf Adapter Installed
-
-Your project is now configured for Windsurf.
-...
-    `;
-  }
-}
-```
-
-## Testing Adapters
-
-Each adapter MUST have minimum 3 test cases in `test-cases/`:
-
-```
-src/adapters/cursor/
-├── adapter.ts
-├── .cursorrules (template)
-└── test-cases/
-    ├── test-1-install.yaml
-    ├── test-2-detection.yaml
-    └── test-3-workflow.yaml
-```
-
-## Related Documentation
-
-- [adapter-interface.ts](./adapter-interface.ts) - Complete interface definition
-- [adapter-base.ts](./adapter-base.ts) - Base class implementation
-- [registry.yaml](./registry.yaml) - List of all adapters
-- [.specweave/increments/0002-multi-tool-support/](../../.specweave/increments/0002-multi-tool-support/) - Implementation plan
-
-## Design Philosophy
-
-**Core Principle**: Separate tool-agnostic core from tool-specific enhancements.
-
-**Benefits**:
-1. ✅ Users can switch AI tools without losing SpecWeave benefits
-2. ✅ 100% market coverage (works with ANY AI)
-3. ✅ No tool lock-in
-4. ✅ Best experience with supported tools, functional experience with any tool
-5. ✅ Easy to add support for new tools
-
-**Inspiration**:
-- **spec-kit** (GitHub): Agent-agnostic approach, plain text commands
-- **BMAD-METHOD**: Portable prompt bundles work across multiple AIs
-
----
-
-**Status**: Implementation in progress (Increment 0002)
-**Branch**: features/002-multi-tool-support
-**Target**: v0.2.0-beta.1

package/src/adapters/adapter-base.ts

@@ -1,182 +0,0 @@
-/**
- * Base Adapter Class
- *
- * Provides common functionality for all adapters.
- * Concrete adapters extend this class and implement tool-specific logic.
- */
-
-import fs from 'fs-extra';
-import * as path from 'path';
-import { execSync } from 'child_process';
-import {
-  IAdapter,
-  AdapterOptions,
-  RequirementsResult,
-  AdapterFile,
-  AutomationLevel
-} from './adapter-interface.js';
-import { getDirname } from '../utils/esm-helpers.js';
-import type { Plugin } from '../core/types/plugin.js';
-
-const __dirname = getDirname(import.meta.url);
-
-export abstract class AdapterBase implements IAdapter {
-  abstract name: string;
-  abstract description: string;
-  abstract automationLevel: AutomationLevel;
-
-  /**
-   * Default detection - override in concrete adapters
-   */
-  async detect(): Promise<boolean> {
-    return false;
-  }
-
-  /**
-   * Check common requirements (Node.js, Git)
-   * Concrete adapters can override to add tool-specific checks
-   */
-  async checkRequirements(): Promise<RequirementsResult> {
-    const result: RequirementsResult = {
-      met: true,
-      missing: [],
-      warnings: []
-    };
-
-    // Check Node.js version
-    const nodeVersion = process.version;
-    const majorVersion = parseInt(nodeVersion.split('.')[0].slice(1));
-
-    if (majorVersion < 18) {
-      result.met = false;
-      result.missing.push(`Node.js >= 18.0.0 (current: ${nodeVersion})`);
-    }
-
-    // Check Git
-    try {
-      execSync('git --version', { stdio: 'ignore' });
-    } catch (error) {
-      result.warnings.push('Git not found - version control features may not work');
-    }
-
-    return result;
-  }
-
-  /**
-   * Get files to install - must be implemented by concrete adapters
-   */
-  abstract getFiles(): AdapterFile[];
-
-  /**
-   * Install adapter files to project
-   */
-  async install(options: AdapterOptions): Promise<void> {
-    const files = this.getFiles();
-    const adapterSourceDir = path.join(__dirname, this.name);
-
-    console.log(`\n📦 Installing ${this.name} adapter files...`);
-
-    for (const file of files) {
-      const sourcePath = path.join(adapterSourceDir, file.sourcePath);
-      const targetPath = path.join(options.projectPath, file.targetPath);
-
-      // Ensure target directory exists
-      await fs.ensureDir(path.dirname(targetPath));
-
-      // Copy file
-      if (await fs.pathExists(sourcePath)) {
-        await fs.copy(sourcePath, targetPath);
-        console.log(`  ✅ ${file.targetPath} - ${file.description}`);
-      } else {
-        console.warn(`  ⚠️  Source file not found: ${sourcePath}`);
-      }
-    }
-  }
-
-  /**
-   * Post-installation actions - can be overridden by concrete adapters
-   */
-  async postInstall(options: AdapterOptions): Promise<void> {
-    // Default: Display instructions
-    console.log('\n' + this.getInstructions());
-  }
-
-  /**
-   * Get usage instructions - must be implemented by concrete adapters
-   */
-  abstract getInstructions(): string;
-
-  /**
-   * Helper: Check if a command exists in PATH
-   */
-  protected async commandExists(command: string): Promise<boolean> {
-    try {
-      const { execSync } = require('child_process');
-      execSync(`which ${command}`, { stdio: 'ignore' });
-      return true;
-    } catch (error) {
-      return false;
-    }
-  }
-
-  /**
-   * Helper: Check if a file exists
-   */
-  protected async fileExists(filePath: string): Promise<boolean> {
-    try {
-      await fs.access(filePath);
-      return true;
-    } catch (error) {
-      return false;
-    }
-  }
-
-  /**
-   * Helper: Read template file and replace variables
-   */
-  protected async readTemplate(
-    templatePath: string,
-    variables: Record<string, string>
-  ): Promise<string> {
-    let content = await fs.readFile(templatePath, 'utf-8');
-
-    // Replace all {{variable}} with actual values
-    for (const [key, value] of Object.entries(variables)) {
-      content = content.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), value);
-    }
-
-    return content;
-  }
-
-  /**
-   * Check if this adapter supports plugins
-   * Default: No plugin support (override in concrete adapters)
-   */
-  supportsPlugins(): boolean {
-    return false;
-  }
-
-  /**
-   * Compile and install a plugin
-   * Default: Throw error (override in concrete adapters that support plugins)
-   */
-  async compilePlugin(plugin: Plugin): Promise<void> {
-    throw new Error(`Plugin support not implemented for ${this.name} adapter`);
-  }
-
-  /**
-   * Unload a plugin
-   * Default: Throw error (override in concrete adapters that support plugins)
-   */
-  async unloadPlugin(pluginName: string): Promise<void> {
-    throw new Error(`Plugin support not implemented for ${this.name} adapter`);
-  }
-
-  /**
-   * Get installed plugins
-   * Default: Return empty array (override in concrete adapters that support plugins)
-   */
-  async getInstalledPlugins(): Promise<string[]> {
-    return [];
-  }
-}

package/src/adapters/adapter-interface.ts

@@ -1,166 +0,0 @@
-/**
- * Adapter Interface for Multi-Tool Support
- *
- * Defines the contract that all SpecWeave adapters must implement.
- * Enables SpecWeave to work with ANY AI coding tool (Claude, Cursor, Copilot/ChatGPT/Gemini via generic, etc.)
- */
-
-import type { Plugin } from '../core/types/plugin.js';
-
-export interface AdapterOptions {
-  projectPath: string;
-  projectName: string;
-  techStack?: {
-    language: string;
-    framework?: string;
-  };
-  docsApproach?: 'comprehensive' | 'incremental';
-}
-
-export interface RequirementsResult {
-  met: boolean;
-  missing: string[];
-  warnings: string[];
-}
-
-export interface AdapterFile {
-  sourcePath: string;      // Path in src/adapters/{adapter-name}/
-  targetPath: string;       // Path in user's project (relative to project root)
-  description: string;      // What this file does
-}
-
-export type AutomationLevel = 'full' | 'semi' | 'basic' | 'manual';
-
-/**
- * Base Adapter Interface
- *
- * All adapters (Cursor, Generic) must implement this interface.
- * Note: Claude Code is NOT an adapter - it's the native baseline experience.
- */
-export interface IAdapter {
-  /**
-   * Adapter name (e.g., 'cursor', 'generic')
-   */
-  name: string;
-
-  /**
-   * Human-readable description of what this adapter provides
-   */
-  description: string;
-
-  /**
-   * Automation level this adapter provides
-   * - full: Complete automation (skills, agents, hooks auto-activate)
-   * - semi: Semi-automated (context shortcuts, multi-file editing)
-   * - basic: Basic automation (workspace instructions, suggestions)
-   * - manual: Manual workflow (step-by-step guide)
-   */
-  automationLevel: AutomationLevel;
-
-  /**
-   * Detect if this adapter's tool is present in the environment
-   *
-   * Examples:
-   * - Cursor: Check for .cursor/ directory or Cursor process
-   * - Generic: Always true (fallback for any tool)
-   *
-   * @returns Promise<boolean> True if tool detected
-   */
-  detect(): Promise<boolean>;
-
-  /**
-   * Check if system requirements are met for this adapter
-   *
-   * Examples:
-   * - Node.js version >= 18
-   * - Git installed
-   * - Tool-specific requirements
-   *
-   * @returns Promise<RequirementsResult> Requirements check result
-   */
-  checkRequirements(): Promise<RequirementsResult>;
-
-  /**
-   * Get list of files this adapter will install
-   *
-   * @returns AdapterFile[] Array of files to install
-   */
-  getFiles(): AdapterFile[];
-
-  /**
-   * Install this adapter to a project
-   *
-   * Creates tool-specific files (e.g., .cursorrules for Cursor, AGENTS.md for all)
-   * Installs relevant skills/agents if applicable
-   *
-   * @param options Installation options
-   * @returns Promise<void>
-   */
-  install(options: AdapterOptions): Promise<void>;
-
-  /**
-   * Post-installation actions
-   *
-   * Examples:
-   * - Create symlinks
-   * - Update config files
-   * - Display setup instructions to user
-   *
-   * @param options Installation options
-   * @returns Promise<void>
-   */
-  postInstall(options: AdapterOptions): Promise<void>;
-
-  /**
-   * Get human-readable instructions for using this adapter
-   *
-   * Displayed to user after installation
-   *
-   * @returns string Markdown-formatted instructions
-   */
-  getInstructions(): string;
-
-  /**
-   * Check if this adapter supports plugins
-   *
-   * Returns true if the adapter can install and compile plugins
-   * (Cursor AGENTS.md compilation, Generic AGENTS.md)
-   * Returns false for manual-only adapters
-   *
-   * @returns boolean True if plugins are supported
-   */
-  supportsPlugins(): boolean;
-
-  /**
-   * Compile and install a plugin for this adapter
-   *
-   * Transforms plugin content (skills/agents/commands) to tool-specific format:
-   * - Cursor: Compile to AGENTS.md + team commands JSON
-   * - Generic: Compile to AGENTS.md for Copilot/ChatGPT/Gemini
-   *
-   * Note: Claude Code uses native plugin system (no compilation needed)
-   *
-   * @param plugin Plugin to compile and install
-   * @returns Promise<void>
-   */
-  compilePlugin(plugin: Plugin): Promise<void>;
-
-  /**
-   * Unload (disable) a plugin for this adapter
-   *
-   * Removes plugin-specific files and restores previous state
-   *
-   * @param pluginName Name of plugin to unload
-   * @returns Promise<void>
-   */
-  unloadPlugin(pluginName: string): Promise<void>;
-
-  /**
-   * Get plugin installation status
-   *
-   * Returns information about which plugins are currently installed
-   *
-   * @returns Promise<string[]> Array of installed plugin names
-   */
-  getInstalledPlugins(): Promise<string[]>;
-}