proagents 1.0.0

package/proagents/ide-integration/github-copilot.md

@@ -0,0 +1,384 @@
+# GitHub Copilot Configuration
+
+Configure GitHub Copilot to work with ProAgents workflow.
+
+---
+
+## Overview
+
+GitHub Copilot uses instructions files and workspace settings to customize AI behavior.
+
+---
+
+## Quick Setup
+
+```bash
+# Generate Copilot instructions
+proagents ide generate copilot
+
+# Creates .github/copilot-instructions.md
+```
+
+---
+
+## Instructions File
+
+Create `.github/copilot-instructions.md`:
+
+```markdown
+# GitHub Copilot Instructions
+
+## Project Overview
+
+This project uses the ProAgents development workflow. Follow these guidelines when providing suggestions and completions.
+
+## Code Style
+
+### TypeScript
+- Use strict TypeScript with no implicit any
+- Prefer interfaces over types for objects
+- Use const assertions for literals
+- Always provide return types for functions
+
+### Naming
+- Components: PascalCase (UserProfile)
+- Functions: camelCase (getUserData)
+- Constants: UPPER_SNAKE_CASE (MAX_RETRIES)
+- Files: Match export name
+
+### Imports
+```typescript
+// Order: React → External → Internal → Types → Styles
+import React from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { Button } from '@/components/ui';
+import type { User } from '@/types';
+import styles from './Component.module.css';
+```
+
+## Patterns to Follow
+
+### React Components
+```typescript
+interface Props {
+  title: string;
+  onAction?: () => void;
+}
+
+export function Component({ title, onAction }: Props) {
+  return (
+    <div className="container">
+      <h1>{title}</h1>
+      {onAction && <button onClick={onAction}>Action</button>}
+    </div>
+  );
+}
+```
+
+### Custom Hooks
+```typescript
+export function useData<T>(key: string) {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Implementation...
+
+  return { data, loading, error };
+}
+```
+
+### API Calls
+```typescript
+async function fetchUser(id: string): Promise<User> {
+  const response = await api.get(`/users/${id}`);
+  if (!response.ok) {
+    throw new ApiError('Failed to fetch user', response.status);
+  }
+  return response.data;
+}
+```
+
+## Error Handling
+
+Always include error handling:
+```typescript
+try {
+  const result = await riskyOperation();
+  return result;
+} catch (error) {
+  logger.error('Operation failed', { error, context });
+  throw new OperationError('Failed to complete operation', { cause: error });
+}
+```
+
+## Testing
+
+Generate tests that:
+- Cover happy path and edge cases
+- Use descriptive test names
+- Follow AAA pattern (Arrange, Act, Assert)
+- Mock external dependencies
+
+```typescript
+describe('UserService', () => {
+  describe('getUser', () => {
+    it('should return user when found', async () => {
+      // Arrange
+      const mockUser = createMockUser();
+      mockRepo.findById.mockResolvedValue(mockUser);
+
+      // Act
+      const result = await service.getUser('123');
+
+      // Assert
+      expect(result).toEqual(mockUser);
+    });
+  });
+});
+```
+
+## Documentation
+
+Include JSDoc for public APIs:
+```typescript
+/**
+ * Fetches user data by ID
+ * @param id - The user's unique identifier
+ * @returns The user object or null if not found
+ * @throws {ApiError} When the API request fails
+ */
+async function getUser(id: string): Promise<User | null> {
+  // Implementation
+}
+```
+
+## Security
+
+- Never hardcode secrets or credentials
+- Validate and sanitize all inputs
+- Use parameterized queries
+- Escape user content in HTML
+
+## Accessibility
+
+Include accessibility attributes:
+```typescript
+<button
+  aria-label="Close dialog"
+  aria-pressed={isPressed}
+  onClick={handleClick}
+>
+  <CloseIcon aria-hidden="true" />
+</button>
+```
+
+## Performance
+
+- Use React.memo for expensive components
+- Implement proper dependency arrays
+- Avoid inline object/function creation in renders
+- Use proper loading states
+```
+
+---
+
+## VS Code Settings
+
+Configure Copilot behavior in `.vscode/settings.json`:
+
+```json
+{
+  "github.copilot.enable": {
+    "*": true,
+    "markdown": true,
+    "yaml": true
+  },
+
+  "github.copilot.advanced": {
+    "inlineSuggestCount": 3,
+    "listCount": 10
+  },
+
+  "editor.inlineSuggest.enabled": true,
+
+  "github.copilot.chat.localeOverride": "en",
+
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true
+  },
+
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true
+  }
+}
+```
+
+---
+
+## Copilot Chat Custom Instructions
+
+For Copilot Chat, create `.github/copilot-chat-instructions.md`:
+
+```markdown
+# Copilot Chat Instructions
+
+## Role
+You are a senior developer helping with the ProAgents workflow.
+
+## Response Style
+- Be concise but thorough
+- Show code examples when helpful
+- Explain trade-offs of different approaches
+- Reference existing project patterns
+
+## Slash Commands
+
+Respond to these custom commands:
+
+### /proagents-feature
+Start a new feature workflow:
+1. Ask about the feature requirements
+2. Analyze affected areas
+3. Propose implementation plan
+4. Guide through implementation
+
+### /proagents-fix
+Quick bug fix workflow:
+1. Help identify the bug
+2. Suggest fix approach
+3. Generate fix code
+4. Suggest test cases
+
+### /proagents-review
+Code review assistance:
+1. Check for common issues
+2. Verify patterns are followed
+3. Suggest improvements
+4. Check test coverage
+
+## When Answering
+
+1. First check existing codebase for patterns
+2. Follow established conventions
+3. Consider edge cases
+4. Include error handling
+5. Suggest tests when relevant
+```
+
+---
+
+## Workspace Configuration
+
+For multi-root workspaces, create `.code-workspace`:
+
+```json
+{
+  "folders": [
+    { "path": "packages/web" },
+    { "path": "packages/api" },
+    { "path": "packages/shared" }
+  ],
+  "settings": {
+    "github.copilot.enable": {
+      "*": true
+    }
+  }
+}
+```
+
+---
+
+## Context Files
+
+Create context files that Copilot can reference:
+
+### `.github/copilot-context/architecture.md`
+```markdown
+# Architecture Overview
+
+## Stack
+- Frontend: Next.js 14, React 18, TypeScript
+- Backend: Node.js, Express, PostgreSQL
+- Styling: Tailwind CSS
+- State: Zustand + React Query
+
+## Key Patterns
+- Feature-based folder structure
+- Repository pattern for data access
+- Custom hooks for business logic
+```
+
+### `.github/copilot-context/api-patterns.md`
+```markdown
+# API Patterns
+
+## Endpoint Structure
+- GET /api/resource - List
+- GET /api/resource/:id - Get one
+- POST /api/resource - Create
+- PUT /api/resource/:id - Update
+- DELETE /api/resource/:id - Delete
+
+## Response Format
+{
+  "success": true,
+  "data": { ... },
+  "meta": { "page": 1, "total": 100 }
+}
+```
+
+---
+
+## ProAgents Integration
+
+```yaml
+# proagents.config.yaml
+ide:
+  copilot:
+    enabled: true
+
+    # Instructions location
+    instructions_path: ".github/copilot-instructions.md"
+    chat_instructions_path: ".github/copilot-chat-instructions.md"
+
+    # Context files to generate
+    context_files:
+      - architecture
+      - api-patterns
+      - component-patterns
+
+    # Include in instructions
+    include:
+      - code_standards
+      - naming_conventions
+      - patterns
+      - testing_guidelines
+```
+
+---
+
+## Syncing Instructions
+
+```bash
+# Generate instructions from ProAgents config
+proagents ide generate copilot
+
+# Include detected patterns
+proagents ide generate copilot --include-patterns
+
+# Update after config changes
+proagents ide sync copilot
+```
+
+---
+
+## Best Practices
+
+1. **Keep Instructions Focused**: Don't overload with too many rules
+2. **Use Context Files**: Separate concerns into different files
+3. **Update Regularly**: Sync when project evolves
+4. **Version Control**: Commit all instruction files
+5. **Team Alignment**: Ensure team uses consistent instructions

package/proagents/ide-integration/windsurf-rules.md

@@ -0,0 +1,314 @@
+# Windsurf Rules Configuration
+
+Configure Windsurf IDE (Codeium) to work with ProAgents workflow.
+
+---
+
+## Overview
+
+Windsurf uses a `.windsurfrules` file in the project root to guide its Cascade AI assistant.
+
+---
+
+## Quick Setup
+
+```bash
+# Generate Windsurf rules from ProAgents config
+proagents ide generate windsurf
+
+# This creates .windsurfrules in your project root
+```
+
+---
+
+## Complete .windsurfrules Template
+
+Create `.windsurfrules` in your project root:
+
+```markdown
+# ProAgents Development Workflow for Windsurf
+
+You are Cascade, integrated with the ProAgents development workflow. Follow these guidelines for all development tasks.
+
+## Workflow Recognition
+
+Recognize and respond to these workflow commands:
+
+| Command | Action |
+|---------|--------|
+| `/init` | Initialize ProAgents workflow |
+| `/feature <name>` | Start new feature development |
+| `/fix <desc>` | Quick bug fix workflow |
+| `/doc` | Generate documentation |
+| `/test` | Run test suite |
+| `/qa` | Quality checks |
+| `/deploy` | Deployment preparation |
+
+## Cascade Flow Integration
+
+When using Cascade Flows:
+
+### Feature Flow
+1. Analyze existing codebase
+2. Gather requirements
+3. Design solution
+4. Plan implementation
+5. Generate code
+6. Create tests
+7. Review output
+
+### Fix Flow
+1. Identify bug location
+2. Analyze root cause
+3. Implement fix
+4. Verify with tests
+5. Document change
+
+## Code Generation Rules
+
+### Always
+- Follow existing project patterns
+- Use TypeScript with strict mode
+- Add proper type annotations
+- Include error handling
+- Write accompanying tests
+
+### Never
+- Skip type definitions
+- Ignore existing conventions
+- Create duplicate utilities
+- Leave TODO comments without context
+
+## Project Structure
+
+```
+src/
+├── components/     # React components
+├── hooks/          # Custom hooks
+├── services/       # Business logic
+├── utils/          # Utilities
+├── types/          # TypeScript types
+└── __tests__/      # Test files
+```
+
+## Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Components | PascalCase | `UserProfile.tsx` |
+| Hooks | camelCase with use | `useAuth.ts` |
+| Utils | kebab-case | `string-helpers.ts` |
+| Types | PascalCase | `UserTypes.ts` |
+| Constants | UPPER_SNAKE | `API_ENDPOINTS.ts` |
+
+## Code Patterns
+
+### Component Pattern
+```typescript
+interface ComponentProps {
+  // Props definition
+}
+
+export function Component({ prop }: ComponentProps) {
+  // Implementation
+}
+```
+
+### Hook Pattern
+```typescript
+export function useCustomHook(param: Type) {
+  // Hook logic
+  return { data, loading, error };
+}
+```
+
+### Service Pattern
+```typescript
+class ServiceName {
+  async method(input: Input): Promise<Output> {
+    // Implementation
+  }
+}
+```
+
+## Quality Standards
+
+### Before Completion
+- [ ] TypeScript compiles without errors
+- [ ] ESLint passes
+- [ ] Tests written and passing
+- [ ] Error states handled
+- [ ] Loading states handled
+- [ ] Accessibility considered
+
+### Performance
+- Avoid unnecessary re-renders
+- Use proper memoization
+- Lazy load when appropriate
+- Optimize images and assets
+
+## Communication Style
+
+When interacting:
+1. Explain approach before implementing
+2. Show relevant existing code for context
+3. Highlight any breaking changes
+4. Suggest improvements when appropriate
+5. Ask for clarification when needed
+
+## Multi-File Changes
+
+When changes span multiple files:
+1. List all affected files first
+2. Explain the relationship between changes
+3. Implement in dependency order
+4. Provide a summary of all changes
+
+## Context Awareness
+
+Always consider:
+- Current file location in project
+- Related files and dependencies
+- Recent changes in conversation
+- Project-wide patterns and conventions
+```
+
+---
+
+## Windsurf-Specific Features
+
+### Cascade Flows
+
+Configure custom flows in `.windsurfrules`:
+
+```markdown
+## Custom Flows
+
+### /refactor Flow
+1. Analyze current implementation
+2. Identify improvement opportunities
+3. Propose refactoring plan
+4. Implement changes incrementally
+5. Verify no regressions
+6. Update tests if needed
+
+### /optimize Flow
+1. Profile current performance
+2. Identify bottlenecks
+3. Propose optimizations
+4. Implement with benchmarks
+5. Verify improvements
+```
+
+### Supercomplete Integration
+
+```markdown
+## Supercomplete Settings
+
+When providing completions:
+- Consider full file context
+- Match existing code style
+- Include type annotations
+- Add JSDoc for public APIs
+```
+
+---
+
+## Dynamic Configuration
+
+```yaml
+# proagents.config.yaml
+ide:
+  windsurf:
+    enabled: true
+
+    # Flow configurations
+    flows:
+      feature:
+        phases: ["analyze", "design", "implement", "test"]
+        checkpoints: ["after_design"]
+
+      fix:
+        phases: ["identify", "fix", "verify"]
+        fast_track: true
+
+    # Cascade settings
+    cascade:
+      context_depth: "full"
+      include_tests: true
+      auto_format: true
+```
+
+---
+
+## Project Detection
+
+Windsurf rules can include project-type specific guidance:
+
+### React/Next.js
+```markdown
+## Framework: Next.js
+
+- Use App Router patterns
+- Prefer Server Components
+- Use 'use client' only when needed
+- Implement proper metadata
+- Use next/image for images
+```
+
+### Node.js/Express
+```markdown
+## Framework: Express
+
+- Use async route handlers
+- Implement proper middleware order
+- Validate all inputs
+- Use consistent error responses
+- Document with OpenAPI
+```
+
+---
+
+## Multi-Root Workspace
+
+For monorepos:
+
+```markdown
+## Monorepo Structure
+
+This is a monorepo with multiple packages:
+
+- `/packages/web` - Next.js frontend
+- `/packages/api` - Express backend
+- `/packages/shared` - Shared utilities
+
+When working in a package:
+- Use package-specific patterns
+- Import shared code from @shared/
+- Run tests in package context
+```
+
+---
+
+## Syncing Rules
+
+```bash
+# Sync with ProAgents config
+proagents ide sync windsurf
+
+# Include detected patterns
+proagents ide generate windsurf --include-patterns
+
+# Validate rules
+proagents ide validate windsurf
+```
+
+---
+
+## Best Practices
+
+1. **Keep Flows Focused**: Each flow should have a clear purpose
+2. **Context Matters**: Include project-specific context
+3. **Update Regularly**: Sync when patterns evolve
+4. **Test Flows**: Verify flows work as expected
+5. **Team Consistency**: Share rules across the team