proagents 1.0.0

package/proagents/getting-started/mcp-setup.md

@@ -0,0 +1,239 @@
+# Getting Started with MCP Integration
+
+Step-by-step guide to setting up Model Context Protocol (MCP) for ProAgents.
+
+---
+
+## What is MCP?
+
+Model Context Protocol (MCP) allows AI assistants like Claude to access external tools and data sources. With MCP, ProAgents can:
+
+- Execute workflow commands natively
+- Access project context automatically
+- Integrate with your development tools
+- Provide real-time project information
+
+---
+
+## Prerequisites
+
+- Claude Desktop app (or compatible MCP client)
+- Node.js 18+ installed
+- ProAgents initialized in your project
+
+---
+
+## Step 1: Install MCP Server
+
+### Option A: Global Installation
+
+```bash
+npm install -g @proagents/mcp-server
+```
+
+### Option B: Project Installation
+
+```bash
+npm install --save-dev @proagents/mcp-server
+```
+
+### Option C: Use npx (No Installation)
+
+```bash
+npx @proagents/mcp-server
+```
+
+---
+
+## Step 2: Configure Claude Desktop
+
+Edit your Claude Desktop configuration:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "proagents": {
+      "command": "npx",
+      "args": ["@proagents/mcp-server"],
+      "env": {
+        "PROAGENTS_PROJECT_PATH": "/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Step 3: Verify Installation
+
+1. Restart Claude Desktop
+2. Start a new conversation
+3. Ask Claude: "What ProAgents tools are available?"
+
+You should see a list of available tools like:
+- `proagents_init`
+- `proagents_analyze`
+- `proagents_feature_start`
+- etc.
+
+---
+
+## Step 4: Configure Project Settings
+
+In your project's `proagents.config.yaml`:
+
+```yaml
+mcp:
+  enabled: true
+
+  # Tools to expose
+  tools:
+    - init
+    - analyze
+    - feature_start
+    - fix
+    - test
+    - deploy
+
+  # Context to provide
+  context:
+    project_info: true
+    git_status: true
+    active_features: true
+    recent_changes: true
+
+  # Security settings
+  security:
+    allow_file_write: true
+    allow_git_operations: true
+    require_confirmation:
+      - deploy
+      - rollback
+```
+
+---
+
+## Step 5: Test MCP Integration
+
+Try these commands in Claude:
+
+```
+"Initialize ProAgents in my project"
+→ Claude uses proagents_init tool
+
+"Analyze the codebase"
+→ Claude uses proagents_analyze tool
+
+"Start working on user authentication"
+→ Claude uses proagents_feature_start tool
+```
+
+---
+
+## Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `proagents_init` | Initialize ProAgents in a project |
+| `proagents_analyze` | Analyze codebase |
+| `proagents_feature_start` | Start a new feature |
+| `proagents_fix` | Start bug fix mode |
+| `proagents_test` | Run tests |
+| `proagents_review` | Code review |
+| `proagents_deploy` | Deployment preparation |
+| `proagents_status` | Get current status |
+
+---
+
+## Context Providers
+
+MCP provides these context resources:
+
+| Resource | URI | Description |
+|----------|-----|-------------|
+| Project Info | `proagents://project` | Project configuration |
+| Analysis | `proagents://analysis` | Codebase analysis results |
+| Features | `proagents://features` | Active features list |
+| Status | `proagents://status` | Current workflow status |
+
+---
+
+## Troubleshooting
+
+### MCP Server Not Found
+
+```bash
+# Verify installation
+which proagents-mcp-server
+
+# Or use npx
+npx @proagents/mcp-server --version
+```
+
+### Connection Issues
+
+1. Check Claude Desktop logs
+2. Verify config.json syntax
+3. Restart Claude Desktop
+
+### Permission Errors
+
+```yaml
+# In proagents.config.yaml
+mcp:
+  security:
+    allow_file_write: true
+```
+
+---
+
+## Advanced Configuration
+
+### Multiple Projects
+
+```json
+{
+  "mcpServers": {
+    "proagents-frontend": {
+      "command": "npx",
+      "args": ["@proagents/mcp-server"],
+      "env": {
+        "PROAGENTS_PROJECT_PATH": "/path/to/frontend"
+      }
+    },
+    "proagents-backend": {
+      "command": "npx",
+      "args": ["@proagents/mcp-server"],
+      "env": {
+        "PROAGENTS_PROJECT_PATH": "/path/to/backend"
+      }
+    }
+  }
+}
+```
+
+### Custom Tool Configuration
+
+```yaml
+mcp:
+  custom_tools:
+    - name: "run_migrations"
+      description: "Run database migrations"
+      command: "npm run migrate"
+
+    - name: "seed_database"
+      description: "Seed the database"
+      command: "npm run seed"
+```
+
+---
+
+## Next Steps
+
+- [Configure PM Integration](./pm-integration.md)
+- [Set up AI Training](./ai-training-setup.md)
+- [Review MCP Tools Reference](../mcp/tools-definition.md)

package/proagents/getting-started/pm-integration.md

@@ -0,0 +1,336 @@
+# Getting Started with PM Tool Integration
+
+Connect ProAgents to your project management tools for seamless workflow tracking.
+
+---
+
+## Supported Tools
+
+| Tool | Features |
+|------|----------|
+| **Jira** | Issues, sprints, status sync |
+| **Linear** | Issues, cycles, bi-directional sync |
+| **Trello** | Cards, boards, labels |
+| **GitHub Issues** | Full integration with PRs |
+| **GitLab Issues** | Full integration with MRs |
+| **Asana** | Tasks, projects, sections |
+| **Notion** | Database sync, documentation |
+
+---
+
+## Quick Setup
+
+### Step 1: Choose Your Tool
+
+```bash
+/pm setup
+```
+
+Select from the interactive menu, or specify directly:
+
+```bash
+/pm setup jira
+/pm setup linear
+/pm setup github
+```
+
+### Step 2: Authenticate
+
+#### Jira
+
+```yaml
+# proagents.config.yaml
+integrations:
+  jira:
+    enabled: true
+    base_url: "https://your-company.atlassian.net"
+    email: "${JIRA_EMAIL}"
+    api_token: "${JIRA_API_TOKEN}"
+    project_key: "PROJ"
+```
+
+Get your API token: https://id.atlassian.com/manage-profile/security/api-tokens
+
+#### Linear
+
+```yaml
+integrations:
+  linear:
+    enabled: true
+    api_key: "${LINEAR_API_KEY}"
+    team_id: "TEAM-123"
+```
+
+Get your API key: Linear Settings → API → Personal API Keys
+
+#### GitHub Issues
+
+```yaml
+integrations:
+  github:
+    enabled: true
+    token: "${GITHUB_TOKEN}"
+    owner: "your-org"
+    repo: "your-repo"
+```
+
+### Step 3: Test Connection
+
+```bash
+/pm test
+```
+
+Expected output:
+```
+✓ Connected to Jira
+✓ Project PROJ found
+✓ Can create issues
+✓ Can read issues
+✓ Integration ready!
+```
+
+---
+
+## Basic Usage
+
+### Create Issue from Feature
+
+When you start a feature:
+```bash
+/feature-start "Add user authentication"
+```
+
+ProAgents automatically:
+1. Creates an issue in your PM tool
+2. Links it to the feature branch
+3. Updates status as you progress
+
+### Sync Status
+
+```bash
+/pm sync
+```
+
+Updates your PM tool with current feature status.
+
+### Link Existing Issue
+
+```bash
+/feature-start "Add auth" --issue PROJ-123
+```
+
+---
+
+## Configuration Options
+
+### Jira Configuration
+
+```yaml
+integrations:
+  jira:
+    enabled: true
+    base_url: "https://your-company.atlassian.net"
+    email: "${JIRA_EMAIL}"
+    api_token: "${JIRA_API_TOKEN}"
+    project_key: "PROJ"
+
+    # Auto-create issues
+    auto_create_issues: true
+
+    # Status mapping
+    status_mapping:
+      analysis: "To Do"
+      implementation: "In Progress"
+      review: "In Review"
+      testing: "Testing"
+      completed: "Done"
+
+    # Issue type mapping
+    issue_types:
+      feature: "Story"
+      bug: "Bug"
+      task: "Task"
+
+    # Fields to sync
+    sync_fields:
+      - summary
+      - description
+      - status
+      - assignee
+      - labels
+
+    # Transitions
+    transitions:
+      to_in_progress: "Start Progress"
+      to_review: "Request Review"
+      to_done: "Mark Complete"
+```
+
+### Linear Configuration
+
+```yaml
+integrations:
+  linear:
+    enabled: true
+    api_key: "${LINEAR_API_KEY}"
+    team_id: "TEAM-123"
+
+    # Bi-directional sync
+    bi_directional: true
+
+    # Status mapping
+    status_mapping:
+      analysis: "Backlog"
+      implementation: "In Progress"
+      review: "In Review"
+      completed: "Done"
+
+    # Labels
+    auto_labels:
+      - "proagents"
+
+    # Cycle assignment
+    assign_to_current_cycle: true
+```
+
+### GitHub Issues Configuration
+
+```yaml
+integrations:
+  github:
+    enabled: true
+    token: "${GITHUB_TOKEN}"
+    owner: "your-org"
+    repo: "your-repo"
+
+    # Auto-create issues
+    auto_create: true
+
+    # Labels
+    default_labels:
+      - "feature"
+      - "proagents"
+
+    # Link PRs
+    auto_link_pr: true
+
+    # Close on merge
+    close_on_merge: true
+
+    # Issue templates
+    templates:
+      feature: ".github/ISSUE_TEMPLATE/feature.md"
+      bug: ".github/ISSUE_TEMPLATE/bug.md"
+```
+
+---
+
+## Workflow Integration
+
+### Feature Lifecycle
+
+```
+┌─────────────────┐
+│ /feature-start  │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐     ┌─────────────────┐
+│ Create Issue    │────▶│ PM Tool         │
+│ (Jira/Linear)   │     │ Issue Created   │
+└────────┬────────┘     └─────────────────┘
+         │
+         ▼
+┌─────────────────┐     ┌─────────────────┐
+│ Implementation  │────▶│ Status: In      │
+│ Phase           │     │ Progress        │
+└────────┬────────┘     └─────────────────┘
+         │
+         ▼
+┌─────────────────┐     ┌─────────────────┐
+│ Create PR       │────▶│ PR Linked to    │
+│                 │     │ Issue           │
+└────────┬────────┘     └─────────────────┘
+         │
+         ▼
+┌─────────────────┐     ┌─────────────────┐
+│ Merge PR        │────▶│ Issue Closed    │
+│                 │     │                 │
+└─────────────────┘     └─────────────────┘
+```
+
+### Bug Fix Integration
+
+```bash
+/fix "Login button broken" --issue BUG-456
+```
+
+ProAgents:
+1. Links to existing bug
+2. Updates status to "In Progress"
+3. Creates branch from issue
+4. Updates issue on completion
+
+---
+
+## Commands
+
+```bash
+# Setup
+/pm setup [tool]           # Initialize PM integration
+
+# Status
+/pm status                  # Show integration status
+/pm test                    # Test connection
+
+# Sync
+/pm sync                    # Sync current feature
+/pm sync-all                # Sync all active features
+
+# Issues
+/pm create "Title"          # Create new issue
+/pm link ISSUE-123          # Link current feature to issue
+/pm unlink                  # Unlink current feature
+
+# Queries
+/pm issues                  # List assigned issues
+/pm search "query"          # Search issues
+```
+
+---
+
+## Troubleshooting
+
+### Authentication Failed
+
+```bash
+# Re-authenticate
+/pm auth
+
+# Test with debug output
+/pm test --debug
+```
+
+### Status Not Syncing
+
+1. Check status mapping in config
+2. Verify transition names match your workflow
+3. Check permissions on the PM tool
+
+### Rate Limiting
+
+```yaml
+integrations:
+  jira:
+    rate_limit:
+      requests_per_minute: 30
+      retry_on_limit: true
+```
+
+---
+
+## Next Steps
+
+- [Set up AI Training](./ai-training-setup.md)
+- [Configure IDE](./ide-setup.md)
+- [Review PM integration details](../integrations/pm/)