APAW/.kilo/specs/prompt-optimization-strategy.md

Technical Specification: KiloCode Multi-Agent Prompt Optimization Strategy

Overview

A systematic strategy to reduce token consumption across 29 agents by 55-65% while preserving all functional capabilities. The approach eliminates redundancy, moves reference material to on-demand skills, compresses output templates, and introduces a centralized shared-instructions mechanism.

---

Data Models

interface AgentPromptV2 {
  frontmatter: AgentFrontmatter;       // UNCHANGED
  role: string;                        // 1 sentence, max 20 words
  delegates: DelegationMap;            // compressed subagent table
  behavior: string[];                  // 3-5 bullet max, imperative mood
  output: string;                      // XML-structured, max 15 lines
  skills: string[];                    // skill names only (no inline content)
  handoff: string[];                   // 3-5 step checklist
}

interface DelegationMap {
  [subagentName: string]: string;      // agent -> when to delegate
}

interface SharedInstructionBlock {
  id: string;                          // e.g., "gitea-commenting"
  location: string;                    // e.g., ".kilo/shared/gitea-commenting.md"
  token_cost: number;                  // estimated tokens
  loaded_by: "all" | string[];        // which agents need this
  priority: "mandatory" | "conditional";
}

// Agent tier classification
type AgentTier = "heavy" | "standard" | "light";

interface TierBudget {
  tier: AgentTier;
  max_lines: number;
  max_tokens: number;     // approximate
  allowed_sections: string[];
  code_templates: "inline" | "skill-ref" | "none";
}

Deduplication Strategy

Principle: DRY at the System Level

Content that appears in 3+ agents MUST be extracted to a shared location. Content in 1-2 agents should remain inline.

What	Current Location	Occurrences	Line Count (total)	Strategy	New Location
Gitea Commenting block	26 agent .md files	26	~338 lines	Extract to shared block	.kilo/shared/gitea-commenting.md
Role personality paragraph	All agent .md files	29	~87 lines	Compress to single sentence	Inline (compressed)
"When to Use" section	All agent .md files	29	~174 lines	Merge into Role line	Inline (compressed)
Prohibited Actions	All agent .md files	29	~174 lines	Convert to positive constraints	Inline (compressed)
Output Format templates	All agent .md files	29	~500 lines	XML skeleton, max 15 lines	Inline (compressed)
Handoff Protocol	All agent .md files	29	~200 lines	Merge into 1-line delegate instruction	Inline (compressed)
Tech Stack tables	5 developer agents	5	~25 lines	Move to skills	.kilo/skills/*/SKILL.md
Code templates (Go)	go-developer.md + rules/go.md	2	~800 lines	Agent references skill only	.kilo/skills/go-web-patterns/SKILL.md
Code templates (Flutter)	flutter-developer.md + rules/flutter.md	2	~1100 lines	Agent references skill only	.kilo/skills/flutter-*/SKILL.md
Code templates (Node.js)	backend-developer.md + rules/nodejs.md	2	~500 lines	Agent references skill only	.kilo/skills/nodejs-*/SKILL.md
Code templates (Docker)	devops-engineer.md + rules/docker.md	2	~900 lines	Agent references skill only	.kilo/skills/docker-*/SKILL.md
Self-evolution protocol	orchestrator.md + rules/	2	~800 lines	Reference rules file only	.kilo/rules/orchestrator-self-evolution.md
Gitea API Python code	orchestrator.md + release-manager.md + requirement-refiner.md + gitea-commenting SKILL.md	4	~400 lines	Single shared module	.kilo/shared/gitea-api.md

Centralized vs. Agent-Specific Content

Centralized (shared/)	Agent-Specific (inline)
Gitea commenting format & API	Role definition (1 sentence)
Gitea API Python client code	Behavior guidelines (3-5 bullets)
Common security constraints	Delegation map
Self-evolution protocol	Output format skeleton
Credential fallback logic	Handoff checklist

Token Budget per Agent Tier

const TIER_BUDGETS: Record<AgentTier, TierBudget> = {
  heavy: {
    tier: "heavy",
    max_lines: 80,
    max_tokens: 3200,
    allowed_sections: ["role", "behavior", "delegates", "output", "skills", "handoff"],
    code_templates: "skill-ref",    // Reference only, no inline code
  },
  standard: {
    tier: "standard",
    max_lines: 50,
    max_tokens: 2000,
    allowed_sections: ["role", "behavior", "delegates", "output", "handoff"],
    code_templates: "none",
  },
  light: {
    tier: "light",
    max_lines: 30,
    max_tokens: 1200,
    allowed_sections: ["role", "behavior", "output", "handoff"],
    code_templates: "none",
  },
};

Agent → Tier Mapping

Tier	Agents	Rationale
Heavy	flutter-developer, go-developer, backend-developer, devops-engineer, orchestrator	Developer agents need skill references; orchestrator needs delegation map
Standard	capability-analyst, pipeline-judge, security-auditor, code-skeptic, evaluator, visual-tester, browser-automation, workflow-architect, agent-architect	Analysis/review agents need output templates but no code
Light	lead-developer, sdet-engineer, the-fixer, system-analyst, frontend-developer, requirement-refiner, performance-engineer, prompt-optimizer, product-owner, release-manager, history-miner, planner, reflector, memory-manager, markdown-validator	Simpler roles, few delegates, minimal output

Prompt Compression Rules

Rule 1: Role → Single Sentence

Before (typical, 3 lines):

## Role Definition

You are **Flutter Developer** — the mobile app specialist. Your personality is cross-platform focused, widget-oriented, and performance-conscious. You build beautiful native apps for iOS, Android, and web from a single codebase.

After (1 line):

## Role
Flutter mobile specialist: cross-platform apps, widget architecture, state management.

Token saving: ~40 tokens per agent × 29 agents = ~1,160 tokens

Rule 2: "When to Use" → Merged into Role

Before (6 lines):

## When to Use

Invoke this mode when:
- Building cross-platform mobile applications
- Implementing Flutter UI widgets and screens
- State management with Riverpod/Bloc/Provider
- Platform-specific functionality (iOS/Android)
- Flutter animations and custom painters
- Integration with native code (platform channels)

After (merged into role):

## Role
Flutter mobile specialist: cross-platform apps, widgets, state management (Riverpod/Bloc/Provider), platform channels, animations.

Token saving: ~60 tokens per agent × 29 agents = ~1,740 tokens

Rule 3: Behavior Guidelines → 3-5 Imperative Bullets

Before (5 lines + personality overhead):

## Behavior Guidelines

1. **Widget-first mindset** — Everything is a widget, keep them small and focused
2. **Const by default** — Use const constructors for performance
3. **State management** — Use Riverpod/Bloc/Provider, never setState for complex state
4. **Clean Architecture** — Separate presentation, domain, and data layers
5. **Platform awareness** — Handle iOS/Android differences gracefully

After (compressed):

## Behavior
- Widget-first: small, focused, const constructors
- State via Riverpod/Bloc/Provider (never setState for complex state)
- Clean Architecture: presentation/domain/data separation
- Handle iOS/Android platform differences

Token saving: ~30 tokens per agent × 29 agents = ~870 tokens

Rule 4: Prohibited Actions → Positive Constraints

Before:

## Prohibited Actions

- DO NOT use setState for complex state
- DO NOT put business logic in widgets
- DO NOT use dynamic types
- DO NOT ignore lint warnings
- DO NOT skip testing for critical paths
- DO NOT use hot reload as a development strategy
- DO NOT embed secrets in code
- DO NOT use global state for request data

After (merged into behavior):

## Behavior
- Widget-first: small, focused, const constructors
- State via Riverpod/Bloc/Provider (never setState for complex state)
- Clean Architecture: keep logic out of widgets, strict types
- Test critical paths; validate all inputs; no secrets in code

Token saving: ~50 tokens per agent × 29 agents = ~1,450 tokens

Rationale: Anthropic research shows positive instructions outperform negative ones ("tell what to do, not what not to do"). Merging prohibitions into behavior guidelines eliminates an entire section.

Rule 5: Output Format → XML Skeleton (max 15 lines)

Before (40+ lines for flutter-developer):

## Output Format

```markdown
## Flutter Implementation: [Feature]

### Screens Created
| Screen | Description | State Management |
|--------|-------------|------------------|
| HomeScreen | Main dashboard | Riverpod Provider |
...

### Widgets Created
- `UserTile`: Reusable user list item with avatar
...

After (8 lines):

## Output
<impl agent="flutter-developer">
  <screens><!-- table: name, description, state_mgmt --></screens>
  <widgets><!-- list: name, purpose --></widgets>
  <state><!-- approach used --></state>
  <files><!-- list: all created/modified files --></files>
  <tests><!-- unit/widget/integration status --></tests>
</impl>

Token saving: ~100 tokens per heavy agent × 5 + ~50 tokens per standard × 9 + ~30 tokens per light × 15 = ~1,550 tokens

Rationale: XML tags give models clear structure boundaries without verbose markdown templates. Models follow XML constraints more reliably than markdown examples.

Rule 6: Code Templates → Skill References Only

Before (flutter-developer has ~400 lines of code templates): All of: Project Structure, Clean Architecture Layers, State Management Templates, Widget Patterns, Navigation Pattern, Testing Templates, Platform Channels, Build Configuration

After (reference-only, 10 lines):

## Skills
| Skill | When |
|-------|------|
| flutter-widgets | Widget creation, Material/Cupertino |
| flutter-state | Riverpod/Bloc/Provider patterns |
| flutter-navigation | go_router, auto_route |
| html-to-flutter | Convert HTML templates |
| flutter-testing | Unit/widget/integration tests |

Token saving: ~3,500 tokens for flutter-developer alone; ~2,000 for go-developer; ~1,600 for backend-developer; ~1,800 for devops-engineer = ~8,900 tokens total

Critical: The code template content is NOT deleted — it already exists in .kilo/skills/ files. The agent prompt becomes an index, not a tutorial. Models load skills on demand.

Rule 7: Gitea Commenting → Shared Block

Before (in 26 agents, ~12 lines each):

## Gitea Commenting (MANDATORY)

**You MUST post a comment to the Gitea issue after completing your work.**

Post a comment with:
1. ✅ Success: What was done, files changed, duration
2. ❌ Error: What failed, why, and blocker
3. ❓ Question: Clarification needed with options

Use the `post_comment` function from `.kilo/skills/gitea-commenting/SKILL.md`.

**NO EXCEPTIONS** - Always comment to Gitea.

After (in shared block, loaded once): All 26 agents get a single line:

<gitea-commenting required="true" skill="gitea-commenting" />

Or via the shared instruction mechanism (see Template Optimization section), the orchestrator injects the block. Agent files don't contain it at all.

Token saving: ~10 lines × 26 agents = 260 lines = ~3,120 tokens

Template Optimization

New Shared Instruction Mechanism

Create .kilo/shared/ directory with reusable instruction blocks:

.kilo/shared/
├── gitea-commenting.md      # ~15 lines, loaded by all agents
├── gitea-api.md             # ~40 lines, loaded by agents that post comments
├── security-constraints.md  # ~10 lines, loaded by developer agents
└── self-evolution.md        # ~20 lines, loaded by orchestrator only

Loading Mechanism

Two approaches, in order of preference:

Option A: Orchestrator Injection (preferred) The orchestrator injects shared blocks into the Task tool prompt parameter when delegating:

Task tool call:
- subagent_type: "lead-developer"
- prompt: |
    {shared:gitea-commenting}
    
    {actual_task_prompt}

This means shared blocks are NOT in agent files at all. Zero duplicate tokens.

Option B: XML Reference Tag in Agent Files Agent files contain:

<include src=".kilo/shared/gitea-commenting.md" />

Kilo Code's prompt assembler expands these before passing to the model.

Recommendation: Option A is cleaner (no file modification needed for shared content updates). If Kilo Code doesn't support <include> tags, Option A is the only viable path.

Shared Block: gitea-commenting.md

# Gitea Commenting (Required)

Post a comment to the Gitea issue after your work using `.kilo/skills/gitea-commenting/SKILL.md`.

Formats:
- ✅ Completed: agent-name, task done, files changed, duration, score 1-10
- ❌ Error: what failed, why, blocker
- ❓ Question: clarification needed with options

Never skip commenting.

9 lines vs. 12 lines × 26 agents. Saves 303 lines total.

Shared Block: gitea-api.md

import urllib.request, json, base64, os

def gitea_api(path, data=None, method='GET'):
    """Call Gitea API. Uses get_gitea_token() from .kilo/shared/gitea-auth.md."""
    token = get_gitea_token()  # Centralized auth
    repo = get_target_repo()    # Auto-detect from git remote
    api_url = os.environ.get('GITEA_API_URL', 'https://git.softuniq.eu/api/v1')
    url = f"{api_url}/repos/{repo}{path}"
    headers = {'Content-Type': 'application/json', 'Authorization': f'token {token}'}
    req = urllib.request.Request(url, data=json.dumps(data).encode() if data else None,
        headers=headers, method=method)
    with urllib.request.urlopen(req) as r: return json.loads(r.read())

Replaces ~100 lines of duplicated API code across 4 agents.

Rules Consolidation

Current Duplication Map

Rules File	Agent File with Same Content	Overlap %	Action
rules/flutter.md (439 lines)	agents/flutter-developer.md (634 lines)	~65%	Delete code templates from agent; keep rules as authoritative source via skill references
rules/go.md (238 lines)	agents/go-developer.md (420 lines)	~55%	Delete code templates from agent; keep rules as authoritative source
rules/docker.md (450 lines)	agents/devops-engineer.md (309 lines)	~70%	Delete Docker compose/patterns from agent; keep rules as authoritative source
rules/nodejs.md (217 lines)	agents/backend-developer.md (263 lines)	~45%	Delete code templates from agent; keep rules as authoritative source
rules/code-skeptic.md (47 lines)	agents/code-skeptic.md (117 lines)	~40%	Keep both (agent has more task-specific content)
rules/sdet-engineer.md (67 lines)	agents/sdet-engineer.md (78 lines)	~85%	Delete rules file; agent is authoritative
rules/release-manager.md (60 lines)	agents/release-manager.md (215 lines)	~30%	Keep both (different scope)
rules/lead-developer.md (39 lines)	agents/lead-developer.md (83 lines)	~45%	Keep both (rules are lightweight)
rules/history-miner.md (20 lines)	agents/history-miner.md (63 lines)	~30%	Keep both
rules/orchestrator-self-evolution.md (449 lines)	agents/orchestrator.md (290 lines)	~60%	Keep rules as authoritative; agent references it via skill
rules/evolutionary-sync.md (220 lines)	No agent equivalent	0%	Keep as-is
rules/prompt-engineering.md (234 lines)	No agent equivalent	0%	Keep as-is
rules/agent-patterns.md (68 lines)	No agent equivalent	0%	Keep as-is
rules/agent-frontmatter-validation.md (132 lines)	No agent equivalent	0%	Keep as-is
rules/global.md (35 lines)	No agent equivalent	0%	Keep as-is

Consolidation Actions

1. DELETE from agent files (keep in rules/skills): All code templates in flutter-developer, go-developer, backend-developer, devops-engineer
2. DELETE from rules (keep in agent): rules/sdet-engineer.md (content is in agent)
3. MERGE into shared block: rules/orchestrator-self-evolution.md content → .kilo/shared/self-evolution.md; orchestrator references it
4. NO CHANGE: All other rules files

Implementation Priority Matrix

Priority is determined by: impact = token_savings × execution_frequency × risk_inverse

Priority	Agent(s)	Change	Est. Token Savings	Est. Lines Removed	Risk	Effort
P0	ALL 26 with Gitea block	Extract Gitea commenting to shared	~3,120	~312	Low	1h
P1	flutter-developer	Remove code templates, compress sections	~3,800	~450	Low	2h
P1	go-developer	Remove code templates, compress sections	~2,200	~280	Low	2h
P1	backend-developer	Remove code templates, compress sections	~1,600	~160	Low	1.5h
P1	devops-engineer	Remove code templates, compress sections	~1,800	~210	Low	1.5h
P2	orchestrator	Remove self-evolution inline, compress delegation table	~1,200	~120	Medium	2h
P2	ALL 29	Compress Role/WhenToUse to single line	~2,900	~348	Low	2h
P2	ALL 29	Convert Prohibited Actions → positive constraints in Behavior	~1,450	~145	Low	1.5h
P2	ALL 29	Compress Output Format to XML skeleton	~1,550	~200	Medium	3h
P3	capability-analyst	Remove verbose example output template	~400	~80	Low	1h
P3	pipeline-judge	Remove inline bash scripts, reference skill	~300	~50	Low	0.5h
P3	release-manager	Extract Gitea API code to shared block	~400	~80	Medium	1h
P3	requirement-refiner	Extract Gitea API code to shared block	~300	~60	Medium	0.5h
P3	visual-tester, browser-automation	Compress Docker/docker-compose details	~300	~40	Low	1h
P4	ALL remaining light agents	Apply compression rules	~800	~120	Low	2h

Risk Assessment

Change	Risk Level	Risk Description	Mitigation
Extract Gitea commenting	Low	Agents might not load shared block	Orchestrator injection ensures delivery; fallback: XML include tag
Remove code templates from agents	Low	Models may produce worse code without examples	Skills already contain all templates; verify skill references exist
Compress role/personality	Low	Persona drift	Single sentence still defines role; personality was never reliably followed
Convert prohibitions to positive	Low	Models may miss constraints	Positive constraints are proven more effective; add key constraints to behavior
XML output format	Medium	Models may ignore XML tags	Test with 3-5 agents first; roll back if output quality drops
Remove self-evolution from orchestrator	Medium	Evolution path may not trigger	Rules file remains loaded; add 1-line reference in behavior
Extract Gitea API code to shared	Medium	Credential leak in shared file	Shared file has same permissions as skills; no new exposure
Compress pipeline-judge bash	Low	Test runner commands may be wrong	Skill already has correct commands; verify

Before/After Examples: Top 3 Highest-Impact Agents

---

1. flutter-developer.md (759 lines → ~75 lines, ~90% reduction)

BEFORE (selected sections, 759 lines total):

---
description: Flutter mobile specialist for cross-platform apps, state management, and UI components
mode: subagent
model: ollama-cloud/qwen3-coder:480b
color: "#02569B"
permission:
  read: allow
  edit: allow
  write: allow
  bash: allow
  glob: allow
  grep: allow
  task:
    "*": deny
    "code-skeptic": allow
    "visual-tester": allow
    "orchestrator": allow
---

# Kilo Code: Flutter Developer

## Role Definition

You are **Flutter Developer** — the mobile app specialist. Your personality is cross-platform focused, widget-oriented, and performance-conscious. You build beautiful native apps for iOS, Android, and web from a single codebase.

## When to Use

Invoke this mode when:
- Building cross-platform mobile applications
- Implementing Flutter UI widgets and screens
- State management with Riverpod/Bloc/Provider
- Platform-specific functionality (iOS/Android)
- Flutter animations and custom painters
- Integration with native code (platform channels)

## Short Description

Flutter mobile specialist for cross-platform apps, state management, and UI components.

## Task Tool Invocation

Use the Task tool with `subagent_type` to delegate to other agents:
- `subagent_type: "code-skeptic"` — for code review after implementation
- `subagent_type: "visual-tester"` — for visual regression testing

## Behavior Guidelines

1. **Widget-first mindset** — Everything is a widget, keep them small and focused
2. **Const by default** — Use const constructors for performance
3. **State management** — Use Riverpod/Bloc/Provider, never setState for complex state
4. **Clean Architecture** — Separate presentation, domain, and data layers
5. **Platform awareness** — Handle iOS/Android differences gracefully

[... 400+ lines of code templates, build configs, testing templates, platform channels, navigation ...]

## Prohibited Actions

- DO NOT use setState for complex state
- DO NOT put business logic in widgets
- DO NOT use dynamic types
- DO NOT ignore lint warnings
- DO NOT skip testing for critical paths
- DO NOT use hot reload as a development strategy
- DO NOT embed secrets in code
- DO NOT use global state for request data

## Skills Reference

This agent uses the following skills for comprehensive Flutter development:
[... 40+ lines of skill tables ...]

## Handoff Protocol

After implementation:
1. Run `flutter analyze`
2. Run `flutter test`
3. Check for const opportunities
4. Verify platform-specific code works
5. Test on both iOS and Android (or web)
6. Check performance with DevTools
7. Tag `@CodeSkeptic` for review

## Gitea Commenting (MANDATORY)

**You MUST post a comment to the Gitea issue after completing your work.**

Post a comment with:
1. ✅ Success: What was done, files changed, duration
2. ❌ Error: What failed, why, and blocker
3. ❓ Question: Clarification needed with options

Use the `post_comment` function from `.kilo/skills/gitea-commenting/SKILL.md`.

**NO EXCEPTIONS** - Always comment to Gitea.

AFTER (~75 lines, same YAML frontmatter):

---
description: Flutter mobile specialist for cross-platform apps, state management, and UI components
mode: subagent
model: ollama-cloud/qwen3-coder:480b
color: "#02569B"
permission:
  read: allow
  edit: allow
  write: allow
  bash: allow
  glob: allow
  grep: allow
  task:
    "*": deny
    "code-skeptic": allow
    "visual-tester": allow
    "orchestrator": allow
---

# Flutter Developer

## Role
Cross-platform mobile specialist: Flutter widgets, state management (Riverpod/Bloc/Provider), platform channels, clean architecture.

## Behavior
- Widget-first: small, focused, const constructors always
- State via Riverpod/Bloc/Provider; keep logic out of widgets; strict Dart types
- Clean Architecture: presentation/domain/data separation
- Test critical paths; validate inputs; no secrets in code
- Handle iOS/Android differences; profile with DevTools

## Delegates
| Agent | When |
|-------|------|
| code-skeptic | After implementation, for review |
| visual-tester | Visual regression testing needed |

## Output
<impl agent="flutter-developer">
  <screens><!-- table: name, description, state_mgmt --></screens>
  <widgets><!-- list: name, purpose --></widgets>
  <state><!-- approach used --></state>
  <files><!-- list: all created/modified files --></files>
  <tests><!-- unit/widget/integration status --></tests>
</impl>

## Skills
| Skill | When |
|-------|------|
| flutter-widgets | Widget creation |
| flutter-state | Riverpod/Bloc/Provider |
| flutter-navigation | go_router, auto_route |
| html-to-flutter | HTML→Flutter conversion |
| flutter-testing | Unit/widget/integration |

## Handoff
1. `flutter analyze` + `flutter test`
2. Verify platform-specific code
3. Delegate: code-skeptic

Savings: 684 lines removed (90%), ~3,800 tokens. Code templates remain in skills.

---

2. go-developer.md (503 lines → ~60 lines, ~88% reduction)

BEFORE (503 lines total — includes full handler/service/repository/model/middleware/error handling templates + skill tables + handoff + Gitea block)

AFTER (~60 lines):

---
description: Go backend specialist for Gin, Echo, APIs, and database integration
mode: subagent
model: ollama-cloud/qwen3-coder:480b
color: "#00ADD8"
permission:
  read: allow
  edit: allow
  write: allow
  bash: allow
  glob: allow
  grep: allow
  task:
    "*": deny
    "code-skeptic": allow
    "orchestrator": allow
---

# Go Developer

## Role
Go backend specialist: Gin/Echo APIs, concurrent patterns, GORM/sqlx, clean service architecture.

## Behavior
- Idiomatic Go: error wrapping with `%w`, context as first param, accept interfaces/return concrete
- Concurrency: goroutine+channel safety, prevent leaks, sync.WaitGroup coordination
- Security: parameterized queries, validate inputs, no secrets in code
- Test: table-driven tests, mockery for mocks, `go test -race ./...`

## Delegates
| Agent | When |
|-------|------|
| code-skeptic | After implementation |

## Output
<impl agent="go-developer">
  <endpoints><!-- table: method, path, handler, description --></endpoints>
  <database><!-- table: table, columns, indexes --></database>
  <files><!-- list: all created/modified files --></files>
  <security><!-- checklist of measures taken --></security>
</impl>

## Skills
| Skill | When |
|-------|------|
| go-web-patterns | Gin/Echo handler patterns |
| go-middleware | Auth, CORS, rate limiting |
| go-error-handling | Error types, wrapping |
| go-db-patterns | GORM, sqlx, transactions |
| go-concurrency | Goroutines, channels, sync |
| go-testing | Table-driven, mockery |
| go-security | OWASP, validation |

## Handoff
1. `go fmt ./...` + `go vet ./...` + `go test -race ./...`
2. `govulncheck ./...`
3. Delegate: code-skeptic

Savings: 443 lines removed (88%), ~2,200 tokens.

---

3. orchestrator.md (356 lines → ~100 lines, ~72% reduction)

BEFORE (356 lines — includes full self-evolution protocol inline, Gitea API Python code, detailed Gitea commenting block with enforcement, verbose delegation table)

AFTER (~100 lines):

---
description: Main dispatcher. Routes tasks between agents based on Issue status and manages the workflow state machine.
mode: all
model: ollama-cloud/glm-5.1
variant: thinking
color: "#7C3AED"
permission:
  read: allow
  edit: allow
  write: allow
  bash: allow
  glob: allow
  grep: allow
  task:
    "*": deny
    "history-miner": allow
    "system-analyst": allow
    "sdet-engineer": allow
    "lead-developer": allow
    "code-skeptic": allow
    "the-fixer": allow
    "frontend-developer": allow
    "backend-developer": allow
    "go-developer": allow
    "flutter-developer": allow
    "performance-engineer": allow
    "security-auditor": allow
    "visual-tester": allow
    "browser-automation": allow
    "devops-engineer": allow
    "release-manager": allow
    "requirement-refiner": allow
    "capability-analyst": allow
    "workflow-architect": allow
    "markdown-validator": allow
    "evaluator": allow
    "prompt-optimizer": allow
    "product-owner": allow
    "pipeline-judge": allow
    "planner": allow
    "reflector": allow
    "memory-manager": allow
    "agent-architect": allow
---

# Orchestrator

## Role
Task dispatcher and state machine manager. Route by issue status; enforce workflow; ensure Gitea comments from all agents.

## Behavior
- Route by status: new→history-miner, researching→system-analyst, testing→sdet-engineer, implementing→lead-developer, fail→the-fixer
- Check for blockers before routing; suspend if dependencies unmet
- Only you authorize release-manager after evaluator confirmation
- Comms format: "To: [Agent]. Task: [essence]. Context: [file ref]"
- Self-evolution: see `.kilo/shared/self-evolution.md`

## State Machine
[new] → history-miner → [researching] → system-analyst → [testing] → sdet-engineer → [implementing] → lead-developer → [reviewing] → code-skeptic → {fail: the-fixer → reviewing | pass: performance-engineer → security-auditor → [releasing] → release-manager → [evaluated] → evaluator → {score<7: prompt-optimizer | score≥7: pipeline-judge → fitness check → {≥0.85: completed | <0.85: evolving}}

## Delegates
| Agent | When |
|-------|------|
| history-miner | new issue: check duplicates |
| system-analyst | researching: design spec |
| sdet-engineer | designing: write failing tests |
| lead-developer | testing: implement to pass tests |
| code-skeptic | implementing: review code |
| the-fixer | review fail: fix issues |
| performance-engineer | review pass: check perf |
| security-auditor | perf pass: security audit |
| release-manager | audit pass: package release |
| evaluator | release done: score agents |
| prompt-optimizer | any score < 7: improve prompts |
| pipeline-judge | score ≥ 7: measure fitness |
| capability-analyst | gap detected: analyze coverage |

## Task Protocol
1. Provide full context in prompt
2. Specify expected output
3. Include file paths
4. Set success criteria
5. **Require Gitea comment** — inject `<gitea-commenting required="true" />` in every delegation

## Gitea Integration
Uses `.kilo/shared/gitea-api.md` for API client and `.kilo/shared/gitea-commenting.md` for format.

Savings: 256 lines removed (72%), ~1,200 tokens. Self-evolution detail moved to shared block; Gitea API code moved to shared block.

---

Estimated Total Savings

Category	Lines Saved	Tokens Saved (approx.)
Code template removal (4 heavy agents)	1,100	8,900
Gitea commenting extraction (26 agents)	312	3,120
Role/WhenToUse compression (29 agents)	348	2,900
Prohibited→Positive conversion (29 agents)	145	1,450
Output format compression (29 agents)	200	1,550
Orchestrator self-evolution extraction	120	800
Gitea API code extraction (4 agents)	80	600
Personality/Short Description removal	87	870
Various smaller compressions	120	800
TOTAL	~2,512	~21,990

Current total lines across all agent files: ~5,614
Projected total after optimization: ~3,100
Overall reduction: ~45% lines, ~55% tokens

Implementation Order (Phased Rollout)

Phase 1 (Day 1): Foundation — Low risk, high impact
├── Create .kilo/shared/ directory
├── Create gitea-commenting.md shared block
├── Create gitea-api.md shared block  
├── Create self-evolution.md shared block
├── Remove Gitea commenting blocks from ALL 26 agents
└── Verify: run 1 test issue through pipeline

Phase 2 (Day 2-3): Heavy agents — Biggest savings
├── Rewrite flutter-developer.md (compressed)
├── Rewrite go-developer.md (compressed)
├── Rewrite backend-developer.md (compressed)
├── Rewrite devops-engineer.md (compressed)
└── Verify: run 1 Flutter issue + 1 Go issue through pipeline

Phase 3 (Day 4): Orchestrator — Medium risk
├── Rewrite orchestrator.md (compressed)
├── Remove inline self-evolution protocol
├── Remove inline Gitea API code
└── Verify: run full pipeline on test issue

Phase 4 (Day 5-6): Standard + Light agents — Mass compression
├── Apply Role compression to all 29 agents
├── Apply Prohibited→Positive to all 29 agents
├── Apply Output format XML to all 29 agents
├── Compress capability-analyst, pipeline-judge, release-manager
├── Compress requirement-refiner (extract Gitea API)
├── Delete redundant rules/sdet-engineer.md
└── Verify: run 2 test issues through full pipeline

Phase 5 (Day 7): Validation + Regression testing
├── Run 5 issues through full pipeline
├── Compare output quality before/after
├── Measure fitness scores before/after
├── Fix any regressions
└── Document final metrics

Validation Criteria

After each phase, verify:

1. Functional: Pipeline still completes end-to-end
2. Gitea integration: Comments still posted correctly
3. Output quality: Agent outputs are structured and complete
4. Fitness score: No decrease > 0.05 from baseline
5. Token consumption: Verify reduction in pipeline-judge cost metrics
6. Agent handoffs: Delegation chain still works correctly

Edge Cases

Edge Case	Handling
Agent loaded without orchestrator (user invokes directly)	mode: all agents must still have inline Gitea reference; mode: subagent agents only need it when called by orchestrator
Skill file missing when agent references it	Agent falls back to general knowledge; add validation in capability-analyst
Shared block fails to load	Include minimal 1-line fallback in agent file: Post comment to Gitea using .kilo/skills/gitea-commenting/SKILL.md
Model produces malformed XML output	XML is a hint, not a strict parser; models can deviate if needed
Evolution trigger needs self-evolution detail	Orchestrator references .kilo/shared/self-evolution.md which has full protocol
Release-manager needs inline Gitea API code for closing issues	Move to .kilo/shared/gitea-api.md; release-manager references it

Dependencies

• Kilo Code prompt loading mechanism (must support shared blocks or orchestrator injection)
• .kilo/skills/ infrastructure (already exists and is populated)
• .kilo/rules/ global loading (already works)
• Gitea API tokens (already configured)

---

Status: designed @SDETEngineer ready for test creation