APAW/STRUCTURE.md

Project Structure

This document describes the organized structure of the APAW project.

Root Directory

APAW/
├── .kilo/                    # Kilo Code configuration
│   ├── agents/               # 29 agent definitions (YAML frontmatter)
│   │   ├── orchestrator.md   # Main dispatcher
│   │   ├── php-developer.md  # PHP/Laravel/Symfony/WordPress
│   │   ├── lead-developer.md # Primary code writer
│   │   ├── code-skeptic.md   # Adversarial review
│   │   └── ... (25 more)
│   ├── commands/             # Slash commands
│   │   ├── pipeline.md       # Full agent pipeline
│   │   ├── laravel.md        # Laravel web app pipeline
│   │   ├── wordpress.md     # WordPress development pipeline
│   │   ├── feature.md        # Feature development
│   │   ├── commerce.md       # E-commerce site
│   │   └── ... (15 more)
│   ├── rules/                # Global rules (loaded for all agents)
│   │   ├── global.md         # Base rules
│   │   ├── atomic-tasks.md   # 1 action = 1 task principle
│   │   ├── modular-code.md  # Modules, libraries, microservices
│   │   ├── token-optimization.md  # Token budget rules
│   │   ├── gitea-centric-workflow.md  # Gitea as center of work
│   │   └── ... (10 more)
│   ├── skills/               # Agent skills
│   │   ├── php-laravel-patterns/   # Laravel patterns
│   │   ├── php-symfony-patterns/  # Symfony patterns
│   │   ├── php-wordpress-patterns/ # WordPress patterns
│   │   ├── php-security/          # OWASP, CSRF, XSS
│   │   ├── php-testing/           # PHPUnit, Pest
│   │   ├── php-modular-architecture/  # Module separation
│   │   ├── agent-logging/          # Execution logging
│   │   ├── gitea-workflow/         # Gitea integration (auto-detect project)
│   │   ├── gitea-commenting/       # Comment format (auto-detect project)
│   │   └── ... (30+ more)
│   ├── shared/               # Shared modules
│   │   ├── gitea-api.md      # Centralized API client (auto-detect repo)
│   │   ├── gitea-commenting.md # Comment format
│   │   └── self-evolution.md # Evolution protocol
│   ├── logs/                 # Execution logs
│   │   ├── agent-executions.jsonl  # Every agent invocation
│   │   ├── fitness-history.jsonl   # Fitness scores
│   │   └── efficiency_score.json   # Efficiency history
│   ├── capability-index.yaml # Agent capabilities & routing
│   ├── kilo.jsonc           # Primary agent config
│   ├── KILO_SPEC.md          # Specification
│   └── EVOLUTION_LOG.md      # Evolution timeline
├── agent-evolution/          # Evolution Dashboard
│   ├── index.standalone.html # Standalone dashboard
│   ├── scripts/              # Sync & build scripts
│   ├── data/                 # Agent version history
│   └── docker-compose.yml    # Docker launch
├── scripts/                  # Utility scripts
│   └── agent-stats.ts        # Agent execution statistics
├── docker/                   # Docker configurations
│   ├── Dockerfile.playwright # Playwright MCP container
│   ├── docker-compose.yml    # Base config
│   └── docker-compose.web-testing.yml
├── AGENTS.md                 # Agent reference (main config)
├── STRUCTURE.md              # This document
└── README.md                 # Project overview

Key Configuration Files

capability-index.yaml

Maps agent capabilities for orchestrator routing:

agents:
  php-developer:
    capabilities:
      - php_web_development
      - laravel_development
      - symfony_development
      - wordpress_development
    model: ollama-cloud/qwen3-coder:480b
    mode: subagent
    delegates_to:
      - code-skeptic
      - security-auditor

capability_routing:
  php_web_development: php-developer
  laravel_development: php-developer

kilo.jsonc

Primary agents configuration:

{
  "model": "ollama-cloud/glm-5.1",
  "default_agent": "orchestrator",
  "agent": {
    "orchestrator": { "model": "ollama-cloud/glm-5.1", "variant": "thinking" },
    "code": { "model": "ollama-cloud/qwen3-coder:480b" },
    "ask": { "model": "ollama-cloud/glm-5.1", "variant": "instant" },
    "plan": { "model": "ollama-cloud/nemotron-3-super" },
    "debug": { "model": "ollama-cloud/glm-5.1", "variant": "thinking" }
  }
}

Rules System

Rules in .kilo/rules/ are loaded globally for all agents:

Critical Rules

Rule	Purpose
atomic-tasks.md	1 action = 1 task, max 100 lines/file, task sizing
modular-code.md	Modules, services, repositories, events
token-optimimization.md	Token budgets, no scope creep
gitea-centric-workflow.md	Issues before work, progress tracking, research
global.md	Base coding rules

Language-Specific Rules

Rule	Purpose
php.md	PSR-12, TDD, security
nodejs.md	Express, JWT, async
go.md	Error wrapping, context, table-driven tests
flutter.md	Riverpod, Clean Architecture
docker.md	Multi-stage, security

Skills System

Skills are capability modules agents reference:

PHP Development (NEW)

Skill	Lines	Purpose
php-laravel-patterns	403	Routing, Eloquent, Services, Repositories, Auth, Queues
php-symfony-patterns	233	Controllers, Doctrine, Messenger, Voters
php-wordpress-patterns	276	Plugins, CPT, REST API, Security
php-security	147	OWASP Top 10, CSRF, XSS, SQL injection
php-testing	242	PHPUnit, Pest, Dusk browser tests
php-modular-architecture	242	Module separation, interfaces, events

Infrastructure

Skill	Purpose
gitea-workflow	Issue creation, quality gates, progress tracking
gitea-commenting	Comment format with auto-project detection
agent-logging	Execution logging to agent-executions.jsonl
docker-compose	Docker Compose patterns
docker-swarm	Docker Swarm orchestration

Execution Logging

Every agent invocation is logged to .kilo/logs/agent-executions.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"}

Required Fields

Field	Description
agent	Agent name
issue	Gitea issue number
project	Target project repo (auto-detected, NOT hardcoded)
task	Atomic task description
duration_ms	Execution time
tokens_used	Token estimate
status	success/fail/pass/blocked
score	Self-assessment 1-10
next_agent	Next agent in pipeline

Statistics

bun run agent:stats              # Last 30 days
bun run agent:stats:week         # Last 7 days
bun run agent:stats:project      # Filter by project

Gitea Integration

Critical: Target Project Detection

Issues MUST be created in the target project, NOT in APAW:

def get_target_repo():
    """Auto-detect from git remote - NEVER hardcode"""
    result = subprocess.run(['git', 'remote', 'get-url', 'origin'], capture_output=True, text=True)
    match = re.search(r'[:/]([^/]+/[^/]+?)(?:\.git)?$', result.stdout.strip())
    if match:
        return match.group(1)
    return os.environ.get('GITEA_TARGET_REPO', 'UniqueSoft/APAW')

All API calls use get_target_repo() instead of hardcoded repo.

Environment Variables

Variable	Default	Description
GITEA_API_URL	https://git.softuniq.eu/api/v1	Gitea API endpoint
GITEA_TOKEN	-	Gitea API token
GITEA_TARGET_REPO	auto-detect	Override target project
GITEA_USER	NW	Gitea username
GITEA_PASS	-	Gitea password
TARGET_URL	http://localhost:3000	URL for testing
PIXELMATCH_THRESHOLD	0.05	Visual diff tolerance

Quick Reference

# Pipeline for issue
/pipeline 42

# Laravel app
/laravel project_name

# WordPress plugin
/wordpress plugin_name

# Agent statistics
bun run agent:stats

# Evolution dashboard
bun run sync:evolution
bun run evolution:open

# Docker containers
docker compose -f docker/docker-compose.web-testing.yml up -d

# Web tests
./scripts/web-test.sh https://your-app.com