aiox-core 5.0.7 → 5.0.8

package/.claude/skills/architect-first/assets/config-template.yaml

@@ -0,0 +1,351 @@
+# Configuration Template for Architect-First Projects
+#
+# This template demonstrates the principle: Config > Hardcoding
+# All mutable values should be externalized to configuration files like this.
+#
+# Usage:
+#   1. Copy this template to your project's config directory
+#   2. Rename to config.yaml or config.{environment}.yaml
+#   3. Fill in values appropriate for your project
+#   4. NEVER hardcode these values in source code
+#   5. Load configuration at runtime from this file
+
+# =============================================================================
+# System Configuration
+# =============================================================================
+system:
+  name: "my-project"                    # Project/system name
+  version: "1.0.0"                      # Current version
+  environment: "development"            # development|staging|production
+  debug: true                           # Enable debug mode
+
+# =============================================================================
+# Application Settings
+# =============================================================================
+application:
+  host: "localhost"                     # Application host
+  port: 8000                            # Application port
+  workers: 4                            # Number of worker processes
+  timeout: 30                           # Request timeout (seconds)
+  max_connections: 100                  # Maximum concurrent connections
+
+# =============================================================================
+# Logging Configuration
+# =============================================================================
+logging:
+  level: "INFO"                         # DEBUG|INFO|WARNING|ERROR|CRITICAL
+  format: "json"                        # json|text
+  output: "stdout"                      # stdout|file
+  file_path: "logs/app.log"            # Log file path (if output=file)
+  rotation:
+    enabled: true                       # Enable log rotation
+    max_size: "100MB"                  # Max size before rotation
+    max_files: 10                      # Number of files to keep
+
+# =============================================================================
+# Database Configuration
+# =============================================================================
+database:
+  primary:
+    engine: "postgresql"                # postgresql|mysql|sqlite
+    host: "localhost"
+    port: 5432
+    name: "myapp_dev"
+    username: "developer"
+    password: "${DB_PASSWORD}"          # From environment variable
+    pool_size: 10                       # Connection pool size
+    pool_timeout: 30                    # Pool timeout (seconds)
+    ssl_mode: "prefer"                  # disable|allow|prefer|require
+
+  replica:                              # Optional read replica
+    enabled: false
+    host: "replica.localhost"
+    port: 5432
+    # ... same structure as primary
+
+# =============================================================================
+# Cache Configuration
+# =============================================================================
+cache:
+  enabled: true
+  backend: "redis"                      # redis|memcached|memory
+  host: "localhost"
+  port: 6379
+  db: 0
+  password: "${REDIS_PASSWORD}"         # From environment variable
+  ttl: 3600                             # Default TTL in seconds
+  key_prefix: "myapp:"                  # Key prefix for namespace
+
+# =============================================================================
+# External Services / Integrations
+# =============================================================================
+integrations:
+  # Example: External API integration
+  external_api:
+    enabled: true
+    base_url: "https://api.example.com"
+    api_key: "${EXTERNAL_API_KEY}"      # From environment variable
+    timeout: 10                         # Request timeout (seconds)
+    retry:
+      enabled: true
+      max_attempts: 3
+      backoff_factor: 2                 # Exponential backoff multiplier
+
+  # Example: Email service
+  email:
+    enabled: true
+    provider: "smtp"                    # smtp|sendgrid|ses
+    smtp_host: "smtp.example.com"
+    smtp_port: 587
+    smtp_user: "${EMAIL_USER}"
+    smtp_password: "${EMAIL_PASSWORD}"
+    from_address: "noreply@example.com"
+    from_name: "My Application"
+
+  # Example: Cloud storage
+  storage:
+    enabled: true
+    provider: "s3"                      # s3|gcs|azure
+    bucket: "my-app-uploads"
+    region: "us-east-1"
+    access_key: "${AWS_ACCESS_KEY}"
+    secret_key: "${AWS_SECRET_KEY}"
+    public_url_base: "https://cdn.example.com"
+
+# =============================================================================
+# Feature Flags
+# =============================================================================
+features:
+  new_feature_x:
+    enabled: false                      # Enable/disable feature
+    rollout_percentage: 0               # Gradual rollout (0-100)
+    allowed_users: []                   # Whitelist of user IDs
+
+  experimental_feature_y:
+    enabled: true
+    config:                             # Feature-specific configuration
+      threshold: 0.8
+      max_items: 100
+
+# =============================================================================
+# Security Settings
+# =============================================================================
+security:
+  # Authentication
+  auth:
+    jwt:
+      secret: "${JWT_SECRET}"           # From environment variable
+      algorithm: "HS256"
+      expiration: 3600                  # Token expiration (seconds)
+      refresh_expiration: 604800        # Refresh token expiration (7 days)
+
+    session:
+      secret: "${SESSION_SECRET}"
+      cookie_name: "session_id"
+      secure: true                      # HTTPS only
+      http_only: true                   # Not accessible via JavaScript
+      same_site: "lax"                  # lax|strict|none
+
+  # Rate limiting
+  rate_limit:
+    enabled: true
+    requests_per_minute: 60
+    burst: 10                           # Burst allowance
+
+  # CORS
+  cors:
+    enabled: true
+    allowed_origins:
+      - "https://example.com"
+      - "https://app.example.com"
+    allowed_methods:
+      - "GET"
+      - "POST"
+      - "PUT"
+      - "DELETE"
+    allowed_headers:
+      - "Content-Type"
+      - "Authorization"
+    max_age: 3600
+
+# =============================================================================
+# Monitoring & Observability
+# =============================================================================
+monitoring:
+  # Metrics
+  metrics:
+    enabled: true
+    provider: "prometheus"              # prometheus|datadog|custom
+    port: 9090
+    path: "/metrics"
+
+  # Distributed tracing
+  tracing:
+    enabled: true
+    provider: "jaeger"                  # jaeger|zipkin|datadog
+    endpoint: "http://localhost:14268/api/traces"
+    sample_rate: 0.1                    # Sample 10% of requests
+
+  # Health checks
+  health:
+    enabled: true
+    path: "/health"
+    checks:
+      - name: "database"
+        critical: true
+      - name: "cache"
+        critical: false
+      - name: "external_api"
+        critical: false
+
+# =============================================================================
+# Module/Expansion Pack Paths
+# =============================================================================
+# CRITICAL: Never hardcode module paths in source code
+# Always reference modules through configuration
+modules:
+  expansion_packs_dir: "expansion-packs"
+
+  # Individual expansion pack paths (relative to project root)
+  creator_os: "expansion-packs/creator-os"
+  mmos_mind_mapper: "expansion-packs/mmos"
+  innerlens: "expansion-packs/innerlens"
+  etl_data_collector: "expansion-packs/etl-data-collector"
+
+  # Module discovery (alternative to explicit paths)
+  auto_discover:
+    enabled: true                       # Automatically discover modules
+    search_paths:
+      - "expansion-packs"
+      - "plugins"
+    pattern: "*/module.yaml"           # Module metadata file pattern
+
+# =============================================================================
+# File Paths & Directories
+# =============================================================================
+# CRITICAL: All file paths should be configurable, never hardcoded
+paths:
+  # Input/output directories
+  data_dir: "data"
+  output_dir: "outputs"
+  temp_dir: "/tmp/myapp"
+  upload_dir: "uploads"
+
+  # Application directories
+  templates_dir: "templates"
+  static_dir: "static"
+
+  # Specific output paths
+  courses_output: "outputs/courses"
+  minds_output: "outputs/minds"
+  database_output: "outputs/database"
+
+# =============================================================================
+# Performance & Optimization
+# =============================================================================
+performance:
+  # Caching
+  cache_templates: true
+  cache_static_files: true
+
+  # Compression
+  enable_compression: true
+  compression_level: 6                  # 1-9 (higher = more compression)
+  compression_min_size: 1024            # Minimum size to compress (bytes)
+
+  # Connection pooling
+  http_pool_size: 10
+  http_pool_timeout: 30
+
+  # Async processing
+  async_enabled: true
+  async_workers: 4
+  queue_backend: "redis"
+
+# =============================================================================
+# Development & Testing
+# =============================================================================
+development:
+  # Auto-reload on code changes
+  auto_reload: true
+
+  # Debug toolbar
+  debug_toolbar: true
+
+  # Mock external services
+  mock_external_services: true
+
+  # Test data
+  use_test_data: true
+  test_data_path: "tests/fixtures"
+
+# =============================================================================
+# Environment-Specific Overrides
+# =============================================================================
+# This section demonstrates how to handle environment-specific configs
+# In practice, use separate files: config.dev.yaml, config.prod.yaml
+
+environments:
+  development:
+    debug: true
+    logging:
+      level: "DEBUG"
+    database:
+      name: "myapp_dev"
+
+  staging:
+    debug: false
+    logging:
+      level: "INFO"
+    database:
+      name: "myapp_staging"
+
+  production:
+    debug: false
+    logging:
+      level: "WARNING"
+    database:
+      name: "myapp_prod"
+    security:
+      rate_limit:
+        requests_per_minute: 100
+
+# =============================================================================
+# Custom Application Settings
+# =============================================================================
+# Add your application-specific configuration here
+custom:
+  # Example: Business logic thresholds
+  thresholds:
+    max_upload_size: 10485760           # 10MB in bytes
+    min_password_length: 8
+    session_timeout: 1800               # 30 minutes
+
+  # Example: Feature-specific settings
+  notification:
+    channels:
+      email: true
+      sms: false
+      push: true
+    batch_size: 100
+    retry_failed: true
+
+# =============================================================================
+# Configuration Metadata
+# =============================================================================
+_metadata:
+  version: "1.0"
+  last_updated: "2024-01-01"
+  schema_version: "2.0"
+
+  # Validation rules (optional - for config validation tools)
+  validation:
+    required_env_vars:
+      - "DB_PASSWORD"
+      - "JWT_SECRET"
+      - "SESSION_SECRET"
+
+    deprecated_keys:
+      - key: "old_setting"
+        replacement: "new_setting"
+        since: "0.9.0"

package/.claude/skills/architect-first/references/architecture-checklist.md

@@ -0,0 +1,216 @@
+# Architecture Validation Checklist
+
+Use this checklist when validating architectural decisions before implementation.
+
+## 1. Current State Documentation
+
+**Map Before Modify** - Document what exists before making changes.
+
+- [ ] Current system architecture documented
+  - [ ] Component diagram created
+  - [ ] Data flow diagram created
+  - [ ] Integration points identified
+  - [ ] Dependencies mapped
+
+- [ ] Touch points identified
+  - [ ] All modules that will be affected listed
+  - [ ] Cross-module dependencies documented
+  - [ ] External system integrations noted
+
+- [ ] Baseline capabilities cataloged
+  - [ ] Current feature list documented
+  - [ ] Performance metrics recorded
+  - [ ] User workflows mapped
+
+## 2. Proposed Solution Design
+
+**Architect Before Build** - Complete design before code.
+
+- [ ] Multiple options presented (A/B/C minimum)
+  - [ ] Option A: [Name and brief description]
+  - [ ] Option B: [Name and brief description]
+  - [ ] Option C: [Name and brief description]
+
+- [ ] Trade-offs explicitly documented
+  - [ ] Performance implications
+  - [ ] Complexity implications
+  - [ ] Maintainability implications
+  - [ ] Scalability implications
+
+- [ ] Chosen architecture documented
+  - [ ] System architecture diagram
+  - [ ] Component interaction diagram
+  - [ ] Data flow diagram
+  - [ ] Configuration schema (YAML)
+  - [ ] Integration points
+  - [ ] API contracts
+
+## 3. Multi-Agent Validation
+
+**No Unilateral Structural Decisions** - Get validation from multiple perspectives.
+
+- [ ] Product Owner validation
+  - [ ] Business goals alignment confirmed
+  - [ ] User value clearly articulated
+  - [ ] Priority justified
+
+- [ ] Architect validation
+  - [ ] Technical soundness confirmed
+  - [ ] Scalability verified
+  - [ ] Security reviewed
+  - [ ] Performance acceptable
+
+- [ ] User/Stakeholder validation
+  - [ ] Final decision documented
+  - [ ] Rationale recorded
+  - [ ] Approval obtained
+
+## 4. Capability Preservation
+
+**Never Lose Capability** - Ensure no regression in functionality.
+
+- [ ] Gold Standard Baseline comparison
+  - [ ] All previous capabilities mapped
+  - [ ] New design maintains ALL capabilities
+  - [ ] Any removals explicitly justified and approved
+
+- [ ] Feature parity verified
+  - [ ] Feature comparison table created
+  - [ ] Migration path for removed features (if any)
+  - [ ] Backward compatibility plan
+
+## 5. Zero Coupling Validation
+
+**Max Modularity** - Ensure independence between components.
+
+- [ ] Module independence verified
+  - [ ] Each expansion pack can run independently
+  - [ ] No hardcoded cross-module dependencies
+  - [ ] Clean interfaces defined
+
+- [ ] Configuration externalized
+  - [ ] All cross-module references in YAML config
+  - [ ] No hardcoded paths or identifiers
+  - [ ] Configuration schema documented
+
+- [ ] Coupling check script passed
+  - [ ] `scripts/check_coupling.py` executed
+  - [ ] All coupling violations resolved
+  - [ ] Zero-coupling principle maintained
+
+## 6. Configuration Strategy
+
+**Config > Hardcoding** - Externalize all mutable values.
+
+- [ ] Mutable values identified
+  - [ ] List of all configuration points
+  - [ ] Default values defined
+  - [ ] Override mechanisms specified
+
+- [ ] YAML configuration created
+  - [ ] Configuration schema defined
+  - [ ] Example configurations provided
+  - [ ] Validation rules specified
+
+- [ ] No hardcoding violations
+  - [ ] All paths configurable
+  - [ ] All thresholds configurable
+  - [ ] All integration points configurable
+
+## 7. Testing Strategy
+
+**Quality Escape Hatch** - Tests as safety net for implementation.
+
+- [ ] Test plan defined
+  - [ ] Unit test strategy
+  - [ ] Integration test strategy
+  - [ ] End-to-end test scenarios
+
+- [ ] Test coverage targets set
+  - [ ] Minimum coverage percentage
+  - [ ] Critical paths identified
+  - [ ] Edge cases documented
+
+- [ ] Logging strategy defined
+  - [ ] Key observation points identified
+  - [ ] Log levels specified
+  - [ ] Debugging hooks planned
+
+## 8. Documentation Requirements
+
+**Documentation is Non-Negotiable** - Must precede implementation.
+
+- [ ] Architecture Decision Record (ADR) created
+  - [ ] Context documented
+  - [ ] Decision documented
+  - [ ] Consequences documented
+  - [ ] Use template: `assets/adr-template.md`
+
+- [ ] Implementation guide created
+  - [ ] Short and actionable
+  - [ ] "How to customize" focus
+  - [ ] Code examples included
+  - [ ] Configuration examples included
+
+- [ ] API documentation created (if applicable)
+  - [ ] Endpoints documented
+  - [ ] Request/response schemas
+  - [ ] Authentication requirements
+  - [ ] Rate limits and constraints
+
+## 9. Risk Assessment
+
+**Mitigate Before Implementing** - Identify and address risks upfront.
+
+- [ ] Risks identified
+  - [ ] Technical risks listed
+  - [ ] Business risks listed
+  - [ ] Timeline risks listed
+
+- [ ] Mitigations defined
+  - [ ] Each risk has mitigation strategy
+  - [ ] Mitigation feasibility verified
+  - [ ] Contingency plans documented
+
+- [ ] Risk mitigation validated
+  - [ ] `scripts/validate_risk_mitigation.py` executed
+  - [ ] All high-priority risks addressed
+  - [ ] Acceptable risk level confirmed
+
+## 10. Implementation Readiness
+
+**Final Gate** - Ready to proceed to code.
+
+- [ ] All previous checklist items completed
+- [ ] Architecture approved by all stakeholders
+- [ ] Zero coupling verified
+- [ ] Configuration externalized
+- [ ] Tests defined
+- [ ] Documentation complete
+- [ ] Risks mitigated
+
+---
+
+## Stop Rules Trigger Check
+
+**If ANY of these are true, STOP and remediate:**
+
+- ⛔ Capability loss detected vs baseline
+- ⛔ Structural decision without multi-agent validation
+- ⛔ Coupling between modules detected
+- ⛔ Missing architectural documentation
+- ⛔ Hardcoded mutable configuration values
+
+→ If stopped, consult `stop-rules-guide.md` for remediation steps.
+
+---
+
+## Sign-Off
+
+- **Product Owner**: _________________ Date: _______
+- **Architect**: _________________ Date: _______
+- **Lead Developer**: _________________ Date: _______
+
+**Architecture Approved**: [ ] YES [ ] NO
+
+**Proceed to Implementation**: [ ] YES [ ] NO

package/.claude/skills/architect-first/references/pre-implementation-checklist.md

@@ -0,0 +1,119 @@
+# Pre-Implementation Checklist
+
+Use this checklist before writing any code to ensure architectural validation is complete.
+
+## Architecture Validation
+
+- [ ] **Architecture documented and validated?**
+  - [ ] Architecture diagrams created
+  - [ ] Component interactions defined
+  - [ ] Data flows mapped
+  - [ ] Integration points identified
+  - [ ] Multi-agent validation completed
+  - [ ] Architecture Decision Record (ADR) written
+
+## Core Use Case Definition
+
+- [ ] **Core use case clearly defined?**
+  - [ ] Primary user workflow documented
+  - [ ] Success criteria specified
+  - [ ] Acceptance criteria written
+  - [ ] Edge cases identified
+  - [ ] Error scenarios mapped
+
+## Configuration Externalization
+
+- [ ] **Configuration externalized to YAML?**
+  - [ ] All mutable values identified
+  - [ ] YAML schema defined
+  - [ ] Default configuration created
+  - [ ] Configuration validation rules specified
+  - [ ] No hardcoded values in planned implementation
+  - [ ] Configuration documentation written
+
+## Test Strategy
+
+- [ ] **Test strategy defined?**
+  - [ ] Test plan written
+  - [ ] Unit test cases identified
+  - [ ] Integration test scenarios defined
+  - [ ] Coverage targets set
+  - [ ] Test data requirements identified
+
+## Logging Strategy
+
+- [ ] **Logging/observation points identified?**
+  - [ ] Key decision points for logging marked
+  - [ ] Log levels assigned
+  - [ ] Error handling points identified
+  - [ ] Debugging hooks planned
+  - [ ] Monitoring requirements specified
+
+## Dependencies
+
+- [ ] **Dependencies validated?**
+  - [ ] All required libraries/packages identified
+  - [ ] Version compatibility verified
+  - [ ] License compliance checked
+  - [ ] Zero-coupling maintained (no hardcoded cross-module deps)
+
+## Documentation Plan
+
+- [ ] **Documentation plan ready?**
+  - [ ] API documentation outline created
+  - [ ] Usage examples planned
+  - [ ] Configuration guide outline created
+  - [ ] "How to customize" focus maintained
+
+## Implementation Readiness
+
+- [ ] **Ready to implement?**
+  - [ ] All above checklist items completed
+  - [ ] Team has clear understanding of architecture
+  - [ ] First coding task identified
+  - [ ] Code review process established
+
+---
+
+## Quality Escape Hatch Acknowledgment
+
+**Remember**: Code quality is negotiable IF backed by tests.
+
+You may proceed with:
+- ✓ "Ugly" code WITH comprehensive tests
+- ✓ Quick implementation WITH test plan + logging
+- ✓ 80% feature completeness IF core case works
+
+You must NOT proceed with:
+- ✗ "Ugly" code WITHOUT tests
+- ✗ Hardcoded mutable values
+- ✗ Implementation without core case defined
+
+---
+
+## Stop Rules Check
+
+Before proceeding, verify NONE of these conditions are true:
+
+- ⛔ Capability loss vs baseline
+- ⛔ Structural decision without multi-agent validation
+- ⛔ Coupling between modules
+- ⛔ Missing architectural documentation
+- ⛔ Quick & dirty code WITHOUT test plan and logs
+- ⛔ Hardcoded mutable configuration values
+
+**If any stop rule triggered**: HALT and remediate before coding.
+
+---
+
+## Approval
+
+**Pre-Implementation Checklist Completed**: [ ] YES [ ] NO
+
+**Approved to Start Coding**: [ ] YES [ ] NO
+
+**Approver**: _________________ Date: _______
+
+**First Task**: _________________________________________________
+
+**Estimated Completion**: _______