APAW/.kilo/rules/token-optimization.md

# Token Optimization Rules

Reduce token waste by ensuring 1 action = 1 task. No vague broad assignments, no scope creep, no unnecessary context.

## Core Principle: 1 Action = 1 Task

Every agent invocation solves exactly ONE atomic task. No more, no less.

## Token Budget Awareness

| Task Size | Max Tokens | Max Time | Example |
|----------|-----------|----------|---------|
| Tiny | 2,000 | 1 min | Fix a typo, add a config value |
| Small | 5,000 | 2 min | Create a model + migration |
| Medium | 10,000 | 5 min | Create an API endpoint + test |
| Large | 20,000 | 10 min | Create a full service with 3 methods |

## Optimization Strategies

### 1. Precise Task Descriptions

```
❌ BAD: "Implement the product feature"
   - Too broad, no boundaries, will try to do everything
   - Likely to hang or produce incomplete results

✅ GOOD: "Create Product model at app/Models/Product.php with fields: name, price, category_id, is_active. Create migration at database/migrations/2026_04_18_create_products_table.php"
   - Specific files, specific fields, atomic scope
```

### 2. Minimal Context

Only provide context that is directly needed for the task.

```
❌ BAD: Providing the entire codebase as context

✅ GOOD: Providing only the relevant files and interfaces
```

### 3. No Scope Creep

```
❌ BAD: Agent decides to also "improve" nearby code while fixing a bug
❌ BAD: Agent adds "helpful" features not requested
❌ BAD: Agent refactors unrelated code

✅ GOOD: Agent does exactly what was asked, nothing more
✅ GOOD: If agent sees improvement opportunity, REPORT it, don't implement it
```

### 4. Sequential Decomposition

Break large features into sequential atomic tasks:

```
Feature: Product Catalog
  ├── Task 1: Create Product model + migration (php-developer, 5k tokens)
  ├── Task 2: Create ProductRepository (php-developer, 5k tokens)
  ├── Task 3: Create ProductService (php-developer, 8k tokens)
  ├── Task 4: Create ProductController with index/show (php-developer, 5k tokens)
  ├── Task 5: Create ProductController with store/update/delete (php-developer, 5k tokens)
  ├── Task 6: Create ProductStoreRequest validation (php-developer, 3k tokens)
  ├── Task 7: Create ProductResource transformer (php-developer, 3k tokens)
  ├── Task 8: Create Product API routes (php-developer, 2k tokens)
  ├── Task 9: Write tests for ProductService (sdet-engineer, 8k tokens)
  ├── Task 10: Review all Product code (code-skeptic, 5k tokens)
```

Each task is independent, verifiable, and within token budget.

### 5. Skip Unnecessary Steps

If a task doesn't need design or research, skip those phases:

```
❌ BAD: Running full pipeline for a config change
   (requirement-refiner → history-miner → system-analyst → sdet → lead-dev → review)
   
✅ GOOD: Direct implementation for a config change
   (lead-developer → code-skeptic)
```

### 6. Reuse Existing Code

Before writing anything:
1. Search for existing implementations
2. Check if a similar pattern already exists
3. Use existing utilities and helpers
4. Don't reinvent what's already there

### 7. Verification After Each Task

After each atomic task:
1. Run relevant tests
2. Check lint/format
3. Log execution to `.kilo/logs/agent-executions.jsonl`
4. Post Gitea comment with results
5. Only then delegate to next agent

## Anti-Patterns to Avoid

### Kitchen Sink Invocations
```
❌ Task: "Build the entire admin panel"
   → Agent tries to do everything, hangs, wastes tokens, produces incomplete work

✅ Tasks: 
   1. "Create AdminDashboardController with stats endpoint"
   2. "Create AdminProductIndexController with list/search endpoint"
   3. "Create AdminProductFormController with create/edit endpoints"
```

### Over-Contexting
```
❌ Including entire file contents when only a few lines are relevant
✅ Including only the function that needs to change and its interface
```

### Multiple Responsibilities
```
❌ One agent doing both backend AND frontend
✅ Separate atomic tasks: backend-developer for API, frontend-developer for UI
```

## Task Routing Matrix

| Task Type | Agent | Typical Tokens |
|-----------|-------|---------------|
| Create model + migration | php-developer | 3-5k |
| Create API endpoint | php-developer | 5-8k |
| Create service method | php-developer | 3-5k |
| Create Vue component | frontend-developer | 5-8k |
| Write test for one function | sdet-engineer | 3-5k |
| Review code changes | code-skeptic | 3-8k |
| Fix specific bug | the-fixer | 3-5k |
| Security audit | security-auditor | 5-10k |
| Performance review | performance-engineer | 5-8k |
| Create Docker config | devops-engineer | 3-5k |
| Create Gitea issue | orchestrator | 1-2k |

## Monitoring Token Usage

Check `.kilo/logs/agent-executions.jsonl` for token usage patterns:

```bash
# Find most expensive agent invocations
cat .kilo/logs/agent-executions.jsonl | sort -t'"tokens_used":' -k2 -rn | head -10

# Find failed tasks (tokens wasted)
cat .kilo/logs/agent-executions.jsonl | grep '"status":"fail"'
```

## Checklist

- [ ] Each task has exactly ONE atomic deliverable
- [ ] Task description specifies exact files and changes
- [ ] No agent tries to do more than its assigned task
- [ ] Token budget is respected per task type
- [ ] Verification happens after each atomic task
- [ ] Unnecessary pipeline steps are skipped
- [ ] Existing code is reused, not rewritten
- [ ] Execution is logged for monitoring