Add ai-code-project-template repo files.

2025-08-23 06:09:26 -07:00
parent 9321e54bce
commit e725ecf942
76 changed files with 17830 additions and 8 deletions
--- a/.ai/docs/ai-context.md
+++ b/.ai/docs/ai-context.md
@@ -0,0 +1,388 @@
+# AI Context Management Guide
+
+Master the art of feeding AI the right information at the right time for optimal results.
+
+## 📚 Overview
+
+The AI context system helps you:
+
+- Provide consistent reference materials to your AI assistant
+- Generate comprehensive project documentation
+- Manage external library documentation
+- Organize project-specific context
+- Maintain philosophy alignment
+
+## 🗂️ Directory Structure
+
+```
+ai_context/                    # Persistent reference materials
+├── README.md                  # Directory documentation
+├── IMPLEMENTATION_PHILOSOPHY.md   # Core development philosophy
+├── MODULAR_DESIGN_PHILOSOPHY.md   # Architecture principles
+├── generated/                 # Auto-generated project docs
+│   └── [project-rollups]     # Created by build_ai_context_files.py
+└── git_collector/            # External library docs
+    └── [fetched-docs]        # Created by build_git_collector_files.py
+
+ai_working/                   # Active AI workspace
+├── README.md                 # Usage instructions
+├── [feature-folders]/        # Feature-specific context
+└── tmp/                      # Temporary files (git-ignored)
+    └── [scratch-files]       # Experiments, debug logs, etc.
+```
+
+## 🎯 Quick Start
+
+### 1. Generate Project Context
+
+```bash
+# Generate comprehensive project documentation
+make ai-context-files
+
+# Or run directly
+python tools/build_ai_context_files.py
+```
+
+This creates rollup files in `ai_context/generated/` containing:
+
+- All source code organized by type
+- Configuration files
+- Documentation
+- Test files
+
+### 2. Add External Documentation
+
+```bash
+# Fetch library documentation
+python tools/build_git_collector_files.py
+
+# Configure libraries in git_collector_config.json
+{
+  "libraries": [
+    {
+      "name": "react",
+      "repo": "facebook/react",
+      "docs_path": "docs/"
+    }
+  ]
+}
+```
+
+### 3. Load Philosophy
+
+```
+# In your AI assistant
+/prime
+
+# Or manually reference
+Please read @ai_context/IMPLEMENTATION_PHILOSOPHY.md and follow these principles
+```
+
+## 🧠 Philosophy Documents
+
+### IMPLEMENTATION_PHILOSOPHY.md
+
+Core principles that guide all development:
+
+- **Simplicity First**: Clean, maintainable code
+- **Human-Centric**: AI amplifies, doesn't replace
+- **Pragmatic Choices**: Real-world solutions
+- **Trust in Emergence**: Let good architecture emerge
+
+### MODULAR_DESIGN_PHILOSOPHY.md
+
+Architecture principles for scalable systems:
+
+- **Bricks & Studs**: Self-contained modules with clear interfaces
+- **Contract-First**: Define interfaces before implementation
+- **Regenerate, Don't Patch**: Rewrite modules when needed
+- **AI-Ready**: Design for future automation
+
+### Using Philosophy in Prompts
+
+```
+/ultrathink-task Build a user authentication system following our philosophy:
+@ai_context/IMPLEMENTATION_PHILOSOPHY.md
+@ai_context/MODULAR_DESIGN_PHILOSOPHY.md
+
+Focus especially on simplicity and contract-first design.
+```
+
+## 📋 Context Generation Tools
+
+### build_ai_context_files.py
+
+Generates comprehensive project documentation:
+
+```python
+# Default configuration
+FILE_GROUPS = {
+    "Source Code": {
+        "patterns": ["**/*.py", "**/*.js", "**/*.ts"],
+        "exclude": ["**/test_*", "**/*.test.*"]
+    },
+    "Configuration": {
+        "patterns": ["**/*.json", "**/*.yaml", "**/*.toml"],
+        "exclude": ["**/node_modules/**"]
+    }
+}
+```
+
+**Features**:
+
+- Groups files by type
+- Respects .gitignore
+- Adds helpful headers
+- Creates single-file rollups
+
+**Customization**:
+
+```python
+# In build_ai_context_files.py
+FILE_GROUPS["My Custom Group"] = {
+    "patterns": ["**/*.custom"],
+    "exclude": ["**/temp/**"]
+}
+```
+
+### collect_files.py
+
+Core utility for pattern-based file collection:
+
+```bash
+# Collect all Python files
+python tools/collect_files.py "**/*.py" > python_files.md
+
+# Collect with exclusions
+python tools/collect_files.py "**/*.ts" --exclude "**/node_modules/**" > typescript.md
+```
+
+### build_git_collector_files.py
+
+Fetches external documentation:
+
+```bash
+# Configure libraries
+cat > git_collector_config.json << EOF
+{
+  "libraries": [
+    {
+      "name": "fastapi",
+      "repo": "tiangolo/fastapi",
+      "docs_path": "docs/",
+      "include": ["tutorial/", "advanced/"]
+    }
+  ]
+}
+EOF
+
+# Fetch documentation
+python tools/build_git_collector_files.py
+```
+
+## 🎨 Best Practices
+
+### 1. Layer Your Context
+
+```
+Base Layer (Philosophy)
+    ↓
+Project Layer (Generated docs)
+    ↓
+Feature Layer (Specific requirements)
+    ↓
+Task Layer (Current focus)
+```
+
+### 2. Reference Strategically
+
+```
+# Good: Specific, relevant context
+@ai_context/generated/api_endpoints.md
+@ai_working/auth-feature/requirements.md
+
+# Avoid: Everything at once
+@ai_context/**/*
+```
+
+### 3. Keep Context Fresh
+
+```bash
+# Update before major work
+make ai-context-files
+
+# Add to git hooks
+echo "make ai-context-files" >> .git/hooks/pre-commit
+```
+
+### 4. Use Working Spaces
+
+```
+ai_working/
+├── feature-x/
+│   ├── requirements.md    # What to build
+│   ├── decisions.md       # Architecture choices
+│   ├── progress.md        # Current status
+│   └── blockers.md        # Issues to resolve
+└── tmp/
+    └── debug-session-1/   # Temporary investigation
+```
+
+## 🔧 Advanced Techniques
+
+### Dynamic Context Loading
+
+```
+# Load context based on current task
+/ultrathink-task I need to work on the API layer.
+Load relevant context:
+@ai_context/generated/api_*.md
+@ai_context/api-guidelines.md
+```
+
+### Context Templates
+
+Create reusable context sets:
+
+```bash
+# .ai/contexts/api-work.md
+# API Development Context
+
+## Load these files:
+- @ai_context/generated/api_routes.md
+- @ai_context/generated/models.md
+- @ai_context/api-standards.md
+- @docs/api/README.md
+
+## Key principles:
+- RESTful design
+- Comprehensive error handling
+- OpenAPI documentation
+```
+
+### Incremental Context
+
+Build context progressively:
+
+```
+# Start broad
+Read @ai_context/IMPLEMENTATION_PHILOSOPHY.md
+
+# Get specific
+Now read @ai_context/generated/auth_module.md
+
+# Add requirements
+Also consider @ai_working/auth-v2/requirements.md
+```
+
+### Context Versioning
+
+Track context evolution:
+
+```bash
+# Version generated docs
+cd ai_context/generated
+git add .
+git commit -m "Context snapshot: pre-refactor"
+```
+
+## 📊 Context Optimization
+
+### Size Management
+
+```python
+# In build_ai_context_files.py
+MAX_FILE_SIZE = 100_000  # Skip large files
+MAX_ROLLUP_SIZE = 500_000  # Split large rollups
+```
+
+### Relevance Filtering
+
+```python
+# Custom relevance scoring
+def is_relevant(file_path: Path) -> bool:
+    # Skip generated files
+    if 'generated' in file_path.parts:
+        return False
+
+    # Skip vendor code
+    if 'vendor' in file_path.parts:
+        return False
+
+    # Include based on importance
+    important_dirs = ['src', 'api', 'core']
+    return any(d in file_path.parts for d in important_dirs)
+```
+
+### Context Caching
+
+```bash
+# Cache expensive context generation
+CONTEXT_CACHE=".ai/context-cache"
+CACHE_AGE=$(($(date +%s) - $(stat -f %m "$CONTEXT_CACHE" 2>/dev/null || echo 0)))
+
+if [ $CACHE_AGE -gt 3600 ]; then  # 1 hour
+    make ai-context-files
+    touch "$CONTEXT_CACHE"
+fi
+```
+
+## 🎯 Common Patterns
+
+### Feature Development
+
+```
+1. Create feature workspace:
+   mkdir -p ai_working/new-feature
+
+2. Add requirements:
+   echo "..." > ai_working/new-feature/requirements.md
+
+3. Generate fresh context:
+   make ai-context-files
+
+4. Start development:
+   /ultrathink-task Implement @ai_working/new-feature/requirements.md
+```
+
+### Debugging Sessions
+
+```
+1. Capture context:
+   echo "Error details..." > ai_working/tmp/debug-notes.md
+
+2. Add relevant code:
+   python tools/collect_files.py "**/auth*.py" > ai_working/tmp/auth-code.md
+
+3. Analyze:
+   Help me debug using:
+   @ai_working/tmp/debug-notes.md
+   @ai_working/tmp/auth-code.md
+```
+
+### Documentation Updates
+
+```
+1. Generate current state:
+   make ai-context-files
+
+2. Update docs:
+   Update the API documentation based on:
+   @ai_context/generated/api_routes.md
+
+3. Verify consistency:
+   /review-code-at-path docs/
+```
+
+## 🚀 Pro Tips
+
+1. **Front-Load Philosophy**: Always start with philosophy docs
+2. **Layer Gradually**: Add context as needed, not all at once
+3. **Clean Regularly**: Remove outdated context from ai_working
+4. **Version Important Context**: Git commit key snapshots
+5. **Automate Generation**: Add to build pipelines
+
+## 🔗 Related Documentation
+
+- [Command Reference](commands.md) - Commands that use context
+- [Philosophy Guide](philosophy.md) - Core principles