proagents 1.0.0

package/proagents/migrations/from-claude-projects.md

@@ -0,0 +1,312 @@
+# Migrating from Claude Projects
+
+Convert your Claude Project instructions to ProAgents configuration.
+
+---
+
+## Overview
+
+Claude Projects use custom instructions to guide AI behavior. ProAgents provides:
+
+- Structured configuration instead of free-form text
+- Workflow automation beyond just instructions
+- Cross-platform compatibility
+- Version control integration
+
+---
+
+## Automated Migration
+
+```bash
+# Export Claude Project instructions first (manual step)
+# Then migrate from the exported file
+
+proagents migrate --from claude-project --source ./claude-instructions.md
+```
+
+---
+
+## Manual Migration
+
+### Step 1: Export Claude Instructions
+
+From your Claude Project, copy:
+1. Project instructions
+2. Knowledge base documents
+3. Custom conversation starters
+
+### Step 2: Categorize Content
+
+Separate your instructions into:
+
+| Category | ProAgents Location |
+|----------|-------------------|
+| Project overview | `README.md` |
+| Coding standards | `standards/*.md` |
+| Architecture rules | `standards/architecture-rules.md` |
+| Workflow instructions | `prompts/*.md` |
+| Custom commands | `slash-commands.json` |
+| Reference docs | `docs/` |
+
+### Step 3: Convert Instructions to Standards
+
+**From Claude Project:**
+```
+## Project Overview
+This is a React application using TypeScript.
+
+## Coding Guidelines
+- Always use TypeScript
+- Use functional components
+- Follow existing patterns in the codebase
+- Add proper error handling
+- Write tests for new features
+
+## Patterns
+- State: Zustand
+- Styling: Tailwind CSS
+- Forms: React Hook Form
+- API: React Query
+```
+
+**To ProAgents:**
+
+**`proagents/README.md`:**
+```markdown
+# Project Name
+
+React TypeScript application.
+
+## Quick Start
+proagents init
+proagents feature start "Feature name"
+
+## Tech Stack
+- React 18
+- TypeScript
+- Tailwind CSS
+- Zustand
+```
+
+**`proagents/standards/coding-standards.md`:**
+```markdown
+# Coding Standards
+
+## TypeScript
+- Strict mode required
+- No any types
+- Explicit return types
+
+## React
+- Functional components only
+- Props interface required
+- Use memo for expensive renders
+```
+
+**`proagents/standards/architecture-patterns.md`:**
+```markdown
+# Architecture Patterns
+
+## State Management
+- **Global State**: Zustand stores in `/stores`
+- **Form State**: React Hook Form
+- **Server State**: React Query
+
+## Styling
+- Tailwind CSS utility classes
+- Custom components in `/components/ui`
+
+## Data Fetching
+- React Query for server state
+- Custom hooks in `/hooks/api`
+```
+
+### Step 4: Convert Workflow Instructions
+
+**From Claude Project:**
+```
+## When building new features:
+1. First understand what exists
+2. Plan the implementation
+3. Write the code
+4. Add tests
+5. Update documentation
+```
+
+**To ProAgents Prompts:**
+
+**`proagents/prompts/05-implementation.md`:**
+```markdown
+# Implementation Phase
+
+## Before Coding
+1. Review existing codebase patterns
+2. Check for similar implementations
+3. Understand data flow
+
+## During Implementation
+1. Follow project patterns
+2. Add TypeScript types
+3. Handle errors properly
+4. Keep functions focused
+
+## After Coding
+1. Self-review the code
+2. Write unit tests
+3. Update documentation
+```
+
+### Step 5: Convert Knowledge Base
+
+Move Claude Project documents to ProAgents:
+
+```
+proagents/
+├── docs/
+│   ├── api-reference.md
+│   ├── database-schema.md
+│   └── deployment.md
+```
+
+### Step 6: Create Configuration
+
+**`proagents/proagents.config.yaml`:**
+```yaml
+project:
+  name: "My React App"
+  type: "web-frontend"
+
+standards:
+  path: "./proagents/standards"
+
+checkpoints:
+  after_analysis: true
+  after_design: false
+  before_deployment: true
+
+learning:
+  enabled: true
+  track_patterns: true
+```
+
+---
+
+## Feature Comparison
+
+| Feature | Claude Projects | ProAgents |
+|---------|-----------------|-----------|
+| Instructions | Free-form text | Structured YAML/Markdown |
+| Knowledge Base | File uploads | Version-controlled docs |
+| Workflow | Manual prompting | Automated phases |
+| IDE Integration | Copy/paste | Native integration |
+| Collaboration | Per-user projects | Shared repository config |
+| Versioning | None | Git-tracked |
+| Offline | No | Yes |
+
+---
+
+## Mapping Reference
+
+### Instruction Sections
+
+| Claude Section | ProAgents File |
+|----------------|----------------|
+| Project Overview | `README.md` |
+| How to Respond | `proagents.config.yaml` (communication settings) |
+| Coding Style | `standards/coding-standards.md` |
+| Architecture | `standards/architecture-patterns.md` |
+| Testing | `standards/testing-standards.md` |
+| Error Handling | `patterns/error-types.md` |
+
+### Conversation Starters
+
+**From Claude:**
+```
+- Help me build a new feature
+- Review this code
+- Debug this issue
+- Write tests for this
+```
+
+**To ProAgents Slash Commands:**
+
+**`proagents/slash-commands.json`:**
+```json
+{
+  "commands": [
+    {
+      "name": "/feature",
+      "description": "Start new feature development",
+      "prompt": "Start a new feature workflow"
+    },
+    {
+      "name": "/review",
+      "description": "Code review assistance",
+      "prompt": "Review the current code changes"
+    },
+    {
+      "name": "/debug",
+      "description": "Debug an issue",
+      "prompt": "Help debug the following issue"
+    },
+    {
+      "name": "/test",
+      "description": "Generate tests",
+      "prompt": "Generate tests for the current code"
+    }
+  ]
+}
+```
+
+---
+
+## Using Claude with ProAgents
+
+You can still use Claude AI while benefiting from ProAgents:
+
+### Option 1: MCP Integration
+
+```json
+// Claude Desktop config
+{
+  "mcpServers": {
+    "proagents": {
+      "command": "npx",
+      "args": ["-y", "@proagents/mcp-server"]
+    }
+  }
+}
+```
+
+### Option 2: Import Standards
+
+Copy ProAgents standards into Claude Project instructions:
+
+```bash
+# Generate Claude-compatible instructions
+proagents export --format claude-project > claude-instructions.md
+```
+
+---
+
+## Migration Checklist
+
+- [ ] Export Claude Project instructions
+- [ ] Create ProAgents structure
+- [ ] Migrate coding standards
+- [ ] Migrate architecture patterns
+- [ ] Set up workflow prompts
+- [ ] Configure slash commands
+- [ ] Test with a small feature
+- [ ] Set up MCP integration (optional)
+
+---
+
+## Benefits of Migration
+
+1. **Version Control**: Track changes to instructions over time
+2. **Team Sharing**: Single source of truth for the team
+3. **IDE Integration**: Works with Cursor, VS Code, JetBrains
+4. **Workflow Automation**: More than just instructions
+5. **Validation**: Automated enforcement of standards
+6. **Offline Access**: Works without internet

package/proagents/migrations/from-cursor-rules.md

@@ -0,0 +1,345 @@
+# Migrating from Cursor Rules
+
+Convert your `.cursorrules` file to ProAgents configuration.
+
+---
+
+## Overview
+
+Cursor uses a `.cursorrules` file for AI instructions. ProAgents provides a more structured approach with:
+
+- Separate standards, rules, and prompts
+- Version-controlled configuration
+- Cross-IDE compatibility
+- Workflow integration
+
+---
+
+## Automated Migration
+
+```bash
+# Detect and migrate Cursor rules
+proagents migrate --from cursor-rules
+
+# Preview changes
+proagents migrate --from cursor-rules --dry-run
+
+# Specify custom source path
+proagents migrate --from cursor-rules --source ./.cursorrules
+```
+
+---
+
+## Manual Migration
+
+### Step 1: Analyze Existing Rules
+
+Review your `.cursorrules` content and identify:
+
+1. **Coding Standards** - Style, naming, formatting rules
+2. **Project Patterns** - Architecture, state management, etc.
+3. **Instructions** - How AI should behave
+4. **Custom Commands** - Slash commands or workflows
+
+### Step 2: Create Standards Files
+
+**From Cursor:**
+```markdown
+## Code Style
+- Use TypeScript strict mode
+- Prefer functional components
+- Use named exports
+```
+
+**To ProAgents (`proagents/standards/coding-standards.md`):**
+```markdown
+# Coding Standards
+
+## TypeScript
+- Use strict mode (`"strict": true` in tsconfig.json)
+- No implicit any
+- Explicit return types for public functions
+
+## React
+- Functional components only
+- Named exports for components
+- Props interface above component
+```
+
+### Step 3: Create Rules Files
+
+**From Cursor:**
+```markdown
+## Naming
+- Components: PascalCase
+- Hooks: useXxx
+- Constants: UPPER_SNAKE
+```
+
+**To ProAgents (`proagents/rules/naming-rules.yaml`):**
+```yaml
+rules:
+  - id: component-naming
+    type: naming
+    pattern: "^[A-Z][a-zA-Z]+$"
+    applies_to: "components/**/*.tsx"
+    message: "Components must use PascalCase"
+    severity: error
+
+  - id: hook-naming
+    type: naming
+    pattern: "^use[A-Z]"
+    applies_to: "hooks/**/*.ts"
+    message: "Hooks must start with 'use'"
+    severity: error
+
+  - id: constant-naming
+    type: naming
+    pattern: "^[A-Z][A-Z0-9_]+$"
+    applies_to: "constants/**/*.ts"
+    message: "Constants must use UPPER_SNAKE_CASE"
+    severity: warning
+```
+
+### Step 4: Update Prompts
+
+**From Cursor:**
+```markdown
+## Instructions
+When writing code:
+1. Check existing patterns first
+2. Follow naming conventions
+3. Add proper error handling
+```
+
+**To ProAgents (`proagents/prompts/05-implementation.md`):**
+```markdown
+# Implementation Phase
+
+## Pre-Implementation Checklist
+- [ ] Review existing patterns in codebase
+- [ ] Verify naming conventions
+- [ ] Plan error handling approach
+
+## Implementation Guidelines
+1. **Check Existing Patterns**
+   - Search for similar implementations
+   - Follow established patterns
+   - Match code style
+
+2. **Apply Naming Conventions**
+   - Components: PascalCase
+   - Hooks: useXxx prefix
+   - Constants: UPPER_SNAKE_CASE
+
+3. **Error Handling**
+   - Use try-catch for async operations
+   - Provide meaningful error messages
+   - Log errors with context
+```
+
+### Step 5: Configure ProAgents
+
+Create `proagents/proagents.config.yaml`:
+
+```yaml
+project:
+  name: "My Project"
+  type: "fullstack"
+
+standards:
+  path: "./proagents/standards"
+  enforce: true
+
+rules:
+  path: "./proagents/rules"
+  severity_threshold: "warning"
+
+# Generate IDE rules for Cursor compatibility
+ide:
+  cursor:
+    enabled: true
+    auto_generate: true
+    include:
+      - standards
+      - rules
+      - patterns
+```
+
+### Step 6: Generate Cursor-Compatible Rules
+
+ProAgents can generate `.cursorrules` from your configuration:
+
+```bash
+# Generate .cursorrules from ProAgents config
+proagents ide generate cursor
+
+# Keep both in sync
+proagents ide sync cursor
+```
+
+---
+
+## Mapping Reference
+
+| Cursor Section | ProAgents Location |
+|----------------|-------------------|
+| Code Style | `standards/coding-standards.md` |
+| Naming Conventions | `rules/naming-rules.yaml` |
+| Project Structure | `standards/architecture-rules.md` |
+| Testing Guidelines | `standards/testing-standards.md` |
+| Instructions | `prompts/*.md` |
+| Custom Commands | `slash-commands.json` |
+
+---
+
+## Side-by-Side Comparison
+
+### Before (Cursor)
+
+```markdown
+# .cursorrules
+
+You are an AI assistant helping with a Next.js project.
+
+## Code Style
+- TypeScript strict mode
+- Functional components
+- Tailwind CSS
+
+## Patterns
+- Use Zustand for state
+- React Query for data fetching
+- Zod for validation
+
+## Rules
+- No console.log in production
+- Always handle errors
+- Write tests for new code
+
+## When coding
+1. Check existing patterns
+2. Follow conventions
+3. Add tests
+```
+
+### After (ProAgents)
+
+**`proagents/standards/coding-standards.md`:**
+```markdown
+# Coding Standards
+
+## TypeScript
+- Strict mode enabled
+- No implicit any
+
+## React
+- Functional components only
+- Use Tailwind CSS for styling
+```
+
+**`proagents/standards/architecture-patterns.md`:**
+```markdown
+# Architecture Patterns
+
+## State Management
+- Zustand for global state
+- React hooks for local state
+
+## Data Fetching
+- React Query for server state
+- Axios for HTTP client
+
+## Validation
+- Zod for runtime validation
+- TypeScript for compile-time
+```
+
+**`proagents/rules/quality-rules.yaml`:**
+```yaml
+rules:
+  - id: no-console-log
+    pattern: "console\\.log"
+    severity: error
+    message: "Remove console.log before committing"
+
+  - id: require-error-handling
+    type: pattern
+    condition: "async function"
+    requires: "try-catch"
+    severity: warning
+```
+
+**`proagents/proagents.config.yaml`:**
+```yaml
+project:
+  name: "My Next.js Project"
+  type: "fullstack"
+
+testing:
+  require_for_new_code: true
+  coverage_threshold: 80
+```
+
+---
+
+## Benefits of Migration
+
+| Aspect | Cursor Rules | ProAgents |
+|--------|--------------|-----------|
+| Structure | Single file | Organized directories |
+| Versioning | Manual | Automatic tracking |
+| IDE Support | Cursor only | Multiple IDEs |
+| Workflow | Instructions only | Full development workflow |
+| Enforcement | AI honor system | Automated validation |
+| Collaboration | Copy/paste | Shared configuration |
+
+---
+
+## Keeping Both Systems
+
+You can use ProAgents while keeping Cursor rules:
+
+```yaml
+# proagents.config.yaml
+ide:
+  cursor:
+    enabled: true
+    auto_generate: true
+    sync_on_change: true
+```
+
+This automatically updates `.cursorrules` when ProAgents config changes.
+
+---
+
+## Troubleshooting
+
+### Migration Warnings
+
+```bash
+# View migration warnings
+proagents migrate --from cursor-rules --verbose
+```
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Rules not enforced | Enable `enforce: true` in config |
+| IDE not updating | Run `proagents ide sync cursor` |
+| Missing patterns | Run `proagents analyze` first |
+
+---
+
+## Rollback
+
+If you need to revert:
+
+```bash
+# Restore original .cursorrules
+git checkout .cursorrules
+
+# Remove ProAgents config
+rm -rf ./proagents
+```