APAW/AGENTS.md

Kilo Code Agents Reference

This file configures AI agent behavior for the APAW 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
/status <issue>	Check pipeline status for issue	/status 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

Pipeline Agents (Subagents)

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

Core Development

Agent	Role	When Invoked
@requirement-refiner	Converts ideas to User Stories	Issue status: new
@history-miner	Finds duplicates in git	Status: planned
@system-analyst	Designs specifications	Status: researching
@sdet-engineer	Writes tests (TDD)	Status: designed
@lead-developer	Implements code	Status: testing (tests fail)
@frontend-developer	UI implementation	When UI work needed
@backend-developer	Node.js/Express/APIs	When backend needed
@go-developer	Go/Gin/Echo APIs	When Go backend needed
@devops-engineer	Docker/Kubernetes/CI/CD	When deployment/infra needed

Quality Assurance

Agent	Role	When Invoked
@code-skeptic	Adversarial review	Status: implementing
@the-fixer	Fixes issues	When review fails
@performance-engineer	Performance review	After code-skeptic
@security-auditor	Security audit	After performance
@visual-tester	Visual regression	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 (New)

Agent	Role	When Invoked
@planner	Task decomposition (CoT/ToT)	Complex tasks
@reflector	Self-reflection (Reflexion)	After each agent
@memory-manager	Memory systems	Context management

Meta & Process

Agent	Role	When Invoked
@release-manager	Git operations	Status: releasing
@evaluator	Scores effectiveness	Status: evaluated
@prompt-optimizer	Improves prompts	When score < 7
@capability-analyst	Analyzes task coverage	When starting new task
@agent-architect	Creates new agents	When gaps identified
@workflow-architect	Creates workflows	New workflow needed
@markdown-validator	Validates Markdown	Before issue creation

Workflow State Machine

[new] 
  ↓ @requirement-refiner
[planned] 
  ↓ @capability-analyst → (gaps?) → @agent-architect → create new agents
  ↓ @history-miner
[researching] 
  ↓ @system-analyst
[designed] 
  ↓ @sdet-engineer (writes failing tests)
[testing] 
  ↓ @lead-developer (makes tests pass)
[implementing] 
  ↓ @code-skeptic (review)
[reviewing] ──[fail]──→ [fixing] ──→ [reviewing]
  ↓ @review-watcher → (auto-validate) → create fix tasks
  ↓ [pass]
[perf-check] 
  ↓ @performance-engineer
[security-check] 
  ↓ @security-auditor
[releasing] 
  ↓ @release-manager
[evaluated] 
  ↓ @evaluator
  ├── [score ≥ 7] → [completed]
  └── [score < 7] → @prompt-optimizer → [completed]

Capability Analysis Flow

When starting a complex task:

[User Request]
      ↓
[@capability-analyst] ← Analyzes requirements vs existing capabilities
      ↓
[Gap Analysis] ← Identifies missing agents, workflows, skills
      ↓
[Recommendations] → Create new or enhance existing?
      ↓
[Decision]
  ├── [Create New] → [@agent-architect] → Create component → Review
  └── [Enhance] → [@lead-developer] → Modify existing
      ↓
[Integration] ← Verify new component works with system
      ↓
[Complete] ← Task can now be handled

Gitea Integration

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
    }
  ]
}

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

Required for Gitea integration:

GITEA_API_URL=https://git.softuniq.eu/api/v1
GITEA_TOKEN=your-token-here

Self-Improvement Cycle

1. Pipeline runs for each issue
2. Evaluator scores each agent (1-10)
3. Low scores (<7) trigger prompt-optimizer
4. Prompt optimizer analyzes failures and improves prompts
5. New prompts saved to .kilo/agents/
6. Next run uses improved prompts

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
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 })

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