APAW/HOW_TO_SYNC_KILO.md

How to Sync .kilo/ from APAW to Your Project

The Problem

APAW is the framework repository — it contains the master definitions for all agents, skills, rules, and workflows. Your project is the target repository — it needs these definitions to work with the agent system.

Agents DO NOT read from Gitea. They read from .kilo/ in the current working directory. If you want your project's agents to use the new landing visual debugging capabilities, you MUST copy the updated files into your project's .kilo/ directory.

Sync Pattern

Option 1: Copy .kilo/ from APAW (Recommended for now)

When you want agents in your project to use the new landing visual debugging skill/rule/agent updates:

# 1. In APAW repo — verify you have the latest
cd /home/swp/Projects/APAW
git pull origin dev

# 2. Copy new/modified files to YOUR project
cp -r .kilo/skills/landing-design-interpretation   /path/to/your/project/.kilo/skills/
cp .kilo/rules/landing-visual-debugging.md         /path/to/your/project/.kilo/rules/
cp .kilo/agents/frontend-developer.md            /path/to/your/project/.kilo/agents/
# Also copy any updated skills/rules/agents you need
cp .kilo/skills/web-testing/SKILL.md               /path/to/your/project/.kilo/skills/web-testing/
cp .kilo/skills/visual-testing/SKILL.md          /path/to/your/project/.kilo/skills/visual-testing/

# 3. Copy scripts if you want the contrast extractor
cp tests/scripts/extract-contrast.js              /path/to/your/project/tests/scripts/

# 4. Commit in YOUR project
cd /path/to/your/project
git add .kilo/skills/landing-design-interpretation .kilo/rules/landing-visual-debugging.md .kilo/agents/frontend-developer.md
git commit -m "chore: sync .kilo/ from APAW — landing visual debugging pipeline"

Option 2: Submodule (Future / CI-friendly)

If your project uses Git submodules, you can link APAW as .kilo/ source. However, this requires CI to copy files at build time because agents read from the local filesystem, not from submodule path directly.

Option 3: Release Manager Sync (Automated)

In the release pipeline (.kilo/rules/branch-strategy.md § Release Process):

# Step 6 of release: sync .kilo/ to target projects
# This is done BY THE RELEASE MANAGER agent when creating a release from dev → main
git -C /path/to/your/project pull origin dev --ff-only
rsync -av --exclude='*.tmp' /home/swp/Projects/APAW/.kilo/ /path/to/your/project/.kilo/

What Changed (2026-05-22)

New Files (MUST be copied to project)

• .kilo/skills/landing-design-interpretation/SKILL.md — translation dictionary + contrast protocol
• .kilo/rules/landing-visual-debugging.md — mandatory 3-phase pipeline
• tests/scripts/extract-contrast.js — Playwright-based contrast extraction script

Updated Files (SHOULD be copied to project)

• .kilo/agents/frontend-developer.md — added mandatory measurement-first protocol for landing tasks
• .kilo/agents/orchestrator.md — no changes needed for this evolution

Sync Script

Save this as scripts/sync-from-apaw.sh in your project:

#!/usr/bin/env bash
set -euo pipefail

APAW_DIR="${APAW_DIR:-/home/swp/Projects/APAW}"
TARGET_DIR="${TARGET_DIR:-$(pwd)}"

echo "=== Syncing .kilo/ from APAW ==="
echo "Source: $APAW_DIR"
echo "Target: $TARGET_DIR"

# New skill
if [ -d "$APAW_DIR/.kilo/skills/landing-design-interpretation" ]; then
  mkdir -p "$TARGET_DIR/.kilo/skills"
  rsync -av "$APAW_DIR/.kilo/skills/landing-design-interpretation/" "$TARGET_DIR/.kilo/skills/landing-design-interpretation/"
  echo "✅ landing-design-interpretation skill synced"
fi

# New rule
if [ -f "$APAW_DIR/.kilo/rules/landing-visual-debugging.md" ]; then
  cp "$APAW_DIR/.kilo/rules/landing-visual-debugging.md" "$TARGET_DIR/.kilo/rules/"
  echo "✅ landing-visual-debugging rule synced"
fi

# Updated agent
if [ -f "$APAW_DIR/.kilo/agents/frontend-developer.md" ]; then
  cp "$APAW_DIR/.kilo/agents/frontend-developer.md" "$TARGET_DIR/.kilo/agents/"
  echo "✅ frontend-developer agent synced"
fi

# Script
if [ -f "$APAW_DIR/tests/scripts/extract-contrast.js" ]; then
  mkdir -p "$TARGET_DIR/tests/scripts"
  cp "$APAW_DIR/tests/scripts/extract-contrast.js" "$TARGET_DIR/tests/scripts/"
  echo "✅ extract-contrast.js synced"
fi

echo "=== Sync complete ==="

Usage After Sync

1. Landing Visual Task Comes In

User says: "Исправь цветовую схему лендинга, текст сливается с фоном"

2. Orchestrator Routes to frontend-developer

Agent prompt MUST include:

Task: Fix landing page contrast issue
Context:
- Follow .kilo/rules/landing-visual-debugging.md (MANDATORY)
- Load skill .kilo/skills/landing-design-interpretation/SKILL.md on entry
- Use measurement-first protocol — never change colors without running extract-contrast.js
- URL: http://localhost:8080 (or project landing URL)

3. Agent Executes Pipeline

1. Reads landing-design-interpretation skill → translates "сливается" → contrast ratio < 4.5
2. Runs measurement:

   docker compose -f docker/docker-compose.web-testing.yml run --rm browser-automation \
     node tests/scripts/extract-contrast.js http://localhost:8080 --threshold 4.5 --output contrast-report.json
   

3. Reads report → gets exact selectors + current colors + ratios
4. Applies minimal CSS fixes → changes only the specific hex values
5. Re-runs measurement → confirms all ratios >= 4.5
6. Takes screenshot → verifies no regressions

4. Expected Output

## Frontend Developer: Contrast Fix Complete

### Measurement
- Tool: extract-contrast.js (Playwright)
- URL: http://localhost:8080
- Threshold: 4.5:1
- Violations found: 3

### Fixes Applied
1. `.hero p` — color: #888 → #555 (ratio: 2.8 → 5.1)
2. `.card-body` — color: #666 → #444 (ratio: 3.2 → 4.8)
3. `.cta-subtitle` — color: #999 → #555 (ratio: 2.1 → 5.1)

### Verification
- [x] Re-run extract-contrast.js — all ratios >= 4.5
- [x] Screenshot comparison — no regressions
- [x] Hover states maintain contrast

Common Mistakes

❌ Wrong: Agent works without reading the skill

# Bad prompt — no skill reference
"Fix the landing page colors"
# Result: agent guesses, 7 iterations, no result

✅ Right: Skill is loaded into agent context

# Good prompt — skill loaded
"Fix landing page colors. Load .kilo/skills/landing-design-interpretation/SKILL.md on entry. Follow Phase 1→2→3 protocol."
# Result: 1 iteration with measurement + verification

❌ Wrong: Project has outdated frontend-developer.md

# Old agent ignores measurement protocol
# Result: agent changes colors based on visual intuition

✅ Right: frontend-developer.md synced from APAW

# Updated agent has mandatory Landing Visual Protocol in behavior guidelines
# Result: agent automatically follows measure-first approach

One-Line Summary

Agents read .kilo/ from disk, not from Gitea. Copy new files from APAW to your project before using them.