Skip to content

ADAPTERS.md

Latest commit

 

History

History
478 lines (361 loc) · 13.5 KB

ADAPTERS.md

File metadata and controls

478 lines (361 loc) · 13.5 KB

DevPlan Adapter Comparison

This document provides a comprehensive comparison of all DevPlan output adapters.

Quick Reference

Adapter Main File Executor Verifier Plan Transform IDE Status
Claude CLAUDE.md Yes Yes No Claude Code ✅ Default
Cursor .cursorrules No No Yes Cursor IDE ✅ Native
Aider .aider.conf.yml No No Yes Terminal ✅ Native
Cline .cline/instructions.md Yes Yes No VS Code ✅ Native
Windsurf .windsurf/rules.md No No Yes Windsurf ✅ Native
Generic AGENTS.md Yes Yes No Any Model ✅ Native

Detailed Comparison

Claude Adapter

Target Tool: Claude Code IDE Repository: https://github.com/anthropics/claude-code

Main File:

  • Filename: CLAUDE.md
  • Location: Project root
  • Format: Markdown
  • Size: Typically 2-5 KB

Generated Files:

  1. CLAUDE.md - Main agent instructions
  2. .claude/agents/{project}-executor.md - Executor agent with Task tool integration
  3. .claude/agents/{project}-verifier.md - Verifier agent with Task tool integration

Key Features:

  • ✅ Full executor/verifier support
  • ✅ Task tool integration for real-time progress tracking
  • ✅ Session checklists and git discipline
  • ✅ Can generate specialized agents (executor, verifier)
  • ✅ Best for teams using Claude Code

Limitations:

  • Claude Code specific (not portable to other tools)
  • Requires Claude Code IDE or Claude API for optimal use

Example Usage:

Use devplan_generate_plan to create a plan with target='claude' (default)
Then use devplan_generate_executor and devplan_generate_verifier

When to Use:

  • Primary development with Claude Code
  • Need executor/verifier separation and Task tool integration
  • Building AI-assisted development teams

Cursor Adapter

Target Tool: Cursor IDE Website: https://cursor.com Documentation: https://docs.cursor.com

Main File:

  • Filename: .cursorrules
  • Location: Project root
  • Format: Plain text
  • Size: Typically 3-6 KB

Generated Files:

  1. .cursorrules - All guidance in single rules file

Key Features:

  • ✅ Plain text rules format (no YAML/JSON parsing)
  • ✅ Sections for different concern areas
  • ✅ Simple, readable format for Cursor Composer
  • ✅ Includes executor/verifier guidance in main file
  • ✅ Plan transformation adapts structure for Cursor workflow

Limitations:

  • ❌ No separate executor agent (guidance included in .cursorrules)
  • ❌ No separate verifier agent (guidance included in .cursorrules)
  • ❌ No IDE-level task tracking
  • ✅ Works well with Cursor Composer multi-file editing

Format Specification:

[Section Name]

Description and rules...
- First rule
- Second rule

[Another Section]

More guidance...

Example Usage:

Use devplan_generate_plan with target='cursor'
Then use devplan_generate_claude_md with target='cursor'

When to Use:

  • Primary IDE is Cursor
  • Need simple, readable .cursorrules file
  • Prefer single-file guidance format
  • Using Cursor Composer for multi-file editing

Related Documentation: See docs/adapters/cursor.md for detailed Cursor adapter documentation.

Aider Adapter

Target Tool: Aider CLI Website: https://aider.chat Repository: https://github.com/paul-gauthier/aider

Main File:

  • Filename: .aider.conf.yml
  • Location: Project root
  • Format: YAML
  • Size: Typically 2-4 KB

Generated Files:

  1. .aider.conf.yml - Configuration with system prompt

Key Features:

  • ✅ YAML configuration format (standard Aider format)
  • ✅ System prompt includes DevPlan methodology
  • ✅ Architect mode support for complex tasks
  • ✅ Command integration (/code, /read, etc.)
  • ✅ Plan transformation optimizes for Aider workflow

Limitations:

  • ❌ No separate executor agent (uses architect mode)
  • ❌ No separate verifier agent (uses architect mode)
  • ❌ No file-based task tracking
  • ✅ Aider's architect mode handles complexity automatically

Configuration Example:

# DevPlan methodology guidance
system-prompt: |
  You are an Aider agent implementing a DevPlan...

# Phase-by-phase architecture guidance
# Executor/verifier roles embedded in system prompt

Example Usage:

Use devplan_generate_plan with target='aider'
Then use devplan_generate_claude_md with target='aider'

When to Use:

  • Primary tool is Aider CLI
  • Working in terminal environment
  • Need YAML-based configuration
  • Using Aider's architect mode for multi-file changes

Related Documentation: See docs/adapters/aider.md for detailed Aider adapter documentation.

Cline Adapter

Target Tool: VS Code Cline Extension Repository: https://github.com/cline/cline

Main File:

  • Filename: .cline/instructions.md
  • Location: .cline/ directory
  • Format: Markdown
  • Size: Typically 3-5 KB

Generated Files:

  1. .cline/instructions.md - Main instructions
  2. .cline/executor.md - Executor instructions (if supported)
  3. .cline/verifier.md - Verifier instructions (if supported)

Key Features:

  • ✅ VS Code extension format
  • ✅ Executor/verifier support
  • ✅ Directory structure for organization
  • ✅ Markdown format (readable in editor)
  • ✅ Compatible with VS Code extension API

Limitations:

  • Requires VS Code Cline extension to be installed
  • No IDE-level task tracking (unlike Claude Code)

File Structure:

.cline/
├── instructions.md      # Main agent instructions
├── executor.md          # Executor subtask guidance
└── verifier.md          # Verification procedure guidance

Example Usage:

Use devplan_generate_plan with target='cline'
Then use devplan_generate_executor with target='cline'

When to Use:

  • Primary IDE is VS Code with Cline extension
  • Need executor/verifier separation
  • Working in team environment with VS Code

Windsurf Adapter

Target Tool: Codium Windsurf IDE Website: https://codeium.com/windsurf Documentation: https://docs.codeium.com/windsurf

Main File:

  • Filename: .windsurf/rules.md
  • Location: .windsurf/ directory
  • Format: Markdown
  • Size: Typically 3-6 KB

Generated Files:

  1. .windsurf/rules.md - All guidance in rules format

Key Features:

  • ✅ Cascade-optimized format for multi-file edits
  • ✅ Markdown rules format
  • ✅ All guidance in single file
  • ✅ Windsurf IDE integration
  • ✅ Plan transformation adapts for Cascade workflow

Limitations:

  • ❌ No separate executor agent (guidance in rules)
  • ❌ No separate verifier agent (guidance in rules)
  • ✅ Cascade handles multi-file workflows automatically

Format:

# Windsurf Rules

## Phase 1: Setup

Rules for phase 1...

## Phase 2: Development

Rules for phase 2...

## Executor Guidelines

Guidance for execution...

## Verifier Guidelines

Verification procedures...

Example Usage:

Use devplan_generate_plan with target='windsurf'
Then use devplan_generate_claude_md with target='windsurf'

When to Use:

  • Primary IDE is Windsurf
  • Using Cascade for multi-file AI edits
  • Prefer single-file rules format

Generic Adapter

Target Tool: Any Model/Tool Use Case: Cross-platform, model-agnostic format

Main Files:

  • Filename: AGENTS.md (required), EXECUTOR.md, VERIFIER.md
  • Location: Project root
  • Format: Markdown
  • Size: Typically 4-8 KB total

Generated Files:

  1. AGENTS.md - Main agent instructions
  2. EXECUTOR.md - Executor agent guidance (if needed)
  3. VERIFIER.md - Verifier agent guidance (if needed)

Key Features:

  • ✅ Model-agnostic markdown format
  • ✅ Can be used with any AI model or tool
  • ✅ Full executor/verifier support
  • ✅ No dependencies on specific IDE or tool
  • ✅ Portable across different platforms

Limitations:

  • No tool-specific integrations
  • No IDE-level features
  • Requires manual setup in new environments

File Structure:

AGENTS.md           # Main development agent instructions
EXECUTOR.md         # Subtask executor guidance
VERIFIER.md         # Verification and testing guidance

Example Usage:

Use devplan_generate_plan with target='generic'
Then use devplan_generate_executor with target='generic'
And use devplan_generate_verifier with target='generic'

When to Use:

  • Multiple teams using different tools
  • Need portable format across environments
  • Using custom or emerging AI tools
  • Building cross-tool documentation

Adapter Capability Matrix

File Generation

Capability Claude Cursor Aider Cline Windsurf Generic
Main agent file ✅ ✅ ✅ ✅ ✅ ✅
Separate executor ✅ ❌ ❌ ✅ ❌ ✅
Separate verifier ✅ ❌ ❌ ✅ ❌ ✅
Plan transformation ❌ ✅ ✅ ❌ ✅ ❌
IDE integration ✅ ✅ ❌ ✅ ✅ ❌

Feature Support

Feature Claude Cursor Aider Cline Windsurf Generic
Task tool integration ✅ ❌ ❌ ❌ ❌ ❌
Executor role ✅ Embedded Architect ✅ Embedded ✅
Verifier role ✅ Embedded Architect ✅ Embedded ✅
Multi-file editing ✅ ✅ ✅ ✅ ✅ ❌
Terminal friendly ❌ ❌ ✅ ❌ ❌ ✅
Config file format Markdown Plain text YAML Markdown Markdown Markdown

Choosing an Adapter

Decision Tree

Which IDE/tool are you using?

  • Claude Code → Use claude adapter

    • Best DevPlan support with Task tools
    • Full executor/verifier agents
    • Real-time progress tracking

  • Cursor IDE → Use cursor adapter

    • Generate .cursorrules for Cursor
    • Works with Cursor Composer
    • Single-file guidance format

  • Aider CLI → Use aider adapter

    • Generate .aider.conf.yml
    • Works in terminal environment
    • Architect mode for complex tasks

  • VS Code + Cline → Use cline adapter

    • Generate .cline/instructions.md
    • Runs in VS Code extension
    • Executor/verifier separation

  • Windsurf IDE → Use windsurf adapter

    • Generate .windsurf/rules.md
    • Cascade-optimized format
    • Codium's AI IDE

  • Other tool or multi-team → Use generic adapter

    • Generate portable markdown files
    • Use with any AI tool
    • No tool-specific dependencies

Recommendation Table

Scenario Recommended Adapter Reason
Solo Claude Code developer claude Full features, real-time tracking
Cursor IDE user cursor Native .cursorrules support
Aider CLI power user aider YAML config, architect mode
VS Code Cline user cline VS Code extension compatibility
Windsurf IDE user windsurf Cascade optimization
Multi-tool team generic Portable markdown format
Building for community generic No tool dependencies
Unknown target audience generic Works everywhere

Migration Between Adapters

If you want to switch from one adapter to another, here's the process:

  1. Keep your original plan - DEVELOPMENT_PLAN.md stays the same
  2. Generate new adapter files: 
    Use devplan_generate_plan with target='new_target'
Use devplan_generate_claude_md with target='new_target'
Use devplan_generate_executor with target='new_target' (if supported)
Use devplan_generate_verifier with target='new_target' (if supported)
  3. Update tool configuration - Move agent files to new tool's location
  4. Continue from same point - Same progress, new tool

Example: Migrating from Claude to Cursor

# You have CLAUDE.md and DEVELOPMENT_PLAN.md
# Generate Cursor equivalents
Use devplan_generate_claude_md with target='cursor'
# Now you have .cursorrules with same guidance
# Continue execution with Cursor using same DEVELOPMENT_PLAN.md

Contributing New Adapters

See docs/CONTRIBUTING_ADAPTERS.md for instructions on building and contributing new adapters.

Adapter Implementation Status

  • ✅ Claude - Fully implemented and production-ready
  • ✅ Cursor - Fully implemented and production-ready
  • ✅ Aider - Fully implemented and production-ready
  • ✅ Cline - Fully implemented and production-ready
  • ✅ Windsurf - Fully implemented and production-ready
  • ✅ Generic - Fully implemented and production-ready

All adapters pass comprehensive test suites and are ready for production use.

Testing Adapters

Each adapter is tested with:

  1. Unit tests - Individual adapter methods
  2. Integration tests - Full plan generation and transformation
  3. Output validation - Generated files match expected format
  4. Round-trip tests - Ensuring consistency across adapters

Run tests with:

npx vitest run src/__tests__/adapters.test.ts

API Reference

See the OutputAdapter Interface for the complete API that each adapter implements.

Key methods:

  • generateAgentFile() - Create main agent instructions
  • generateExecutorAgent() - Create executor (if supported)
  • generateVerifierAgent() - Create verifier (if supported)
  • transformPhasePlan() - Adapt plan for this adapter
  • getPlanInstructions() - Get target-specific instructions

For more details on a specific adapter, see the documentation in docs/adapters/