proagents 1.0.0

package/proagents/offline-mode/caching.md

@@ -0,0 +1,344 @@
+# Offline Caching
+
+Manage cached data for offline operations.
+
+---
+
+## Cache Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Cache Structure                           │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  .proagents/cache/                                          │
+│  ├── analysis/           # Codebase analysis               │
+│  │   ├── structure.json                                    │
+│  │   ├── patterns.json                                     │
+│  │   └── dependencies.json                                 │
+│  ├── templates/          # Code templates                  │
+│  │   ├── components/                                       │
+│  │   └── tests/                                            │
+│  ├── standards/          # Project standards               │
+│  │   ├── rules.json                                        │
+│  │   └── conventions.json                                  │
+│  ├── glossary/           # Domain knowledge                │
+│  │   └── terms.json                                        │
+│  └── metadata.json       # Cache metadata                  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Cache Configuration
+
+### Basic Settings
+
+```yaml
+offline:
+  cache:
+    enabled: true
+    path: ".proagents/cache"
+    max_size: "500MB"
+
+    # Automatic caching
+    auto_cache:
+      enabled: true
+      on_analysis: true      # Cache analysis results
+      on_success: true       # Cache successful operations
+      frequency: "daily"     # Full refresh frequency
+```
+
+### What to Cache
+
+```yaml
+offline:
+  cache:
+    include:
+      # Analysis data
+      - type: "analysis"
+        ttl: "7d"
+        priority: "high"
+
+      # Learned patterns
+      - type: "patterns"
+        ttl: "30d"
+        priority: "high"
+
+      # Templates
+      - type: "templates"
+        ttl: "30d"
+        priority: "medium"
+
+      # Standards and rules
+      - type: "standards"
+        ttl: "7d"
+        priority: "high"
+
+      # Domain glossary
+      - type: "glossary"
+        ttl: "30d"
+        priority: "medium"
+
+      # Recent AI responses
+      - type: "responses"
+        ttl: "1d"
+        max_items: 100
+        priority: "low"
+
+    exclude:
+      - "*.env"
+      - "**/secrets/**"
+      - "**/credentials/**"
+```
+
+---
+
+## Cache Operations
+
+### Pre-Cache for Offline Work
+
+```bash
+# Prepare comprehensive cache
+proagents offline prepare
+
+# Output:
+┌─────────────────────────────────────────────────────────────┐
+│ Preparing Offline Cache                                     │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ ✓ Codebase analysis cached (2.3 MB)                        │
+│ ✓ Learned patterns cached (456 KB)                         │
+│ ✓ Templates cached (128 files, 1.8 MB)                     │
+│ ✓ Standards cached (34 KB)                                 │
+│ ✓ Domain glossary cached (89 KB)                           │
+│                                                             │
+│ Total cache size: 4.7 MB                                   │
+│ Estimated offline capability: 85%                          │
+│                                                             │
+│ Missing for full offline:                                   │
+│ • Complex code generation (requires AI)                    │
+│ • Natural language processing (requires AI)                │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### View Cache Status
+
+```bash
+proagents offline cache-status
+
+# Output:
+┌─────────────────────────────────────────────────────────────┐
+│ Cache Status                                                │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ Total Size: 4.7 MB / 500 MB (1%)                           │
+│ Last Updated: 2 hours ago                                   │
+│                                                             │
+│ Components:                                                 │
+│ ├── Analysis:   2.3 MB  (fresh, 2h old)                   │
+│ ├── Patterns:   456 KB  (fresh, 1d old)                   │
+│ ├── Templates:  1.8 MB  (fresh, 5d old)                   │
+│ ├── Standards:  34 KB   (fresh, 2h old)                   │
+│ └── Glossary:   89 KB   (fresh, 3d old)                   │
+│                                                             │
+│ Cache Health: Good                                          │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Clear Cache
+
+```bash
+# Clear all cache
+proagents offline cache-clear
+
+# Clear specific type
+proagents offline cache-clear --type analysis
+
+# Clear expired only
+proagents offline cache-clear --expired
+```
+
+---
+
+## Cache Invalidation
+
+### Automatic Invalidation
+
+```yaml
+offline:
+  cache:
+    invalidation:
+      # Invalidate on file changes
+      on_file_change:
+        analysis: true
+        patterns: true
+
+      # Invalidate on config changes
+      on_config_change:
+        standards: true
+
+      # Time-based expiration
+      ttl:
+        analysis: "7d"
+        patterns: "30d"
+        templates: "30d"
+        standards: "7d"
+```
+
+### Manual Invalidation
+
+```bash
+# Invalidate specific cache
+proagents offline invalidate --type analysis
+
+# Invalidate for specific files
+proagents offline invalidate --files "src/auth/**"
+
+# Force refresh
+proagents offline refresh
+```
+
+---
+
+## Incremental Caching
+
+### Smart Updates
+
+```yaml
+offline:
+  cache:
+    incremental:
+      enabled: true
+
+      # Only cache changed files
+      track_changes: true
+
+      # Merge with existing cache
+      merge_strategy: "update"  # update, replace
+
+      # Compression
+      compress: true
+      compression_level: 6
+```
+
+### Change Detection
+
+```bash
+# Show what needs caching
+proagents offline changes
+
+# Output:
+┌─────────────────────────────────────────────────────────────┐
+│ Cache Changes Needed                                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ Modified since last cache:                                  │
+│ ├── src/components/UserProfile.tsx                         │
+│ ├── src/services/AuthService.ts                            │
+│ └── src/utils/validation.ts                                │
+│                                                             │
+│ Cache impact:                                               │
+│ • Analysis: Needs update (3 files changed)                 │
+│ • Patterns: Needs update (new pattern detected)            │
+│                                                             │
+│ Run 'proagents offline prepare --incremental' to update    │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Cache Storage
+
+### Local Storage
+
+```yaml
+offline:
+  cache:
+    storage:
+      type: "local"
+      path: ".proagents/cache"
+
+      # Encryption
+      encrypt: false
+
+      # Compression
+      compress: true
+```
+
+### Shared Cache
+
+```yaml
+offline:
+  cache:
+    storage:
+      type: "shared"
+      path: "/shared/proagents-cache"
+
+      # Team sharing
+      share_with_team: true
+      sync_frequency: "hourly"
+
+      # Access control
+      read_only: false
+```
+
+---
+
+## Cache Optimization
+
+### Size Management
+
+```yaml
+offline:
+  cache:
+    optimization:
+      # Maximum cache size
+      max_size: "500MB"
+
+      # Cleanup policy
+      cleanup:
+        when: "size > 80%"
+        strategy: "lru"  # Least recently used
+        keep_minimum: ["analysis", "standards"]
+
+      # Compression
+      compress_old:
+        after: "7d"
+        level: 9
+```
+
+### Priority-Based Retention
+
+```yaml
+offline:
+  cache:
+    retention:
+      priorities:
+        high:
+          - "analysis"
+          - "standards"
+        medium:
+          - "patterns"
+          - "templates"
+        low:
+          - "responses"
+
+      # Evict low priority first
+      eviction_order: ["low", "medium", "high"]
+```
+
+---
+
+## Best Practices
+
+1. **Regular Updates**: Run `prepare` daily for fresh cache
+2. **Monitor Size**: Keep cache under limit to avoid issues
+3. **Incremental Updates**: Use incremental caching for efficiency
+4. **Test Offline**: Periodically test offline mode works
+5. **Secure Cache**: Enable encryption for sensitive projects
+6. **Clean Up**: Remove expired cache regularly

package/proagents/offline-mode/offline-operations.md

@@ -0,0 +1,312 @@
+# Offline Operations
+
+Available operations when working without AI connectivity.
+
+---
+
+## Operation Categories
+
+### Fully Available Offline
+
+| Operation | Description |
+|-----------|-------------|
+| Git Operations | Commit, branch, merge, push/pull |
+| Testing | Run all tests locally |
+| Linting | Code style validation |
+| Building | Compile and bundle |
+| Standards Check | Validate against project standards |
+| Template Generation | Use cached templates |
+| Documentation | Generate from templates |
+| Changelog | Update changelog entries |
+
+### Degraded Mode
+
+| Operation | Online | Offline |
+|-----------|--------|---------|
+| Code Analysis | Full AI | Cached results |
+| Code Review | AI-powered | Checklist-based |
+| Documentation | AI-generated | Template-based |
+| Suggestions | Real-time | Cached patterns |
+
+### Unavailable Offline
+
+| Operation | Reason |
+|-----------|--------|
+| New Code Generation | Requires AI |
+| Complex Refactoring | Requires AI analysis |
+| Natural Language Processing | Requires AI |
+| Design Interpretation | Requires AI |
+| Context-Aware Suggestions | Requires AI |
+
+---
+
+## Using Offline Operations
+
+### Git Operations
+
+```bash
+# All git operations work offline
+proagents feature start "new-feature"   # Creates branch
+proagents commit                         # Commits changes
+
+# Queue push for when online
+proagents push --queue
+```
+
+### Testing
+
+```bash
+# Run tests normally
+proagents test run
+
+# Run with coverage
+proagents test coverage
+
+# Run specific tests
+proagents test run --file auth.test.ts
+```
+
+### Standards Validation
+
+```bash
+# Validate against cached standards
+proagents validate
+
+# Output:
+┌─────────────────────────────────────────────────────────────┐
+│ Standards Validation (Offline Mode)                         │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ Using cached standards from: 2 hours ago                   │
+│                                                             │
+│ ✓ Naming conventions: PASSED                               │
+│ ✓ File structure: PASSED                                   │
+│ ⚠ Code patterns: 2 warnings                                │
+│   └── src/utils/format.ts:15 - Consider using helper       │
+│   └── src/components/Card.tsx:42 - Missing memo            │
+│                                                             │
+│ Note: Full AI analysis available when online               │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Template Generation
+
+```bash
+# Generate from cached templates
+proagents generate component UserProfile
+
+# Output:
+┌─────────────────────────────────────────────────────────────┐
+│ Template Generation (Offline Mode)                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ Using cached template: component.tsx                        │
+│                                                             │
+│ Generated files:                                            │
+│ ├── src/components/UserProfile/index.tsx                   │
+│ ├── src/components/UserProfile/UserProfile.tsx             │
+│ ├── src/components/UserProfile/UserProfile.test.tsx        │
+│ └── src/components/UserProfile/UserProfile.module.css      │
+│                                                             │
+│ Note: AI customization available when online               │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Degraded Mode Operations
+
+### Code Review (Offline)
+
+```bash
+proagents review
+
+# Output:
+┌─────────────────────────────────────────────────────────────┐
+│ Code Review (Offline Mode - Checklist)                      │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ Automated Checks:                                           │
+│ ✓ Linting passed                                           │
+│ ✓ Type checking passed                                     │
+│ ✓ Tests passing                                            │
+│ ✓ No security issues detected                              │
+│                                                             │
+│ Manual Review Checklist:                                    │
+│ ☐ Code follows project conventions                         │
+│ ☐ Error handling is comprehensive                          │
+│ ☐ Edge cases are handled                                   │
+│ ☐ Documentation is complete                                │
+│ ☐ No hardcoded values                                      │
+│                                                             │
+│ AI-powered review available when online                    │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Documentation (Offline)
+
+```bash
+proagents docs generate
+
+# Output:
+┌─────────────────────────────────────────────────────────────┐
+│ Documentation (Offline Mode)                                │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ Using template-based documentation                         │
+│                                                             │
+│ Generated:                                                  │
+│ ├── docs/api/UserService.md (from JSDoc)                  │
+│ ├── docs/components/UserProfile.md (from template)        │
+│ └── docs/README.md (updated)                              │
+│                                                             │
+│ Queued for AI enhancement when online:                     │
+│ • Add usage examples                                       │
+│ • Generate architecture diagram                            │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Analysis (Offline)
+
+```bash
+proagents analyze
+
+# Output:
+┌─────────────────────────────────────────────────────────────┐
+│ Codebase Analysis (Offline Mode)                            │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ Using cached analysis from: 2 hours ago                    │
+│                                                             │
+│ Structure:                                                  │
+│ ├── Components: 45 files                                   │
+│ ├── Services: 12 files                                     │
+│ ├── Utils: 23 files                                        │
+│ └── Tests: 78 files                                        │
+│                                                             │
+│ Changes since cache:                                        │
+│ ├── 3 files modified                                       │
+│ └── 1 file added                                           │
+│                                                             │
+│ Note: Analysis may be outdated. Refresh when online.       │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Offline Queue
+
+### Queuing Operations
+
+```yaml
+offline:
+  queue:
+    enabled: true
+    max_items: 100
+
+    # What to queue
+    queue_operations:
+      - "ai_review"
+      - "ai_documentation"
+      - "ai_suggestions"
+      - "sync_to_cloud"
+
+    # Process when online
+    auto_process: true
+```
+
+### Managing Queue
+
+```bash
+# View queued operations
+proagents offline queue
+
+# Output:
+┌─────────────────────────────────────────────────────────────┐
+│ Offline Queue                                               │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ Queued Items: 5                                             │
+│                                                             │
+│ 1. AI Code Review - UserService.ts                         │
+│    Queued: 30 min ago                                       │
+│                                                             │
+│ 2. Generate Documentation - AuthModule                      │
+│    Queued: 1 hour ago                                       │
+│                                                             │
+│ 3. Push to remote - feature/user-auth                      │
+│    Queued: 2 hours ago                                      │
+│                                                             │
+│ 4. Sync analysis to cloud                                   │
+│    Queued: 2 hours ago                                      │
+│                                                             │
+│ 5. Request AI suggestions for performance                   │
+│    Queued: 3 hours ago                                      │
+│                                                             │
+│ Items will process automatically when online               │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+
+# Clear queue
+proagents offline queue clear
+
+# Remove specific item
+proagents offline queue remove 3
+```
+
+---
+
+## Offline Workflow Example
+
+```bash
+# 1. Check offline status
+proagents offline status
+# → Offline mode active, cache fresh
+
+# 2. Start feature
+proagents feature start "user-settings"
+# → Branch created locally
+
+# 3. Generate component from template
+proagents generate component SettingsPanel
+# → Component generated from cached template
+
+# 4. Write code and tests manually
+# (AI assistance unavailable)
+
+# 5. Run tests
+proagents test run
+# → Tests run normally
+
+# 6. Validate standards
+proagents validate
+# → Validates against cached standards
+
+# 7. Commit changes
+proagents commit -m "Add settings panel"
+# → Committed locally
+
+# 8. Queue for AI review when online
+proagents review --queue
+# → Added to offline queue
+
+# 9. When back online
+proagents offline sync
+# → Processes queue, pushes changes, runs AI review
+```
+
+---
+
+## Best Practices
+
+1. **Prepare Before Going Offline**: Run `proagents offline prepare`
+2. **Use Templates**: Leverage cached templates for consistency
+3. **Queue AI Tasks**: Queue AI-dependent tasks for later
+4. **Test Thoroughly**: Run full test suite since AI can't catch issues
+5. **Document Changes**: Keep notes for AI review when online
+6. **Sync Promptly**: Process queue soon after going online