lytics · prosdev · Dec 12, 2025 · Dec 12, 2025 · Dec 12, 2025 · Dec 12, 2025
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -7,17 +7,22 @@
 <!-- Link to related GitHub issues -->
 Closes #
 
-## 🧪 Testability Checklist
+## 🧪 Code Standards Checklist
 
-<!-- Check all that apply -->
+<!-- Check all that apply - See docs/TYPESCRIPT_STANDARDS.md -->
 
 - [ ] Pure functions extracted to `utils/` modules
 - [ ] Utilities achieve 100% coverage (statements & functions)
-- [ ] No `!` non-null assertions (use guard clauses or optional chaining)
+- [ ] **No type assertions (`as`, `!`)** without validation
+- [ ] **Runtime validation** for external data (Zod/type guards)
+- [ ] **Result types** used instead of exceptions
 - [ ] Modules organized by domain (not generic "utils")
-- [ ] Each module < 200 lines
+- [ ] Each module < 300 lines, each class < 400 lines
+- [ ] Constructor injection for dependencies
 - [ ] Atomic commits with clear dependencies
 
+**See:** [TypeScript Standards](../docs/TYPESCRIPT_STANDARDS.md)
+
 ## ✅ Testing
 
 <!-- Describe testing approach -->

diff --git a/WORKFLOW.md b/WORKFLOW.md
@@ -2,6 +2,14 @@
 
 Standard workflow for implementing features in dev-agent.
 
+## 📚 Related Documentation
+
+Before starting development, familiarize yourself with our coding standards:
+
+- **[TypeScript Standards](./docs/TYPESCRIPT_STANDARDS.md)** ⭐ **START HERE** - Our coding manifesto
+- **[Feature Template](./docs/FEATURE_TEMPLATE.md)** - Step-by-step guide for new features
+- **[Architecture](./ARCHITECTURE.md)** - System design and package structure
+
 ## The Drill™
 
 ### 1. Find Next Work (Dogfooding! 🐕🍽️)
@@ -99,6 +107,7 @@ pnpm typecheck
 - ✅ 100% function coverage
 - ✅ No linter errors
 - ✅ No TypeScript errors
+- ✅ **Follows [TypeScript Standards](./docs/TYPESCRIPT_STANDARDS.md)** (no `as`, Result types, pure functions)
 - ✅ Documentation with examples
 
 ### 6. Commit & PR
@@ -175,6 +184,156 @@ Fix MCP install error handling' > .changeset/fix-name.md
 - The wrapper package needs to pull in the latest CLI changes
 - Ensures `npm install -g dev-agent` gets all improvements
 
+## 🎯 Commit Checkpoints (Know When to Commit)
+
+**Principle:** Commit when you reach a "green state" at a logical boundary. Secure working progress before entering complexity.
+
+### The Checkpoint Signals
+
+Commit when you hit **any 2** of these signals:
+
+#### 1. ✅ Green State
+- All tests passing
+- Build successful  
+- No linter/TypeScript errors
+- **This is non-negotiable** - never commit broken code
+
+#### 2. 🎯 Logical Boundary
+- Foundation complete (schemas, types, utils)
+- Feature partially working (demo-able)
+- Pattern proven (1+ examples working)
+- Module/component finished
+
+#### 3. ⚠️ Before Complexity
+- About to refactor large file (>500 lines)
+- About to change core architecture
+- About to touch multiple interconnected systems
+- About to migrate/upgrade major dependencies
+
+#### 4. 📊 Demonstrable Value
+- Can show progress in PR review
+- Reviewers can understand what changed
+- Rollback would still leave useful code
+- "X/Y complete" milestones (e.g., "5/9 adapters migrated")
+
+#### 5. 🧠 Context Limits
+- Approaching 150K+ tokens in AI session
+- Been working >2 hours on single task
+- About to switch tasks/contexts
+- End of work session
+
+### Examples of Good Checkpoints
+
+✅ **Foundation + Pattern Proven**
+```bash
+git commit -m "feat(mcp): add Zod validation to MCP adapters (5/9 complete)
+
+- Create schemas for all 9 adapters (247 lines, 33 tests)
+- Migrate 5 adapters (eliminates ~150 lines of validation)
+- Pattern proven, remaining 4 follow same approach
+
+All tests passing, build successful"
+```
+
+✅ **Before Complexity**
+```bash
+git commit -m "refactor(indexer): extract pure stat merging functions
+
+- Extract 6 pure functions from 102-line method
+- Add comprehensive tests (17 tests, 100% coverage)
+- About to integrate into RepositoryIndexer class
+
+Foundation secure before complex integration"
+```
+
+✅ **Logical Boundary**
+```bash
+git commit -m "feat(core): add stats metadata tracking
+
+- Add StatsMetadata interface
+- Implement in getStats() method
+- Update CLI formatters to display metadata
+
+Next: Incremental update merging (complex)"
+```
+
+### Anti-Patterns (Don't Commit)
+
+❌ **Broken State**
+```bash
+# NEVER commit this:
+git commit -m "WIP: refactoring adapters, tests failing"
+git commit -m "fix: half-done, will finish tomorrow"
+```
+
+❌ **No Value**
+```bash
+# Don't commit just to save work:
+git commit -m "save work"
+git commit -m "checkpoint" # (what's done?)
+git commit -m "WIP" # (what works?)
+```
+
+❌ **Debug Code**
+```bash
+# Don't commit with:
+console.log('DEBUG: ...')
+// TODO: fix this later
+// HACK: temporary workaround
+```
+
+### Quick Checkpoint Checklist
+
+Run before every commit:
+
+```bash
+# 1. Quality gates
+pnpm build      # ✅ Builds without errors?
+pnpm test       # ✅ All tests pass?
+pnpm typecheck  # ✅ No TypeScript errors?
+
+# 2. Review changes
+git diff --stat # 📊 Reasonable change size?
+git status      # 🔍 All intended files staged?
+
+# 3. If all pass → commit!
+git add -A
+git commit -m "feat(scope): description..."
+```
+
+### Why This Matters
+
+**For Teams:**
+- Reduces risk of losing working code
+- Makes code review easier (incremental progress)
+- Git bisect finds bugs faster
+- Enables parallel work (others can pull partial features)
+
+**For AI Collaboration:**
+- Context windows reset - commits are checkpoints
+- Recovery is instant (just read git log)
+- TODOs + commits = perfect state reconstruction
+- Enables long-running refactorings (>1 session)
+
+**For You:**
+- Sleep better (work is secured)
+- Switch contexts freely (commit before leaving)
+- Experiment safely (can always rollback)
+- Build confidence (see progress accumulate)
+
+### Real Example: Zod Migration
+
+**Checkpoint Decision:** After migrating 5/9 adapters
+- ✅ Green: All tests passing, build successful
+- ✅ Logical boundary: Foundation complete, pattern proven
+- ✅ Before complexity: Next 4 adapters are 690-724 lines each
+- ✅ Demonstrable: "5/9 complete, 150 lines eliminated"
+- ✅ Context: At 115K tokens, approaching limit
+
+**Result:** Committed working state. If next adapters break, we can rollback to this checkpoint.
+
+---
+
 ## Commit Message Format
 
 ### Structure

diff --git a/docs/FEATURE_TEMPLATE.md b/docs/FEATURE_TEMPLATE.md
@@ -260,24 +260,16 @@ Before submitting your feature:
 
 ---
 
-## 📚 Examples
+## 📚 Examples & Resources
 
-See these implementations:
+**Real implementations:**
+1. `packages/subagents/src/explorer/` - 99 tests, 100% on utilities
+2. `packages/core/src/indexer/stats-merger.ts` - 17 tests, pure functions
+3. `packages/cli/src/utils/date-utils.ts` - 18 tests, 100% coverage
 
-1. **Explorer Subagent**
-   - Path: `packages/subagents/src/explorer/`
-   - 99 tests, 100% on utilities
-   - 4 domain modules: metadata, filters, relationships, analysis
-
-2. **Repository Indexer**
-   - Path: `packages/core/src/indexer/`
-   - 87 tests on utilities
-   - 3 domain modules: language, formatting, documents
-
-3. **Subagent Coordinator**
-   - Path: `packages/subagents/src/coordinator/`
-   - Context manager, task queue, message protocol
-   - High test coverage with mocks where needed
+**Documentation:**
+- [TYPESCRIPT_STANDARDS.md](./TYPESCRIPT_STANDARDS.md) - Our coding manifesto
+- [REFACTORING_SUMMARY.md](./REFACTORING_SUMMARY.md) - Recent refactoring example
 
 ---
 

diff --git a/docs/README.md b/docs/README.md
@@ -1,20 +1,125 @@
-# Dev-Agent Documentation
+# Documentation Index
 
-This directory contains comprehensive documentation for the Dev-Agent project.
+Welcome to the dev-agent documentation! This index helps you find the right doc for your needs.
 
-## Contents
+---
 
-- [Getting Started](./getting-started.md) - Installation and basic usage
-- [Architecture](./architecture.md) - System architecture and components
-- [Configuration](./configuration.md) - Configuration options
-- [Integrations](./integrations.md) - Integration with AI tools
-- [API Reference](./api-reference.md) - API documentation
-- [Subagents](./subagents.md) - Working with subagents
+## 🚀 Getting Started
 
-## Quick Start
+- **[AGENTS.md](../AGENTS.md)** - AI agent guidance for working with this codebase
+- **[CLAUDE.md](../CLAUDE.md)** - Claude Code specific integration guide
+- **[README.md](../README.md)** - Project overview and quick start
 
-See the [Getting Started](./getting-started.md) guide for installation and basic usage instructions.
+---
 
-## Contributing
+## 📐 Architecture & Design
 
-For contribution guidelines, see the [Contributing](./contributing.md) document.
+- **[ARCHITECTURE.md](../ARCHITECTURE.md)** - System architecture, design decisions
+- **[LANGUAGE_SUPPORT.md](../LANGUAGE_SUPPORT.md)** - Supported languages and parsers
+
+---
+
+## 💻 Development
+
+### Core Standards (Read These First!)
+
+- **[TYPESCRIPT_STANDARDS.md](./TYPESCRIPT_STANDARDS.md)** ⭐ **START HERE - Our Manifesto**
+  - Pure function extraction
+  - Runtime validation (Zod)
+  - Result types vs exceptions
+  - Dependency injection
+  - Testing requirements
+  - Module organization
+
+- **[WORKFLOW.md](../WORKFLOW.md)** ⭐ **Essential**
+  - Branch strategy
+  - Commit standards
+  - PR process
+  - Testing requirements
+
+### Feature Development
+
+- **[FEATURE_TEMPLATE.md](./FEATURE_TEMPLATE.md)**
+  - Step-by-step guide for new features
+  - Structure and organization
+  - Testing strategy
+  - Checklist and examples
+
+---
+
+## 🧪 Testing & Quality
+
+- **[TYPESCRIPT_STANDARDS.md](./TYPESCRIPT_STANDARDS.md)** - Testing philosophy, coverage targets, patterns
+
+---
+
+## 🤝 Contributing
+
+- **[CONTRIBUTING.md](../CONTRIBUTING.md)** - How to contribute
+- **[CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md)** - Community standards
+- **[WORKFLOW.md](../WORKFLOW.md)** - Development workflow
+
+---
+
+## 🔧 Operations
+
+- **[TROUBLESHOOTING.md](../TROUBLESHOOTING.md)** - Common issues and solutions
+- **[SECURITY.md](../SECURITY.md)** - Security policy
+
+---
+
+## 📝 Other Resources
+
+- **[CHANGELOG.md](../CHANGELOG.md)** - Version history
+- **[PLAN.md](../PLAN.md)** - Project roadmap
+
+---
+
+## 🎯 Quick Reference by Task
+
+### "I'm implementing a new feature"
+1. Read [TYPESCRIPT_STANDARDS.md](./TYPESCRIPT_STANDARDS.md) (our manifesto)
+2. Follow [WORKFLOW.md](../WORKFLOW.md)
+3. Use [FEATURE_TEMPLATE.md](./FEATURE_TEMPLATE.md) for structure
+
+### "I'm refactoring existing code"
+1. Apply [TYPESCRIPT_STANDARDS.md](./TYPESCRIPT_STANDARDS.md) patterns
+2. See [REFACTORING_SUMMARY.md](./REFACTORING_SUMMARY.md) for example
+
+### "I'm fixing a bug"
+1. Follow [WORKFLOW.md](../WORKFLOW.md#bug-fixes)
+2. Add regression tests
+3. Document in [TROUBLESHOOTING.md](../TROUBLESHOOTING.md) if common
+
+### "I'm reviewing a PR"
+1. Check [.github/pull_request_template.md](../.github/pull_request_template.md)
+2. Verify [TYPESCRIPT_STANDARDS.md](./TYPESCRIPT_STANDARDS.md) compliance
+
+### "I'm using AI to help code"
+1. Share [AGENTS.md](../AGENTS.md) and [TYPESCRIPT_STANDARDS.md](./TYPESCRIPT_STANDARDS.md) with AI
+2. Use [FEATURE_TEMPLATE.md](./FEATURE_TEMPLATE.md) for structure
+
+---
+
+## 📚 External Resources
+
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
+- [Zod Documentation](https://zod.dev/)
+- [Vitest Guide](https://vitest.dev/guide/)
+- [Turborepo Docs](https://turbo.build/repo/docs)
+
+---
+
+## ❓ Questions?
+
+If you can't find what you're looking for:
+
+1. Check this index again
+2. Search the repository
+3. Ask in GitHub Discussions
+4. Create an issue with label `documentation`
+
+---
+
+**Last Updated:** 2024-12-12  
+**Maintained By:** dev-agent contributors