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:

# 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