docs: document multi-agent architecture evolution and future vision

.github/dependabot.yml

@@ -0,0 +1,55 @@
+# Dependabot configuration for automated dependency updates
+# Documentation: https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  # Python dependencies via pip/uv
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "03:00"
+    open-pull-requests-limit: 5
+    reviewers:
+      - "niksacdev"
+    labels:
+      - "dependencies"
+      - "python"
+    commit-message:
+      prefix: "chore"
+      prefix-development: "chore"
+      include: "scope"
+    groups:
+      development:
+        patterns:
+          - "pytest*"
+          - "mypy*"
+          - "ruff*"
+          - "black*"
+          - "pre-commit*"
+      openai:
+        patterns:
+          - "openai*"
+          - "agents*"
+      documentation:
+        patterns:
+          - "mkdocs*"
+          - "sphinx*"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "03:00"
+    open-pull-requests-limit: 3
+    reviewers:
+      - "niksacdev"
+    labels:
+      - "dependencies"
+      - "github-actions"
+    commit-message:
+      prefix: "ci"
+      include: "scope"

.gitignore

@@ -209,6 +209,49 @@ __marimo__/
 # SpecStory (AI code documentation)
 .specstory/
 
-# Application results and logs
+# ============================================================================
+# Project-Specific Ignores
+# ============================================================================
+
+# Results and output files
 results/
 console_app/results/
+loan_processing/results/
+*.result.json
+*.decision.json
+
+# Temporary files
+*.tmp
+*.temp
+*.bak
+*.swp
+*.swo
+*~
+
+# Local development
+.env.local
+.env.*.local
+local_notes.md
+scratch/
+
+# MCP Server data
+mcp_server_data/
+*.db
+*.sqlite
+
+# Generated documentation
+docs/_build/
+docs/generated/
+
+# Performance profiling
+*.prof
+*.pstats
+profile_output/
+
+# Test coverage reports (duplicates removed as they're already above)
+
+# IDE specific files
+.idea/
+.vscode/
+*.sublime-*
+.DS_Store

.pre-commit-config.yaml

@@ -0,0 +1,73 @@
+# Pre-commit hooks for security and code quality
+# Install: pip install pre-commit && pre-commit install
+
+repos:
+  # Security - Detect secrets
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.4.0
+    hooks:
+      - id: detect-secrets
+        args: ['--baseline', '.secrets.baseline']
+        exclude: .*\.lock|package-lock\.json
+
+  # Python code quality
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  # Python type checking
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-all]
+        args: [--ignore-missing-imports]
+
+  # Check for common issues
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: ['--maxkb=1000']
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-json
+      - id: check-toml
+      - id: detect-private-key
+      - id: no-commit-to-branch
+        args: ['--branch', 'main']
+
+  # Markdown formatting
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.39.0
+    hooks:
+      - id: markdownlint
+        args: ['--fix']
+
+  # Security - Safety check
+  - repo: https://github.com/Lucas-C/pre-commit-hooks-safety
+    rev: v1.3.3
+    hooks:
+      - id: python-safety-dependencies-check
+
+# Additional local hooks
+- repo: local
+  hooks:
+    - id: no-env-files
+      name: Block .env files
+      entry: .env files must not be committed
+      language: fail
+      files: '^\.env$'
+
+    - id: no-api-keys
+      name: Check for API keys
+      entry: 'sk-[a-zA-Z0-9]{48}|AKIA[0-9A-Z]{16}'
+      language: pygrep
+      types: [text]
+      exclude: \.env\.example|SECURITY\.md

CLAUDE.md

@@ -71,6 +71,8 @@ Claude has access to specialized development agents that MUST be used proactivel
 - **Persona-driven behavior**: Agent instructions are loaded from persona markdown files
 - **No hardcoded logic**: Avoid embedding business logic in orchestrator code
 - **Jobs-to-be-Done focused**: Agents designed around customer jobs, not internal processes
+- **Strategic multi-agent choice**: Architecture designed for future growth - agents will gain intelligence as MCP servers expand from current 3 to planned 20+
+- **Progressive autonomy**: Agents start simple but evolve independently without refactoring
 
 ### 2. Clean Orchestration
 - **Minimal orchestrator code**: Orchestrators should only handle agent coordination and context passing