@iservu-inc/adf-cli 0.1.6 → 0.3.0

package/.project/docs/tool-integrations/IDE-CUSTOMIZATIONS.md

@@ -0,0 +1,578 @@
+# IDE Tool Customizations
+
+## Overview
+
+ADF CLI generates tool-specific configurations to integrate framework outputs directly into IDE workflows.
+
+**Supported Tools:**
+1. Windsurf (Codeium)
+2. Cursor
+3. VS Code (GitHub Copilot / Claude Code)
+
+---
+
+## 1. Windsurf Customizations
+
+### File Structure
+
+```
+project/
+├── .windsurfrules              # Main rules file
+├── .windsurfrules/
+│   ├── memories/
+│   │   ├── project-context.md
+│   │   ├── architecture.md
+│   │   └── coding-standards.md
+│   ├── slash-commands/
+│   │   ├── review-prd.md
+│   │   ├── implement-story.md
+│   │   └── check-requirements.md
+│   └── workflows/
+│       ├── feature-development.yaml
+│       └── code-review.yaml
+```
+
+### .windsurfrules Format
+
+```markdown
+# Project Rules
+
+## Context
+[From PRP/BMAD outputs]
+
+## Constraints
+[From Constitution]
+
+## Code Standards
+[From Technical Plan]
+
+## AI Behavior
+- Always reference PRD before implementing
+- Follow architecture patterns defined in architecture.md
+- Validate against success criteria
+- Ask clarifying questions if requirements unclear
+```
+
+### Memories
+
+**Purpose:** Long-term context retention
+
+**project-context.md:**
+```markdown
+# Project Context
+
+## Goal
+[PRP Goal section]
+
+## Tech Stack
+[PRP Context section]
+
+## User Personas
+[BMAD Personas]
+
+## Key Principles
+[Constitution principles]
+```
+
+**architecture.md:**
+```markdown
+# System Architecture
+
+[C4 diagrams from BMAD]
+[Component breakdown from Spec-Kit]
+[Data flow from PRP]
+```
+
+### Slash Commands
+
+**Purpose:** Quick actions within Cascade chat
+
+**/review-prd:**
+```markdown
+Review the current code against the PRD requirements.
+Check for:
+- [ ] All acceptance criteria met
+- [ ] Edge cases handled
+- [ ] Performance requirements satisfied
+```
+
+**/implement-story [ID]:**
+```markdown
+Implement user story {ID} following:
+1. Review story acceptance criteria
+2. Check architecture for component location
+3. Follow code standards
+4. Write tests first
+5. Implement feature
+6. Verify against success criteria
+```
+
+### Workflows
+
+**Purpose:** Multi-step automations
+
+**feature-development.yaml:**
+```yaml
+name: Feature Development
+steps:
+  - name: Review Requirements
+    action: load_prd
+  - name: Create Branch
+    action: git_branch
+    pattern: "feature/{story-id}-{description}"
+  - name: Implement
+    action: cascade_chat
+    context: [prd, architecture, story]
+  - name: Test
+    action: run_tests
+  - name: Review
+    action: self_review
+```
+
+### Flow System Integration
+
+**Purpose:** Real-time AI assistance
+
+**Configuration:**
+```json
+{
+  "flow": {
+    "enabled": true,
+    "context": [
+      ".windsurfrules/memories/project-context.md",
+      ".windsurfrules/memories/architecture.md"
+    ],
+    "rules": ".windsurfrules",
+    "autoComplete": {
+      "checkRequirements": true,
+      "suggestPatterns": true
+    }
+  }
+}
+```
+
+---
+
+## 2. Cursor Customizations
+
+### File Structure
+
+```
+project/
+├── .cursorrules                    # Main rules (alternative)
+├── .cursor/
+│   ├── rules                       # Main rules (primary)
+│   ├── commands/
+│   │   ├── check-requirements.md
+│   │   └── implement-feature.md
+│   ├── modes/
+│   │   ├── architect.md
+│   │   └── reviewer.md
+│   ├── hooks/
+│   │   ├── pre-commit.js
+│   │   └── post-generate.js
+│   └── notepads/
+│       ├── current-task.md
+│       └── decisions-log.md
+```
+
+### .cursor/rules Format
+
+```markdown
+# Project Rules
+
+You are a senior developer working on {PROJECT_NAME}.
+
+## Context Files
+- PRD: .adf/sessions/{session}/outputs/prd.md
+- Architecture: .adf/sessions/{session}/outputs/architecture.md
+- Constitution: .adf/sessions/{session}/outputs/constitution.md
+
+## Always Follow
+1. Read PRD before implementing features
+2. Follow architecture patterns
+3. Validate against acceptance criteria
+4. Write tests first
+5. Check constitution for constraints
+
+## Code Style
+[From technical plan]
+
+## Forbidden
+[From constitution non-negotiables]
+```
+
+### Custom Modes
+
+**Purpose:** Different AI personalities for different tasks
+
+**architect.md:**
+```markdown
+You are a system architect. When reviewing code:
+- Focus on architectural patterns
+- Check component boundaries
+- Validate data flow
+- Ensure scalability
+- Review performance implications
+
+Reference: .adf/sessions/{session}/outputs/architecture.md
+```
+
+**reviewer.md:**
+```markdown
+You are a code reviewer. Check for:
+- Requirements compliance (against PRD)
+- Code quality and standards
+- Test coverage
+- Edge case handling
+- Security vulnerabilities
+- Performance issues
+
+Be thorough but constructive.
+```
+
+### MCP (Model Context Protocol) Integration
+
+**Purpose:** Extend Cursor with custom tools
+
+**tools/requirements-checker.js:**
+```javascript
+// MCP tool to validate code against requirements
+export default {
+  name: "check_requirements",
+  description: "Validate implementation against PRD requirements",
+  parameters: {
+    feature_id: "string"
+  },
+  async execute({ feature_id }) {
+    const prd = await loadPRD();
+    const feature = prd.features[feature_id];
+    const code = await getCurrentFile();
+
+    return validateAgainstRequirements(code, feature);
+  }
+}
+```
+
+### Hooks
+
+**Purpose:** Automated checks during development
+
+**pre-commit.js:**
+```javascript
+// Check if code meets requirements before commit
+const { loadPRD, validateCode } = require('./utils');
+
+async function preCommit(files) {
+  const prd = await loadPRD();
+  const results = await validateCode(files, prd);
+
+  if (results.missingRequirements.length > 0) {
+    console.log("Missing requirements:", results.missingRequirements);
+    return false; // Block commit
+  }
+
+  return true;
+}
+```
+
+### Notepads
+
+**Purpose:** Persistent context within Cursor
+
+**current-task.md:**
+```markdown
+# Current Task: Implement User Dashboard
+
+## Story
+[User story from BMAD]
+
+## Requirements
+- [ ] Requirement 1
+- [ ] Requirement 2
+
+## Decisions Made
+- Using React Query for data fetching
+- Chart.js for visualizations
+- Daily aggregation in backend
+
+## Questions
+- Max data points to display?
+```
+
+---
+
+## 3. VS Code Customizations
+
+### File Structure
+
+```
+project/
+├── .github/
+│   └── copilot-instructions.md     # GitHub Copilot
+├── .vscode/
+│   ├── settings.json
+│   └── tasks.json
+├── .claude/
+│   ├── commands/
+│   │   ├── review.md
+│   │   └── implement.md
+│   └── context/
+│       └── project.md
+```
+
+### GitHub Copilot Instructions
+
+**Purpose:** Guide Copilot's code generation
+
+**.github/copilot-instructions.md:**
+```markdown
+# Copilot Instructions for {PROJECT_NAME}
+
+## Project Context
+[PRP Goal + Context]
+
+## Architecture
+[Component structure from Spec-Kit]
+
+## Code Style
+- TypeScript strict mode
+- Functional components (React)
+- Async/await (no callbacks)
+- 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
+```
+
+### Custom Chat Modes
+
+**Purpose:** Different Copilot behaviors
+
+**VS Code settings.json:**
+```json
+{
+  "github.copilot.chat.modes": {
+    "architect": {
+      "instructions": "Focus on system design and architecture patterns. Reference architecture.md.",
+      "context": [
+        ".adf/sessions/{session}/outputs/architecture.md"
+      ]
+    },
+    "implementer": {
+      "instructions": "Implement features according to PRD. Write tests first.",
+      "context": [
+        ".adf/sessions/{session}/outputs/prd.md",
+        ".adf/sessions/{session}/outputs/specification.md"
+      ]
+    },
+    "reviewer": {
+      "instructions": "Review code against requirements and best practices.",
+      "context": [
+        ".adf/sessions/{session}/outputs/constitution.md"
+      ]
+    }
+  }
+}
+```
+
+### Claude Code Integration
+
+**Purpose:** Claude-specific configurations
+
+**.claude/commands/review.md:**
+```markdown
+# Review Command
+
+Review the current file against:
+1. PRD requirements (.adf/sessions/{session}/outputs/prd.md)
+2. Architecture patterns (.adf/sessions/{session}/outputs/architecture.md)
+3. Constitution constraints (.adf/sessions/{session}/outputs/constitution.md)
+
+Provide:
+- Compliance status
+- Missing requirements
+- Improvement suggestions
+```
+
+### Language Model Tools API
+
+**Purpose:** Extend VS Code AI with custom tools
+
+**tools/requirement-lookup.ts:**
+```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(parameters: { feature_id: string }) {
+      const prdPath = '.adf/sessions/{session}/outputs/prd.md';
+      const content = await vscode.workspace.fs.readFile(
+        vscode.Uri.file(prdPath)
+      );
+
+      // Parse PRD and return relevant requirement
+      return parseRequirement(content.toString(), parameters.feature_id);
+    }
+  });
+
+  context.subscriptions.push(tool);
+}
+```
+
+---
+
+## Output Generation Strategy
+
+### Per Framework
+
+**PRP → Simple Integration**
+- Single .windsurfrules file
+- Single .cursorrules file
+- Single copilot-instructions.md
+- Reference prp.md for all context
+
+**Balanced → Structured Integration**
+- Separate memory files per output
+- Multiple slash commands
+- Custom modes for each phase
+- Reference constitution, specification, plan
+
+**BMAD → Comprehensive Integration**
+- Full workflow automation
+- MCP tools for requirement validation
+- Hooks for compliance checking
+- Multiple notepads for tracking
+- Reference all BMAD outputs
+
+### Template Variables
+
+All generated files use variables:
+
+```
+{PROJECT_NAME}       - From session metadata
+{SESSION_ID}         - Current session ID
+{FRAMEWORK}          - rapid/balanced/comprehensive
+{OUTPUT_PATH}        - Path to outputs directory
+{TECH_STACK}         - From PRP context
+{PRINCIPLES}         - From constitution
+```
+
+### Example Generated File
+
+**.windsurfrules (from PRP):**
+```markdown
+# Rules for {PROJECT_NAME}
+
+## Project Goal
+{PRP_GOAL}
+
+## Tech Stack
+{PRP_TECH_STACK}
+
+## Implementation Guidelines
+{PRP_IMPLEMENTATION_BLUEPRINT}
+
+## Success Criteria
+{PRP_VALIDATION}
+
+## AI Instructions
+When implementing features:
+1. Read the full PRP: .adf/sessions/{SESSION_ID}/outputs/prp.md
+2. Follow the implementation blueprint exactly
+3. Validate against success criteria
+4. Ask if requirements are unclear
+```
+
+---
+
+## Future Enhancements
+
+### Planned
+
+1. **JetBrains IDEs** (IntelliJ, WebStorm, etc.)
+2. **Neovim** with Copilot.vim
+3. **Zed Editor**
+4. **Sublime Text** with AI plugins
+
+### Advanced Features
+
+1. **Real-time Requirement Sync**
+   - Update IDE rules when PRD changes
+   - Hot reload configurations
+
+2. **Requirement Traceability**
+   - Link code to specific requirements
+   - Show coverage in IDE
+
+3. **AI Pair Programming**
+   - Step-by-step feature implementation
+   - Guided by framework outputs
+
+4. **Automated Testing**
+   - Generate tests from acceptance criteria
+   - Validate against success metrics
+
+---
+
+## Tool Comparison
+
+| Feature | Windsurf | Cursor | VS Code |
+|---------|----------|--------|---------|
+| Custom Rules | ✅ | ✅ | ✅ |
+| Memories | ✅ | ❌ | ❌ |
+| Slash Commands | ✅ | ✅ | ❌ |
+| Custom Modes | ❌ | ✅ | ✅ |
+| Workflows | ✅ | ❌ | ⚠️ (tasks) |
+| Hooks | ❌ | ✅ | ⚠️ (extensions) |
+| MCP Support | ❌ | ✅ | ❌ |
+| Notepads | ❌ | ✅ | ❌ |
+| Tools API | ❌ | ⚠️ (MCP) | ✅ |
+
+✅ = Native support
+⚠️ = Partial/alternative support
+❌ = Not available
+
+---
+
+## Implementation Priority
+
+### Phase 2A: Basic Integration
+1. Generate .windsurfrules (simple format)
+2. Generate .cursorrules (simple format)
+3. Generate copilot-instructions.md
+
+### Phase 2B: Advanced Features
+1. Windsurf memories
+2. Cursor custom modes
+3. VS Code custom chat modes
+
+### Phase 2C: Automation
+1. Windsurf workflows
+2. Cursor hooks
+3. VS Code tools API
+
+### Phase 2D: All Tools
+1. JetBrains
+2. Neovim
+3. Zed