proagents 1.0.0

package/proagents/parallel-features/conflict-detection.md

@@ -0,0 +1,226 @@
+# Parallel Feature Conflict Detection
+
+Detect and resolve conflicts when developing multiple features simultaneously.
+
+---
+
+## Overview
+
+When working on multiple features in parallel, conflicts can occur when:
+- Same files are modified
+- Same components are changed
+- Database schema changes overlap
+- API contracts conflict
+
+---
+
+## Conflict Types
+
+### File-Level Conflicts
+
+**Detection:**
+```
+Feature A modifies: [file1.ts, file2.ts, file3.ts]
+Feature B modifies: [file2.ts, file4.ts]
+
+⚠️ CONFLICT: file2.ts
+```
+
+**Risk Levels:**
+| Scenario | Risk | Action |
+|----------|------|--------|
+| Same file, different sections | Low | Proceed with caution |
+| Same file, same section | Medium | Coordinate changes |
+| Same function/component | High | Sequential development |
+
+### Semantic Conflicts
+
+Beyond file-level, detect:
+- State management conflicts
+- API contract changes
+- Type definition conflicts
+- Route conflicts
+
+---
+
+## Conflict Detection Process
+
+### 1. Pre-Development Check
+
+Before starting a new feature:
+
+```
+/conflict-check "feature-name"
+
+Output:
+Feature: user-profile
+Files to modify: [UserCard.tsx, userService.ts, User.ts]
+
+Checking against active features...
+
+⚠️ Potential Conflicts:
+- Feature 'user-settings' also modifies UserCard.tsx
+  Risk: MEDIUM (same component, different sections)
+
+- Feature 'auth-refresh' modifies userService.ts
+  Risk: LOW (different functions)
+
+Recommendation: Coordinate with user-settings feature owner
+```
+
+### 2. During Development
+
+Track file modifications:
+
+```json
+{
+  "feature": "user-profile",
+  "files_modified": [
+    {
+      "path": "src/components/UserCard.tsx",
+      "sections": ["header", "avatar"],
+      "last_modified": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "conflicts_detected": [],
+  "last_check": "2024-01-15T10:30:00Z"
+}
+```
+
+### 3. Pre-Merge Check
+
+```
+/conflict-check-merge "feature-name"
+
+Checking feature-user-profile for merge conflicts...
+
+Files with potential conflicts:
+- UserCard.tsx: Modified by both feature-user-profile and feature-user-settings
+  → Review needed before merge
+
+API changes:
+- No conflicting API changes detected
+
+Database changes:
+- No conflicting schema changes
+
+Recommended merge order:
+1. feature-user-settings (PR #123)
+2. feature-user-profile (this feature)
+```
+
+---
+
+## Resolution Strategies
+
+### Strategy 1: Rebase and Resolve
+
+```bash
+# Update your branch with latest from develop
+git fetch origin
+git rebase origin/develop
+
+# Resolve conflicts file by file
+# For each conflict:
+# 1. Review both changes
+# 2. Combine or choose appropriate version
+# 3. Test the result
+
+git add .
+git rebase --continue
+```
+
+### Strategy 2: Feature Flag Isolation
+
+```javascript
+// Both features can merge, but only one active
+if (featureFlags.userProfile) {
+  return <NewUserProfile />;
+} else if (featureFlags.userSettings) {
+  return <UserSettings />;
+} else {
+  return <LegacyProfile />;
+}
+```
+
+### Strategy 3: Component Decomposition
+
+If two features need same component:
+1. Extract shared logic to new component
+2. Each feature uses shared + own additions
+3. Reduces direct conflicts
+
+### Strategy 4: Coordinated Development
+
+```markdown
+## Coordination Agreement
+
+Features: user-profile, user-settings
+Shared File: UserCard.tsx
+
+Agreement:
+- user-profile: Modifies header and avatar sections
+- user-settings: Modifies footer and settings button
+- Neither touches: card body
+
+Review: Both must review each other's PRs for this file
+```
+
+---
+
+## Conflict Status Dashboard
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Parallel Feature Conflict Status                        │
+├─────────────────────────────────────────────────────────┤
+│ Active Features: 3                                      │
+├─────────────────────────────────────────────────────────┤
+│ Feature             │ Files │ Conflicts │ Status        │
+├─────────────────────┼───────┼───────────┼───────────────┤
+│ user-profile        │ 8     │ 1         │ ⚠️ Medium     │
+│ user-settings       │ 5     │ 1         │ ⚠️ Medium     │
+│ dashboard-redesign  │ 12    │ 0         │ ✅ Clear      │
+├─────────────────────────────────────────────────────────┤
+│ Conflict Details:                                       │
+│ UserCard.tsx: user-profile ↔ user-settings             │
+│ Recommended: Coordinate before merge                    │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Configuration
+
+```yaml
+# proagents.config.yaml
+parallel_features:
+  conflict_detection:
+    enabled: true
+    check_on:
+      - feature_start
+      - file_save
+      - pre_commit
+      - pre_merge
+
+    risk_thresholds:
+      same_file_different_sections: "low"
+      same_file_same_section: "medium"
+      same_function: "high"
+      api_contract_change: "high"
+      schema_change: "high"
+
+    alerts:
+      notify_on: "medium"
+      block_on: "high"
+```
+
+---
+
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/conflict-check` | Check for conflicts |
+| `/conflict-status` | Show conflict status |
+| `/conflict-resolve` | Help resolve conflicts |

package/proagents/parallel-features/dependency-management.md

@@ -0,0 +1,392 @@
+# Feature Dependency Management
+
+Manage dependencies between parallel features.
+
+---
+
+## Overview
+
+Dependency management ensures:
+- Clear dependency relationships
+- Correct development order
+- Blocker identification
+- Efficient resource allocation
+
+---
+
+## Dependency Types
+
+### 1. Hard Dependencies
+
+Feature cannot proceed without dependency completion.
+
+```yaml
+hard_dependency:
+  feature: "feature-dashboard"
+  depends_on: "feature-user-auth"
+  type: "hard"
+  reason: "Dashboard requires auth API for user data"
+  required_phase: "implementation_complete"
+  blocks_at_phase: "implementation"
+```
+
+### 2. Soft Dependencies
+
+Feature can proceed but will need integration later.
+
+```yaml
+soft_dependency:
+  feature: "feature-notifications"
+  depends_on: "feature-dashboard"
+  type: "soft"
+  reason: "Notifications will integrate with dashboard"
+  integration_phase: "testing"
+  can_parallel: true
+```
+
+### 3. Shared Resource Dependencies
+
+Features share common code or resources.
+
+```yaml
+shared_resource:
+  resource: "src/lib/api.ts"
+  features:
+    - "feature-user-auth"
+    - "feature-dashboard"
+  conflict_risk: "medium"
+  coordination: "required"
+```
+
+---
+
+## Dependency Declaration
+
+### In Feature Status
+
+```json
+// feature-dashboard/dependencies.json
+{
+  "feature_id": "feature-dashboard",
+
+  "depends_on": [
+    {
+      "feature": "feature-user-auth",
+      "type": "hard",
+      "reason": "Requires auth context and user API",
+      "required_phase": "implementation",
+      "status": "waiting",
+      "blocking_since": "2024-01-13T10:00:00Z"
+    }
+  ],
+
+  "blocks": [
+    {
+      "feature": "feature-notifications",
+      "type": "soft",
+      "reason": "Notifications will use dashboard components",
+      "unblock_at_phase": "implementation"
+    }
+  ],
+
+  "shared_resources": [
+    {
+      "path": "src/lib/api.ts",
+      "shared_with": ["feature-user-auth"],
+      "sections_affected": ["interceptors", "error handling"],
+      "coordination_status": "aligned"
+    }
+  ]
+}
+```
+
+---
+
+## Dependency Graph
+
+### Visual Representation
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Feature Dependency Graph                  │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌──────────────┐                                          │
+│  │  user-auth   │ ← No dependencies (can start)           │
+│  │   [60%] 🔄   │                                          │
+│  └──────┬───────┘                                          │
+│         │                                                   │
+│         │ hard                                              │
+│         ▼                                                   │
+│  ┌──────────────┐                                          │
+│  │  dashboard   │ ← Blocked by user-auth                   │
+│  │   [30%] ⏸️   │                                          │
+│  └──────┬───────┘                                          │
+│         │                                                   │
+│         │ soft                                              │
+│         ▼                                                   │
+│  ┌──────────────┐                                          │
+│  │notifications │ ← Can proceed, integrate later           │
+│  │   [10%] 🔄   │                                          │
+│  └──────────────┘                                          │
+│                                                             │
+│  Legend:                                                    │
+│  ─── hard dependency (blocks)                              │
+│  ··· soft dependency (integration needed)                  │
+│  🔄 in progress  ⏸️ blocked  ✅ complete                   │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Mermaid Diagram
+
+```mermaid
+graph TD
+    A[user-auth<br/>60% 🔄] -->|hard| B[dashboard<br/>30% ⏸️]
+    B -->|soft| C[notifications<br/>10% 🔄]
+    A -->|soft| D[settings<br/>0% ⏳]
+
+    style A fill:#90EE90
+    style B fill:#FFB6C1
+    style C fill:#87CEEB
+    style D fill:#F0F0F0
+```
+
+---
+
+## Dependency Resolution
+
+### Resolution Strategies
+
+```yaml
+resolution_strategies:
+  hard_dependency_blocked:
+    actions:
+      - "Notify blocking feature owner"
+      - "Add to blocker dashboard"
+      - "Track waiting time"
+      - "Escalate if >24 hours"
+
+  soft_dependency:
+    actions:
+      - "Allow parallel development"
+      - "Schedule integration checkpoint"
+      - "Create integration task"
+
+  shared_resource_conflict:
+    actions:
+      - "Identify overlapping sections"
+      - "Coordinate changes"
+      - "Merge more frequently"
+      - "Consider feature branches from feature branches"
+```
+
+### Unblocking Process
+
+```typescript
+// Unblock dependent features when dependency completes
+async function onPhaseComplete(featureId: string, phase: string) {
+  const blockedFeatures = await getBlockedBy(featureId);
+
+  for (const blocked of blockedFeatures) {
+    const dep = blocked.dependencies.find(d => d.feature === featureId);
+
+    if (dep.required_phase === phase) {
+      // Unblock the feature
+      await unblockFeature(blocked.id, {
+        unblocked_by: featureId,
+        unblocked_at: new Date().toISOString(),
+      });
+
+      // Notify team
+      await notify({
+        type: 'feature_unblocked',
+        feature: blocked.name,
+        unblocked_by: featureId,
+      });
+    }
+  }
+}
+```
+
+---
+
+## Circular Dependency Detection
+
+```typescript
+// Detect circular dependencies
+function detectCircularDependencies(features: Feature[]): Cycle[] {
+  const cycles: Cycle[] = [];
+  const visited = new Set<string>();
+  const recursionStack = new Set<string>();
+
+  function dfs(featureId: string, path: string[]): boolean {
+    visited.add(featureId);
+    recursionStack.add(featureId);
+
+    const feature = features.find(f => f.id === featureId);
+    if (!feature) return false;
+
+    for (const dep of feature.depends_on) {
+      if (!visited.has(dep.feature)) {
+        if (dfs(dep.feature, [...path, featureId])) {
+          return true;
+        }
+      } else if (recursionStack.has(dep.feature)) {
+        // Cycle detected
+        cycles.push({
+          path: [...path, featureId, dep.feature],
+          severity: 'error',
+        });
+        return true;
+      }
+    }
+
+    recursionStack.delete(featureId);
+    return false;
+  }
+
+  for (const feature of features) {
+    if (!visited.has(feature.id)) {
+      dfs(feature.id, []);
+    }
+  }
+
+  return cycles;
+}
+```
+
+**Alert on Circular Dependency:**
+```
+⛔ CIRCULAR DEPENDENCY DETECTED
+
+Path: user-auth → dashboard → user-settings → user-auth
+
+This creates a deadlock where no feature can proceed.
+
+Resolution Options:
+1. Remove one of the dependencies
+2. Break feature into smaller parts
+3. Extract shared functionality to separate feature
+```
+
+---
+
+## Dependency Impact Analysis
+
+```yaml
+impact_analysis:
+  feature: "feature-user-auth"
+
+  if_delayed:
+    directly_blocked:
+      - "feature-dashboard"
+      - "feature-settings"
+    indirectly_affected:
+      - "feature-notifications"
+    total_impact_days: 5
+
+  if_scope_changes:
+    api_changes_affect:
+      - "feature-dashboard": "API integration"
+      - "feature-settings": "Auth context usage"
+    notification_required: true
+
+  completion_enables:
+    immediate:
+      - "feature-dashboard can proceed"
+    subsequent:
+      - "feature-notifications integration"
+```
+
+---
+
+## Coordination Workflow
+
+### Daily Dependency Check
+
+```yaml
+daily_check:
+  time: "09:00"
+  actions:
+    - "Check all blocked features"
+    - "Update dependency status"
+    - "Identify new blockers"
+    - "Generate coordination report"
+    - "Notify relevant teams"
+```
+
+### Coordination Report
+
+```markdown
+# Daily Dependency Report - 2024-01-15
+
+## Blocked Features: 2
+
+### feature-dashboard
+- **Blocked by:** feature-user-auth
+- **Waiting since:** 2 days
+- **Expected unblock:** Today (user-auth at 60%)
+- **Action:** Monitor user-auth progress
+
+### feature-reports
+- **Blocked by:** feature-dashboard
+- **Waiting since:** 2 days
+- **Expected unblock:** 3 days (cascading)
+- **Action:** Consider parallel design work
+
+## Unblocked Today: 1
+
+### feature-settings
+- **Was blocked by:** feature-user-auth
+- **Unblocked at:** 09:30
+- **Action:** Resume implementation
+
+## Upcoming Dependencies
+
+| Feature | Depends On | Expected Resolution |
+|---------|------------|---------------------|
+| notifications | dashboard | 5 days |
+| analytics | user-auth | 1 day |
+```
+
+---
+
+## Configuration
+
+```yaml
+# proagents.config.yaml
+
+dependencies:
+  enabled: true
+
+  detection:
+    circular: true
+    alert_on_circular: true
+
+  blocking:
+    max_wait_time: "48h"
+    escalate_after: "24h"
+
+  coordination:
+    daily_check: true
+    check_time: "09:00"
+    report_channel: "slack"
+
+  visualization:
+    generate_graph: true
+    format: "mermaid"
+```
+
+---
+
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/deps` | View dependency graph |
+| `/deps [feature]` | View feature dependencies |
+| `/deps --blocked` | List blocked features |
+| `/deps --add [from] [to]` | Add dependency |
+| `/deps --remove [from] [to]` | Remove dependency |
+| `/deps --check` | Check for issues |