Dev

.ai-context/DYNAMICS.md

@@ -0,0 +1,58 @@
+# Dynamics — Active Issues & Constraints
+
+> **Last updated:** 2026-04-17
+> **Stability:** Dynamic — Update as issues arise/resolve
+
+---
+
+## ⚡ Quick Scan
+
+| Status | Issue | Impact | Workaround |
+|--------|-------|--------|------------|
+| 🟡 | LLM serial execution | Throughput limited by concurrency=1 | Intentional; rate limit compliance |
+| 🟡 | Keyword-based intent recognition (PM Agent) | Ambiguous requests may be misclassified | PM Agent asks for clarification |
+| 🟡 | JSON persistence lacks query capabilities | No efficient search across projects | Use file system tools for search |
+
+---
+
+## 🟡 Known Constraints
+
+### LLM Serial Execution
+- Global semaphore (concurrency=1) means all LLM calls are serialized
+- This is intentional for rate limit compliance (30 req/min)
+- Pipeline stages cannot parallelize LLM-dependent work
+
+### PM Agent Intent Recognition
+- Uses keyword-based NLP (not ML-based)
+- Ambiguous user input triggers clarification requests
+- Intent types: bug_fix, requirement_change, new_feature, consultation, ambiguous
+
+### JSON Storage Limitations
+- No built-in indexing or query engine
+- Concurrent access not protected (single-user assumption)
+- Large projects may experience slower load times
+
+### Storage Location
+- Project data: `.cowork-v2/` in project root
+- User config: platform-specific app data directory
+- See `crates/cowork-core/src/config.rs` for path resolution
+
+---
+
+## 🟢 Recently Resolved
+
+| Issue | Resolution | Date |
+|-------|------------|------|
+| N/A | N/A | — |
+
+---
+
+## 📋 Under Consideration
+
+- SQLite backend option for team/large-project scenarios
+- Local model support (Llama, Mistral) for offline operation
+- Multi-user collaboration features (not currently in scope)
+
+---
+
+*Remember: This file changes frequently. Verify against current code state.*

.ai-context/SKILL.md

@@ -0,0 +1,110 @@
+---
+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 — Cowork Forge
+
+> 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
+
+| 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 |
+
+### 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
+- Use `grep` and file search to locate actual implementations
+- Verify knowledge against current code state
+- Update knowledge if you find drift
+
+### 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
+
+### Update PROJECT-ESSENCE.md when:
+- Project purpose or scope fundamentally changes
+- New major capability is added
+
+### Update ARCHITECTURE.md when:
+- New component/subproject added
+- Component responsibilities shift
+- Data flow changes significantly
+
+### Update DECISIONS.md when:
+- A new design decision is made
+- An existing decision is revisited/changed
+
+### Update DYNAMICS.md when:
+- New issue discovered
+- Issue resolved
+- Workaround found
+
+---
+
+## 📚 File Reference
+
+- [Project Essence](references/PROJECT-ESSENCE.md)
+- [Architecture](references/ARCHITECTURE.md)
+- [Decisions](references/DECISIONS.md)
+- [Dynamics](DYNAMICS.md)
+- [Maintenance Guide](meta/MAINTENANCE.md)
+
+---
+
+*Generated by ai-context-generator on 2026-04-17*