Plně autonomní

AI-Powered
Development Pipeline

Od YouTrack issue k nasazené aplikaci na staging. Bez lidského zásahu. Orchestrátor + 11 specializovaných AI agentů, 18 kroků pipeline, 7 autonomních workflow.

YouTrack Claude Code GitHub Docker Nginx Proxy Manager Playwright OpenRouter Leonardo AI
// Architektura

Systémový přehled

🔗

Webhook Trigger

YouTrack webhook spouští pipeline přes webhook receiver (port 9009). Skript detekuje novou Open issue a přiřadí ji AI agentovi (Claude / Gemini).

📋

YouTrack Integration

Plná integrace s REST API — čtení issues, komentářů, změna stavu, publikace do Knowledge Base. Novější komentáře mají přednost před původním popisem.

🤖

AI Orchestrátor

Hlavní Claude session řídí celý workflow. Deleguje práci na 11 specializovaných agentů — nikdy neimplementuje přímo, ani pro triviální změny.

🐙

GitHub CI/CD

Automatický clone, branch podle issue ID, commit, push a vytvoření Pull Requestu. Při inkrementálním re-runu se existující PR aktualizuje.

🐳

Docker Deployment

Každá issue běží ve vlastním Docker Compose projektu s izolovaným prostředím. Automatický health check a rollback při selhání.

🌐

Nginx Proxy Manager

Automatická konfigurace reverse proxy přes API. Wildcard SSL certifikát na *.staging.nknop.cz. Proxy host se nikdy nemaže.

// Workflow

18 kroků pipeline

01

Research direct

Načtení issue z YouTrack API — popis, požadavky, komentáře. Posouzení potřeby architekta, designera, grafiky a herní grafiky dle klíčových slov.

02

Změna stavu direct

Issue → In Progress. První viditelná akce v YouTrack. Pipeline skript automaticky vloží komentář s PID procesu agenta.

03

Setup direct

Vytvoření pracovního adresáře /opt/staging/running/<ISSUE-ID>/

04

Clone & Branch direct

Git clone repozitáře, vytvoření feature větve. Respektuje zdrojovou větev z YouTrack, jinak fallback na main/master.

4b

📄 Project Doc Agent podmíněný

Pokud v rootu projektu chybí CLAUDE.md (nebo je starší než 30 dní), agent analyzuje codebase a vygeneruje projektovou dokumentaci (tech stack, struktura, konvence, build příkazy). Všichni následující agenti ji automaticky načítají.

05

🏗 Architect Agent podmíněný

Technický návrh — datový model, API specifikace, závislosti, pořadí implementace. Spouští se při netriviálních technických rozhodnutích.

06

🎨 Designer Agent podmíněný

UI/UX návrh — layout, komponenty, vizuální specifikace. Identifikuje potřebné grafické assety a signalizuje to přes NEEDS_ASSETS=YES.

07

🖼 Grafika Agent podmíněný

Generování obecných grafických assetů přes OpenRouter API. Náklady se agregují do openrouter_cost_usd v logu. Max 1 retry.

7b

🎮 Herní Grafika Agent podmíněný

Herní grafické assety (sprity, textury, character art) přes Leonardo AI. Rozhodovací logika 7 vs. 7b podle herních klíčových slov. Max 1 retry.

08

🔧 Coder Agent agent

Implementace kódu, testy, ověření buildu. Přijímá kompletní kontext od architekta, designera a grafika agentů jako součást promptu.

09

📋 Reviewer Agent agent

Code review — kvalita, bezpečnost, konvence, tech debt detekce. Max 2 iterace s Coderem. Sekce ### Tech Debt spouští krok 15b.

10

🧪 Tester Agent agent

Unit testy, build verification, Docker build (bez up -d). Max 2 iterace s Coderem.

11

Pull Request direct

Vytvoření PR na GitHubu s popisem provedených změn. Při inkrementálním re-runu se existující PR aktualizuje automaticky.

12

Deployment direct

docker compose -p <issue-id> up -d — spuštění služby v izolovaném kontejneru.

12b

Health Check direct

Kontrola docker compose ps, crash indikátory v logu, HTTP health check přes curl. Při selhání → coder → redeploy (max 1 iterace).

13

Proxy konfigurace direct

NPM API → proxy host <prefix>.staging.nknop.cz směřující na Docker bridge (172.17.0.1).

14

👁 Visual Tester Agent agent

Playwright screenshoty běžícího UI → vizuální verifikace oproti zadání. Max 1 iterace s Coderem + redeploy.

15

📝 Summarizer Agent agent

Finální shrnutí celého workflow — co bylo implementováno, PR link, staging URL, průběh agentů.

15b

🔧 Tech Debt sub-tasky podmíněný

Pokud reviewer vrátil neprázdnou sekci ### Tech Debt a workflow skončil úspěšně, orchestrátor vytvoří max 2 sub-tasky v YouTracku (Type=Task, Priority=Low, State=Backlog) a propojí je s parent issue.

16

Finalizace direct

Issue → To Verify. Komentář se shrnutím, PR URL a staging URL.

17

Workflow Execution Log direct

JSONL záznam do /opt/staging/logs/workflow-runs.jsonl včetně telemetrie tokenů (agents_run[].tokens, top-level totals) a openrouter_cost_usd. Agent tokens doplňuje deterministický post-processor merge_workflow_tokens.sh.

18

Pipeline State File direct

Zápis .pipeline_state (JSON) do adresáře issue — obsahuje last_run_at, pr_url, commit_sha, branch. Umožňuje inkrementální re-run při dopracování.

// Specializace

11 AI agentů

Podmíněný
📄

Project Doc Agent

Generuje CLAUDE.md v rootu projektu — tech stack, struktura, konvence. Předává kontext všem následujícím agentům.

SUCCESS | PARTIAL | BLOCKED
Podmíněný
🏗

Architect Agent

Technický návrh, datový model, API specifikace. Analyzuje codebase a navrhuje technický plán.

SUCCESS | BLOCKED
Podmíněný
🎨

Designer Agent

UI/UX návrh, layout, komponenty, vizuální specifikace. Identifikuje potřebné grafické assety.

SUCCESS | BLOCKED
Podmíněný
🖼

Grafika Agent

Generuje obecné grafické assety (loga, ikony, bannery) přes OpenRouter API.

SUCCESS | PARTIAL | BLOCKED max 1 retry
Podmíněný
🎮

Herní Grafika Agent

Herní grafické assety (sprity, textury, character art, pixel art) přes Leonardo AI.

SUCCESS | PARTIAL | BLOCKED max 1 retry
Povinný
🔧

Coder Agent

Jádro pipeline. Implementuje kód, píše testy, ověřuje build. Přijímá feedback z Reviewera, Testera, Health Checku i Visual Testera.

SUCCESS | PARTIAL | BLOCKED
Povinný
📋

Reviewer Agent

Code review zaměřený na kvalitu kódu, bezpečnost, dodržování konvencí a detekci tech debt.

APPROVED | CHANGES_REQUESTED max 2 iterace
Povinný
🧪

Tester Agent

Spouští unit testy, ověřuje build, buildí Docker image bez up -d (aby nevznikl konflikt portů).

PASS | FAIL max 2 iterace
Povinný
👁

Visual Tester Agent

Pořizuje screenshoty nasazeného UI přes Playwright a vizuálně ověřuje implementaci oproti zadání.

PASS | FAIL max 1 iterace
Povinný
📝

Summarizer Agent

Kompiluje finální shrnutí celého workflow — co bylo implementováno, PR link, staging URL, průběh agentů.

SUCCESS
Workflow
📚

Další agenti

Pro non-pipeline workflow: analyst (design dokumenty), sprint-planner (KB → issues), workflow-improver (denní cron), kb-updater (denní KB aktualizace).

viz Workflows

🚫 Klíčové pravidlo

Orchestrátor NIKDY neimplementuje kód, nedělá review, netestuje, nenavrhuje architekturu ani UI design přímo — ani pro triviální změny (1 řádek). Vždy deleguje na příslušného agenta. Přímá implementace orchestrátorem je porušení workflow.

// Flow diagram

Orchestrace a feedback smyčky

▸ Orchestrátor (hlavní Claude session)
├── Kroky 1–4: Research, stav, setup, clone
├── Krok 4b: → project-doc (generování CLAUDE.md) [PODMÍNĚNÝ]
├── Krok 5: → architect (technický návrh) [PODMÍNĚNÝ]
├── Krok 6: → designer (UI/UX návrh) [PODMÍNĚNÝ]
├── Krok 7: → grafika (OpenRouter) [PODMÍNĚNÝ]
├── Krok 7b: → herni-grafika (Leonardo AI) [PODMÍNĚNÝ]
├── Krok 8: → coder (implementace)
├── Krok 9: → reviewer (code review)
│      └── CHANGES_REQUESTED → coder → reviewer (max 2×)
├── Krok 10: → tester (testy)
│      └── FAIL → coder → tester (max 2×)
├── Kroky 11–12: PR, deploy
├── Krok 12b: Health check
│      └── FAIL → coder → redeploy → health-check (max 1×)
├── Krok 13: Proxy konfigurace
├── Krok 14: → visual-tester (vizuální verifikace UI)
│      └── FAIL → coder → redeploy → visual-tester (max 1×)
├── Krok 15: → summarizer (finální shrnutí + YT komentář)
├── Krok 15b: Tech Debt sub-tasky [PODMÍNĚNÝ]
├── Krok 16: Finalizace → To Verify
├── Krok 17: Workflow Execution Log (+ tokens/cost telemetrie)
└── Krok 18: Pipeline State File (.pipeline_state)

⟳ Grafika retry

Grafika Agent
Max 1 iterace

⟳ Herní Grafika retry

Herní Grafika Agent
Max 1 iterace

⟳ Review loop

Coder ↔ Reviewer
Max 2 iterace

⟳ Test loop

Coder ↔ Tester
Max 2 iterace

⟳ Health check loop

Coder ↔ Health Check
Max 1 iterace

⟳ Visual loop

Coder ↔ Visual Tester
Max 1 iterace

// Další workflow

7 autonomních workflow

🚀

Issue Handling (hlavní pipeline)

Plný 18krokový workflow od Open issue k nasazené aplikaci na staging. Delegace na 11 agentů, feedback smyčky, telemetrie.

Open → 18 kroků → To Verify → .pipeline_state
🔁

Inkrementální re-run

Zkrácený workflow aktivovaný přes .pipeline_state, když uživatel vrátí issue k dopracování. Přeskakuje setup, clone, podmíněné agenty a PR vytvoření. Úspora ~50 % času.

Nové komentáře → coder → reviewer → tester → redeploy → visual-tester → summarizer
✅

AutoVerify

Automatický merge ověřených issues do auto-verify větve a řetězení k další issue. Per-project locking umožňuje paralelní běh různých projektů.

To Verify + autoVerify=true → Merge do auto-verify → Stav → Waiting → Aktivace další issue → Ruční merge do main
📄

Design Document

Tvorba návrhových dokumentů přes analysta, architekta a designera s publikací do YouTrack Knowledge Base. Aktivuje se klíčovými slovy jako "návrh", "specifikace", "plán aplikace".

analyst → architect → designer [PODMÍNĚNÝ] → Kompilace → KB publikace → To Verify
📅

Sprint Planning (KB → issues)

Dekompozice KB dokumentu na strukturované YouTrack issues se závislostmi a sprint plánem. Aktivuje se požadavkem "vytvoř issues z [KB link]".

KB dokument → sprint-planner → Vytvoření issues v YT → Propojení závislostí
⚙

Workflow Improver

Denní cron agent analyzující aktuální stav workflow (agenty, CLAUDE.md, skripty) a navrhující 1–2 konkrétní zlepšení jako YouTrack issues.

Analýza agentů, CLAUDE.md, skriptů → 1–2 návrhy → Vytvoření issues v YT
Denně v 9:17 UTC
📰

KB Updater

Denní generování obsahu pro dva KB články v projektu aipowereddevelopment: 2 nové tipy na Claude/AI development (článek A-1) a 1 zpráva ze světa AI (článek A-2). Agent má minimální toolset (Read, WebSearch, WebFetch) — žádné API credentials, veškeré zápisy provádí orchestrátor po sanitizaci výstupu.

Načtení A-1 + A-2 → kb-updater (WebSearch deduplikace) → Sanitizace → POST /api/articles → Tracking issue (To Verify)
Denně v 5:00 CEST (cron 0 3 * * *)
// Infrastruktura

Deployment & konvence

🌐 Staging doména

Vzor <prefix>.staging.nknop.cz
SSL *.staging.nknop.cz (wildcard)
LIN-33 → lin.staging.nknop.cz ✓
LIN-33 → lin-33.staging.nknop.cz ✗
// Wildcard cert pokrývá jen jednu úroveň
// lin-33 = dvě úrovně → SSL error
prefix = issueId.split("-")[0].toLowerCase()

🐳 Docker

Projekt prefix -p <issue-id-lowercase>
Pracovní dir /opt/staging/running/<ISSUE-ID>/
Forward host 172.17.0.1 (bridge)
NPM API localhost:81
# Spuštění projektu
docker compose -p lin-33 up -d

# Proxy: UPDATE existující, nikdy DELETE
PUT /api/nginx/proxy-hosts/<id>

📊 Workflow Execution Log (krok 17)

Každý běh se zapisuje jako jeden řádek do /opt/staging/logs/workflow-runs.jsonl. Token telemetrii doplňuje deterministický post-processor merge_workflow_tokens.sh.

issue_id, started_at, finished_at, duration_minutes
agents_run[]: agent, status, iterations,
  tokens {input, output, cache_*, cost_usd}
totals: {input, output, cache_*, cost_usd}
openrouter_cost_usd: grafika/herni-grafika
pr_url, staging_url, final_status
tech_debt_issues[], disk_usage_pct

💾 Pipeline State File (krok 18)

JSON soubor .pipeline_state v adresáři issue — umožňuje inkrementální re-run. Pokud youtrack_to_gemini.sh detekuje existenci, přidá do promptu INCREMENTAL_RERUN=true.

{
  "last_run_at": // ISO 8601 UTC
  "pr_url": // existující PR
  "staging_url": // <prefix>.staging...
  "commit_sha": // poslední commit
  "final_status": "To verify",
  "branch": // název větve
}
// Životní cyklus

Stavy YouTrack issue

Open
→
In Progress
→
To Verify
→
Done
Alternativní cesta při blockeru:
In Progress
→
Waiting

🛑 Fallback na Waiting

Nastává při: max iteracích review/test cyklu bez úspěchu, selhání health checku, kritickém blockeru bez možnosti řešení, nebo chybějícím vstupu od uživatele. Issue dostane komentář vysvětlující důvod a potřebné informace.

📝 YouTrack komentáře

Po každém dokončení agenta se automaticky postne komentář do YouTrack issue s prefixem podle typu agenta:

📄 Project Doc: <výstup>
🏗 Architect: <výstup>
🎨 Designer: <výstup>
🖼 Grafika: <výstup>
🎮 Herní Grafika: <výstup>
🔧 Coder: <výstup>
📋 Reviewer: <výstup>
🧪 Tester: <výstup>
👁 Visual Tester: <výstup>
📝 Summarizer: <výstup>

🧹 Cleanup (stav Done)

Při úklidu Done issues se automaticky:

# 1. Zastavení kontejneru
docker compose -p <id> down

# 2. Smazání pracovního adresáře
rm -rf /opt/staging/running/<ISSUE-ID>/

# 3. Proxy host se NESMAŽE!
# (kvůli SSL certifikátu)