Agent Frontmatter: Thinking Configuration

Agent Frontmatter: Thinking Configuration

Status: Production Version: 1.0.0 Created: 2025-12-22 Category: Agent Configuration

---

Overview

The thinking_config frontmatter extension allows agents to specify their thinking budget preferences, constraints, and optimization settings. This enables cost-efficient AI operations while maintaining quality standards.

Frontmatter Schema

---
name: agent-name
description: Agent description
tools: Read, Write, Grep
model: sonnet

# Thinking Budget Configuration
thinking_config:
  default_level: medium          # Default budget level for this agent
  max_level: high                # Maximum budget level allowed
  min_level: low                 # Minimum budget level (quality floor)
  budget_tokens: 4096            # Explicit token budget override
  adaptive: true                 # Enable adaptive budget adjustment
  track_usage: true              # Track thinking token consumption
---

Configuration Fields

default_level

Type: String (enum) Values: none, low, medium, high, ultrathink Default: medium

The default thinking budget level for this agent's operations.

Examples:

• low - Documentation writer (simple edits)
• medium - Feature developer (standard implementation)
• high - QA specialist (thorough review)
• ultrathink - System architect (complex planning)

max_level

Type: String (enum) Values: none, low, medium, high, ultrathink Default: ultrathink

Maximum thinking budget level this agent can use, even for complex tasks.

Use Cases:

• Prevent cost overruns for routine agents
• Enforce budget constraints on specific agents
• Balance quality vs. cost for different agent types

min_level

Type: String (enum) Values: none, low, medium, high, ultrathink Default: none

Minimum thinking budget level for quality assurance.

Use Cases:

• Ensure minimum quality for critical agents (QA, Security)
• Prevent under-thinking on important tasks
• Maintain consistency in agent output quality

budget_tokens

Type: Integer or null Default: null (use level-based budgets)

Explicit token budget override, bypassing level-based budgets.

Examples:

• 2048 - Custom budget for specialized agent
• 8192 - Mid-range custom budget
• null - Use standard level-based budgets

adaptive

Type: Boolean Default: true

Enable adaptive budget adjustment based on task complexity.

When true:

• Simple tasks → budget downgraded automatically
• Complex tasks → budget upgraded automatically
• Critical tasks → maximum budget applied

When false:

• Always use default_level regardless of complexity
• Predictable, consistent costs
• Suitable for routine, standardized agents

track_usage

Type: Boolean Default: true

Track thinking token consumption for cost analysis.

When true:

• Usage logged to .coditect/thinking-usage.json
• Statistics available via --stats command
• Cost optimization recommendations generated

Budget Levels

Level	Tokens	Use Cases	Cost Multiplier
ultrathink	65,536	Architecture design, strategic planning, complex system design	4.0x
high	16,384	QA review, security audit, critical analysis	2.0x
medium	4,096	Feature implementation, bug fixes, refactoring	1.0x
low	1,024	Formatting, documentation, simple edits	0.25x
none	null	Information retrieval, status checks, file reads	0.0x

Example Configurations

QA Specialist

---
name: qa-specialist
description: Quality assurance and code review expert
tools: Read, Grep, Bash
model: sonnet

thinking_config:
  default_level: high
  max_level: ultrathink
  min_level: medium
  adaptive: true
  track_usage: true
---

Rationale:

• High default for thorough reviews
• Allows ultrathink for critical security audits
• Never drops below medium (quality floor)
• Adapts to task complexity
• Tracks usage for cost optimization

Documentation Writer

---
name: documentation-writer
description: Technical documentation specialist
tools: Read, Write, Edit
model: sonnet

thinking_config:
  default_level: low
  max_level: medium
  min_level: none
  adaptive: true
  track_usage: true
---

Rationale:

• Low default for routine documentation
• Medium max for complex technical docs
• Can use none for simple typo fixes
• Cost-optimized for high-volume tasks

System Architect

---
name: system-architect
description: Architecture design and strategic planning
tools: Read, Write, Grep, Glob
model: sonnet

thinking_config:
  default_level: ultrathink
  max_level: ultrathink
  min_level: high
  adaptive: false
  track_usage: true
---

Rationale:

• Always uses maximum thinking budget
• No adaptation (always deep thinking)
• Never drops below high quality
• Suitable for critical architecture work

Usage with Thinking Budget Manager

Get Budget for Agent

# Get recommended budget for agent
python3 scripts/thinking-budget-manager.py \
  --agent qa-specialist \
  --task code_review \
  --complexity standard

# Output:
# Budget Level: high
# Tokens: 16,384
# Estimated Cost: $0.0360

Track Agent Usage

# Track actual usage
python3 scripts/thinking-budget-manager.py --track \
  --task code_review \
  --budget-level high \
  --tokens-used 12500 \
  --agent qa-specialist

View Agent Statistics

# Show statistics by agent
python3 scripts/thinking-budget-manager.py --stats

# Output includes:
# 🤖 By Agent:
#   qa-specialist    - 45 sessions, 675,000 tokens, $15.1875
#   doc-writer       - 120 sessions, 98,000 tokens, $1.7150

Integration Examples

Agent Initialization

# In agent orchestration system
def initialize_agent(agent_name: str, task: str):
    """Initialize agent with thinking budget"""
    manager = ThinkingBudgetManager(framework_root)

    # Load agent config
    agent_config = load_agent_frontmatter(agent_name)
    thinking_config = agent_config.get("thinking_config", {})

    # Get recommended budget
    complexity = detect_task_complexity(task)
    level, tokens = manager.get_thinking_budget(
        task_type=task,
        complexity=complexity,
        agent_name=agent_name
    )

    # Apply agent constraints
    if thinking_config.get("adaptive") is False:
        level = thinking_config["default_level"]
        tokens = manager.get_budget_tokens(level)

    return {
        "agent": agent_name,
        "budget_level": level,
        "budget_tokens": tokens,
        "thinking_config": thinking_config
    }

Usage Tracking

# After agent execution
def track_agent_usage(agent_name: str, task: str, tokens_used: int):
    """Track thinking token usage"""
    manager = ThinkingBudgetManager(framework_root)

    # Determine budget level used
    level = infer_budget_level(tokens_used)

    # Track usage
    manager.track_usage(
        task_type=task,
        budget_level=level,
        tokens_used=tokens_used,
        agent_name=agent_name
    )

Cost Optimization Strategies

1. Default Level Selection

Choose appropriate defaults based on agent purpose:

Agent Type	Recommended Default	Rationale
Formatters, Linters	low	Simple, predictable tasks
Feature Developers	medium	Standard implementation work
Code Reviewers	high	Thorough analysis required
Architects	ultrathink	Complex system design
Info Retrievers	none	No thinking needed

2. Max Level Constraints

Set max_level to prevent cost overruns:

# Prevent documentation agent from expensive thinking
thinking_config:
  max_level: medium  # Cap at 4,096 tokens

3. Adaptive Budgets

Enable adaptive: true for variable workloads:

# Agent handles both simple and complex tasks
thinking_config:
  default_level: medium
  adaptive: true  # Adjust based on complexity

4. Quality Floors

Set min_level for critical agents:

# Security agent must never use low budgets
thinking_config:
  min_level: high  # Never drop below 16,384 tokens

Monitoring and Analytics

Usage Statistics

# View comprehensive statistics
python3 scripts/thinking-budget-manager.py --stats

# JSON output for automation
python3 scripts/thinking-budget-manager.py --stats --json

Cost Analysis

# Estimate task cost
python3 scripts/thinking-budget-manager.py \
  --estimate "comprehensive security audit of authentication system"

# Output includes:
# - Detected task type
# - Detected complexity
# - Recommended budget level
# - Cost estimates for all levels

Optimization Recommendations

The system automatically suggests optimizations when:

1. Agent consistently under-uses budget → Recommend lower default
2. Agent frequently exceeds budget → Recommend higher default
3. Budget efficiency below threshold → Suggest adaptive mode

See .coditect/thinking-usage.json for detailed analytics.

Best Practices

1. Start Conservative

Begin with lower defaults and increase based on data:

thinking_config:
  default_level: medium  # Start here
  adaptive: true         # Allow upgrades
  track_usage: true      # Monitor performance

2. Review Usage Regularly

# Weekly cost review
python3 scripts/thinking-budget-manager.py --stats

# Check top cost drivers
# Adjust agent configs based on data

3. Differentiate Agent Roles

Different agents = different budgets:

• High-volume, routine agents → Low defaults, strict maxes
• Critical quality agents → High defaults, high mins
• Strategic planning agents → Ultrathink defaults, no limits

4. Enable Tracking

Always enable tracking for optimization:

thinking_config:
  track_usage: true  # Essential for cost analysis

5. Test Configuration Changes

Before deploying config changes:

# Test with estimation
python3 scripts/thinking-budget-manager.py \
  --task typical_task \
  --agent agent-name \
  --complexity standard

Migration Guide

Adding to Existing Agent

# Before
---
name: my-agent
description: Does things
tools: Read, Write
---

# After
---
name: my-agent
description: Does things
tools: Read, Write

thinking_config:
  default_level: medium
  max_level: high
  adaptive: true
  track_usage: true
---

Batch Update Script

# Update all agents in category
agents = ["agent1", "agent2", "agent3"]

for agent in agents:
    add_thinking_config(
        agent,
        default_level="medium",
        max_level="high",
        adaptive=True
    )

Related Documentation

• Thinking Budget Manager Script
• Budget Configuration
• Cost Optimization Guide
• Agent Development Guide

---

Last Updated: 2025-12-22 Compliance: CODITECT Documentation Standard v1.0.0 Related: ADR-XXX: Thinking Budget System