# Kilo Code Agents Reference

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

## Quick Setup

```bash
# 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:
```markdown
## ✅ 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`:
```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

```typescript
// 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:
```bash
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

```typescript
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*