@iservu-inc/adf-cli 0.2.0 → 0.3.0

package/.project/docs/tool-integrations/RESEARCH-FINDINGS.md

@@ -0,0 +1,828 @@
+# Tool Integration Research Findings
+
+**Date:** 2025-10-03
+**Status:** Complete - Ready for Implementation
+**Phase:** Option B - IDE Tool Integrations
+
+---
+
+## Executive Summary
+
+Research identified **4 primary integration strategies**:
+
+1. **AGENTS.md** - Universal open standard (recommended primary approach)
+2. **Windsurf** - .windsurfrules, memories, workflows
+3. **Cursor** - .cursorrules, .cursor/rules, modes, MCP
+4. **VS Code** - .github/copilot-instructions.md, chat modes, tools API
+
+**Key Insight:** AGENTS.md should be the **foundation** with tool-specific configurations as **supplements**.
+
+---
+
+## 1. AGENTS.md - Universal Standard
+
+### Overview
+
+AGENTS.md is an **open, markdown-based specification** for AI coding agent instructions, developed collaboratively by:
+- OpenAI (Codex/Copilot)
+- Google (Gemini/Jules)
+- Cursor
+- Factory
+- Amp
+- RooCode
+- Aider
+
+### Adoption (2025)
+
+- **20,000+** open-source projects on GitHub
+- **All major AI coding tools** support it
+- **Industry standard** for agent configuration
+
+### Why It Matters for ADF CLI
+
+1. **Universal Compatibility**: Works across all tools automatically
+2. **Future-Proof**: New tools will support it
+3. **Simplicity**: Just markdown, no complex syntax
+4. **Nesting**: Can have project-level + submodule-level files
+5. **Complements Tools**: Doesn't replace tool-specific configs, enhances them
+
+### File Format
+
+**Location:** `AGENTS.md` at project root
+
+**Format:** Standard Markdown (any headings)
+
+**Nesting:** Agents read nearest file in directory tree
+
+### Structure (Recommended Sections)
+
+```markdown
+# Project Name
+
+## Overview
+[Brief description of what this project does]
+
+## Build Commands
+\`\`\`bash
+npm install
+npm run build
+\`\`\`
+
+## Test Commands
+\`\`\`bash
+npm test
+npm run test:coverage
+\`\`\`
+
+## Architecture Overview
+[High-level architecture description]
+
+## Coding Style
+- Use TypeScript strict mode
+- Functional components for React
+- Async/await (no callbacks)
+
+## Development Workflow
+1. Create feature branch
+2. Write tests first
+3. Implement feature
+4. Run tests and linter
+5. Create PR
+
+## CI/PR Instructions
+- All tests must pass
+- Coverage must be >= 80%
+- No linting errors
+
+## Security Notes
+- Never commit secrets
+- Use environment variables for API keys
+- Validate all user input
+
+## Key Files
+- src/index.ts - Entry point
+- src/lib/ - Core library code
+- tests/ - Test files
+```
+
+### ADF CLI Integration Strategy
+
+**Generate AGENTS.md from framework outputs:**
+
+**From PRP:**
+```markdown
+# {PROJECT_NAME}
+
+## Goal
+{PRP_GOAL}
+
+## Tech Stack
+{PRP_CONTEXT_TECH_STACK}
+
+## Implementation Blueprint
+{PRP_IMPLEMENTATION_BLUEPRINT}
+
+## Success Criteria
+{PRP_VALIDATION_SUCCESS_CRITERIA}
+```
+
+**From Balanced:**
+```markdown
+# {PROJECT_NAME}
+
+## Constitution
+{CONSTITUTION_PRINCIPLES}
+
+## Architecture
+{SPECIFICATION_ARCHITECTURE}
+
+## Technical Plan
+{PLAN_ARCHITECTURE_DECISIONS}
+
+## Tasks
+{TASKS_IMPLEMENTATION_PHASES}
+```
+
+**From BMAD:**
+```markdown
+# {PROJECT_NAME}
+
+## Product Overview
+{PRD_EXECUTIVE_SUMMARY}
+
+## Architecture
+{ARCHITECTURE_SYSTEM_DESIGN}
+
+## User Stories
+{STORIES_LIST}
+
+## Technical Requirements
+{PRD_TECHNICAL_REQUIREMENTS}
+```
+
+### Nested AGENTS.md Strategy
+
+**Root Level:** `AGENTS.md` - Project-wide instructions
+
+**Submodule Level:** `packages/frontend/AGENTS.md` - Frontend-specific
+
+**Example:**
+```
+project/
+├── AGENTS.md (general project context)
+├── frontend/
+│   └── AGENTS.md (React-specific instructions)
+├── backend/
+│   └── AGENTS.md (API-specific instructions)
+└── shared/
+    └── AGENTS.md (shared library instructions)
+```
+
+---
+
+## 2. Windsurf Integration
+
+### Overview
+
+**Windsurf** (by Codeium) is an agentic IDE with Cascade AI assistant.
+
+### Configuration Files
+
+#### .windsurfrules (Legacy, Still Supported)
+
+**Location:** Project root
+
+**Format:** Markdown
+
+**Character Limit:** 12,000 per file
+
+**Alternative:** Paste via Settings → Set Workspace AI Rules → Edit Rules
+
+#### .windsurf/rules/ (Modern, Recommended)
+
+**Location:** `.windsurf/rules/*.md`
+
+**Format:** Markdown files
+
+**Activation Modes:**
+1. **Manual** - Via @mention in Cascade
+2. **Model Decision** - AI decides when to apply
+3. **Always On** - Applied to all conversations
+4. **File Glob** - Applied to specific file patterns
+
+**Example File:** `.windsurf/rules/typescript-strict.md`
+```markdown
+# TypeScript Strict Mode Rule
+
+When working with TypeScript files:
+- Enable strict mode in tsconfig.json
+- Use explicit types (no `any`)
+- Handle all null/undefined cases
+- Use readonly for immutable data
+```
+
+#### .windsurf/workflows/
+
+**Location:** `.windsurf/workflows/*.md`
+
+**Purpose:** Saved prompts invoked via slash commands
+
+**Example:** `.windsurf/workflows/implement-feature.md`
+```markdown
+# Implement Feature Workflow
+
+1. Review requirements from PRD
+2. Create feature branch
+3. Write tests first
+4. Implement feature following architecture
+5. Verify all tests pass
+6. Create pull request
+```
+
+**Usage:** Type `/implement-feature` in Cascade
+
+#### Cascade Memories
+
+**Types:**
+1. **User-Generated Memories** (Rules) - Explicitly defined
+2. **Auto-Generated Memories** - Cascade creates based on interactions
+
+**Access:** Customizations icon → Manage memories
+
+**Purpose:** Remember important context between conversations
+
+### Windsurf Best Practices
+
+**Formatting:**
+- Use bullet points and numbered lists
+- Markdown > long paragraphs
+- Short, focused rules
+
+**Organization:**
+- Separate rules by concern (style, architecture, testing)
+- Use descriptive filenames
+- Keep rules under 12K characters
+
+**Templates:**
+- Official directory: https://windsurf.com/editor/directory
+- Community: github.com/SchneiderSam/awesome-windsurfrules
+
+### ADF CLI Generator for Windsurf
+
+**Files to Generate:**
+
+1. **`.windsurfrules`** (Compatibility)
+   - Contains project-level rules from framework outputs
+   - Combines constitution + key principles + tech stack
+
+2. **`.windsurf/rules/project-context.md`**
+   - From PRP Goal + Context
+
+3. **`.windsurf/rules/architecture.md`**
+   - From Spec-Kit or BMAD Architecture
+
+4. **`.windsurf/rules/coding-standards.md`**
+   - From Technical Plan
+
+5. **`.windsurf/workflows/implement-story.md`**
+   - Workflow for implementing user stories
+
+6. **`.windsurf/workflows/review-requirements.md`**
+   - Workflow to review PRD before coding
+
+---
+
+## 3. Cursor Integration
+
+### Overview
+
+**Cursor** is an AI-first code editor with multiple configuration strategies.
+
+### Configuration Files
+
+#### .cursorrules (Legacy, Being Deprecated)
+
+**Location:** Project root
+
+**Status:** Still supported but migrate to Project Rules
+
+**Format:** Plain text or Markdown
+
+#### .cursor/rules (Modern, Recommended)
+
+**Location:** `.cursor/rules` (file, not directory)
+
+**Scope:** Project-specific (version-controlled)
+
+**Alternative User Rules:** Global to Cursor environment (in settings)
+
+**Format:** Markdown
+
+**Example:**
+```markdown
+# Project Rules
+
+## Context
+You are working on {PROJECT_NAME}, a {DESCRIPTION}.
+
+## Tech Stack
+- Frontend: React 18, TypeScript
+- Backend: Node.js, Express
+- Database: PostgreSQL
+
+## Code Style
+- Use TypeScript strict mode
+- Functional components only
+- Async/await for all async code
+
+## Before Implementing
+1. Read PRD: .adf/sessions/{SESSION}/outputs/prd.md
+2. Review architecture: .adf/sessions/{SESSION}/outputs/architecture.md
+3. Check constraints: .adf/sessions/{SESSION}/outputs/constitution.md
+```
+
+#### .cursor/mcp.json (Model Context Protocol)
+
+**Location:** `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)
+
+**Purpose:** Add MCP servers for extended functionality
+
+**Example:**
+```json
+{
+  "mcpServers": {
+    "requirement-checker": {
+      "command": "node",
+      "args": ["./tools/requirement-checker.js"],
+      "env": {
+        "PRD_PATH": ".adf/sessions/latest/outputs/prd.md"
+      }
+    }
+  }
+}
+```
+
+**Use Case:** Custom tool to validate code against requirements
+
+#### Custom Modes
+
+**Purpose:** Specific prompts + available tools per mode
+
+**Example Modes:**
+- **Architect Mode** - Focus on design, read-only tools
+- **Implementer Mode** - Write code, full access
+- **Reviewer Mode** - Check compliance, linting tools
+
+**Configuration:** Via Cursor settings UI (no file format documented yet)
+
+### Cursor Resources
+
+**Official:** https://docs.cursor.com/
+
+**Community:**
+- https://cursor.directory/ - Custom rules & MCP servers
+- https://github.com/PatrickJS/awesome-cursorrules
+- https://github.com/ample-education/cursor-resources
+
+### ADF CLI Generator for Cursor
+
+**Files to Generate:**
+
+1. **`.cursor/rules`** (Primary)
+   - Combines all framework outputs
+   - References session outputs for context
+   - Includes tech stack, principles, constraints
+
+2. **`.cursor/mcp.json`** (Optional, Advanced)
+   - MCP server for requirement validation
+   - Tool to check code against PRD
+
+3. **Migration Note in README**
+   - Inform users about .cursorrules deprecation
+   - Guide to .cursor/rules
+
+**Template for .cursor/rules:**
+```markdown
+# {PROJECT_NAME} - Cursor Rules
+
+## Project Context
+{PRP_GOAL or PRD_OVERVIEW}
+
+## Technical Stack
+{TECH_STACK}
+
+## Core Principles
+{CONSTITUTION_PRINCIPLES}
+
+## Architecture
+Reference: .adf/sessions/{SESSION_ID}/outputs/architecture.md
+
+{ARCHITECTURE_SUMMARY}
+
+## Coding Standards
+{TECHNICAL_PLAN_CODE_STYLE}
+
+## Before Writing Code
+1. Review PRD: .adf/sessions/{SESSION_ID}/outputs/prd.md
+2. Check architecture patterns: {ARCH_FILE}
+3. Verify constraints: {CONSTITUTION_FILE}
+
+## Forbidden
+{CONSTITUTION_NON_NEGOTIABLES}
+```
+
+---
+
+## 4. VS Code Integration
+
+### Overview
+
+**VS Code** with **GitHub Copilot** or **Claude Code** extension.
+
+### Configuration Files
+
+#### .github/copilot-instructions.md
+
+**Location:** `.github/copilot-instructions.md`
+
+**Purpose:** Instructions for GitHub Copilot
+
+**Format:** Markdown
+
+**Example:**
+```markdown
+# Copilot Instructions for {PROJECT_NAME}
+
+## Project Overview
+{DESCRIPTION}
+
+## Tech Stack
+- React 18, TypeScript, Node.js
+
+## Code Style
+- Use functional components
+- Async/await only
+- Descriptive variable names
+
+## Patterns to Use
+- Custom hooks for logic reuse
+- Context for global state
+- Error boundaries for error handling
+
+## Patterns to Avoid
+- Class components
+- Inline styles
+- Direct DOM manipulation
+
+## Testing
+- Jest + React Testing Library
+- Test files: *.test.ts
+- Coverage minimum: 80%
+
+## When Generating Code
+1. Check PRD in .adf/sessions/{SESSION}/outputs/
+2. Follow architecture patterns
+3. Include error handling
+4. Add TypeScript types
+5. Write accompanying tests
+```
+
+#### .chatmode.md (Custom Chat Modes)
+
+**Location:** Workspace or user profile
+
+**Purpose:** Define custom chat modes with instructions + tools
+
+**Example:** `.chatmode/architect.md`
+```markdown
+# Architect Mode
+
+## Instructions
+Focus on system design and architecture patterns.
+Check component boundaries, data flow, scalability.
+
+## Context
+- .adf/sessions/{SESSION}/outputs/architecture.md
+- .adf/sessions/{SESSION}/outputs/prd.md
+
+## Tools
+- Read-only access
+- Diagram generation
+- Architecture validation
+```
+
+#### Language Model Tools API
+
+**Purpose:** VS Code extensions can register custom tools
+
+**Example Tool:**
+```typescript
+import * as vscode from 'vscode';
+
+export function registerTools(context: vscode.ExtensionContext) {
+  const tool = vscode.lm.registerTool('requirement-lookup', {
+    description: 'Look up requirements from PRD',
+    async invoke(params: { feature_id: string }) {
+      const prdPath = '.adf/sessions/latest/outputs/prd.md';
+      const content = await vscode.workspace.fs.readFile(
+        vscode.Uri.file(prdPath)
+      );
+      return parseRequirement(content.toString(), params.feature_id);
+    }
+  });
+
+  context.subscriptions.push(tool);
+}
+```
+
+### VS Code Resources
+
+**Official:**
+- https://code.visualstudio.com/api/extension-guides/ai/language-model
+- https://code.visualstudio.com/api/extension-guides/ai/tools
+- https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes
+
+### ADF CLI Generator for VS Code
+
+**Files to Generate:**
+
+1. **`.github/copilot-instructions.md`**
+   - From all framework outputs
+   - Includes tech stack, patterns, testing requirements
+
+2. **`.vscode/settings.json`** (Enhancement)
+   - Add custom chat modes configuration
+   - Reference framework outputs
+
+**Template for copilot-instructions.md:**
+```markdown
+# Copilot Instructions for {PROJECT_NAME}
+
+## Project Context
+{PRP_GOAL or PRD_OVERVIEW}
+
+## Tech Stack
+{TECH_STACK}
+
+## Architecture
+{ARCHITECTURE_SUMMARY}
+
+See full architecture: .adf/sessions/{SESSION}/outputs/architecture.md
+
+## Code Standards
+{TECHNICAL_PLAN_CODE_STYLE}
+
+## Patterns to Use
+{RECOMMENDED_PATTERNS}
+
+## Patterns to Avoid
+{ANTI_PATTERNS}
+
+## Testing Requirements
+{TESTING_APPROACH}
+
+## Security Requirements
+{SECURITY_NOTES}
+
+## When Generating Code
+1. Review requirements: .adf/sessions/{SESSION}/outputs/
+2. Follow architecture: {ARCH_PATTERNS}
+3. Include error handling
+4. Add type definitions
+5. Write tests
+
+## Reference Documents
+- PRD: .adf/sessions/{SESSION}/outputs/prd.md
+- Architecture: .adf/sessions/{SESSION}/outputs/architecture.md
+- Constitution: .adf/sessions/{SESSION}/outputs/constitution.md
+```
+
+---
+
+## Implementation Strategy
+
+### Unified Generator Architecture
+
+```javascript
+class ToolConfigGenerator {
+  constructor(sessionPath, framework) {
+    this.sessionPath = sessionPath;
+    this.framework = framework;
+    this.outputs = this.loadOutputs();
+  }
+
+  loadOutputs() {
+    // Load all generated framework outputs
+    // (prp.md, prd.md, architecture.md, etc.)
+  }
+
+  generateAll() {
+    // Generate all tool configurations
+    this.generateAgentsMd();      // Universal
+    this.generateWindsurf();      // Windsurf-specific
+    this.generateCursor();        // Cursor-specific
+    this.generateVSCode();        // VS Code-specific
+  }
+
+  generateAgentsMd() {
+    // Create AGENTS.md from framework outputs
+  }
+
+  generateWindsurf() {
+    // Create .windsurfrules, .windsurf/rules/, .windsurf/workflows/
+  }
+
+  generateCursor() {
+    // Create .cursor/rules, .cursor/mcp.json
+  }
+
+  generateVSCode() {
+    // Create .github/copilot-instructions.md, .vscode/settings.json
+  }
+}
+```
+
+### Priority Order
+
+1. **AGENTS.md** (Universal) - ALWAYS generate
+2. **Windsurf** - If user selects Windsurf as tool
+3. **Cursor** - If user selects Cursor as tool
+4. **VS Code** - If user selects VS Code as tool
+
+### Template Variables
+
+All generators use:
+```javascript
+{
+  PROJECT_NAME,
+  SESSION_ID,
+  FRAMEWORK,          // rapid/balanced/comprehensive
+  PRP_GOAL,
+  PRP_CONTEXT,
+  PRP_IMPLEMENTATION,
+  PRD_OVERVIEW,
+  ARCHITECTURE_SUMMARY,
+  CONSTITUTION_PRINCIPLES,
+  TECH_STACK,
+  CODE_STYLE,
+  TESTING_APPROACH,
+  SECURITY_NOTES
+}
+```
+
+### File Organization
+
+```
+project/
+├── AGENTS.md                                    # Universal (ALWAYS)
+├── .windsurfrules                               # Windsurf (legacy compat)
+├── .windsurf/
+│   ├── rules/
+│   │   ├── project-context.md
+│   │   ├── architecture.md
+│   │   └── coding-standards.md
+│   └── workflows/
+│       ├── implement-story.md
+│       └── review-requirements.md
+├── .cursor/
+│   ├── rules                                    # Cursor (primary)
+│   └── mcp.json                                 # MCP servers (optional)
+├── .github/
+│   └── copilot-instructions.md                  # GitHub Copilot
+└── .vscode/
+    └── settings.json                            # VS Code chat modes
+```
+
+---
+
+## Next Steps for Implementation
+
+### Phase 2A: Core Generator (Priority 1)
+
+1. **Create tool-config-generator.js**
+   - Base class for all generators
+   - Template variable substitution
+   - Output file writing
+
+2. **Implement AGENTS.md Generator**
+   - Works for all frameworks (PRP, Balanced, BMAD)
+   - Simple, focused content
+   - Nested support for monorepos
+
+3. **Test with Real Outputs**
+   - Use existing framework outputs
+   - Verify generated AGENTS.md quality
+   - Test with Cursor, Windsurf, Copilot
+
+### Phase 2B: Tool-Specific Generators (Priority 2)
+
+4. **Windsurf Generator**
+   - .windsurfrules (compatibility)
+   - .windsurf/rules/*.md (modern)
+   - .windsurf/workflows/*.md (slash commands)
+
+5. **Cursor Generator**
+   - .cursor/rules (primary)
+   - Migration guide for .cursorrules
+
+6. **VS Code Generator**
+   - .github/copilot-instructions.md
+   - .vscode/settings.json enhancements
+
+### Phase 2C: Advanced Features (Priority 3)
+
+7. **MCP Server Generation**
+   - Custom requirement validation tool
+   - PRD lookup tool
+   - Architecture compliance checker
+
+8. **Custom Mode Templates**
+   - Architect mode
+   - Implementer mode
+   - Reviewer mode
+
+9. **Nested AGENTS.md Support**
+   - Detect monorepo structure
+   - Generate submodule-specific AGENTS.md
+   - Maintain hierarchy
+
+### Phase 2D: Integration & Testing (Priority 4)
+
+10. **Deploy Command Enhancement**
+    - Update `adf deploy` to generate configs
+    - Add `--generate-configs` flag
+    - Support `--tool` selection
+
+11. **End-to-End Testing**
+    - Test with real projects
+    - Verify all tools read configs correctly
+    - User acceptance testing
+
+12. **Documentation**
+    - User guide for generated configs
+    - Customization guide
+    - Tool-specific tips
+
+---
+
+## Success Criteria
+
+### For Each Tool Integration
+
+- [ ] Generated config is syntactically valid
+- [ ] Tool recognizes and uses config
+- [ ] All framework outputs mapped correctly
+- [ ] Template variables substituted properly
+- [ ] File permissions correct
+- [ ] Works on Windows, Mac, Linux
+
+### For Overall System
+
+- [ ] AGENTS.md works in Cursor, Windsurf, Copilot
+- [ ] Tool-specific configs enhance AGENTS.md (don't conflict)
+- [ ] Users can customize generated configs
+- [ ] Clear documentation for each tool
+- [ ] Migration guides from manual to ADF-generated
+
+---
+
+## Key Takeaways
+
+1. **AGENTS.md is the future** - Universal standard, all tools support it
+2. **Tool-specific = Enhancement** - Not replacement for AGENTS.md
+3. **Simple > Complex** - Markdown beats proprietary formats
+4. **Nesting = Power** - Monorepo support via nested files
+5. **Community-Driven** - Leverage existing templates and best practices
+
+---
+
+## Resources
+
+### AGENTS.md
+- Spec: https://github.com/openai/agents.md
+- Site: https://agents.md/
+- Factory Docs: https://docs.factory.ai/factory-cli/configuration/agents-md
+- Examples: https://www.builder.io/blog/agents-md
+
+### Windsurf
+- Docs: https://docs.windsurf.com/
+- Rules Directory: https://windsurf.com/editor/directory
+- Awesome List: https://github.com/SchneiderSam/awesome-windsurfrules
+- Guide: https://www.paulmduvall.com/using-windsurf-rules-workflows-and-memories/
+
+### Cursor
+- Docs: https://docs.cursor.com/context/rules
+- Directory: https://cursor.directory/
+- Awesome List: https://github.com/PatrickJS/awesome-cursorrules
+- Resources: https://github.com/ample-education/cursor-resources
+
+### VS Code
+- Language Model API: https://code.visualstudio.com/api/extension-guides/ai/language-model
+- Tools API: https://code.visualstudio.com/api/extension-guides/ai/tools
+- Chat Modes: https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes
+
+---
+
+**Research Complete:** 2025-10-03
+**Ready for Implementation:** YES ✅
+**Recommended Start:** AGENTS.md Generator (universal compatibility)