# Context Generation Workflow

Generate hierarchical CLAUDE.md documentation structure with directed context loading for {{ project.name }}.

## Purpose

This workflow creates CLAUDE.md files with front matter that enables **directed context loading** - each file specifies what child contexts to load based on task keywords, allowing Claude Code to load only the relevant context for each task.

## Prerequisites

1. Repository should be initialized with `taid init`
2. Run `taid context generate --dry-run` first to see the plan

## Workflow Steps

### Step 1: Analyze Repository Structure

```bash
# See what directories will be documented
taid context generate --dry-run
```

### Step 2: Generate Base CLAUDE.md Files

```bash
# Create initial CLAUDE.md templates
taid context generate
```

### Step 3: Add Context Directives to Root CLAUDE.md

Update the root CLAUDE.md with front matter that directs context loading:

```yaml
---
context:
  keywords: [{{ project.name | lower | replace(' ', '-') }}, framework, project, overview]
  task_types: [any]
  priority: high
  max_tokens: 1500
  children:
    - path: src/CLAUDE.md
      when: [implementation, code, feature, bug, api]
    - path: tests/CLAUDE.md
      when: [test, testing, pytest, coverage]
    - path: docs/CLAUDE.md
      when: [documentation, api-docs]
    # Add other directories as needed based on your project structure
  dependencies: []
---
# Project Name
...
```

**Front Matter Fields:**
- `keywords`: Keywords that make this context relevant
- `task_types`: Types of tasks this context applies to
- `priority`: high/medium/low - affects token allocation
- `max_tokens`: Maximum tokens to use from this file
- `children`: Child contexts to potentially load
  - `path`: Relative path to child CLAUDE.md
  - `when`: Keywords that trigger loading this child
- `dependencies`: Contexts that must be loaded first

### Step 4: Add Context Directives to Directory CLAUDE.md Files

For each directory's CLAUDE.md, add appropriate front matter:

**Example for src/CLAUDE.md:**
```yaml
---
context:
  keywords: [source, code, implementation, api, service]
  task_types: [implementation, feature-development, bug-fix]
  priority: high
  max_tokens: 800
  children:
    - path: src/api/CLAUDE.md
      when: [api, endpoint, route, handler]
    - path: src/services/CLAUDE.md
      when: [service, business-logic, domain]
    - path: src/models/CLAUDE.md
      when: [model, schema, entity, database]
  dependencies: []
---
# src - Source Code
...
```

**Example for tests/CLAUDE.md:**
```yaml
---
context:
  keywords: [test, testing, pytest, fixture, mock, coverage]
  task_types: [testing, quality-assurance]
  priority: medium
  max_tokens: 600
  children:
    - path: tests/unit/CLAUDE.md
      when: [unit, fast]
    - path: tests/integration/CLAUDE.md
      when: [integration, e2e]
  dependencies: []
---
# tests - Test Suite
...
```

### Step 5: Enhance CLAUDE.md Content

For each CLAUDE.md, ensure it contains:

1. **Purpose**: What this module does (1 paragraph)
2. **Key Components**: List of important files with descriptions
3. **Architecture**: How components interact
4. **Usage Examples**: Code snippets showing typical usage
5. **Conventions**: Patterns and naming conventions used
6. **Testing**: How to test this module

**Task for Claude:** Read and enhance each CLAUDE.md by analyzing:
- The actual source code in that directory
- Imports and dependencies
- Public interfaces and APIs
- Test files for usage examples

### Step 6: Test Directed Context Loading

Test the directed loader to verify context is loaded correctly:

```bash
# Test context loading for different task types
python -m core.directed_loader load sprint-planning azure work-item
python -m core.directed_loader load implementation api feature
python -m core.directed_loader load testing pytest unit

# View the full context tree
python -m core.directed_loader tree
```

Or use the CLI:

```bash
# Lookup context for a task
taid context lookup "implement user authentication API"
taid context lookup "write unit tests for payment service"
taid context lookup "plan sprint 10 work items"
```

### Step 7: Build Context Index

```bash
# Build the context index
taid context index

# Verify all CLAUDE.md files are indexed
taid context show
```

## How Directed Loading Works

1. **Start at Root**: Loader begins at root CLAUDE.md
2. **Match Keywords**: Compares task keywords against `keywords` and `task_types` in front matter
3. **Follow Children**: If a child's `when` keywords match, that child is loaded
4. **Recurse**: Process continues recursively through the tree
5. **Token Budget**: Respects `max_tokens` per file and total budget

**Example Flow for "sprint planning with azure devops":**
```
Root CLAUDE.md (always loaded, high priority)
├── workflows/CLAUDE.md (matches: "sprint", "planning")
├── agents/CLAUDE.md (matches: "sprint-planning" task type)
└── adapters/azure_devops/CLAUDE.md (matches: "azure", "devops")
```

## Output Structure

```
project/
├── CLAUDE.md                    # Root (with children directives)
├── src/
│   ├── CLAUDE.md               # Source (children: api, services, models)
│   ├── api/
│   │   └── CLAUDE.md           # API context
│   ├── services/
│   │   └── CLAUDE.md           # Services context
│   └── models/
│       └── CLAUDE.md           # Models context
├── tests/
│   ├── CLAUDE.md               # Tests (children: unit, integration)
│   ├── unit/
│   │   └── CLAUDE.md           # Unit test context
│   └── integration/
│       └── CLAUDE.md           # Integration test context
└── .claude/
    └── context-index.yaml      # Index for fast lookup
```

## Configuration

- **Project**: {{ project.name }}
- **Type**: {{ project.type }}
{% if project.tech_stack.languages %}
- **Languages**: {{ project.tech_stack.languages | join(', ') }}
{% endif %}
{% if project.tech_stack.frameworks %}
- **Frameworks**: {{ project.tech_stack.frameworks | join(', ') }}
{% endif %}

## Success Criteria

- [ ] Root CLAUDE.md has context directives pointing to key directories
- [ ] Each directory CLAUDE.md has appropriate keywords and task_types
- [ ] Children directives route to relevant subdirectories
- [ ] `python -m core.directed_loader tree` shows correct hierarchy
- [ ] Context lookup returns relevant files for common tasks
- [ ] Token budgets are respected (verify with `tokens_used` output)
