proagents 1.6.17 → 1.6.19

package/.proagents/existing-projects/challenges.md

@@ -1,861 +0,0 @@
-# Challenges in Existing Projects
-
-Comprehensive analysis of issues existing projects face when adopting ProAgents.
-
----
-
-## Challenge Categories
-
-1. [Codebase Analysis Challenges](#1-codebase-analysis-challenges)
-2. [Pattern & Convention Conflicts](#2-pattern--convention-conflicts)
-3. [Technical Debt Burden](#3-technical-debt-burden)
-4. [Documentation Gaps](#4-documentation-gaps)
-5. [Team & Process Resistance](#5-team--process-resistance)
-6. [Tool & Infrastructure Conflicts](#6-tool--infrastructure-conflicts)
-7. [Gradual Adoption Complexity](#7-gradual-adoption-complexity)
-8. [Configuration Complexity](#8-configuration-complexity)
-
----
-
-## 1. Codebase Analysis Challenges
-
-### Issue 1.1: Inconsistent Code Patterns
-
-**Problem:**
-```
-src/
-├── components/
-│   ├── UserProfile.tsx      # Functional component
-│   ├── Dashboard.jsx        # Class component (legacy)
-│   ├── settings.js          # No TypeScript
-│   └── admin-panel/         # Different naming convention
-│       └── AdminPanel.tsx
-```
-
-Different patterns in the same codebase confuse analysis:
-- Mixed functional/class components
-- TypeScript and JavaScript mixed
-- Inconsistent naming conventions
-- Different folder structures
-
-**Impact:**
-- Pattern detection returns low confidence
-- Generated code may not match existing style
-- Inconsistent recommendations
-
-**Solution:** See `pattern-reconciliation.md`
-
----
-
-### Issue 1.2: Complex Dependency Graphs
-
-**Problem:**
-```
-Circular dependencies detected:
-UserService → AuthService → UserService
-
-Tight coupling found:
-Dashboard imports from 45 different modules
-```
-
-Existing projects often have:
-- Circular dependencies
-- Tightly coupled modules
-- God objects/files
-- Spaghetti imports
-
-**Impact:**
-- Dependency mapping produces messy graphs
-- Impact analysis is unreliable
-- New features may unknowingly break things
-
-**Solution:**
-```yaml
-# Handle gracefully during analysis
-analysis:
-  circular_dependencies:
-    action: "document"  # Don't block, just document
-    suggest_fix: true
-
-  tight_coupling:
-    threshold: 20  # imports
-    action: "warn"
-```
-
----
-
-### Issue 1.3: Missing Type Information
-
-**Problem:**
-```javascript
-// No types, no JSDoc
-function processData(data) {
-  const result = data.items.map(x => x.value * 2);
-  return { processed: result, meta: data.meta };
-}
-```
-
-Untyped code makes analysis difficult:
-- Can't infer function signatures
-- Can't detect API contracts
-- Component props unknown
-
-**Impact:**
-- Incomplete analysis reports
-- Generated code may have type mismatches
-- Integration points unclear
-
-**Solution:**
-```yaml
-# Infer types where possible
-analysis:
-  type_inference:
-    enabled: true
-    use_jsdoc: true
-    use_usage_patterns: true
-    generate_type_stubs: true
-```
-
----
-
-### Issue 1.4: Large Monolithic Files
-
-**Problem:**
-```
-src/utils/helpers.js - 3,500 lines
-src/services/api.js - 2,800 lines
-src/components/Dashboard.jsx - 1,200 lines
-```
-
-Large files are hard to analyze:
-- Multiple responsibilities
-- Hard to identify what's related
-- Conflict-prone for parallel features
-
-**Impact:**
-- Analysis timeout on large files
-- Incorrect pattern detection
-- High conflict risk
-
-**Solution:**
-```yaml
-analysis:
-  large_files:
-    threshold: 500  # lines
-    action: "split_analysis"  # Analyze in sections
-    suggest_refactoring: true
-```
-
----
-
-## 2. Pattern & Convention Conflicts
-
-### Issue 2.1: Multiple Patterns for Same Thing
-
-**Problem:**
-```typescript
-// Pattern A: Redux for state (older code)
-const mapStateToProps = (state) => ({ user: state.user });
-
-// Pattern B: Context for state (newer code)
-const user = useContext(UserContext);
-
-// Pattern C: Zustand for state (newest code)
-const user = useUserStore((state) => state.user);
-```
-
-**Impact:**
-- Which pattern should new code follow?
-- Inconsistent recommendations
-- Team confusion
-
-**Solution:** See `pattern-reconciliation.md` - Define primary vs legacy patterns
-
----
-
-### Issue 2.2: Naming Convention Conflicts
-
-**Problem:**
-```
-Existing naming:
-- user_service.ts (snake_case)
-- UserComponent.tsx (PascalCase)
-- use-auth.ts (kebab-case)
-- utilHelpers.js (camelCase)
-
-ProAgents recommends:
-- userService.ts (camelCase)
-- UserComponent.tsx (PascalCase)
-- useAuth.ts (camelCase with prefix)
-```
-
-**Impact:**
-- Generated code looks different
-- Inconsistent codebase
-- Team confusion
-
-**Solution:**
-```yaml
-# Adapt to project conventions, don't enforce defaults
-conventions:
-  detect_from_codebase: true
-  override_defaults: true
-
-  detected:
-    services: "snake_case"  # Will use project's convention
-    hooks: "kebab-case"     # Will use project's convention
-```
-
----
-
-### Issue 2.3: Architecture Pattern Mismatch
-
-**Problem:**
-```
-Project uses: Feature-sliced design
-ProAgents expects: Feature-based or Atomic design
-
-Project structure:
-src/
-├── entities/
-├── features/
-├── widgets/
-├── pages/
-└── shared/
-
-ProAgents template:
-src/
-├── components/
-├── features/
-├── hooks/
-├── services/
-└── utils/
-```
-
-**Impact:**
-- Generated scaffolding doesn't fit
-- Recommendations don't apply
-- File placement confusion
-
-**Solution:**
-```yaml
-architecture:
-  detect: true
-  adapt_to_detected: true
-
-  # Map detected to ProAgents concepts
-  mapping:
-    "entities": "models"
-    "widgets": "components"
-    "shared": "common"
-```
-
----
-
-## 3. Technical Debt Burden
-
-### Issue 3.1: Low Test Coverage
-
-**Problem:**
-```
-Current coverage: 25%
-Critical paths untested: 60%
-No integration tests
-E2E tests: None
-```
-
-**Impact:**
-- Can't verify new features don't break things
-- Testing phase blocked
-- Confidence in changes is low
-
-**Solution:**
-```yaml
-# Don't block, but track and improve
-testing:
-  existing_coverage:
-    current: 25%
-    require_for_new_code: 80%
-    require_for_existing: false  # Don't block
-
-  improvement_mode:
-    enabled: true
-    add_tests_for_touched_code: true
-    suggest_critical_path_tests: true
-```
-
----
-
-### Issue 3.2: Security Vulnerabilities
-
-**Problem:**
-```
-npm audit:
-- 5 critical vulnerabilities
-- 12 high vulnerabilities
-- 23 moderate vulnerabilities
-
-Code issues:
-- SQL concatenation in 3 places
-- Hardcoded secrets in 2 files
-- No input validation in 15 endpoints
-```
-
-**Impact:**
-- Security scans fail
-- Blocking deployment
-- Risk in production
-
-**Solution:**
-```yaml
-security:
-  existing_issues:
-    action: "document_and_track"
-    block_new_issues: true
-    block_existing: false
-
-  remediation:
-    create_tracking_issues: true
-    prioritize_critical: true
-    timeline: "gradual"
-```
-
----
-
-### Issue 3.3: Outdated Dependencies
-
-**Problem:**
-```
-React: 16.8.0 (current: 18.2.0)
-Node: 14.x (EOL)
-TypeScript: 4.0 (current: 5.3)
-Webpack: 4 (current: 5)
-```
-
-**Impact:**
-- Analysis tools may not support old versions
-- Generated code may use newer syntax
-- Security vulnerabilities
-
-**Solution:**
-```yaml
-dependencies:
-  compatibility_mode:
-    enabled: true
-    target_versions:
-      react: "16.8"  # Generate compatible code
-      node: "14"
-      typescript: "4.0"
-
-  upgrade_tracking:
-    suggest_upgrades: true
-    create_upgrade_plan: true
-```
-
----
-
-### Issue 3.4: Missing Error Handling
-
-**Problem:**
-```typescript
-// Existing code - no error handling
-async function fetchUser(id) {
-  const response = await api.get(`/users/${id}`);
-  return response.data;
-}
-
-// No error boundaries
-// No try-catch patterns
-// Errors crash the app
-```
-
-**Impact:**
-- Analysis shows quality issues
-- New code may expose existing bugs
-- Integration may break
-
-**Solution:**
-```yaml
-error_handling:
-  existing_gaps:
-    document: true
-    require_for_new: true
-    suggest_wrappers: true
-
-  gradual_fix:
-    enabled: true
-    priority_order:
-      - "api_calls"
-      - "user_inputs"
-      - "critical_flows"
-```
-
----
-
-## 4. Documentation Gaps
-
-### Issue 4.1: No Architecture Documentation
-
-**Problem:**
-```
-docs/
-├── README.md (outdated)
-└── api.md (incomplete)
-
-Missing:
-- Architecture decisions
-- Module documentation
-- API documentation
-- Component documentation
-```
-
-**Impact:**
-- Analysis relies on code only
-- Recommendations may miss context
-- New features may contradict hidden decisions
-
-**Solution:**
-```yaml
-documentation:
-  existing_gaps:
-    generate_from_code: true
-    mark_as_auto_generated: true
-    request_review: true
-
-  reverse_engineer:
-    architecture: true
-    api: true
-    components: true
-```
-
----
-
-### Issue 4.2: Outdated Documentation
-
-**Problem:**
-```markdown
-# API Documentation (Last updated: 2022)
-
-## /api/users
-Returns user list...
-
-# Reality: Endpoint changed to /api/v2/users
-# Reality: Response format completely different
-```
-
-**Impact:**
-- Analysis based on wrong information
-- Generated integration may fail
-- Team confusion
-
-**Solution:**
-```yaml
-documentation:
-  staleness_check:
-    enabled: true
-    compare_to_code: true
-    flag_mismatches: true
-
-  auto_update:
-    enabled: true
-    preserve_manual_content: true
-    mark_updates: true
-```
-
----
-
-## 5. Team & Process Resistance
-
-### Issue 5.1: Existing Workflows
-
-**Problem:**
-```
-Team's current workflow:
-1. Create branch
-2. Code (no formal process)
-3. PR review
-4. Merge
-
-ProAgents workflow:
-10 phases with checkpoints
-```
-
-**Impact:**
-- Perceived as too heavyweight
-- Team resistance
-- Workflow collision
-
-**Solution:** See `team-onboarding.md` - Start with minimal adoption
-
----
-
-### Issue 5.2: Different Git Conventions
-
-**Problem:**
-```
-Existing conventions:
-- Branches: feature-AUTH-123
-- Commits: "[AUTH-123] Add login"
-- PRs: Link to Jira ticket
-
-ProAgents default:
-- Branches: feature/user-auth
-- Commits: feat(auth): add login
-- PRs: Template with phases
-```
-
-**Impact:**
-- Generated commits look different
-- CI/CD may break (relies on conventions)
-- Team confusion
-
-**Solution:**
-```yaml
-git:
-  adapt_to_existing: true
-
-  detected:
-    branch_pattern: "feature-{TICKET}-{description}"
-    commit_pattern: "[{TICKET}] {message}"
-
-  use_detected: true  # Don't override
-```
-
----
-
-### Issue 5.3: Existing Code Review Process
-
-**Problem:**
-```
-Team uses:
-- Required reviewers: 2
-- CODEOWNERS for specific paths
-- Custom PR template
-- Required checks: lint, test, build
-
-ProAgents adds:
-- Code review phase
-- Security check
-- Documentation check
-```
-
-**Impact:**
-- Duplicate review processes
-- Confusion about requirements
-- Slower PRs
-
-**Solution:**
-```yaml
-review:
-  integrate_with_existing: true
-
-  mapping:
-    proagents_review: "existing_pr_review"
-    skip_duplicate_checks: true
-
-  additional_checks:
-    security: true  # Add to existing
-    documentation: true
-```
-
----
-
-## 6. Tool & Infrastructure Conflicts
-
-### Issue 6.1: Existing CI/CD Pipeline
-
-**Problem:**
-```yaml
-# Existing .github/workflows/main.yml
-- runs lint
-- runs tests
-- builds
-- deploys
-
-# ProAgents wants to add
-- security scan
-- documentation check
-- phase verification
-```
-
-**Impact:**
-- Pipeline conflicts
-- Duplicate jobs
-- Longer CI times
-
-**Solution:**
-```yaml
-cicd:
-  integration_mode: "extend"  # Don't replace
-
-  extend:
-    add_jobs:
-      - security_scan
-      - doc_check
-
-  reuse_existing:
-    lint: true
-    test: true
-    build: true
-```
-
----
-
-### Issue 6.2: Existing Linting/Formatting
-
-**Problem:**
-```
-Project uses:
-- ESLint with custom config
-- Prettier with specific settings
-- Custom rules
-
-ProAgents recommends:
-- Different ESLint rules
-- Different formatting
-```
-
-**Impact:**
-- Generated code doesn't match formatting
-- Lint errors on generated code
-- Conflicts
-
-**Solution:**
-```yaml
-linting:
-  use_existing: true
-
-  extend_only:
-    security_rules: true  # Add these
-
-  respect:
-    eslint_config: true
-    prettier_config: true
-```
-
----
-
-### Issue 6.3: Existing Automation
-
-**Problem:**
-```
-Project has:
-- Husky pre-commit hooks
-- lint-staged
-- Commitlint
-- Custom scripts
-
-ProAgents automation:
-- May conflict with existing hooks
-- Different commit message format
-```
-
-**Impact:**
-- Hook failures
-- Commit rejections
-- Developer frustration
-
-**Solution:**
-```yaml
-automation:
-  conflict_detection: true
-
-  hooks:
-    integrate_with_husky: true
-    respect_existing: true
-
-  add_to_existing:
-    pre_commit:
-      - "proagents-check"
-    post_commit:
-      - "proagents-log"
-```
-
----
-
-## 7. Gradual Adoption Complexity
-
-### Issue 7.1: Can't Change Everything at Once
-
-**Problem:**
-```
-500+ files in codebase
-20+ developers
-Active features in progress
-Can't pause development to adopt new system
-```
-
-**Impact:**
-- Partial adoption causes confusion
-- Some code follows new patterns, some doesn't
-- Inconsistent experience
-
-**Solution:** See `gradual-adoption.md`
-
----
-
-### Issue 7.2: Active Feature Branches
-
-**Problem:**
-```
-Current branches:
-- feature/payment-system (2 weeks old)
-- feature/user-dashboard (1 week old)
-- feature/reporting (just started)
-
-Starting ProAgents now would conflict
-```
-
-**Impact:**
-- Existing features don't have tracking
-- Merge conflicts with new structure
-- Confusion about which process to follow
-
-**Solution:**
-```yaml
-adoption:
-  existing_features:
-    action: "grandfathered"  # Let them complete as-is
-    track_retroactively: false
-    apply_to_new_only: true
-
-  transition:
-    start_date: "after current sprint"
-    pilot_feature: true
-```
-
----
-
-### Issue 7.3: Mixed New/Old Code
-
-**Problem:**
-```
-After partial adoption:
-src/
-├── features/
-│   ├── auth/            # ProAgents style
-│   │   ├── status.json
-│   │   └── ...
-│   └── payments/        # Old style
-│       └── ... (no tracking)
-```
-
-**Impact:**
-- Inconsistent tracking
-- Partial visibility
-- Confusing for team
-
-**Solution:**
-```yaml
-coexistence:
-  enabled: true
-
-  identify:
-    new_style_paths:
-      - "src/features/*"
-      - marker_file: "status.json"
-
-  handle_legacy:
-    track: false
-    suggest_migration: true
-```
-
----
-
-## 8. Configuration Complexity
-
-### Issue 8.1: Too Many Options
-
-**Problem:**
-```
-User overwhelmed by:
-- 50+ configuration options
-- What applies to their project?
-- Reasonable defaults for existing projects?
-```
-
-**Impact:**
-- Configuration paralysis
-- Wrong settings chosen
-- Suboptimal experience
-
-**Solution:**
-```yaml
-# Smart defaults for existing projects
-init:
-  mode: "existing"
-
-  auto_configure:
-    detect_from_codebase: true
-    suggest_settings: true
-    explain_choices: true
-
-  presets:
-    available:
-      - "minimal"     # Least intrusive
-      - "standard"    # Balanced
-      - "full"        # All features
-    default_for_existing: "minimal"
-```
-
----
-
-### Issue 8.2: Exceptions Everywhere
-
-**Problem:**
-```
-Project has many exceptions:
-- This folder follows different conventions
-- This file is auto-generated, don't analyze
-- This module uses legacy patterns intentionally
-```
-
-**Impact:**
-- Generic rules don't apply
-- False positives in analysis
-- Noise in reports
-
-**Solution:**
-```yaml
-exceptions:
-  enabled: true
-
-  ignore_paths:
-    - "generated/**"
-    - "vendor/**"
-    - "legacy/**"
-
-  pattern_exceptions:
-    - path: "src/admin/**"
-      reason: "Uses different framework"
-      patterns:
-        naming: "custom"
-
-  document_exceptions: true
-```
-
----
-
-## Summary: Issue Impact Matrix
-
-| Issue | Frequency | Impact | Effort to Solve |
-|-------|-----------|--------|-----------------|
-| Inconsistent patterns | Very High | High | Medium |
-| Low test coverage | High | High | High |
-| Naming conflicts | High | Medium | Low |
-| Outdated dependencies | Medium | High | High |
-| Missing documentation | High | Medium | Medium |
-| Team resistance | Medium | High | Medium |
-| CI/CD conflicts | Medium | Medium | Low |
-| Existing workflows | High | Medium | Low |
-| Configuration complexity | High | Low | Low |
-| Active branches | Medium | Medium | Low |
-
----
-
-## Next Steps
-
-1. Run `pa:assess-compatibility` to identify which issues affect your project
-2. Review `gradual-adoption.md` for step-by-step adoption
-3. Use `pattern-reconciliation.md` to handle convention conflicts
-4. See `coexistence-mode.md` for running alongside existing workflows