AGENTS.md

1<!-- Parent: ../AGENTS.md -->
2<!-- Generated: 2026-01-28 | Updated: 2026-01-31 -->
3 
4# features
5 
6Core feature modules for oh-my-claudecode - model routing, state management, verification, and more.
7 
8## Purpose
9 
10This directory contains self-contained feature modules that enhance orchestration:
11- **model-routing/** - Smart routing to Haiku/Sonnet/Opus based on task complexity
12- **boulder-state/** - Plan state persistence and tracking
13- **verification/** - Reusable verification protocol
14- **notepad-wisdom/** - Plan-scoped learnings, decisions, issues
15- **delegation-categories/** - Semantic task categorization
16- **task-decomposer/** - Task breakdown for parallel execution
17- **state-manager/** - Standardized state file management
18- **context-injector/** - Context enhancement injection
19- **background-agent/** - Background task concurrency
20- **rate-limit-wait/** - API rate limit handling
21 
22## Key Files
23 
24| File | Description |
25|------|-------------|
26| `index.ts` | Re-exports all feature modules |
27| `magic-keywords.ts` | Magic keyword detection (ultrawork, analyze, etc.) |
28| `continuation-enforcement.ts` | Ensures task completion before stopping |
29| `auto-update.ts` | Silent version checking and updates |
30| `background-tasks.ts` | Background task execution patterns |
31| `delegation-enforcer.ts` | Enforces delegation-first protocol |
32 
33## Subdirectories
34 
35| Directory | Purpose |
36|-----------|---------|
37| `model-routing/` | Intelligent model selection based on complexity |
38| `boulder-state/` | Plan state and progress persistence |
39| `verification/` | Verification protocol with evidence tracking |
40| `notepad-wisdom/` | Plan-scoped knowledge capture |
41| `delegation-categories/` | Task categorization for model/temp selection |
42| `task-decomposer/` | Task breakdown for parallelization |
43| `state-manager/` | Standardized state file locations |
44| `context-injector/` | Context enhancement for prompts |
45| `background-agent/` | Background task management |
46| `rate-limit-wait/` | Rate limit detection and waiting |
47| `builtin-skills/` | Built-in skill definitions |
48 
49## For AI Agents
50 
51### Working In This Directory
52 
53#### Model Routing
54 
55Routes tasks to optimal model based on complexity signals:
56 
57```typescript
58import { routeToModel, extractComplexitySignals } from './model-routing';
59 
60const signals = extractComplexitySignals(prompt);
61const model = routeToModel(signals); // 'haiku' | 'sonnet' | 'opus'
62```
63 
64**Signal types:**
65- Code complexity (LOC, cyclomatic complexity)
66- Task keywords (debug, refactor, implement)
67- File count and scope
68- Error/risk indicators
69 
70#### Boulder State
71 
72Persists plan state across sessions:
73 
74```typescript
75import { readBoulderState, writeBoulderState, hasBoulder } from './boulder-state';
76 
77if (hasBoulder()) {
78  const state = readBoulderState();
79  state.progress.completedTasks++;
80  writeBoulderState(state);
81}
82```
83 
84**State location:** `.omc/state/boulder.json`
85 
86#### Verification Protocol
87 
88Standardized verification with evidence:
89 
90```typescript
91import { createVerificationContext, addEvidence, isVerified } from './verification';
92 
93const ctx = createVerificationContext(['BUILD', 'TEST', 'FUNCTIONALITY']);
94addEvidence(ctx, 'BUILD', { passed: true, output: '...' });
95addEvidence(ctx, 'TEST', { passed: true, output: '...' });
96 
97if (isVerified(ctx)) {
98  // All checks passed
99}
100```
101 
102**Check types:** BUILD, TEST, LINT, FUNCTIONALITY, ARCHITECT, TODO, ERROR_FREE
103 
104#### Notepad Wisdom
105 
106Capture learnings during execution:
107 
108```typescript
109import { initPlanNotepad, addLearning, addDecision } from './notepad-wisdom';
110 
111initPlanNotepad('my-plan');
112addLearning('my-plan', 'The API requires auth headers');
113addDecision('my-plan', 'Using JWT for authentication');
114```
115 
116**Location:** `.omc/notepads/{plan-name}/`
117 
118#### Delegation Categories
119 
120Semantic categorization for model selection:
121 
122```typescript
123import { categorizeTask, getCategoryConfig } from './delegation-categories';
124 
125const category = categorizeTask(prompt); // 'ultrabrain' | 'visual-engineering' | etc.
126const config = getCategoryConfig(category);
127// { tier: 'HIGH', temperature: 0.3, thinking: 'max' }
128```
129 
130### Modification Checklist
131 
132#### When Adding a New Feature
133 
1341. Create feature directory with `index.ts`, `types.ts`, `constants.ts`
1352. Export from `features/index.ts`
1363. Update `docs/FEATURES.md` with API documentation
1374. Update `docs/AGENTS.md` if architecture changes
138 
139#### When Modifying State File Paths
140 
1411. Update `state-manager/` for path standardization
1422. Consider migration logic for existing state files
1433. Document new paths in feature's README or AGENTS.md
144 
145### Common Patterns
146 
147#### Feature Module Structure
148 
149```
150feature-name/
151├── index.ts     # Main exports
152├── types.ts     # TypeScript interfaces
153├── constants.ts # Configuration constants
154└── *.ts         # Implementation files
155```
156 
157### Testing Requirements
158 
159```bash
160npm test -- --grep &quot;features&quot;
161```
162 
163## Dependencies
164 
165### Internal
166- Features are self-contained but may import from `shared/types.ts`
167 
168### External
169| Package | Purpose |
170|---------|---------|
171| `fs`, `path` | File operations for state persistence |
172 
173## Feature Summary
174 
175| Feature | Purpose | State Location |
176|---------|---------|----------------|
177| model-routing | Smart model selection | N/A (stateless) |
178| boulder-state | Plan progress tracking | `.omc/state/boulder.json` |
179| verification | Evidence-based verification | In-memory |
180| notepad-wisdom | Knowledge capture | `.omc/notepads/` |
181| delegation-categories | Task categorization | N/A (stateless) |
182| task-decomposer | Parallelization | In-memory |
183| state-manager | File path standardization | `.omc/state/`, `~/.omc/state/` |
184| context-injector | Prompt enhancement | In-memory |
185| background-agent | Concurrency control | In-memory |
186| rate-limit-wait | Rate limit handling | `.omc/state/rate-limits.json` |
187 
188<!-- MANUAL: -->
189