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

### Fitness Tracking

Fitness scores saved to `.kilo/logs/fitness-history.jsonl`:
```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

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

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

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

```bash
# 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

```json
{
  "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

```jsonl
{"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

```bash
# 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.

```bash
# 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