aiwf 0.3.18 → 0.3.19

package/ai-tools/cursor/README.md

@@ -0,0 +1,314 @@
+# Cursor AIWF Integration Template
+
+## Overview
+
+This template optimizes Cursor IDE for AIWF projects, providing deep integration with Feature Ledger, AI Personas, and Sprint Management systems. It enhances Cursor's AI capabilities with AIWF's structured development approach.
+
+## Features
+
+- **Multi-File Context Awareness**: Cursor understands AIWF's interconnected structure
+- **Feature Ledger Integration**: Automatic feature tracking and referencing
+- **AI Persona Optimization**: Context-aware code suggestions based on active persona
+- **Sprint Task Tracking**: Real-time task status integration
+- **Context Compression**: Efficient handling of large codebases
+- **Composer Enhancement**: AIWF-aware prompts and completions
+
+## Installation
+
+```bash
+# Install Cursor template
+aiwf ai-tool install cursor
+
+# Or manually copy template files
+cp -r .aiwf/ai-tools/cursor/template/.cursorrules .
+cp -r .aiwf/ai-tools/cursor/template/.cursor .
+```
+
+## Configuration
+
+The template includes:
+
+1. **.cursorrules**: Main configuration file
+   - AIWF integration rules
+   - Code generation patterns
+   - Best practices
+   - Project-specific guidelines
+
+2. **.cursor/**: Directory for Cursor-specific settings
+   - Context providers
+   - Custom completions
+   - AIWF shortcuts
+
+## Usage
+
+### 1. Feature-Aware Development
+
+Cursor automatically:
+- Checks Feature Ledger before suggesting implementations
+- Includes feature IDs in generated code
+- Maintains feature traceability
+
+```javascript
+// Start typing a function
+// Cursor suggests:
+/**
+ * Feature: FL-001 - User Authentication
+ * Task: T13_S03
+ */
+function authenticateUser(credentials) {
+  // Feature-aware implementation
+}
+```
+
+### 2. Composer Integration
+
+Use AIWF context in Composer:
+
+```
+Composer> Implement the user profile feature following FL-002 specifications
+
+Composer> Using architect persona, design the payment system architecture
+
+Composer> Compress and analyze the authentication module for optimization
+```
+
+### 3. Multi-File Operations
+
+Leverage Cursor's multi-file edit:
+
+1. **Feature Implementation**
+   - Opens feature file, implementation, tests together
+   - Maintains consistency across files
+   - Updates documentation automatically
+
+2. **Sprint Task Completion**
+   - Updates task status
+   - Modifies related files
+   - Commits with proper references
+
+### 4. Context Management
+
+Efficient context usage:
+
+```javascript
+// Large file handling
+// @compress src/large-module.js
+// Cursor automatically uses compressed version
+
+// Feature reference
+// @feature FL-001
+// Cursor loads feature specification
+```
+
+### 5. AI Persona Integration
+
+Switch personas for different contexts:
+
+```javascript
+// @persona architect
+// Cursor provides architectural patterns and design suggestions
+
+// @persona developer
+// Cursor focuses on implementation details and optimization
+
+// @persona reviewer
+// Cursor highlights potential issues and suggests improvements
+```
+
+## Best Practices
+
+### 1. Start with Context
+
+Always provide AIWF context:
+
+```javascript
+/**
+ * Working on: Sprint S03
+ * Task: T13_S03 - AI Tool Integration
+ * Feature: FL-010 - Tool Templates
+ */
+```
+
+### 2. Use Feature References
+
+Reference features in all code:
+
+```javascript
+// Good
+import { UserAuth } from './features/FL001-auth'; // Feature: FL-001
+
+// Avoid
+import { UserAuth } from './auth'; // No feature reference
+```
+
+### 3. Maintain Task Flow
+
+Follow task lifecycle:
+
+```bash
+# Start work
+aiwf task start T13_S03
+
+# During development (in Cursor)
+// Task: T13_S03 - Status: in_progress
+
+# Complete work
+aiwf task complete T13_S03
+```
+
+### 4. Leverage Compression
+
+For large files:
+
+```bash
+# Compress before including in context
+aiwf context compress src/large-component.js
+
+# Reference in Cursor
+// @compressed large-component.js
+```
+
+## Advanced Features
+
+### 1. Custom Context Providers
+
+Create `.cursor/providers.json`:
+
+```json
+{
+  "providers": [
+    {
+      "name": "feature-ledger",
+      "path": ".aiwf/feature-ledger/",
+      "pattern": "FL-*.json"
+    },
+    {
+      "name": "current-sprint",
+      "path": ".aiwf/03_SPRINTS/current/",
+      "pattern": "*.md"
+    }
+  ]
+}
+```
+
+### 2. AIWF Snippets
+
+Define in `.cursor/snippets.json`:
+
+```json
+{
+  "aiwf-feature": {
+    "prefix": "aiwf-feat",
+    "body": [
+      "/**",
+      " * Feature: FL-${1:XXX} - ${2:Feature Name}",
+      " * Sprint: S${3:XX}",
+      " * Task: T${4:XX}_S${3:XX}",
+      " */"
+    ]
+  }
+}
+```
+
+### 3. Workspace Settings
+
+Configure `.cursor/settings.json`:
+
+```json
+{
+  "aiwf": {
+    "autoCheckFeatureLedger": true,
+    "showTaskStatus": true,
+    "enablePersonaHints": true,
+    "contextCompression": {
+      "threshold": 1000,
+      "automatic": true
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Cursor not recognizing AIWF patterns**
+   - Ensure .cursorrules is in project root
+   - Restart Cursor to reload rules
+   - Check file permissions
+
+2. **Feature references missing**
+   - Run `aiwf ledger sync`
+   - Verify Feature Ledger structure
+   - Update .cursorrules if needed
+
+3. **Context overflow**
+   - Use compression for large files
+   - Reference features by ID
+   - Clear unnecessary context
+
+### Debug Mode
+
+Enable AIWF debug in Cursor:
+
+```json
+{
+  "aiwf.debug": true,
+  "aiwf.logLevel": "verbose"
+}
+```
+
+## Integration Tips
+
+### 1. Composer Workflows
+
+Effective Composer prompts:
+
+```
+"Implement FL-001 authentication with test coverage"
+"Using reviewer persona, analyze the payment module"
+"Update all files related to task T13_S03"
+```
+
+### 2. Multi-File Patterns
+
+Common multi-file operations:
+
+- Feature + Tests + Docs
+- API Route + Controller + Service + Tests
+- Component + Styles + Tests + Story
+
+### 3. Context Optimization
+
+Manage context efficiently:
+
+- Use feature IDs instead of full descriptions
+- Compress files over 1000 lines
+- Reference ADRs by number
+- Include only active sprint tasks
+
+## Updates
+
+Keep template synchronized:
+
+```bash
+# Check for updates
+aiwf ai-tool check cursor
+
+# Update template
+aiwf ai-tool update cursor
+
+# Verify installation
+aiwf ai-tool verify cursor
+```
+
+## Resources
+
+- [Cursor Documentation](https://cursor.sh/docs)
+- [AIWF Documentation](https://aiwf.dev/docs)
+- [Integration Guide](https://aiwf.dev/guides/cursor)
+- [Community Forum](https://forum.aiwf.dev/cursor)
+
+---
+
+*Cursor Integration Template v1.0.0*

package/ai-tools/cursor/config.json

@@ -0,0 +1,29 @@
+{
+  "name": "cursor",
+  "version": "1.0.0",
+  "description": "Cursor IDE integration template for AIWF",
+  "compatible_aiwf_version": ">=0.1.0",
+  "features": {
+    "feature_ledger": true,
+    "ai_persona": true,
+    "context_compression": true,
+    "offline_cache": true,
+    "multi_file_edit": true
+  },
+  "setup_commands": [],
+  "files_to_copy": [
+    {
+      "source": "template/.cursorrules",
+      "destination": ".cursorrules"
+    },
+    {
+      "source": "template/.cursor",
+      "destination": ".cursor"
+    }
+  ],
+  "settings": {
+    "aiwf_context_provider": true,
+    "feature_aware_completions": true,
+    "sprint_task_tracking": true
+  }
+}

package/ai-tools/cursor/template/.cursorrules

@@ -0,0 +1,362 @@
+# Cursor AI Rules for AIWF Projects
+
+## Project Context
+This project uses the AI Workflow Framework (AIWF) for structured development with AI assistance. Follow these rules to ensure Cursor provides AIWF-aware suggestions.
+
+## Core Principles
+
+### 1. Feature-Driven Development
+- Always check Feature Ledger before implementing new features
+- Reference Feature IDs (FL###) in all related code
+- Maintain feature traceability throughout the codebase
+
+### 2. Sprint-Aligned Coding
+- Reference current sprint tasks in implementations
+- Update task status as work progresses
+- Follow sprint acceptance criteria strictly
+
+### 3. Persona-Based Development
+- Apply appropriate coding style based on active persona
+- Switch personas for different types of work
+- Document persona usage in code comments
+
+## AIWF Integration Rules
+
+### Feature References
+```javascript
+/**
+ * @feature FL001 - User Authentication System
+ * @task TX01_S01 - Implement login functionality
+ * @persona developer
+ */
+```
+
+### Sprint Context
+```javascript
+// Sprint: S01_M02 - Authentication Foundation
+// Task: TX01_S01
+// Status: in_progress
+// Acceptance Criteria:
+// - [ ] User can log in with email/password
+// - [ ] Sessions are managed securely
+// - [ ] Rate limiting is implemented
+```
+
+### Error Handling with Context
+```javascript
+class FeatureError extends Error {
+  constructor(message, context) {
+    super(`[${context.featureId}/${context.taskId}] ${message}`);
+    this.feature = context.featureId;
+    this.task = context.taskId;
+    this.timestamp = new Date().toISOString();
+  }
+}
+```
+
+## Code Generation Guidelines
+
+### 1. Documentation Standards
+Every function/class must include:
+- Feature ID reference
+- Task ID (if applicable)
+- Active persona
+- Brief description
+- Example usage
+
+### 2. Naming Conventions
+- Features: `FL###_FeatureName`
+- Tasks: `TX##_S##_TaskName`
+- Sprints: `S##_M##_SprintName`
+- Files: `feature-id_component-name.ext`
+
+### 3. Import Organization
+```javascript
+// External dependencies
+import express from 'express';
+import jwt from 'jsonwebtoken';
+
+// AIWF core imports
+import { FeatureLedger } from '@aiwf/core';
+import { TaskManager } from '@aiwf/tasks';
+
+// Project imports
+import { AuthService } from './services/auth.service';
+
+// Feature-specific imports
+import { FL001_UserAuth } from './features/FL001_user_auth';
+```
+
+## Persona-Specific Patterns
+
+### Architect Persona
+Focus on:
+- System design patterns
+- Architecture documentation
+- Technology decisions
+- Scalability considerations
+
+```javascript
+// Architect persona active
+interface IAuthenticationStrategy {
+  authenticate(credentials: ICredentials): Promise<IAuthResult>;
+  refresh(token: string): Promise<IAuthResult>;
+  revoke(token: string): Promise<void>;
+}
+
+// Suggest factory patterns, dependency injection, etc.
+```
+
+### Security Persona
+Focus on:
+- Input validation
+- Security best practices
+- Vulnerability prevention
+- Audit logging
+
+```javascript
+// Security persona active
+class SecureAuthService {
+  async authenticate(credentials) {
+    // Input sanitization
+    this.validator.sanitize(credentials);
+    
+    // Rate limiting check
+    await this.rateLimiter.check(credentials.email);
+    
+    // Secure password comparison
+    const isValid = await bcrypt.compare(
+      credentials.password,
+      hashedPassword
+    );
+    
+    // Audit log
+    this.auditLogger.log('auth_attempt', {
+      email: credentials.email,
+      success: isValid,
+      ip: request.ip,
+      timestamp: new Date()
+    });
+  }
+}
+```
+
+### Developer Persona
+Focus on:
+- Clean implementation
+- Error handling
+- Testing
+- Performance
+
+```javascript
+// Developer persona active
+class UserController {
+  constructor(
+    private authService: AuthService,
+    private logger: Logger
+  ) {}
+
+  async login(req: Request, res: Response) {
+    try {
+      const result = await this.authService.authenticate(req.body);
+      
+      res.json({
+        success: true,
+        data: result
+      });
+      
+      this.logger.info('User logged in', { userId: result.user.id });
+    } catch (error) {
+      this.logger.error('Login failed', error);
+      
+      res.status(401).json({
+        success: false,
+        error: 'Authentication failed'
+      });
+    }
+  }
+}
+```
+
+## Testing Guidelines
+
+### Test Structure
+```javascript
+describe('Feature FL001: User Authentication', () => {
+  describe('Task TX01_S01: Login Implementation', () => {
+    describe('Acceptance Criteria', () => {
+      it('should authenticate valid credentials', async () => {
+        // Test implementation
+      });
+      
+      it('should reject invalid credentials', async () => {
+        // Test implementation
+      });
+      
+      it('should enforce rate limiting', async () => {
+        // Test implementation
+      });
+    });
+  });
+});
+```
+
+### Test Documentation
+```javascript
+/**
+ * Test Suite: User Authentication
+ * @feature FL001
+ * @sprint S01_M02
+ * @coverage Unit, Integration
+ */
+```
+
+## Git Integration
+
+### Commit Message Format
+```
+<type>(<feature-id>): <description>
+
+<body>
+
+Task: <task-id>
+Sprint: <sprint-id>
+Persona: <active-persona>
+```
+
+Example:
+```
+feat(FL001): implement JWT authentication
+
+- Add token generation service
+- Implement refresh token logic
+- Add token validation middleware
+
+Task: TX01_S01
+Sprint: S01_M02
+Persona: developer
+```
+
+### Branch Naming
+```
+feature/FL###-short-description
+task/TX##-S##-task-name
+bugfix/FL###-issue-description
+```
+
+## Code Review Checklist
+
+When reviewing code, ensure:
+- [ ] Feature ID is referenced
+- [ ] Task requirements are met
+- [ ] Appropriate persona patterns are used
+- [ ] AIWF conventions are followed
+- [ ] Documentation is complete
+- [ ] Tests cover acceptance criteria
+- [ ] Security considerations are addressed
+- [ ] Performance impact is acceptable
+
+## Quick Commands
+
+Include these in comments for quick actions:
+```javascript
+// @aiwf-check-feature - Verify feature exists in ledger
+// @aiwf-update-task - Update task progress
+// @aiwf-switch-persona - Change active persona
+// @aiwf-link-sprint - Link to current sprint
+```
+
+## AI Behavior Modifiers
+
+### Context-Aware Suggestions
+- Prioritize AIWF patterns
+- Include feature/task references
+- Apply persona-specific styles
+- Maintain project consistency
+
+### Auto-Complete Preferences
+1. AIWF-specific imports first
+2. Feature-based function names
+3. Task-aligned variable names
+4. Persona-appropriate patterns
+
+## Integration Points
+
+### Feature Ledger
+```javascript
+// Always validate against Feature Ledger
+const ledger = new FeatureLedger();
+const feature = await ledger.getFeature('FL001');
+
+if (feature.status !== 'active') {
+  throw new FeatureError('Feature not active', {
+    featureId: 'FL001',
+    status: feature.status
+  });
+}
+```
+
+### Task Management
+```javascript
+// Update task progress
+const taskManager = new TaskManager();
+await taskManager.updateProgress('TX01_S01', {
+  percentage: 75,
+  notes: 'Authentication implemented, testing remaining'
+});
+```
+
+### Sprint Tracking
+```javascript
+// Get current sprint context
+const sprint = await aiwf.getCurrentSprint();
+console.log(`Working on: ${sprint.name} (${sprint.id})`);
+```
+
+## Performance Considerations
+
+### Feature-Specific Optimization
+```javascript
+// Include performance metrics per feature
+/**
+ * @feature FL001
+ * @performance Target: <100ms response time
+ * @performance Current: 85ms average
+ */
+```
+
+### Caching Strategy
+```javascript
+// Feature-aware caching
+const cacheKey = `feature:${featureId}:${userId}`;
+const cached = await cache.get(cacheKey);
+```
+
+## Security Patterns
+
+### Feature-Level Security
+```javascript
+// Apply security based on feature requirements
+@FeatureSecurity('FL001', ['auth:read', 'auth:write'])
+class AuthenticationEndpoint {
+  // Implementation
+}
+```
+
+### Audit Logging
+```javascript
+// Include feature context in audit logs
+auditLogger.log({
+  action: 'user.login',
+  feature: 'FL001',
+  task: 'TX01_S01',
+  user: userId,
+  timestamp: new Date(),
+  result: 'success'
+});
+```
+
+---
+
+*Cursor AI Rules for AIWF Integration v1.0.0*
+*These rules ensure Cursor provides AIWF-aware code suggestions and maintains project consistency*