proagents 1.0.0

package/proagents/parallel-features/tracking-system.md

@@ -0,0 +1,416 @@
+# Feature Tracking System
+
+Track multiple features simultaneously with clear status visibility.
+
+---
+
+## Overview
+
+The tracking system provides:
+- Real-time feature status
+- Progress tracking per phase
+- Resource allocation visibility
+- Blocker identification
+- Timeline management
+
+---
+
+## Tracking Structure
+
+### Feature Directory
+
+```
+/proagents/active-features/
+├── _index.json                    # Master index
+├── _dashboard.md                  # Human-readable dashboard
+├── feature-user-auth/
+│   ├── status.json                # Machine-readable status
+│   ├── status.md                  # Human-readable status
+│   ├── requirements.md            # Requirements document
+│   ├── design.md                  # Design document
+│   ├── implementation-plan.md     # Implementation plan
+│   ├── files-modified.json        # Files touched by feature
+│   ├── dependencies.json          # Feature dependencies
+│   └── timeline.json              # Phase timeline
+├── feature-dashboard/
+│   └── ...
+└── feature-notifications/
+    └── ...
+```
+
+---
+
+## Master Index
+
+```json
+// _index.json
+{
+  "last_updated": "2024-01-15T14:30:00Z",
+  "active_features": [
+    {
+      "id": "feature-user-auth",
+      "name": "User Authentication",
+      "status": "in_progress",
+      "current_phase": "implementation",
+      "phase_progress": 60,
+      "branch": "feature/user-auth",
+      "assignee": "developer-1",
+      "started": "2024-01-10T09:00:00Z",
+      "estimated_completion": "2024-01-20",
+      "blockers": [],
+      "priority": "high"
+    },
+    {
+      "id": "feature-dashboard",
+      "name": "User Dashboard",
+      "status": "blocked",
+      "current_phase": "implementation",
+      "phase_progress": 30,
+      "branch": "feature/dashboard",
+      "assignee": "developer-2",
+      "started": "2024-01-12T09:00:00Z",
+      "blockers": ["Waiting for user-auth API"],
+      "priority": "medium"
+    }
+  ],
+  "completed_features": [
+    {
+      "id": "feature-login-page",
+      "name": "Login Page",
+      "completed": "2024-01-08",
+      "branch": "feature/login-page",
+      "merged_to": "main"
+    }
+  ],
+  "paused_features": []
+}
+```
+
+---
+
+## Feature Status
+
+```json
+// feature-user-auth/status.json
+{
+  "id": "feature-user-auth",
+  "name": "User Authentication",
+  "description": "Implement user login, registration, and session management",
+
+  "status": "in_progress",
+  "priority": "high",
+  "assignee": "developer-1",
+
+  "branch": {
+    "name": "feature/user-auth",
+    "base": "develop",
+    "commits": 15,
+    "behind_base": 2
+  },
+
+  "phases": {
+    "init": { "status": "completed", "completed_at": "2024-01-10T10:00:00Z" },
+    "analysis": { "status": "completed", "completed_at": "2024-01-10T12:00:00Z" },
+    "requirements": { "status": "completed", "completed_at": "2024-01-10T14:00:00Z" },
+    "design": { "status": "completed", "completed_at": "2024-01-11T12:00:00Z" },
+    "planning": { "status": "completed", "completed_at": "2024-01-11T16:00:00Z" },
+    "implementation": { "status": "in_progress", "progress": 60 },
+    "testing": { "status": "pending" },
+    "review": { "status": "pending" },
+    "documentation": { "status": "pending" },
+    "deployment": { "status": "pending" }
+  },
+
+  "current_task": "Implementing password reset flow",
+
+  "timeline": {
+    "started": "2024-01-10T09:00:00Z",
+    "estimated_completion": "2024-01-20T17:00:00Z",
+    "actual_hours": 24,
+    "estimated_remaining_hours": 16
+  },
+
+  "files_modified": [
+    "src/features/auth/components/LoginForm.tsx",
+    "src/features/auth/hooks/useAuth.ts",
+    "src/features/auth/services/authService.ts",
+    "src/lib/api.ts"
+  ],
+
+  "dependencies": {
+    "depends_on": [],
+    "blocks": ["feature-dashboard", "feature-notifications"]
+  },
+
+  "blockers": [],
+  "risks": [
+    {
+      "description": "OAuth provider integration may take longer",
+      "impact": "medium",
+      "mitigation": "Start with email/password first"
+    }
+  ],
+
+  "notes": [
+    {
+      "date": "2024-01-12",
+      "author": "developer-1",
+      "content": "Decided to use JWT instead of sessions"
+    }
+  ]
+}
+```
+
+---
+
+## Human-Readable Status
+
+```markdown
+<!-- feature-user-auth/status.md -->
+# Feature: User Authentication
+
+## Quick Status
+
+| Attribute | Value |
+|-----------|-------|
+| **Status** | 🔄 In Progress |
+| **Phase** | Implementation (60%) |
+| **Assignee** | developer-1 |
+| **Branch** | feature/user-auth |
+| **Started** | 2024-01-10 |
+| **ETA** | 2024-01-20 |
+
+## Phase Progress
+
+```
+✅ Init          ██████████ 100%
+✅ Analysis      ██████████ 100%
+✅ Requirements  ██████████ 100%
+✅ Design        ██████████ 100%
+✅ Planning      ██████████ 100%
+🔄 Implementation ██████░░░░ 60%
+⏳ Testing       ░░░░░░░░░░ 0%
+⏳ Review        ░░░░░░░░░░ 0%
+⏳ Documentation ░░░░░░░░░░ 0%
+⏳ Deployment    ░░░░░░░░░░ 0%
+```
+
+## Current Task
+Implementing password reset flow
+
+## Files Modified
+- `src/features/auth/components/LoginForm.tsx`
+- `src/features/auth/hooks/useAuth.ts`
+- `src/features/auth/services/authService.ts`
+- `src/lib/api.ts`
+
+## Blockers
+None
+
+## Dependencies
+- **Blocks:** feature-dashboard, feature-notifications
+- **Depends on:** None
+
+## Timeline
+- Started: 2024-01-10
+- Actual hours: 24h
+- Remaining: ~16h
+- On track: ✅ Yes
+
+## Notes
+- 2024-01-12: Decided to use JWT instead of sessions
+```
+
+---
+
+## Dashboard View
+
+```markdown
+<!-- _dashboard.md -->
+# ProAgents Feature Dashboard
+
+**Last Updated:** 2024-01-15 14:30 UTC
+
+## Active Features: 3 / 5 (max)
+
+### 🔄 In Progress
+
+| Feature | Phase | Progress | Assignee | ETA | Status |
+|---------|-------|----------|----------|-----|--------|
+| User Auth | Implementation | 60% | dev-1 | Jan 20 | ✅ On track |
+| Dashboard | Implementation | 30% | dev-2 | Jan 25 | ⚠️ Blocked |
+| Settings | Design | 80% | dev-3 | Jan 22 | ✅ On track |
+
+### ⏸️ Blocked
+
+| Feature | Blocked By | Since |
+|---------|------------|-------|
+| Dashboard | Waiting for User Auth API | 2 days |
+
+### ✅ Recently Completed
+
+| Feature | Completed | Merged |
+|---------|-----------|--------|
+| Login Page | Jan 8 | ✅ |
+| Footer | Jan 5 | ✅ |
+
+---
+
+## Dependency Graph
+
+```
+user-auth ─────┬──▶ dashboard ──▶ notifications
+               │
+               └──▶ settings
+```
+
+## Conflict Alerts
+
+⚠️ **1 potential conflict detected:**
+- `src/lib/api.ts` modified by both `user-auth` and `dashboard`
+
+## Recommended Actions
+
+1. Merge `user-auth` first to unblock `dashboard`
+2. Review potential conflict in `api.ts`
+3. Consider starting `notifications` after `dashboard` unblocked
+```
+
+---
+
+## Progress Tracking
+
+### Phase Completion
+
+```typescript
+// Update phase status
+async function updatePhaseStatus(
+  featureId: string,
+  phase: string,
+  status: 'completed' | 'in_progress' | 'pending',
+  progress?: number
+) {
+  const statusFile = `active-features/${featureId}/status.json`;
+  const featureStatus = await readJSON(statusFile);
+
+  featureStatus.phases[phase] = {
+    status,
+    progress,
+    ...(status === 'completed' && { completed_at: new Date().toISOString() }),
+  };
+
+  // Update current phase
+  if (status === 'in_progress') {
+    featureStatus.current_phase = phase;
+  }
+
+  await writeJSON(statusFile, featureStatus);
+  await updateIndex();
+  await generateDashboard();
+}
+```
+
+### Time Tracking
+
+```yaml
+time_tracking:
+  feature_id: "feature-user-auth"
+
+  by_phase:
+    init: { hours: 0.5 }
+    analysis: { hours: 2 }
+    requirements: { hours: 1.5 }
+    design: { hours: 4 }
+    planning: { hours: 2 }
+    implementation: { hours: 16, in_progress: true }
+    testing: { hours: 0, estimated: 6 }
+    review: { hours: 0, estimated: 2 }
+    documentation: { hours: 0, estimated: 2 }
+    deployment: { hours: 0, estimated: 1 }
+
+  totals:
+    actual: 26
+    estimated_remaining: 11
+    original_estimate: 40
+    variance: "-3 hours"
+```
+
+---
+
+## Notifications
+
+```yaml
+notifications:
+  triggers:
+    - event: "phase_completed"
+      notify: ["assignee", "team_lead"]
+      channel: "slack"
+
+    - event: "blocker_added"
+      notify: ["assignee", "blocking_feature_owner"]
+      channel: "slack"
+      priority: "high"
+
+    - event: "behind_schedule"
+      notify: ["assignee", "team_lead"]
+      channel: "email"
+
+    - event: "ready_for_review"
+      notify: ["reviewers"]
+      channel: "slack"
+
+  templates:
+    phase_completed: |
+      ✅ Feature "{{feature_name}}" completed phase: {{phase}}
+      Progress: {{overall_progress}}%
+
+    blocker_added: |
+      ⚠️ Feature "{{feature_name}}" is now blocked
+      Blocker: {{blocker_description}}
+      Blocked by: {{blocking_feature}}
+```
+
+---
+
+## Configuration
+
+```yaml
+# proagents.config.yaml
+
+tracking:
+  enabled: true
+
+  features:
+    max_concurrent: 5
+    require_assignee: true
+    require_estimate: true
+
+  phases:
+    track_time: true
+    require_completion: true
+
+  dashboard:
+    auto_generate: true
+    refresh_interval: "5m"
+
+  notifications:
+    enabled: true
+    channels: ["slack"]
+
+  reporting:
+    daily_summary: true
+    weekly_report: true
+```
+
+---
+
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/feature-status` | View all features status |
+| `/feature-status [id]` | View specific feature |
+| `/feature-update [id]` | Update feature status |
+| `/feature-block [id]` | Mark feature as blocked |
+| `/feature-unblock [id]` | Remove blocker |
+| `/feature-dashboard` | View dashboard |

package/proagents/patterns/README.md

@@ -0,0 +1,305 @@
+# Error Handling Patterns
+
+Consistent error handling across your application.
+
+---
+
+## Overview
+
+Standardized error handling patterns for predictable, debuggable applications.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Error Types](./error-types.md) | Custom error classes |
+| [API Errors](./api-errors.md) | HTTP error handling |
+| [Async Errors](./async-errors.md) | Promise and async/await |
+| [UI Errors](./ui-errors.md) | Error boundaries and display |
+
+---
+
+## Error Classification
+
+### Error Categories
+
+| Category | HTTP Code | Example |
+|----------|-----------|---------|
+| Validation | 400 | Invalid input |
+| Authentication | 401 | Invalid credentials |
+| Authorization | 403 | Access denied |
+| Not Found | 404 | Resource missing |
+| Conflict | 409 | Duplicate entry |
+| Server | 500 | Internal error |
+
+---
+
+## Custom Error Classes
+
+### Base Error Class
+
+```typescript
+// src/errors/base.ts
+export class AppError extends Error {
+  constructor(
+    public message: string,
+    public code: string,
+    public statusCode: number = 500,
+    public isOperational: boolean = true,
+    public details?: Record<string, any>
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+// Specific error types
+export class ValidationError extends AppError {
+  constructor(message: string, details?: Record<string, any>) {
+    super(message, 'VALIDATION_ERROR', 400, true, details);
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource: string) {
+    super(`${resource} not found`, 'NOT_FOUND', 404, true);
+  }
+}
+
+export class AuthenticationError extends AppError {
+  constructor(message = 'Authentication failed') {
+    super(message, 'AUTH_ERROR', 401, true);
+  }
+}
+
+export class AuthorizationError extends AppError {
+  constructor(message = 'Access denied') {
+    super(message, 'FORBIDDEN', 403, true);
+  }
+}
+```
+
+---
+
+## API Error Handling
+
+### Express Middleware
+
+```typescript
+// src/middleware/error-handler.ts
+export function errorHandler(
+  err: Error,
+  req: Request,
+  res: Response,
+  next: NextFunction
+) {
+  // Log error
+  logger.error({
+    error: err.message,
+    stack: err.stack,
+    path: req.path,
+    method: req.method,
+  });
+
+  // Handle known errors
+  if (err instanceof AppError) {
+    return res.status(err.statusCode).json({
+      error: {
+        code: err.code,
+        message: err.message,
+        details: err.details,
+      },
+    });
+  }
+
+  // Handle unknown errors
+  return res.status(500).json({
+    error: {
+      code: 'INTERNAL_ERROR',
+      message: 'An unexpected error occurred',
+    },
+  });
+}
+```
+
+### API Response Format
+
+```typescript
+// Success response
+{
+  "data": { ... },
+  "meta": {
+    "timestamp": "2024-01-15T10:30:00Z"
+  }
+}
+
+// Error response
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid email format",
+    "details": {
+      "field": "email",
+      "value": "invalid"
+    }
+  }
+}
+```
+
+---
+
+## Async Error Handling
+
+### Async/Await Pattern
+
+```typescript
+// Wrap async route handlers
+const asyncHandler = (fn: Function) => (
+  req: Request,
+  res: Response,
+  next: NextFunction
+) => {
+  Promise.resolve(fn(req, res, next)).catch(next);
+};
+
+// Usage
+app.get('/users/:id', asyncHandler(async (req, res) => {
+  const user = await userService.findById(req.params.id);
+  if (!user) {
+    throw new NotFoundError('User');
+  }
+  res.json({ data: user });
+}));
+```
+
+### Promise Error Handling
+
+```typescript
+// Always handle promise rejections
+async function fetchData() {
+  try {
+    const response = await api.get('/data');
+    return response.data;
+  } catch (error) {
+    if (error.response?.status === 404) {
+      throw new NotFoundError('Data');
+    }
+    throw new AppError('Failed to fetch data', 'FETCH_ERROR', 500);
+  }
+}
+```
+
+---
+
+## UI Error Handling
+
+### React Error Boundary
+
+```typescript
+// src/components/ErrorBoundary.tsx
+class ErrorBoundary extends React.Component {
+  state = { hasError: false, error: null };
+
+  static getDerivedStateFromError(error: Error) {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
+    // Log to error service
+    errorService.log(error, errorInfo);
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return <ErrorFallback error={this.state.error} />;
+    }
+    return this.props.children;
+  }
+}
+
+// Usage
+<ErrorBoundary>
+  <App />
+</ErrorBoundary>
+```
+
+### Error Display Component
+
+```typescript
+// src/components/ErrorMessage.tsx
+function ErrorMessage({ error }: { error: AppError }) {
+  return (
+    <div role="alert" className="error-message">
+      <h3>Something went wrong</h3>
+      <p>{error.message}</p>
+      {error.details && (
+        <details>
+          <summary>Details</summary>
+          <pre>{JSON.stringify(error.details, null, 2)}</pre>
+        </details>
+      )}
+      <button onClick={() => window.location.reload()}>
+        Try Again
+      </button>
+    </div>
+  );
+}
+```
+
+---
+
+## Error Logging
+
+### Structured Logging
+
+```typescript
+// Log errors with context
+logger.error({
+  message: error.message,
+  code: error.code,
+  stack: error.stack,
+  context: {
+    userId: req.user?.id,
+    path: req.path,
+    method: req.method,
+    body: req.body,
+  },
+});
+```
+
+### Error Tracking Services
+
+```yaml
+# proagents.config.yaml
+error_tracking:
+  provider: "sentry"  # sentry, bugsnag, rollbar
+
+  sentry:
+    dsn_env: "SENTRY_DSN"
+    environment: "${NODE_ENV}"
+
+    # What to capture
+    capture:
+      - unhandled_exceptions
+      - unhandled_rejections
+      - console_errors
+
+    # What to ignore
+    ignore:
+      - "NetworkError"
+      - "AbortError"
+```
+
+---
+
+## Best Practices
+
+1. **Use Custom Errors**: Create specific error types
+2. **Include Context**: Add relevant details to errors
+3. **Handle All Paths**: Every code path should handle errors
+4. **Log Appropriately**: Log errors with enough context
+5. **User-Friendly Messages**: Show helpful messages to users
+6. **Don't Expose Internals**: Hide stack traces in production
+7. **Retry When Appropriate**: Implement retry logic for transient errors
+8. **Monitor Errors**: Track error rates and patterns