Dev

.ai-context/DYNAMICS.md

@@ -0,0 +1,98 @@
+# Dynamics — Active Issues & Constraints
+
+> **Last updated:** 2026-04-16
+> **Stability:** Dynamic — Update as issues arise/resolve
+
+---
+
+## ⚡ Quick Scan
+
+| Status | Issue | Impact | Workaround |
+|--------|-------|--------|------------|
+| 🟢 Clean | No active issues | — | — |
+
+---
+
+## 🔴 Active Issues
+
+*No active issues at this time.*
+
+<!-- Template for adding issues:
+### [Issue Title]
+
+**What:** {Brief description of the issue}
+
+**Impact:** {How this affects development/workflow}
+
+**Workaround:**
+```
+{Steps or code to work around the issue}
+```
+
+**Resolution Path:** {Planned fix or "Not yet planned"}
+-->
+
+---
+
+## 🟡 Known Constraints
+
+### LLM API Rate Limits
+
+**What:** Cloud LLM providers have rate limits that can slow down large codebase analysis.
+
+**Impact:** Processing large projects may experience delays or require retries.
+
+**Mitigation:** 
+- Use `--cache-dir` to enable response caching
+- Consider using Ollama for local processing without rate limits
+- Break large projects into smaller analysis runs
+
+---
+
+### Memory Usage for Large Projects
+
+**What:** Analyzing very large codebases can consume significant memory during the preprocessing phase.
+
+**Impact:** May cause slowdowns on machines with limited RAM.
+
+**Mitigation:**
+- Use `--exclude` to skip unnecessary directories (node_modules, target, etc.)
+- Process specific subdirectories separately
+
+---
+
+## 🟢 Recently Resolved
+
+| Issue | Resolution | Date |
+|-------|------------|------|
+| *None recorded yet* | — | — |
+
+---
+
+## 📋 Under Consideration
+
+### Potential: Git History Analysis
+
+**Topic:** Analyzing git commit history to track architecture evolution.
+
+**Trigger for change:** If users request features showing how architecture has changed over time.
+
+---
+
+### Potential: Multi-Repository Analysis
+
+**Topic:** Supporting analysis across multiple related repositories.
+
+**Trigger for change:** Enterprise users with microservices architectures across many repos.
+
+---
+
+## 🔄 Update Log
+
+| Date | Change |
+|------|--------|
+| 2026-04-16 | Initial version created during .ai-context setup |
+
+---
+
+*Remember: This file changes frequently. Always check the "Last updated" date. If it's been > 2 weeks, verify against current code state.*

.ai-context/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: ai-context
+description: |
+  Project knowledge base for coding agents. Activate when: (1) starting a new session in this project, (2) encountering unfamiliar code patterns or architecture decisions, (3) user asks about project design or rationale, (4) before making significant structural changes. Contains tiered knowledge from stable design principles to dynamic issues.
+---
+
+# AI Context — Litho (deepwiki-rs)
+
+> This skill provides pre-generated project knowledge to help you understand the project faster and work more effectively.
+
+---
+
+## 🎯 When to Activate This Skill
+
+**Activate immediately when:**
+- Starting a new coding session in this project
+- You need to understand "why something is designed this way"
+- User asks about project architecture, design decisions, or constraints
+
+**Refer to specific sections when:**
+- Encountering unexpected behavior or errors → `DYNAMICS.md`
+- Planning structural changes → `references/DECISIONS.md`
+- Need high-level overview → `references/PROJECT-ESSENCE.md`
+- Need component relationships → `references/ARCHITECTURE.md`
+
+**Do NOT activate when:**
+- Simple code edits with clear context
+- User requests are purely mechanical (rename, format, etc.)
+- You already have sufficient context from recent conversation
+
+---
+
+## 📁 Knowledge Tiers
+
+This skill organizes knowledge by **stability** — how frequently the knowledge changes:
+
+| Tier | File | Stability | Update Frequency |
+|------|------|-----------|------------------|
+| **Tier 0** | `PROJECT-ESSENCE.md` | High | Quarterly / Major version |
+| **Tier 1** | `ARCHITECTURE.md` | Medium | Monthly / Sprint |
+| **Tier 2** | `DECISIONS.md` | Low | Per decision change |
+| **Tier 3** | `DYNAMICS.md` | Dynamic | As needed (issues, incidents) |
+
+### Reading Order (Recommended)
+
+```
+1. PROJECT-ESSENCE.md  ← Start here (1-2 min read)
+2. ARCHITECTURE.md     ← If working across components
+3. DECISIONS.md        ← If changing established patterns
+4. DYNAMICS.md         ← If something feels wrong
+```
+
+---
+
+## 🔧 How to Use This Knowledge
+
+### 1. Session Start Protocol
+```
+□ Read PROJECT-ESSENCE.md (always)
+□ Scan DYNAMICS.md for active issues
+□ Read ARCHITECTURE.md if working across subprojects
+□ Proceed with dynamic code exploration
+```
+
+### 2. Dynamic Code Exploration
+This knowledge is a **starting point**, not a replacement for reading code:
+- Use `grep` and `find_path` to locate actual implementations
+- Verify knowledge against current code state
+- Update knowledge if you find drift (see Maintenance section)
+
+### 3. Decision Validation
+Before changing established patterns:
+```
+□ Check DECISIONS.md for existing decisions
+□ If decision exists: follow it or explicitly propose change
+□ If new decision needed: document after implementation
+```
+
+---
+
+## 🔄 When to Update This Knowledge
+
+### Update PROJECT-ESSENCE.md when:
+- Project purpose or scope fundamentally changes
+- New major capability is added
+- Core user workflow changes
+
+### Update ARCHITECTURE.md when:
+- New component/subproject added
+- Component responsibilities shift
+- Data flow changes significantly
+- API contracts change
+
+### Update DECISIONS.md when:
+- A new design decision is made (especially if non-obvious)
+- An existing decision is revisited/changed
+- A trade-off is resolved differently
+
+### Update DYNAMICS.md when:
+- New issue discovered that blocks normal workflow
+- Workaround found for existing issue
+- Issue is resolved
+- Temporary constraint is added/removed
+
+---
+
+## ⚠️ Important Principles
+
+1. **Knowledge is a guide, not truth** — Always verify against actual code
+2. **Update responsibly** — Stale knowledge is worse than no knowledge
+3. **Keep it high-level** — Details belong in code comments
+4. **Trust dynamic exploration** — Use tools to find current state
+
+---
+
+## 📚 File Reference
+
+- [Project Essence](references/PROJECT-ESSENCE.md) — What this project is and why
+- [Architecture](references/ARCHITECTURE.md) — How components fit together
+- [Decisions](references/DECISIONS.md) — Key design decisions and rationale
+- [Dynamics](DYNAMICS.md) — Active issues, workarounds, temporary constraints
+- [Maintenance Guide](meta/MAINTENANCE.md) — How to maintain this knowledge base
+
+---
+
+## 🔗 Integration with AGENTS.md
+
+This skill complements `AGENTS.md` in the project root:
+
+| File | Purpose | Who writes |
+|------|---------|------------|
+| `AGENTS.md` | Operational rules, commands, style | Project maintainers |
+| `.ai-context/` | Pre-generated knowledge | System / Auto-generated |
+
+Both should be read at session start. `AGENTS.md` tells you **how to work**, `.ai-context` tells you **what the project is**.
+
+---
+
+*Generated by ai-context-generator skill*