# CONDUCTOR.md
<!-- Generated by Claude Conductor v2.0.0 -->

> _Read me first. Every other doc is linked below._

## Critical Context (Read First)
- **Tech Stack**: [List core technologies]
- **Main File**: [Primary code file and line count]
- **Core Mechanic**: [One-line description]
- **Key Integration**: [Important external services]
- **Platform Support**: [Deployment targets]
- **DO NOT**: [Critical things to avoid]

## Table of Contents
1. [Architecture](ARCHITECTURE.md) - Tech stack, folder structure, infrastructure
2. [Design Tokens](DESIGN.md) - Colors, typography, visual system
3. [UI/UX Patterns](UIUX.md) - Components, interactions, accessibility
4. [Runtime Config](CONFIG.md) - Environment variables, feature flags
5. [Data Model](DATA_MODEL.md) - Database schema, entities, relationships
6. [API Contracts](API.md) - Endpoints, request/response formats, auth
7. [Build & Release](BUILD.md) - Build process, deployment, CI/CD
8. [Testing Guide](TEST.md) - Test strategies, E2E scenarios, coverage
9. [Operational Playbooks](PLAYBOOKS/DEPLOY.md) - Deployment, rollback, monitoring
10. [Contributing](CONTRIBUTING.md) - Code style, PR process, conventions
11. [Error Ledger](ERRORS.md) - Critical P0/P1 error tracking
12. [Task Management](TASKS.md) - Active tasks, phase tracking, context preservation

## Quick Reference
**Main Constants**: `[file:lines]` - Description  
**Core Class**: `[file:lines]` - Description  
**Key Function**: `[file:lines]` - Description  
[Include 10-15 most accessed code locations]

## Current State
- [x] Feature complete
- [ ] Feature in progress
- [ ] Feature planned
[Track active work]

## Development Workflow
[5-6 steps for common workflow]

## Task Templates
### 1. [Common Task Name]
1. Step with file:line reference
2. Step with specific action
3. Test step
4. Documentation update

[Include 3-5 templates]

## Anti-Patterns (Avoid These)
❌ **Don't [action]** - [Reason]  
[List 5-6 critical mistakes]

## Version History
- **v1.0.0** - Initial release
- **v1.1.0** - Feature added (see JOURNAL.md YYYY-MM-DD)  
[Link major versions to journal entries]

## Continuous Engineering Journal <!-- do not remove -->

Claude, keep an ever-growing changelog in [`JOURNAL.md`](JOURNAL.md).

### What to Journal
- **Major changes**: New features, significant refactors, API changes
- **Bug fixes**: What broke, why, and how it was fixed
- **Frustration points**: Problems that took multiple attempts to solve
- **Design decisions**: Why we chose one approach over another
- **Performance improvements**: Before/after metrics
- **User feedback**: Notable issues or requests
- **Learning moments**: New techniques or patterns discovered

### Journal Format
\```
## YYYY-MM-DD HH:MM

### [Short Title]
- **What**: Brief description of the change
- **Why**: Reason for the change
- **How**: Technical approach taken
- **Issues**: Any problems encountered
- **Result**: Outcome and any metrics

### [Short Title] |ERROR:ERR-YYYY-MM-DD-001|
- **What**: Critical P0/P1 error description
- **Why**: Root cause analysis
- **How**: Fix implementation
- **Issues**: Debugging challenges
- **Result**: Resolution and prevention measures

### [Task Title] |TASK:TASK-YYYY-MM-DD-001|
- **What**: Task implementation summary
- **Why**: Part of [Phase Name] phase
- **How**: Technical approach and key decisions
- **Issues**: Blockers encountered and resolved
- **Result**: Task completed, findings documented in ARCHITECTURE.md
\```

### Compaction Rule
When `JOURNAL.md` exceeds **500 lines**:
1. Claude summarizes the oldest half into `JOURNAL_ARCHIVE/<year>-<month>.md`
2. Remaining entries stay in `JOURNAL.md` so the file never grows unbounded

> ⚠️ Claude must NEVER delete raw history—only move & summarize.

### 2. ARCHITECTURE.md
**Purpose**: System design, tech stack decisions, and code structure with line numbers.

**Required Elements**:
- Technology stack listing
- Directory structure diagram
- Key architectural decisions with rationale
- Component architecture with exact line numbers
- System flow diagram (ASCII art)
- Common patterns section
- Keywords for search optimization

**Line Number Format**:
\```
#### ComponentName Structure <!-- #component-anchor -->
\```typescript
// Major classes with exact line numbers
class MainClass { /* lines 100-500 */ }    // <!-- #main-class -->
class Helper { /* lines 501-600 */ }       // <!-- #helper-class -->
\```
\```

### 3. DESIGN.md
**Purpose**: Visual design system, styling, and theming documentation.

**Required Sections**:
- Typography system
- Color palette (with hex values)
- Visual effects specifications
- Character/entity design
- UI/UX component styling
- Animation system
- Mobile design considerations
- Accessibility guidelines
- Keywords section

### 4. DATA_MODEL.md
**Purpose**: Database schema, application models, and data structures.

**Required Elements**:
- Database schema (SQL)
- Application data models (TypeScript/language interfaces)
- Validation rules
- Common queries
- Data migration history
- Keywords for entities

### 5. API.md
**Purpose**: Complete API documentation with examples.

**Structure for Each Endpoint**:
\```
### Endpoint Name

\```http
METHOD /api/endpoint
\```

#### Request
\```json
{
  "field": "type"
}
\```

#### Response
\```json
{
  "field": "value"
}
\```

#### Details
- **Rate limit**: X requests per Y seconds
- **Auth**: Required/Optional
- **Notes**: Special considerations
\```

### 6. CONFIG.md
**Purpose**: Runtime configuration, environment variables, and settings.

**Required Sections**:
- Environment variables (required and optional)
- Application configuration constants
- Feature flags
- Performance tuning settings
- Security configuration
- Common patterns for configuration changes

### 7. BUILD.md
**Purpose**: Build process, deployment, and CI/CD documentation.

**Include**:
- Prerequisites
- Build commands
- CI/CD pipeline configuration
- Deployment steps
- Rollback procedures
- Troubleshooting guide

### 8. TEST.md
**Purpose**: Testing strategies, patterns, and examples.

**Sections**:
- Test stack and tools
- Running tests commands
- Test structure
- Coverage goals
- Common test patterns
- Debugging tests

### 9. UIUX.md
**Purpose**: Interaction patterns, user flows, and behavior specifications.

**Cover**:
- Input methods
- State transitions
- Component behaviors
- User flows
- Accessibility patterns
- Performance considerations

### 10. CONTRIBUTING.md
**Purpose**: Guidelines for contributors.

**Include**:
- Code of conduct
- Development setup
- Code style guide
- Commit message format
- PR process
- Common patterns

### 11. PLAYBOOKS/DEPLOY.md
**Purpose**: Step-by-step operational procedures.

**Format**:
- Pre-deployment checklist
- Deployment steps (multiple options)
- Post-deployment verification
- Rollback procedures
- Troubleshooting

### 12. ERRORS.md (Critical Error Ledger)
**Purpose**: Track and resolve P0/P1 critical errors with full traceability.

**Required Structure**:
\```
# Critical Error Ledger <!-- auto-maintained -->

## Schema
| ID | First seen | Status | Severity | Affected area | Link to fix |
|----|------------|--------|----------|---------------|-------------|

## Active Errors
[New errors added here, newest first]

## Resolved Errors
[Moved here when fixed, with links to fixes]
\```

**Error ID Format**: `ERR-YYYY-MM-DD-001` (increment for multiple per day)

**Severity Definitions**:
- **P0**: Complete outage, data loss, security breach
- **P1**: Major functionality broken, significant performance degradation
- **P2**: Minor functionality (not tracked in ERRORS.md)
- **P3**: Cosmetic issues (not tracked in ERRORS.md)

**Claude's Error Logging Process**:
1. When P0/P1 error occurs, immediately add to Active Errors
2. Create corresponding JOURNAL.md entry with details
3. When resolved:
   - Move to Resolved Errors section
   - Update status to "resolved"
   - Add commit hash and PR link
   - Add `|ERROR:<ID>|` tag to JOURNAL.md entry
   - Link back to JOURNAL entry from ERRORS.md

### 13. TASKS.md (Active Task Management)
**Purpose**: Track ongoing work with phase awareness and context preservation between sessions.

**IMPORTANT**: TASKS.md complements Claude's built-in todo system - it does NOT replace it:
- Claude's todos: For immediate task tracking within a session
- TASKS.md: For preserving context and state between sessions

**Required Structure**:
```
# Task Management

## Active Phase
**Phase**: [High-level project phase name]
**Started**: YYYY-MM-DD
**Target**: YYYY-MM-DD
**Progress**: X/Y tasks completed

## Current Task
**Task ID**: TASK-YYYY-MM-DD-NNN
**Title**: [Descriptive task name]
**Status**: PLANNING | IN_PROGRESS | BLOCKED | TESTING | COMPLETE
**Started**: YYYY-MM-DD HH:MM
**Dependencies**: [List task IDs this depends on]

### Task Context
<!-- Critical information needed to resume this task -->
- **Previous Work**: [Link to related tasks/PRs]
- **Key Files**: [Primary files being modified with line ranges]
- **Environment**: [Specific config/versions if relevant]
- **Next Steps**: [Immediate actions when resuming]

### Findings & Decisions
- **FINDING-001**: [Discovery that affects approach]
- **DECISION-001**: [Technical choice made] → Link to ARCHITECTURE.md
- **BLOCKER-001**: [Issue preventing progress] → Link to resolution

### Task Chain
1. ✅ [Completed prerequisite task] (TASK-YYYY-MM-DD-001)
2. 🔄 [Current task] (CURRENT)
3. ⏳ [Next planned task]
4. ⏳ [Future task in phase]
```

**Task Management Rules**:
1. **One Active Task**: Only one task should be IN_PROGRESS at a time
2. **Context Capture**: Before switching tasks, capture all context needed to resume
3. **Findings Documentation**: Record unexpected discoveries that impact the approach
4. **Decision Linking**: Link architectural decisions to ARCHITECTURE.md
5. **Completion Trigger**: When task completes:
   - Generate JOURNAL.md entry with task summary
   - Archive task details to TASKS_ARCHIVE/YYYY-MM/TASK-ID.md
   - Load next task from chain or prompt for new phase

**Task States**:
- **PLANNING**: Defining approach and breaking down work
- **IN_PROGRESS**: Actively working on implementation
- **BLOCKED**: Waiting on external dependency or decision
- **TESTING**: Implementation complete, validating functionality
- **COMPLETE**: Task finished and documented

**Integration with Journal**:
- Each completed task auto-generates a journal entry
- Journal references task ID for full context
- Critical findings promoted to relevant documentation

## Documentation Optimization Rules

### 1. Line Number Anchors
- Add exact line numbers for every class, function, and major code section
- Format: `**Class Name (Lines 100-200)**`
- Add HTML anchors: `<!-- #class-name -->`
- Update when code structure changes significantly

### 2. Quick Reference Card
- Place in CLAUDE.md after Table of Contents
- Include 10-15 most common code locations
- Format: `**Feature**: `file:lines` - Description`

### 3. Current State Tracking
- Use checkbox format in CLAUDE.md
- `- [x] Completed feature`
- `- [ ] In-progress feature`
- Update after each work session

### 4. Task Templates
- Provide 3-5 step-by-step workflows
- Include specific line numbers
- Reference files that need updating
- Add test/verification steps

### 5. Keywords Sections
- Add to each major .md file
- List alternative search terms
- Format: `## Keywords <!-- #keywords -->`
- Include synonyms and related terms

### 6. Anti-Patterns
- Use ❌ emoji for clarity
- Explain why each is problematic
- Include 5-6 critical mistakes
- Place prominently in CLAUDE.md

### 7. System Flow Diagrams
- Use ASCII art for simplicity
- Show data/control flow
- Keep visual and readable
- Place in ARCHITECTURE.md

### 8. Common Patterns
- Add to relevant docs (CONFIG.md, ARCHITECTURE.md)
- Show exact code changes needed
- Include before/after examples
- Reference specific functions

### 9. Version History
- Link to JOURNAL.md entries
- Format: `v1.0.0 - Feature (see JOURNAL.md YYYY-MM-DD)`
- Track major changes only

### 10. Cross-Linking
- Link between related sections
- Use relative paths: `[Link](./FILE.md#section)`
- Ensure bidirectional linking where appropriate

## Journal System Setup

### JOURNAL.md Structure
\```
# Engineering Journal

## YYYY-MM-DD HH:MM

### [Descriptive Title]
- **What**: Brief description of the change
- **Why**: Reason for the change
- **How**: Technical approach taken
- **Issues**: Any problems encountered
- **Result**: Outcome and any metrics

---

[Entries continue chronologically]
\```

### Journal Best Practices
1. **Entry Timing**: Add entry immediately after significant work
2. **Detail Level**: Include enough detail to understand the change months later
3. **Problem Documentation**: Especially document multi-attempt solutions
4. **Learning Moments**: Capture new techniques discovered
5. **Metrics**: Include performance improvements, time saved, etc.

### Archive Process
When JOURNAL.md exceeds 500 lines:
1. Create `JOURNAL_ARCHIVE/` directory
2. Move oldest 250 lines to `JOURNAL_ARCHIVE/YYYY-MM.md`
3. Add summary header to archive file
4. Keep recent entries in main JOURNAL.md

## Implementation Steps

### Phase 1: Initial Setup (30-60 minutes)
1. **Create CLAUDE.md** with all required sections
2. **Fill Critical Context** with 6 essential facts
3. **Create Table of Contents** with placeholder links
4. **Add Quick Reference** with top 10-15 code locations
5. **Set up Journal section** with formatting rules

### Phase 2: Core Documentation (2-4 hours)
1. **Create each .md file** from the list above
2. **Add Keywords section** to each file
3. **Cross-link between files** where relevant
4. **Add line numbers** to code references
5. **Create PLAYBOOKS/ directory** with DEPLOY.md
6. **Create ERRORS.md** with schema table

### Phase 3: Optimization (1-2 hours)
1. **Add Task Templates** to CLAUDE.md
2. **Create ASCII system flow** in ARCHITECTURE.md
3. **Add Common Patterns** sections
4. **Document Anti-Patterns**
5. **Set up Version History**

### Phase 4: First Journal Entry
Create initial JOURNAL.md entry documenting the setup:
\```
## YYYY-MM-DD HH:MM

### Documentation Framework Implementation
- **What**: Implemented CLAUDE.md modular documentation system
- **Why**: Improve AI navigation and code maintainability
- **How**: Split monolithic docs into focused modules with cross-linking
- **Issues**: None - clean implementation
- **Result**: [Number] documentation files created with full cross-referencing
\```

## Maintenance Guidelines

### Daily
- Update JOURNAL.md with significant changes
- Mark completed items in Current State
- Update line numbers if major refactoring

### Weekly
- Review and update Quick Reference section
- Check for broken cross-links
- Update Task Templates if workflows change

### Monthly
- Review Keywords sections for completeness
- Update Version History
- Check if JOURNAL.md needs archiving

### Per Release
- Update Version History in CLAUDE.md
- Create comprehensive JOURNAL.md entry
- Review all documentation for accuracy
- Update Current State checklist

## Benefits of This System

1. **AI Efficiency**: Claude can quickly navigate to exact code locations
2. **Modularity**: Easy to update specific documentation without affecting others
3. **Discoverability**: New developers/AI can quickly understand the project
4. **History Tracking**: Complete record of changes and decisions
5. **Task Automation**: Templates reduce repetitive instructions
6. **Error Prevention**: Anti-patterns prevent common mistakes