proagents 1.0.0

package/proagents/migrations/from-custom-workflows.md

@@ -0,0 +1,410 @@
+# Migrating from Custom Workflows
+
+Integrate your existing development workflows with ProAgents.
+
+---
+
+## Overview
+
+If you have custom development workflows, scripts, or processes, ProAgents can:
+
+- Preserve your existing practices
+- Add structure and automation
+- Enhance with AI assistance
+- Provide consistency across projects
+
+---
+
+## Assessment
+
+### Step 1: Document Current Workflow
+
+Answer these questions:
+
+1. **How do features start?**
+   - Ticket/issue creation?
+   - Branch naming convention?
+   - Documentation requirements?
+
+2. **What's your development process?**
+   - Code review requirements?
+   - Testing expectations?
+   - Documentation standards?
+
+3. **How do you deploy?**
+   - CI/CD pipeline?
+   - Environment promotion?
+   - Rollback procedures?
+
+4. **What tools do you use?**
+   - Issue tracking (Jira, Linear)?
+   - Communication (Slack, Teams)?
+   - Monitoring (Datadog, Sentry)?
+
+### Step 2: Create Workflow Inventory
+
+```markdown
+# Current Workflow Inventory
+
+## Feature Development
+1. Create Jira ticket
+2. Create feature branch (feature/PROJ-123-description)
+3. Implement with PR
+4. Code review by 2 reviewers
+5. QA testing
+6. Merge to develop
+
+## Coding Standards
+- ESLint + Prettier
+- TypeScript strict mode
+- Jest for testing
+
+## Deployment
+- GitHub Actions CI
+- Auto-deploy to staging on merge to develop
+- Manual promotion to production
+
+## Communication
+- Slack for notifications
+- Daily standups
+```
+
+---
+
+## Migration Strategy
+
+### Option 1: Full Adoption
+
+Replace your workflow entirely with ProAgents.
+
+```yaml
+# proagents.config.yaml
+project:
+  name: "My Project"
+  type: "fullstack"
+
+# Full workflow enabled
+workflow:
+  phases:
+    - init
+    - analysis
+    - requirements
+    - design
+    - planning
+    - implementation
+    - testing
+    - review
+    - documentation
+    - deployment
+
+checkpoints:
+  after_analysis: true
+  after_design: true
+  before_deployment: true
+```
+
+### Option 2: Gradual Integration
+
+Keep existing tools, add ProAgents incrementally.
+
+```yaml
+# proagents.config.yaml
+workflow:
+  # Start with just a few phases
+  phases:
+    - analysis
+    - implementation
+    - testing
+
+  # Disable checkpoints initially
+  checkpoints:
+    all: false
+
+# Keep existing integrations
+integrations:
+  jira:
+    enabled: true
+    # ProAgents syncs with your Jira
+```
+
+### Option 3: AI Enhancement Only
+
+Use ProAgents just for AI assistance without workflow changes.
+
+```yaml
+# proagents.config.yaml
+workflow:
+  enabled: false  # No workflow management
+
+# Just use standards and AI prompts
+standards:
+  enabled: true
+
+prompts:
+  enabled: true
+```
+
+---
+
+## Mapping Your Workflow
+
+### Phase Mapping
+
+| Your Process | ProAgents Phase |
+|--------------|-----------------|
+| Requirements gathering | Phase 2: Requirements |
+| Technical design | Phase 3: UI Design + Phase 4: Planning |
+| Development | Phase 5: Implementation |
+| Testing | Phase 6: Testing |
+| Code review | Phase 6.5: Code Review |
+| Documentation | Phase 7: Documentation |
+| Deployment | Phase 8: Deployment |
+
+### Tool Integration
+
+```yaml
+# proagents.config.yaml
+integrations:
+  # Issue tracking
+  jira:
+    enabled: true
+    base_url: "${JIRA_URL}"
+    auto_create_tickets: false  # Use existing workflow
+    auto_update_status: true    # Sync status to ProAgents
+
+  # CI/CD
+  github:
+    enabled: true
+    auto_create_pr: false  # Manual PR creation
+    pr_template: "./proagents/templates/pr-template.md"
+
+  # Notifications
+  slack:
+    enabled: true
+    channel: "#dev-notifications"
+    events:
+      - feature_complete
+      - deployment_success
+```
+
+### Script Integration
+
+Wrap existing scripts in ProAgents hooks:
+
+```yaml
+# proagents.config.yaml
+hooks:
+  pre_implementation:
+    - script: "./scripts/setup-feature.sh"
+
+  post_testing:
+    - script: "./scripts/run-e2e.sh"
+
+  pre_deployment:
+    - script: "./scripts/build.sh"
+    - script: "./scripts/validate.sh"
+```
+
+---
+
+## Preserving Conventions
+
+### Git Conventions
+
+```yaml
+# proagents.config.yaml
+git:
+  # Keep your existing branch naming
+  branch_prefix: "feature/"
+  branch_format: "{prefix}{ticket}-{description}"
+
+  # Keep your commit convention
+  commit_convention: "conventional"  # or "custom"
+  commit_format: "{type}({scope}): {message}"
+
+  # PR settings
+  require_pr: true
+  pr_template: ".github/pull_request_template.md"  # Use existing
+```
+
+### Coding Standards
+
+Import existing ESLint/Prettier config:
+
+```yaml
+# proagents.config.yaml
+standards:
+  import_from:
+    eslint: "./.eslintrc.js"
+    prettier: "./.prettierrc"
+    typescript: "./tsconfig.json"
+
+  # Generate standards docs from these configs
+  auto_document: true
+```
+
+### Testing Standards
+
+```yaml
+# proagents.config.yaml
+testing:
+  # Use existing test setup
+  framework: "jest"
+  config_path: "./jest.config.js"
+
+  # Preserve your coverage requirements
+  coverage:
+    threshold: 80
+    include: ["src/**/*.ts"]
+    exclude: ["**/*.test.ts"]
+```
+
+---
+
+## Hybrid Workflow Example
+
+Keep existing processes while adding ProAgents AI assistance:
+
+```yaml
+# proagents.config.yaml
+project:
+  name: "Enterprise App"
+  type: "fullstack"
+
+# Minimal workflow - just tracking
+workflow:
+  phases:
+    - analysis      # AI helps understand code
+    - implementation # AI assists coding
+    - testing       # AI helps write tests
+
+  checkpoints:
+    all: false      # No blocking checkpoints
+
+# AI assistance settings
+ai:
+  assist_mode: true
+  auto_suggest: true
+  explain_changes: true
+
+# Keep your existing processes
+integrations:
+  # Continue using Jira as source of truth
+  jira:
+    enabled: true
+    sync_mode: "read"  # Read from Jira, don't write
+
+  # Keep GitHub Actions
+  github:
+    enabled: true
+    use_existing_workflows: true
+
+# Learning from your patterns
+learning:
+  enabled: true
+  learn_from_codebase: true
+  learn_from_prs: true
+```
+
+---
+
+## Migration Steps
+
+### Step 1: Install ProAgents
+
+```bash
+npm install -g proagents
+proagents init --minimal
+```
+
+### Step 2: Import Existing Config
+
+```bash
+# Import from ESLint, Prettier, etc.
+proagents import --from eslint .eslintrc.js
+proagents import --from prettier .prettierrc
+```
+
+### Step 3: Document Standards
+
+```bash
+# Auto-generate standards docs
+proagents analyze --generate-docs
+```
+
+### Step 4: Set Up Integration
+
+```bash
+# Configure integrations
+proagents config set integrations.jira.enabled true
+proagents config set integrations.slack.enabled true
+```
+
+### Step 5: Test Integration
+
+```bash
+# Start a test feature
+proagents feature start "Test integration" --dry-run
+```
+
+### Step 6: Gradual Rollout
+
+1. Start with one developer
+2. Expand to one team
+3. Roll out organization-wide
+
+---
+
+## Troubleshooting
+
+### Conflict with Existing Tools
+
+```yaml
+# Disable conflicting features
+proagents:
+  git:
+    auto_commit: false  # Don't auto-commit if CI does this
+  deployment:
+    enabled: false     # Use existing deployment
+```
+
+### Team Resistance
+
+Start with opt-in features:
+
+```yaml
+workflow:
+  mandatory: false
+  features:
+    - ai_assistance  # Most valuable, least disruptive
+```
+
+### Performance Issues
+
+```yaml
+# Optimize for large codebases
+analysis:
+  incremental: true
+  cache: true
+  exclude:
+    - "node_modules"
+    - "dist"
+    - ".git"
+```
+
+---
+
+## Success Metrics
+
+Track migration success:
+
+1. **Developer Productivity**: Time to complete features
+2. **Code Quality**: Bug rates, review feedback
+3. **Consistency**: Pattern adherence
+4. **Satisfaction**: Team feedback surveys
+
+```bash
+# View ProAgents metrics
+proagents report velocity
+proagents report quality
+```

package/proagents/monitoring/README.md

@@ -0,0 +1,308 @@
+# Monitoring Setup
+
+Application monitoring, alerting, and observability.
+
+---
+
+## Overview
+
+Comprehensive monitoring for application health, performance, and business metrics.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Health Checks](./health-checks.md) | Endpoint health monitoring |
+| [Metrics](./metrics.md) | Application metrics |
+| [Alerting](./alerting.md) | Alert configuration |
+| [Dashboards](./dashboards.md) | Visualization setup |
+
+---
+
+## Monitoring Stack
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Monitoring Stack                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Application                                                │
+│       │                                                     │
+│       ├──▶ Metrics ──▶ Prometheus/DataDog                  │
+│       │                      │                              │
+│       ├──▶ Logs ────▶ ELK/CloudWatch                       │
+│       │                      │                              │
+│       └──▶ Traces ──▶ Jaeger/X-Ray                         │
+│                              │                              │
+│                              ▼                              │
+│                       Dashboards                            │
+│                       Alerting                              │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Health Checks
+
+### Health Endpoint
+
+```typescript
+// src/routes/health.ts
+app.get('/health', async (req, res) => {
+  const health = {
+    status: 'healthy',
+    timestamp: new Date().toISOString(),
+    version: process.env.APP_VERSION,
+    checks: {
+      database: await checkDatabase(),
+      redis: await checkRedis(),
+      externalApi: await checkExternalApi(),
+    },
+  };
+
+  const isHealthy = Object.values(health.checks)
+    .every(check => check.status === 'healthy');
+
+  res.status(isHealthy ? 200 : 503).json(health);
+});
+
+async function checkDatabase() {
+  try {
+    await db.query('SELECT 1');
+    return { status: 'healthy', latency: '5ms' };
+  } catch (error) {
+    return { status: 'unhealthy', error: error.message };
+  }
+}
+```
+
+### Health Response
+
+```json
+{
+  "status": "healthy",
+  "timestamp": "2024-01-15T10:30:00Z",
+  "version": "1.2.3",
+  "checks": {
+    "database": { "status": "healthy", "latency": "5ms" },
+    "redis": { "status": "healthy", "latency": "2ms" },
+    "externalApi": { "status": "healthy", "latency": "150ms" }
+  }
+}
+```
+
+---
+
+## Metrics
+
+### Key Metrics
+
+| Category | Metrics |
+|----------|---------|
+| **Requests** | Rate, latency, error rate |
+| **Resources** | CPU, memory, disk, connections |
+| **Business** | Users, orders, revenue |
+| **Dependencies** | External API latency, availability |
+
+### Prometheus Metrics
+
+```typescript
+import { Counter, Histogram, Gauge } from 'prom-client';
+
+// Request counter
+const httpRequests = new Counter({
+  name: 'http_requests_total',
+  help: 'Total HTTP requests',
+  labelNames: ['method', 'path', 'status'],
+});
+
+// Response time histogram
+const httpDuration = new Histogram({
+  name: 'http_request_duration_seconds',
+  help: 'HTTP request duration',
+  labelNames: ['method', 'path'],
+  buckets: [0.1, 0.5, 1, 2, 5],
+});
+
+// Active connections gauge
+const activeConnections = new Gauge({
+  name: 'active_connections',
+  help: 'Active database connections',
+});
+
+// Middleware to track metrics
+app.use((req, res, next) => {
+  const end = httpDuration.startTimer({ method: req.method, path: req.path });
+
+  res.on('finish', () => {
+    httpRequests.inc({ method: req.method, path: req.path, status: res.statusCode });
+    end();
+  });
+
+  next();
+});
+```
+
+---
+
+## Alerting
+
+### Alert Configuration
+
+```yaml
+# proagents.config.yaml
+monitoring:
+  alerts:
+    # High error rate
+    - name: "high_error_rate"
+      condition: "error_rate > 5%"
+      duration: "5m"
+      severity: "critical"
+      channels: ["pagerduty", "slack:#alerts"]
+
+    # High latency
+    - name: "high_latency"
+      condition: "p99_latency > 3s"
+      duration: "10m"
+      severity: "warning"
+      channels: ["slack:#alerts"]
+
+    # Service down
+    - name: "service_down"
+      condition: "health_check_failed"
+      duration: "1m"
+      severity: "critical"
+      channels: ["pagerduty", "slack:#incidents"]
+
+    # Low disk space
+    - name: "low_disk"
+      condition: "disk_usage > 85%"
+      duration: "15m"
+      severity: "warning"
+      channels: ["slack:#ops"]
+```
+
+### Alert Channels
+
+```yaml
+monitoring:
+  channels:
+    slack:
+      webhook_url_env: "SLACK_WEBHOOK_URL"
+
+    pagerduty:
+      api_key_env: "PAGERDUTY_API_KEY"
+      service_id: "P123ABC"
+
+    email:
+      smtp_host: "smtp.example.com"
+      recipients:
+        - "oncall@example.com"
+```
+
+---
+
+## Dashboards
+
+### Key Dashboard Panels
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Application Dashboard                                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ ┌───────────────┐  ┌───────────────┐  ┌───────────────┐   │
+│ │ Request Rate  │  │ Error Rate    │  │ P99 Latency   │   │
+│ │   1,234/s     │  │    0.5%       │  │    250ms      │   │
+│ │   ▲ 5%        │  │    ▼ 0.1%     │  │    ▼ 10ms     │   │
+│ └───────────────┘  └───────────────┘  └───────────────┘   │
+│                                                             │
+│ ┌─────────────────────────────────────────────────────────┐│
+│ │ Request Rate Over Time                                  ││
+│ │ [Chart showing requests per second over 24 hours]       ││
+│ └─────────────────────────────────────────────────────────┘│
+│                                                             │
+│ ┌─────────────────────────────────────────────────────────┐│
+│ │ Error Rate by Endpoint                                  ││
+│ │ /api/users      ████░░░░░░ 2%                          ││
+│ │ /api/orders     ██░░░░░░░░ 0.5%                        ││
+│ │ /api/payments   ███░░░░░░░ 1%                          ││
+│ └─────────────────────────────────────────────────────────┘│
+│                                                             │
+│ ┌───────────────┐  ┌───────────────┐  ┌───────────────┐   │
+│ │ CPU Usage     │  │ Memory        │  │ DB Pool       │   │
+│ │    45%        │  │   2.1 GB      │  │   12/20       │   │
+│ └───────────────┘  └───────────────┘  └───────────────┘   │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Commands
+
+```bash
+# Check application health
+proagents monitor health
+
+# View current metrics
+proagents monitor metrics
+
+# Test alerting
+proagents monitor test-alert high_error_rate
+
+# View active alerts
+proagents monitor alerts
+
+# Export dashboard config
+proagents monitor export-dashboard --format grafana
+```
+
+---
+
+## Configuration
+
+```yaml
+# proagents.config.yaml
+monitoring:
+  enabled: true
+
+  # Metrics
+  metrics:
+    enabled: true
+    endpoint: "/metrics"
+    provider: "prometheus"  # prometheus, datadog, cloudwatch
+
+  # Health checks
+  health:
+    endpoint: "/health"
+    interval: "30s"
+    timeout: "10s"
+
+  # Tracing
+  tracing:
+    enabled: true
+    provider: "jaeger"
+    sample_rate: 0.1  # 10% of requests
+
+  # Uptime monitoring
+  uptime:
+    provider: "pingdom"
+    check_interval: "1m"
+    endpoints:
+      - "https://api.example.com/health"
+```
+
+---
+
+## Best Practices
+
+1. **Monitor the Four Golden Signals**: Latency, traffic, errors, saturation
+2. **Set Meaningful Alerts**: Actionable, not noisy
+3. **Use Dashboards**: Visualize trends and patterns
+4. **Track Business Metrics**: Not just technical metrics
+5. **Implement Distributed Tracing**: For microservices
+6. **Monitor Dependencies**: External services and databases
+7. **Test Alerting**: Regularly verify alerts work
+8. **Document Runbooks**: What to do when alerts fire