APAW/AGENTS.md

Kilo Code Agents Reference

This file configures AI agent behavior for the project - a self-improving code pipeline with Gitea logging.

Pipeline Workflow

The main workflow is /pipeline - use it to process issues through all agents automatically.

User: /pipeline 42
Agent: Runs full pipeline for issue #42 with Gitea logging

Commands (Slash Commands)

Command	Description	Usage
/pipeline <issue>	Run full agent pipeline for issue	/pipeline 42
/nextjs	Next.js 14+ full-stack app pipeline	/nextjs my-app
/vue	Vue/Nuxt 3 full-stack app pipeline	/vue my-app
/laravel	Laravel full-stack app pipeline	/laravel my-app
/wordpress	WordPress plugin/site pipeline	/wordpress my-plugin
/feature	Feature development pipeline	/feature
/commerce	E-commerce site pipeline	/commerce
/status <issue>	Check pipeline status for issue	/status 42
/evolve	Run evolution cycle with fitness scoring	/evolve --issue 42
/evaluate <issue>	Generate performance report	/evaluate 42
/plan	Creates detailed task plans	/plan feature X
/ask	Answers codebase questions	/ask how does auth work
/debug	Analyzes and fixes bugs	/debug error in login
/code	Quick code generation	/code add validation
/research [topic]	Run research and self-improvement	/research multi-agent
/evolution log	Log agent model change	/evolution log planner "reason"
/evolution report	Generate evolution report	/evolution report
/index-project	Index codebase into .architect/ for agent orientation	/index-project
/web-test <url>	Visual regression testing in Docker	/web-test https://bbox.wtf
/e2e-test <url>	E2E browser automation tests	/e2e-test https://my-app.com

Pipeline Agents (Subagents)

These agents are invoked automatically by /pipeline or manually via @mention:

Core Development

Agent	Role	When Invoked
@RequirementRefiner	Converts vague ideas and bug reports into strict User Stories with acceptance criteria checklists	Issue status: new
@HistoryMiner	Analyzes git history to find duplicates and past solutions, preventing regression and duplicate work	Status: planned
@SystemAnalyst	Designs technical specifications, data schemas, and API contracts before implementation	Status: researching
@SdetEngineer	Writes tests following TDD methodology	Status: designed
@LeadDeveloper	Primary code writer for backend and core logic	Status: testing
@FrontendDeveloper	Handles UI implementation with multimodal capabilities	When UI work needed
@BackendDeveloper	Backend specialist for Node	When backend needed
@GoDeveloper	Go backend specialist for Gin, Echo, APIs, and database integration	When Go backend needed
@DevopsEngineer	DevOps specialist for Docker, Kubernetes, CI/CD pipeline automation, and infrastructure management	When deployment/infra needed

Quality Assurance

Agent	Role	When Invoked
@CodeSkeptic	Adversarial code reviewer	Status: implementing
@TheFixer	Iteratively fixes bugs based on specific error reports and test failures	When review fails
@PerformanceEngineer	Reviews code for performance issues	After code-skeptic
@SecurityAuditor	Scans for security vulnerabilities, OWASP Top 10, dependency CVEs, and hardcoded secrets	After performance
@VisualTester	Visual regression testing agent that compares screenshots and detects UI differences using pixelmatch and image diff	When UI changes

DevOps & Infrastructure

Agent	Role	When Invoked
@devops-engineer	Docker/Swarm/K8s deployment	When deployment needed
@security-auditor	Container security scan	After deployment config

Cognitive Enhancement

Agent	Role	When Invoked
@Planner	Advanced task planner using Chain of Thought, Tree of Thoughts, and Plan-Execute-Reflect	Complex tasks
@Reflector	Self-reflection agent using Reflexion pattern - learns from mistakes	After each agent
@MemoryManager	Manages agent memory systems - short-term (context), long-term (vector store), and episodic (experiences)	Context management

Meta & Process

Agent	Role	When Invoked
@Orchestrator	Main dispatcher	Manages all agent routing
@ReleaseManager	Manages git operations, semantic versioning, branching, and deployments	Status: releasing
@Evaluator	Scores agent effectiveness after task completion for continuous improvement	Status: evaluated
@PromptOptimizer	Improves agent system prompts based on performance failures	When score < 7
@ProductOwner	Manages issue checklists, status labels, tracks progress and coordinates with human users	Manages issues
@AgentArchitect	Creates, modifies, and reviews new agents, workflows, and skills based on capability gap analysis	When gaps identified
@CapabilityAnalyst	Analyzes task requirements against available agents, workflows, and skills	When starting new task
@WorkflowArchitect	Creates and maintains workflow definitions with complete architecture, Gitea integration, and quality gates	New workflow needed
@MarkdownValidator	Validates and corrects Markdown descriptions for Gitea issues	Before issue creation

Status Labels

Pipeline uses Gitea labels to track progress:

• status: new → status: planned → status: researching → ...
• Agents add/remove labels automatically

Performance Logging

Each agent logs to Gitea issue comments:

## ✅ lead-developer completed

**Score**: 8/10
**Duration**: 1.2h
**Files**: src/auth.ts, src/user.ts

### Notes
- Clean implementation
- Follows existing patterns
- Tests passing

Efficiency Tracking

Scores saved to .kilo/logs/efficiency_score.json:

{
  "version": "1.0",
  "history": [
    {
      "issue": 42,
      "date": "2024-01-02T10:00:00Z",
      "agents": {
        "lead-developer": 8,
        "code-skeptic": 7,
        "the-fixer": 9
      },
      "iterations": 2,
      "duration_hours": 1.5
    }
  ]
}

Fitness Tracking

Fitness scores saved to .kilo/logs/fitness-history.jsonl:

{"ts":"2026-04-06T00:00:00Z","issue":42,"workflow":"feature","fitness":0.82,"tokens":38400,"time_ms":245000,"tests_passed":45,"tests_total":47}
{"ts":"2026-04-06T01:30:00Z","issue":43,"workflow":"bugfix","fitness":0.91,"tokens":12000,"time_ms":85000,"tests_passed":47,"tests_total":47}

Manual Agent Invocation

// Use Task tool to invoke subagent
Task tool with:
  subagent_type: "lead-developer"
  prompt: "Implement authentication for issue #42"

Or via @mention:

@lead-developer implement authentication flow

Environment Variables

Gitea integration uses centralized authentication (see .kilo/shared/gitea-auth.md and .kilo/gitea.jsonc):

Variable	Required	Description
GITEA_API_URL	No	API base URL (default: https://git.softuniq.eu/api/v1)
GITEA_TOKEN	Preferred	Pre-existing API token
GITEA_USER	Fallback	Username for Basic Auth token creation
GITEA_PASS	Fallback	Password for Basic Auth token creation
GITEA_TARGET_REPO	No	Override target project (auto-detected otherwise)

Auth resolution: GITEA_TOKEN → GITEA_USER+GITEA_PASS → ValueError. NEVER hardcode credentials.

Self-Improvement Cycle

1. Pipeline runs for each issue
2. Evaluator scores each agent (1-10) - subjective
3. Pipeline Judge measures fitness objectively (0.0-1.0)
4. Low fitness (<0.70) triggers prompt-optimizer
5. Prompt optimizer analyzes failures and improves prompts
6. Re-run workflow with improved prompts
7. Compare fitness before/after - commit if improved
8. Log results to .kilo/logs/fitness-history.jsonl

Evaluator vs Pipeline Judge

Aspect	Evaluator	Pipeline Judge
Type	Subjective	Objective
Score	1-10 (opinion)	0.0-1.0 (metrics)
Metrics	Observations	Tests, tokens, time
Trigger	After workflow	After evaluator
Action	Logs to Gitea	Triggers optimization

Fitness Score Components

fitness = (test_pass_rate × 0.50) + (quality_gates_rate × 0.25) + (efficiency_score × 0.25)

where:
  test_pass_rate = passed_tests / total_tests
  quality_gates_rate = passed_gates / total_gates (build, lint, types, tests, coverage)
  efficiency_score = 1.0 - clamp(normalized_cost, 0, 1)

Architecture Files

File	Purpose
AGENTS.md	This file - main config
.kilo/agents/*.md	Agent definitions with prompts
.kilo/commands/*.md	Workflow commands
.kilo/rules/*.md	Custom rules loaded globally
.kilo/skills/	Skill modules
.kilo/shared/gitea-auth.md	Centralized Gitea auth (env vars, no hardcoded creds)
.kilo/gitea.jsonc	Gitea auth structure (env var mapping)
.kilo/shared/gitea-api.md	Centralized Gitea API client
.kilo/shared/gitea-commenting.md	Comment format for Gitea
.kilo/shared/self-evolution.md	Self-evolution protocol
.kilo/rules/architect-first-contact.md	First-contact project indexing rules
.kilo/skills/project-mapping/SKILL.md	Project mapping skill (.architect/ system)
.architect/	Project codebase map (auto-indexed, see below)
src/kilocode/	TypeScript API for programmatic use

Skills Reference

Containerization Skills

Skill	Purpose	Location
docker-compose	Multi-container orchestration	.kilo/skills/docker-compose/
docker-swarm	Production cluster deployment	.kilo/skills/docker-swarm/
docker-security	Container security hardening	.kilo/skills/docker-security/
docker-monitoring	Container monitoring/logging	.kilo/skills/docker-monitoring/

Node.js Skills

Skill	Purpose	Location
nodejs-express-patterns	Express routing, middleware	.kilo/skills/nodejs-express-patterns/
nodejs-auth-jwt	JWT authentication	.kilo/skills/nodejs-auth-jwt/
nodejs-security-owasp	OWASP security	.kilo/skills/nodejs-security-owasp/

Database Skills

Skill	Purpose	Location
postgresql-patterns	PostgreSQL patterns	.kilo/skills/postgresql-patterns/
sqlite-patterns	SQLite patterns	.kilo/skills/sqlite-patterns/
clickhouse-patterns	ClickHouse patterns	.kilo/skills/clickhouse-patterns/

Go Skills

Skill	Purpose	Location
go-modules	Go modules management	.kilo/skills/go-modules/
go-concurrency	Goroutines and channels	.kilo/skills/go-concurrency/
go-testing	Go testing patterns	.kilo/skills/go-testing/
go-security	Go security patterns	.kilo/skills/go-security/

Process Skills

Skill	Purpose	Location
planning-patterns	CoT/ToT planning	.kilo/skills/planning-patterns/
memory-systems	Memory management	.kilo/skills/memory-systems/
tool-use	Tool usage patterns	.kilo/skills/tool-use/
research-cycle	Self-improvement cycle	.kilo/skills/research-cycle/

Using the TypeScript API

import { 
  PipelineRunner, 
  GiteaClient, 
  decideRouting 
} from './src/kilocode/index.js'

const runner = await createPipelineRunner({
  giteaToken: process.env.GITEA_TOKEN
})

await runner.run({ issueNumber: 42 })

Agent Evolution Dashboard

Track agent model changes, performance, and recommendations in real-time.

Access

# Sync agent data
bun run sync:evolution

# Open dashboard
bun run evolution:dashboard
bun run evolution:open
# or visit http://localhost:3001

Dashboard Tabs

Tab	Description
Overview	Stats, recent changes, pending recommendations
All Agents	Filterable agent cards with history
Timeline	Full evolution history
Recommendations	Priority-based model suggestions
Model Matrix	Agent × Model mapping with fit scores

Data Sources

Source	What it tracks
.kilo/agents/*.md	Model, description, capabilities
.kilo/kilo.jsonc	Model assignments
.kilo/capability-index.yaml	Capability routing
Git History	Model and prompt changes
Gitea Comments	Performance scores

Evolution Data Structure

{
  "agents": {
    "lead-developer": {
      "current": { "model": "qwen3-coder:480b", "fit_score": 92 },
      "history": [{ "type": "model_change", "from": "deepseek", "to": "qwen3" }],
      "performance_log": [{ "issue": 42, "score": 8, "success": true }]
    }
  }
}

Recommendations Priority

Priority	When	Example
Critical	Fit score < 70	Immediate model change required
High	Model unavailable	Switch to fallback
Medium	Better model available	Consider upgrade
Low	Optimization possible	Optional improvement

Agent Execution Monitoring

Every agent invocation is logged to .kilo/logs/agent-executions.jsonl for project-level monitoring.

Log Format

{"ts":"2026-04-18T14:00:00Z","agent":"php-developer","issue":42,"project":"UniqueSoft/my-shop","task":"Create Product model","subtask_type":"model_creation","duration_ms":45000,"tokens_used":8500,"status":"success","files":["app/Models/Product.php"],"score":8,"next_agent":"code-skeptic"}

Monitoring Commands

# Agent stats report
bun run scripts/agent-stats.ts

# Stats for last 7 days
bun run scripts/agent-stats.ts --last 7

# Stats for specific project
bun run scripts/agent-stats.ts --project UniqueSoft/my-shop

Required Logging Fields

Field	Description
agent	Agent name
issue	Gitea issue number
project	Target project repo (NOT hardcoded APAW)
task	Atomic task description
duration_ms	Execution time
tokens_used	Token estimate
status	success/fail/pass/blocked

Critical Rules

Target Project (NOT APAW)

Issues MUST be created in the target project repository, NOT in APAW. APAW is the agent framework, not the default project.

# Auto-detect from git remote
TARGET_REPO=$(git remote get-url origin | sed 's:/*$::' | sed -E 's|.*[:/]([^/]+/[^/]+?)(\.git)?$|\1|')

Atomic Tasks (1 action = 1 task)

Every agent invocation solves exactly ONE atomic task:

• ❌ "Implement the entire e-commerce backend"
• ✅ "Create Product model with migration"
• ✅ "Add POST /api/products endpoint"

Modular Code

• Maximum 100 lines per file
• Maximum 30 lines per function
• Features organized as independent modules
• Cross-module communication via events/interfaces only

Token Budgets

Task Size	Max Tokens	Example
Tiny	2,000	Fix typo, add config
Small	5,000	Create model + migration
Medium	10,000	Create API endpoint + test
Large	20,000	Create service with 3 methods

Code Style

• Use TypeScript for new files
• Follow existing patterns
• Write tests before code (TDD)
• Keep functions under 50 lines
• Use early returns
• No comments unless explicitly requested