TenerifeProp/AGENTS.md

Kilo Code Agents Reference

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

Quick Setup

# Copy to any project
cp -r APAW/.kilo /your-project/
cp APAW/AGENTS.md /your-project/
cp APAW/.kilo/kilo.jsonc /your-project/.kilo/

# Or use the installer
./setup-agents.sh /path/to/your-project

---

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
/feature	Feature development workflow	/feature add payment
/hotfix	Hotfix workflow	/hotfix fix login bug
/review	Code review workflow	/review src/auth.ts
/review-watcher	Auto-validate reviews	/review-watcher

---

Pipeline Agents (Subagents)

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

Agent	Role	Model	When Invoked
@orchestrator	Chief dispatcher	GLM-5	Status routing
@requirement-refiner	Converts ideas to User Stories	Kimi-k2-thinking	Issue status: new
@history-miner	Finds duplicates in git	GPT-OSS 20B	Status: planned
@capability-analyst	Analyzes task coverage	Qwen3.6-Plus	When starting task
@agent-architect	Creates new agents	Qwen3.6-Plus	When gaps identified
@system-analyst	Designs specifications	Qwen3.6-Plus	Status: researching
@sdet-engineer	Writes tests (TDD)	Qwen3-Coder 480B	Status: designed
@lead-developer	Implements code	Qwen3-Coder 480B	Status: testing
@frontend-developer	UI implementation	Kimi-k2.5	When UI work needed
@code-skeptic	Adversarial review	GPT-OSS 120B	Status: implementing
@the-fixer	Fixes issues	MiniMax-m2.7	When review fails
@performance-engineer	Performance review	Nemotron-3-Super	After code-skeptic
@security-auditor	Security audit	GLM-4.7	After performance
@release-manager	Git operations	Devstral-2 123B	Status: releasing
@evaluator	Scores effectiveness	GPT-OSS 120B	Status: evaluated
@prompt-optimizer	Improves prompts	Qwen3.6-Plus	When score < 7
@product-owner	Manages issues	Qwen3.6-Plus	Close issues
@markdown-validator	Validates Markdown	Kimi-k2	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

# Optional
GITEA_USERNAME=NW
GITEA_PASSWORD=eshkink0t

---

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
.kilo/kilo.jsonc	Project configuration
src/kilocode/	TypeScript API for programmatic use

---

Skills (Reusable Modules)

Skill	Purpose
gitea	Gitea API integration
gitea-commenting	Auto-post comments to issues
scoped-labels	Manage status labels
task-analysis	Decompose complex tasks
fix-workflow	Automatic fix workflow
puppeteer	Browser automation

---

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

// Or manually
const client = new GiteaClient({
  apiUrl: 'https://git.softuniq.eu/api/v1',
  token: process.env.GITEA_TOKEN
})

await client.setRepository('UniqueSoft', 'APAW')
await client.setStatus(42, 'implementing')
await client.createComment(42, '## ✅ Implementation started')

---

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

---

Project Structure

project/
├── AGENTS.md              # This file - AI configuration
├── .kilo/
│   ├── agents/            # 19 agent definitions
│   ├── commands/          # 11 slash commands
│   ├── rules/             # Coding rules
│   ├── skills/            # Reusable skill modules
│   ├── logs/              # Efficiency logs
│   ├── prompts/           # Prompt templates
│   └── kilo.jsonc         # Project config
├── .claude/               # Claude Code config (optional)
│   ├── commands/
│   ├── rules/
│   └── logs/
├── scripts/               # Utility scripts
├── docs/                  # Documentation
└── src/kilocode/          # TypeScript API

---

Quick Reference

Start Pipeline

/pipeline 42

Check Status

/status 42

Direct Agent Call

@lead-developer implement auth

Add New Agent

1. Create .kilo/agents/my-agent.md
2. Add YAML frontmatter with model, permissions
3. Use: @my-agent task

Debug Pipeline

/debug pipeline issue 42

---

Generated by APAW - Automatic Programmers Agent Workflow