APAW/STRUCTURE.md

Project Structure

This document describes the organized structure of the APAW project.

Root Directory

APAW/
├── .architect/               # Project codebase map (auto-indexed)
│   ├── README.md              # Navigation index
│   ├── project.json           # Machine-readable project metadata
│   ├── state.json             # Index freshness state (hashes, timestamps)
│   ├── architecture/          # Architecture overview and dependency graph
│   ├── entities/              # Domain entities, fields, relationships
│   ├── db-schema/             # Database tables, columns, indexes
│   ├── api-surface/          # API endpoints, methods, auth
│   ├── conventions/           # Naming, patterns, forbidden practices
│   ├── maps/                  # Programmatic file/module graphs (.gitignored)
│   └── tech-stack/            # Languages, frameworks, databases, tools
├── .kilo/                    # Kilo Code configuration
│   ├── agents/               # 30 agent definitions (YAML frontmatter)
│   │   ├── orchestrator.md   # Main dispatcher
│   │   ├── php-developer.md  # PHP/Laravel/Symfony/WordPress
│   │   ├── python-developer.md # Python/Django/FastAPI
│   │   ├── 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
│   │   ├── nextjs.md         # Next.js app pipeline
│   │   ├── vue.md            # Vue/Nuxt 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-auth.md     # Centralized auth (env vars, no hardcoded creds)
│   │   ├── 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
│   ├── gitea.jsonc           # Gitea auth structure (env var mapping, NO secrets)
│   ├── 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
│   ├── Dockerfile.architect-indexer # Project indexer container
│   ├── docker-compose.yml    # Base config
│   ├── docker-compose.architect.yml # Architect indexer service
│   └── 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:

.architect/ Directory (Project Brain)

Auto-indexed codebase map that all agents read before starting work:

File	Purpose
.architect/README.md	Navigation index (auto-updated)
.architect/project.json	Machine-readable project metadata
.architect/state.json	Index freshness (hashes, timestamps)
.architect/architecture/overview.md	Architecture pattern, layers
.architect/architecture/dependency-graph.md	Module dependency graph
.architect/entities/entities.md	Domain entities, relations
.architect/db-schema/schema.md	Tables, columns, indexes, FKs
.architect/api-surface/endpoints.md	API routes, methods, auth
.architect/conventions/conventions.md	Coding standards, patterns
.architect/tech-stack/stack.md	Languages, frameworks, versions
.architect/maps/file-graph.json	File imports/exports graph
.architect/maps/module-graph.json	Module dependencies graph

See .kilo/skills/project-mapping/SKILL.md for full documentation.

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

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

Frontend Frameworks

Skill	Lines	Purpose
nextjs-patterns	290	Next.js 14+ App Router, Server Components, Server Actions, Auth.js
vue-nuxt-patterns	270	Vue 3 / Nuxt 3 Composition API, Pinia, Nitro, SSR
react-patterns	240	React 18+ hooks, Context, TanStack Query, React Hook Form

Python Development

Skill	Lines	Purpose
python-django-patterns	200	Django models, DRF, services, repositories
python-fastapi-patterns	230	FastAPI async, Pydantic, SQLAlchemy, dependencies

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

Centralized Authentication

All Gitea API calls use get_gitea_token() from .kilo/shared/gitea-auth.md. Configuration structure in .kilo/gitea.jsonc maps env var names — no actual credentials in code.

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 (PREFERRED)
GITEA_USER	-	Gitea username (fallback for Basic Auth)
GITEA_PASS	-	Gitea password (fallback for Basic Auth)
GITEA_TARGET_REPO	auto-detect	Override target project
TARGET_URL	http://localhost:3000	URL for testing
PIXELMATCH_THRESHOLD	0.05	Visual diff tolerance

Auth resolution: GITEA_TOKEN → GITEA_USER+GITEA_PASS → ValueError. See .kilo/shared/gitea-auth.md.

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