proagents 1.0.0

package/proagents/automation/decision-defaults.yaml

@@ -0,0 +1,317 @@
+# Decision Defaults Configuration
+# Pre-configured answers for common AI questions
+# Prevents workflow interruptions by providing automatic decisions
+
+# =============================================================================
+# AUTOMATION LEVEL
+# =============================================================================
+automation:
+  # full: No user intervention, all decisions auto-made
+  # semi: Only pause for critical decisions
+  # guided: Pause at checkpoints only
+  # manual: Ask for guidance (traditional mode)
+  level: "full"
+
+  # Log all auto-decisions for post-review
+  log_decisions: true
+
+  # Show summary after workflow completion
+  show_summary: true
+
+  # Confidence threshold (decisions below this are flagged)
+  confidence_threshold: "medium"  # high, medium, low
+
+# =============================================================================
+# ARCHITECTURE DECISIONS
+# =============================================================================
+architecture:
+  # API Style
+  api_style: "rest"  # rest, graphql, grpc, trpc
+
+  # State Management
+  state_management:
+    global: "zustand"  # zustand, redux, jotai, mobx
+    server: "react-query"  # react-query, swr, apollo
+    forms: "react-hook-form"  # react-hook-form, formik
+
+  # Styling
+  styling: "tailwind"  # tailwind, css-modules, styled-components, scss
+
+  # Database
+  database: "postgresql"  # postgresql, mysql, mongodb, sqlite
+
+  # ORM
+  orm: "prisma"  # prisma, typeorm, drizzle, knex
+
+  # Authentication
+  auth:
+    method: "jwt"  # jwt, session, oauth
+    storage: "httponly-cookie"  # httponly-cookie, localstorage, memory
+    provider: "custom"  # custom, next-auth, auth0, clerk
+
+  # Caching
+  caching: "react-query"  # react-query, redis, in-memory
+
+# =============================================================================
+# CODE STYLE DECISIONS
+# =============================================================================
+code_style:
+  # Components
+  component:
+    style: "functional"  # functional, class
+    memo: "when-needed"  # always, when-needed, never
+    display_name: true
+
+  # Exports
+  exports:
+    style: "named"  # named, default, mixed
+    barrel_files: true  # Use index.ts for re-exports
+
+  # TypeScript
+  typescript:
+    strict: true
+    props_style: "interface"  # interface, type
+    return_types: "infer"  # explicit, infer
+
+  # Naming Conventions
+  naming:
+    components: "PascalCase"
+    hooks: "useCamelCase"
+    services: "camelCase"
+    utilities: "camelCase"
+    constants: "UPPER_SNAKE_CASE"
+    types: "PascalCase"
+    files:
+      components: "PascalCase"
+      others: "kebab-case"
+
+  # File Organization
+  organization:
+    components: "folder-per-component"  # folder-per-component, flat
+    colocate_tests: true
+    colocate_styles: true
+
+# =============================================================================
+# TESTING DECISIONS
+# =============================================================================
+testing:
+  # Frameworks
+  unit_framework: "vitest"  # vitest, jest
+  e2e_framework: "playwright"  # playwright, cypress
+  component_testing: "testing-library"
+
+  # Coverage
+  coverage:
+    target: 80
+    minimum: 60
+    fail_below_minimum: true
+
+  # Test Location
+  location: "colocated"  # colocated, separate (__tests__ folder)
+
+  # What to Test
+  always_test:
+    - "components"
+    - "hooks"
+    - "services"
+    - "utilities"
+
+  # Mocking
+  mock_strategy: "minimal"  # minimal, comprehensive
+
+# =============================================================================
+# IMPLEMENTATION DECISIONS
+# =============================================================================
+implementation:
+  # When multiple approaches exist
+  approach_selection: "simplest"  # simplest, most_performant, most_scalable
+
+  # Error Handling
+  error_handling:
+    style: "try-catch"  # try-catch, result-type, error-boundary
+    logging: true
+    user_friendly_messages: true
+
+  # Async Patterns
+  async:
+    style: "async-await"  # async-await, promises
+    error_handling: "try-catch"
+
+  # Null/Undefined Handling
+  null_handling: "optional-chaining"  # optional-chaining, explicit-checks
+
+  # Data Validation
+  validation:
+    library: "zod"  # zod, yup, joi
+    location: "schema-files"  # inline, schema-files
+
+  # Comments
+  comments:
+    style: "jsdoc"  # jsdoc, inline, minimal
+    when: "complex-logic-only"  # always, complex-logic-only, never
+
+# =============================================================================
+# FILE CREATION DECISIONS
+# =============================================================================
+file_creation:
+  # Component Files
+  component:
+    create_test: true
+    create_styles: false  # If using Tailwind, no separate style files
+    create_index: true
+    create_types: "if-complex"  # always, if-complex, never
+
+  # Service Files
+  service:
+    create_test: true
+    create_types: true
+    create_interface: true
+
+  # API Route Files
+  api_route:
+    create_validation: true
+    create_types: true
+    create_test: true
+
+# =============================================================================
+# DEPENDENCY DECISIONS
+# =============================================================================
+dependencies:
+  # When adding new packages
+  prefer_existing: true  # Use already installed packages when possible
+
+  # Package Selection Priority
+  selection_priority:
+    1: "already-installed"
+    2: "project-default"
+    3: "most-popular-stable"
+
+  # Defaults by Category
+  defaults:
+    http_client: "axios"  # axios, fetch, ky
+    date_handling: "date-fns"  # date-fns, dayjs, luxon
+    icons: "lucide-react"  # lucide-react, heroicons, react-icons
+    forms: "react-hook-form"
+    validation: "zod"
+    animation: "framer-motion"  # framer-motion, react-spring
+
+# =============================================================================
+# GIT DECISIONS
+# =============================================================================
+git:
+  # Branch Naming
+  branch_prefix:
+    feature: "feature/"
+    bugfix: "fix/"
+    hotfix: "hotfix/"
+    refactor: "refactor/"
+
+  # Commit Style
+  commit_style: "conventional"  # conventional, simple
+
+  # Auto Actions
+  auto_stage: true
+  auto_commit_message: true
+
+# =============================================================================
+# DEPLOYMENT DECISIONS
+# =============================================================================
+deployment:
+  # Default Environment
+  default_target: "staging"  # development, staging, production
+
+  # Strategy
+  strategy: "rolling"  # rolling, blue-green, canary
+
+  # Auto-deploy
+  auto_deploy:
+    staging: true
+    production: false  # Always require explicit approval
+
+# =============================================================================
+# COMMON QUESTION ANSWERS
+# =============================================================================
+common_questions:
+  "Should I create a new component or modify existing?":
+    rule: "Create new if functionality is distinct. Modify if extending existing."
+    default: "create_new"
+
+  "Where should I put this file?":
+    rule: "Follow existing project structure patterns."
+    use: "pattern_matching"
+
+  "Should I add tests?":
+    rule: "Always add tests for new code."
+    default: true
+
+  "What should I name this?":
+    rule: "Follow naming conventions from code_style section."
+    use: "naming_conventions"
+
+  "Should I refactor while implementing?":
+    rule: "No. Focus on requested task only."
+    default: false
+
+  "Should I add error handling?":
+    rule: "Always add appropriate error handling."
+    default: true
+
+  "Should I add TypeScript types?":
+    rule: "Always for public interfaces, infer for internals."
+    default: true
+
+  "Should I add comments?":
+    rule: "Only for complex logic that isn't self-explanatory."
+    default: "when_complex"
+
+  "Should I split this into smaller files?":
+    rule: "If file exceeds 300 lines, consider splitting."
+    threshold: 300
+
+  "Which import style should I use?":
+    rule: "Use path aliases when available, relative for nearby files."
+    use: "path_aliases"
+
+# =============================================================================
+# INFERENCE RULES
+# =============================================================================
+inference_rules:
+  # Match existing patterns
+  - condition: "similar_code_exists"
+    action: "follow_existing_pattern"
+    confidence: "high"
+
+  # Use project defaults
+  - condition: "no_existing_pattern"
+    action: "use_project_defaults"
+    confidence: "medium"
+
+  # Conservative fallback
+  - condition: "uncertain"
+    action: "use_safest_option"
+    confidence: "low"
+    flag_for_review: true
+
+# =============================================================================
+# SAFETY RULES
+# =============================================================================
+safety:
+  # Even in full automation, pause for these
+  always_flag:
+    - "deleting_data"
+    - "modifying_auth"
+    - "changing_permissions"
+    - "external_api_keys"
+    - "payment_related"
+
+  # Use safest option for
+  prefer_safe:
+    - "data_handling"
+    - "security_related"
+    - "user_input"
+
+  # Never auto-decide
+  require_explicit_config:
+    - "production_deployment"
+    - "database_migrations_prod"
+    - "secret_management"

package/proagents/cache/README.md

@@ -0,0 +1,110 @@
+# Analysis Cache
+
+Cached codebase analysis data for improved performance.
+
+---
+
+## Overview
+
+The cache system stores expensive analysis results to:
+- Speed up subsequent operations
+- Enable offline mode functionality
+- Reduce AI API calls
+- Provide historical comparison
+
+---
+
+## Cache Structure
+
+```
+cache/
+├── README.md                    # This file
+├── analysis-metadata.json       # Cache metadata and timestamps
+├── structure.json               # Directory structure cache
+├── conventions.json             # Code conventions cache
+├── dependencies.json            # Dependency map cache
+├── features.json                # Feature inventory cache
+├── patterns.json                # Recognized patterns cache
+└── schemas/                     # Schema definitions
+    └── *.json
+```
+
+---
+
+## Cache Lifecycle
+
+### Creation
+Cache is created/updated when:
+- Running `/analyze` command
+- Starting a new feature (incremental update)
+- Manual cache refresh
+
+### Invalidation
+Cache is invalidated when:
+- Cache age exceeds configured TTL (default: 24h)
+- Significant file changes detected
+- Manual invalidation requested
+- Schema version mismatch
+
+### Refresh Strategies
+- **Full refresh**: Complete re-analysis
+- **Incremental**: Update only changed files
+- **Partial**: Refresh specific cache files
+
+---
+
+## Configuration
+
+```yaml
+# proagents.config.yaml
+
+cache:
+  enabled: true
+  path: ".proagents/cache"
+
+  ttl:
+    structure: "24h"
+    conventions: "7d"
+    dependencies: "1h"
+    features: "24h"
+    patterns: "7d"
+
+  max_size: "100MB"
+
+  auto_refresh:
+    on_file_change: true
+    threshold: 10  # files changed
+```
+
+---
+
+## Commands
+
+```bash
+# View cache status
+proagents cache status
+
+# Refresh cache
+proagents cache refresh
+
+# Clear specific cache
+proagents cache clear structure
+
+# Clear all cache
+proagents cache clear --all
+
+# Validate cache integrity
+proagents cache validate
+```
+
+---
+
+## Cache Files
+
+See individual cache files for their structure:
+- [analysis-metadata.json](./analysis-metadata.json)
+- [structure.json](./structure.json)
+- [conventions.json](./conventions.json)
+- [dependencies.json](./dependencies.json)
+- [features.json](./features.json)
+- [patterns.json](./patterns.json)

package/proagents/cache/analysis-metadata.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "./schemas/metadata-schema.json",
+  "version": "1.0.0",
+  "cache_version": "1",
+
+  "project": {
+    "path": "/path/to/project",
+    "name": "example-project",
+    "type": "fullstack"
+  },
+
+  "timestamps": {
+    "created_at": "2024-01-15T08:00:00Z",
+    "updated_at": "2024-01-15T10:30:00Z",
+    "last_full_analysis": "2024-01-15T08:00:00Z",
+    "last_incremental_update": "2024-01-15T10:30:00Z"
+  },
+
+  "cache_status": {
+    "structure": {
+      "valid": true,
+      "age_hours": 2.5,
+      "ttl_hours": 24,
+      "size_bytes": 45678,
+      "last_updated": "2024-01-15T10:30:00Z"
+    },
+    "conventions": {
+      "valid": true,
+      "age_hours": 2.5,
+      "ttl_hours": 168,
+      "size_bytes": 12345,
+      "last_updated": "2024-01-15T08:00:00Z"
+    },
+    "dependencies": {
+      "valid": true,
+      "age_hours": 0.5,
+      "ttl_hours": 1,
+      "size_bytes": 23456,
+      "last_updated": "2024-01-15T10:00:00Z"
+    },
+    "features": {
+      "valid": true,
+      "age_hours": 2.5,
+      "ttl_hours": 24,
+      "size_bytes": 34567,
+      "last_updated": "2024-01-15T08:00:00Z"
+    },
+    "patterns": {
+      "valid": true,
+      "age_hours": 2.5,
+      "ttl_hours": 168,
+      "size_bytes": 56789,
+      "last_updated": "2024-01-15T08:00:00Z"
+    }
+  },
+
+  "file_tracking": {
+    "total_files": 234,
+    "tracked_files": 189,
+    "excluded_files": 45,
+    "last_file_check": "2024-01-15T10:30:00Z",
+    "files_changed_since_analysis": 3
+  },
+
+  "integrity": {
+    "checksum": "sha256:abc123def456...",
+    "verified_at": "2024-01-15T10:30:00Z",
+    "status": "valid"
+  },
+
+  "storage": {
+    "total_size_bytes": 172835,
+    "max_size_bytes": 104857600,
+    "usage_percent": 0.16
+  }
+}

package/proagents/cache/conventions.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "./schemas/conventions-schema.json",
+  "version": "1.0.0",
+  "generated_at": "2024-01-15T08:00:00Z",
+
+  "naming": {
+    "files": {
+      "components": {
+        "pattern": "PascalCase",
+        "extension": ".tsx",
+        "examples": ["UserProfile.tsx", "DashboardCard.tsx"],
+        "confidence": 0.95
+      },
+      "hooks": {
+        "pattern": "camelCase",
+        "prefix": "use",
+        "extension": ".ts",
+        "examples": ["useAuth.ts", "useLocalStorage.ts"],
+        "confidence": 0.98
+      },
+      "utilities": {
+        "pattern": "camelCase",
+        "extension": ".ts",
+        "examples": ["formatDate.ts", "validateEmail.ts"],
+        "confidence": 0.88
+      },
+      "types": {
+        "pattern": "camelCase",
+        "extension": ".ts",
+        "examples": ["user.ts", "apiTypes.ts"],
+        "confidence": 0.82
+      },
+      "tests": {
+        "pattern": "match-source",
+        "suffix": ".test",
+        "examples": ["UserProfile.test.tsx"],
+        "confidence": 0.96
+      }
+    },
+    "code": {
+      "variables": {
+        "pattern": "camelCase",
+        "examples": ["userData", "isLoading", "handleClick"],
+        "confidence": 0.97
+      },
+      "constants": {
+        "pattern": "UPPER_SNAKE_CASE",
+        "examples": ["MAX_RETRIES", "API_BASE_URL"],
+        "confidence": 0.92
+      },
+      "functions": {
+        "pattern": "camelCase",
+        "examples": ["getUserData", "formatCurrency"],
+        "confidence": 0.96
+      },
+      "components": {
+        "pattern": "PascalCase",
+        "examples": ["UserProfile", "NavigationMenu"],
+        "confidence": 0.99
+      },
+      "types_interfaces": {
+        "pattern": "PascalCase",
+        "examples": ["User", "ApiResponse", "FormData"],
+        "confidence": 0.94
+      }
+    }
+  },
+
+  "formatting": {
+    "indentation": {
+      "type": "spaces",
+      "size": 2,
+      "confidence": 1.0
+    },
+    "quotes": {
+      "style": "single",
+      "jsx": "double",
+      "confidence": 0.95
+    },
+    "semicolons": {
+      "required": true,
+      "confidence": 0.98
+    },
+    "trailing_commas": {
+      "style": "es5",
+      "confidence": 0.90
+    },
+    "line_length": {
+      "max": 100,
+      "confidence": 0.85
+    }
+  },
+
+  "imports": {
+    "order": [
+      { "group": "react", "pattern": "^react" },
+      { "group": "next", "pattern": "^next" },
+      { "group": "third-party", "pattern": "^[a-z@]" },
+      { "group": "local", "pattern": "^[@~/]" },
+      { "group": "relative", "pattern": "^\\.\\.?/" },
+      { "group": "styles", "pattern": "\\.(css|scss|sass)$" }
+    ],
+    "style": "named",
+    "newline_between_groups": true,
+    "confidence": 0.88
+  },
+
+  "exports": {
+    "style": "named",
+    "default_exports": "components_only",
+    "barrel_files": true,
+    "confidence": 0.86
+  },
+
+  "comments": {
+    "style": "jsdoc",
+    "required_for": ["public_functions", "complex_logic"],
+    "format": {
+      "single_line": "// comment",
+      "multi_line": "/* comment */",
+      "doc": "/** @description */"
+    },
+    "confidence": 0.78
+  }
+}