proagents 1.0.0

package/proagents/troubleshooting/workflow-issues.md

@@ -0,0 +1,571 @@
+# Troubleshooting Workflow Issues
+
+Solutions for workflow, feature, and phase-related problems.
+
+---
+
+## Feature Management Issues
+
+### Cannot Start New Feature
+
+**Symptom:**
+```
+Error: Cannot start new feature
+Reason: Feature 'user-auth' already in progress
+```
+
+**Solutions:**
+
+```bash
+# Check current feature status
+proagents status
+
+# Option 1: Resume current feature
+proagents feature resume
+
+# Option 2: Complete current feature
+proagents feature complete
+
+# Option 3: Abandon current feature (if stuck)
+proagents feature abandon --confirm
+
+# Option 4: Enable parallel features
+parallel_features:
+  enabled: true
+  max_concurrent: 3
+
+# Then start parallel feature
+proagents feature start "new-feature" --parallel
+```
+
+---
+
+### Feature State Corrupted
+
+**Symptom:**
+- Feature shows wrong phase
+- Feature data doesn't match reality
+- Inconsistent state messages
+
+**Solutions:**
+
+```bash
+# Diagnose feature state
+proagents feature diagnose user-auth
+
+# Repair feature state
+proagents feature repair user-auth
+
+# Manual state reset
+proagents feature reset-phase user-auth --to implementation
+
+# If severely corrupted, recreate
+proagents feature export user-auth > backup.json
+proagents feature delete user-auth --force
+proagents feature import backup.json --fix
+```
+
+---
+
+### Lost Feature Context
+
+**Symptom:**
+- AI doesn't remember previous discussions
+- Requirements seem forgotten
+- Starting over each session
+
+**Solutions:**
+
+```bash
+# Check if context is saved
+proagents feature context show
+
+# Reload context
+proagents feature context reload
+
+# Manually add context
+proagents feature context add "Key requirement: must support SSO"
+
+# Configure context persistence
+feature_context:
+  persist: true
+  save_frequency: "on_phase_complete"
+  include:
+    - "requirements"
+    - "decisions"
+    - "ai_conversations"
+```
+
+---
+
+## Phase Issues
+
+### Phase Won't Complete
+
+**Symptom:**
+```
+Error: Phase 'testing' cannot complete
+Missing requirements:
+- Test coverage below 80%
+- 2 failing tests
+```
+
+**Solutions:**
+
+```bash
+# Check phase requirements
+proagents phase requirements testing
+
+# View detailed status
+proagents phase status testing --verbose
+
+# Fix the issues
+npm test -- --coverage
+# Fix failing tests
+
+# Or override requirements (with justification)
+proagents phase complete testing --override --reason "Tests verified externally"
+
+# Or adjust thresholds
+workflow:
+  phases:
+    testing:
+      coverage_threshold: 70  # Lower temporarily
+```
+
+---
+
+### Phase Stuck/Hanging
+
+**Symptom:**
+- Phase started but never completes
+- No progress indicators
+- System unresponsive
+
+**Solutions:**
+
+```bash
+# Check for background processes
+proagents phase status --processes
+
+# Cancel stuck operation
+proagents phase cancel
+
+# Resume from last checkpoint
+proagents phase resume --from-checkpoint
+
+# Force restart phase
+proagents phase restart implementation --force
+
+# Set timeout to prevent future hangs
+workflow:
+  phases:
+    implementation:
+      timeout: 3600  # 1 hour max
+      checkpoint_interval: 300  # Save every 5 min
+```
+
+---
+
+### Wrong Phase Sequence
+
+**Symptom:**
+- Phases running out of order
+- Skipped phases unexpectedly
+- Dependencies not respected
+
+**Solutions:**
+
+```bash
+# View phase order
+proagents phase list --order
+
+# Check dependencies
+proagents phase dependencies
+
+# Reset to correct phase
+proagents phase goto requirements
+
+# Fix configuration
+workflow:
+  phases:
+    # Define correct order
+    order:
+      - "init"
+      - "analysis"
+      - "requirements"
+      - "design"
+      - "implementation"
+      - "testing"
+      - "review"
+      - "documentation"
+      - "deployment"
+
+    # Define dependencies
+    dependencies:
+      testing:
+        requires: ["implementation"]
+      deployment:
+        requires: ["testing", "review"]
+```
+
+---
+
+## Checkpoint Issues
+
+### Checkpoint Not Triggering
+
+**Symptom:**
+- Expected checkpoint didn't appear
+- Automatic approvals when manual expected
+- Missing review opportunities
+
+**Solutions:**
+
+```bash
+# Check checkpoint configuration
+proagents checkpoint list
+
+# Verify checkpoint is enabled
+checkpoints:
+  after_design: true  # Should be true
+
+# Check conditions
+proagents checkpoint status after_design
+
+# Force checkpoint
+proagents checkpoint trigger after_design
+
+# Debug checkpoint conditions
+proagents checkpoint debug after_design
+```
+
+---
+
+### Stuck at Checkpoint
+
+**Symptom:**
+```
+Waiting for approval: before_deployment
+Status: Pending for 48 hours
+```
+
+**Solutions:**
+
+```bash
+# Check who can approve
+proagents approval who-can-approve
+
+# Send reminder
+proagents approval remind
+
+# Check if approver is available
+proagents team status
+
+# Use delegate approver
+proagents approval delegate @backup-approver
+
+# Emergency bypass (if authorized)
+proagents approval bypass --reason "Approver unavailable, tested externally"
+```
+
+---
+
+### Checkpoint Data Lost
+
+**Symptom:**
+- Previous checkpoint decisions not saved
+- Need to re-approve completed checkpoints
+- Review comments missing
+
+**Solutions:**
+
+```bash
+# Check checkpoint history
+proagents checkpoint history
+
+# Restore from backup
+proagents checkpoint restore before_deployment --from backup
+
+# Re-record decision manually
+proagents checkpoint record before_deployment --approved --by @tech-lead --date "2024-01-15"
+
+# Enable checkpoint persistence
+checkpoints:
+  persistence:
+    enabled: true
+    backup: true
+    retention_days: 90
+```
+
+---
+
+## Parallel Feature Issues
+
+### Feature Conflicts
+
+**Symptom:**
+```
+Warning: Conflict detected
+Features: user-auth, user-profile
+Conflicting files: src/types/user.ts
+```
+
+**Solutions:**
+
+```bash
+# View conflict details
+proagents conflict show user-auth user-profile
+
+# Resolve manually
+proagents conflict resolve --strategy manual
+
+# Use merge strategy
+proagents conflict resolve --strategy auto-merge
+
+# Coordinate with other developer
+proagents feature lock src/types/user.ts --message "Modifying user types"
+
+# Sequential development
+proagents feature pause user-profile --until user-auth-complete
+```
+
+---
+
+### Feature Dependencies Not Respected
+
+**Symptom:**
+- Dependent feature started before dependency complete
+- Missing functionality from incomplete dependency
+- Integration errors
+
+**Solutions:**
+
+```bash
+# Check dependencies
+proagents feature dependencies user-profile
+
+# Set explicit dependency
+proagents feature depends user-profile --on user-auth
+
+# Wait for dependency
+proagents feature wait user-profile --for user-auth
+
+# Configuration
+parallel_features:
+  dependency_check: strict  # Block until dependencies met
+  warn_on_conflict: true
+```
+
+---
+
+### Merge Order Wrong
+
+**Symptom:**
+- Features merged in wrong order
+- Dependent code merged before dependency
+- Integration issues after merge
+
+**Solutions:**
+
+```bash
+# View recommended merge order
+proagents feature merge-order
+
+# Set merge priority
+proagents feature priority user-auth --level 1
+proagents feature priority user-profile --level 2
+
+# Force merge order
+parallel_features:
+  merge_order:
+    strategy: "dependency_first"
+    allow_override: false
+
+# Rollback and re-merge
+git revert HEAD~2
+proagents feature merge user-auth
+proagents feature merge user-profile
+```
+
+---
+
+## Mode Issues
+
+### Wrong Mode Detected
+
+**Symptom:**
+- Bug fix detected as full feature
+- Quick change requiring full workflow
+- Mode switch not working
+
+**Solutions:**
+
+```bash
+# Check detected mode
+proagents mode current
+
+# Override mode
+proagents mode set bug_fix
+
+# Force mode for current operation
+proagents fix "issue" --mode quick_change
+
+# Configure detection
+workflow:
+  mode_detection:
+    bug_fix:
+      indicators:
+        - "fix"
+        - "bug"
+        - "issue"
+      max_files: 5
+
+    quick_change:
+      indicators:
+        - "update"
+        - "config"
+        - "typo"
+      max_files: 2
+```
+
+---
+
+### Cannot Change Modes
+
+**Symptom:**
+```
+Error: Cannot switch to full_workflow mode
+Reason: In progress work would be lost
+```
+
+**Solutions:**
+
+```bash
+# Save current progress
+proagents progress save
+
+# Then switch
+proagents mode switch full_workflow
+
+# Or force switch (may lose progress)
+proagents mode switch full_workflow --force --reason "Need full analysis"
+
+# Configuration for smoother switching
+workflow:
+  mode_switching:
+    auto_save: true
+    confirm_on_data_loss: true
+    preserve_context: true
+```
+
+---
+
+## Recovery Procedures
+
+### Reset Workflow State
+
+```bash
+# Soft reset (preserve work)
+proagents workflow reset --soft
+
+# Hard reset (start fresh)
+proagents workflow reset --hard
+
+# Reset specific feature
+proagents feature reset user-auth
+
+# Reset to specific phase
+proagents feature reset user-auth --to analysis
+```
+
+### Export/Import Feature State
+
+```bash
+# Export current state
+proagents feature export user-auth > feature-backup.json
+
+# Import state
+proagents feature import feature-backup.json
+
+# Transfer to another machine
+scp feature-backup.json other-machine:/path/
+# On other machine:
+proagents feature import feature-backup.json
+```
+
+### Recover from Corruption
+
+```bash
+# Diagnose issues
+proagents doctor --workflow
+
+# Auto-repair
+proagents repair --workflow
+
+# Manual recovery
+cd .proagents/features/user-auth
+# Review and fix JSON files manually
+
+# Rebuild from git history
+proagents feature rebuild user-auth --from-git
+```
+
+---
+
+## Prevention
+
+### Enable Auto-Save
+
+```yaml
+workflow:
+  auto_save:
+    enabled: true
+    interval: 300  # Every 5 minutes
+    on_phase_complete: true
+    on_checkpoint: true
+
+  backup:
+    enabled: true
+    frequency: "daily"
+    retention: 30
+```
+
+### Configure Health Checks
+
+```yaml
+workflow:
+  health_check:
+    enabled: true
+    interval: 3600  # Hourly
+    auto_repair: true
+    notify_on_issues: true
+```
+
+### Set Up Monitoring
+
+```bash
+# Enable workflow monitoring
+proagents monitor enable workflow
+
+# View workflow metrics
+proagents monitor dashboard workflow
+
+# Set up alerts
+monitoring:
+  workflow:
+    alerts:
+      - condition: "feature_stuck > 24h"
+        action: "notify"
+      - condition: "phase_timeout"
+        action: "auto_checkpoint"
+```
+
+---
+
+## Related Documentation
+
+- [Workflow Guide](../WORKFLOW.md)
+- [Parallel Features](../parallel-features/README.md)
+- [Checkpoints](../WORKFLOW.md#checkpoints)
+- [Approval Workflows](../approval-workflows/README.md)

package/proagents/ui-integration/README.md

@@ -0,0 +1,77 @@
+# UI Integration
+
+Design-to-code integration from Figma, exports, or sketches.
+
+---
+
+## Overview
+
+Transform designs into implementation specifications automatically.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Figma Guide](./figma-guide.md) | Figma API integration |
+| [Manual Export Guide](./manual-export-guide.md) | Working with design exports |
+| [Sketch Interpretation](./sketch-interpretation.md) | AI interpretation of wireframes |
+
+## Supported Sources
+
+| Source | Method | Quality |
+|--------|--------|---------|
+| Figma | API integration | Highest (exact specs) |
+| Sketch/XD | Export files | High |
+| PNG/PDF | AI analysis | Medium |
+| Hand sketches | AI interpretation | Basic |
+
+## Quick Start
+
+### Figma Integration
+
+```bash
+# Connect Figma file
+proagents ui figma connect "https://figma.com/file/..."
+
+# Extract design tokens
+proagents ui figma tokens
+
+# Generate component specs
+proagents ui figma components
+```
+
+### Manual Export
+
+```bash
+# Analyze design export
+proagents ui analyze ./designs/homepage.png
+
+# Generate specs
+proagents ui generate-specs
+```
+
+## Configuration
+
+```yaml
+# proagents.config.yaml
+ui_integration:
+  figma:
+    enabled: true
+    api_token_env: "FIGMA_TOKEN"
+
+  extraction:
+    design_tokens: true
+    components: true
+    assets: true
+
+  output:
+    tokens_file: "src/styles/tokens.ts"
+    specs_dir: "docs/ui-specs/"
+```
+
+## Output
+
+- Design tokens (colors, typography, spacing)
+- Component specifications
+- Asset exports (icons, images)
+- Implementation guidelines