AI-Powered Development Pipeline

// Architektura

Systémový přehled

🔗

Webhook Trigger

YouTrack webhook spouští pipeline přes webhook receiver. 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 pro staging doménu. Proxy host se nikdy nemaže.

// Workflow

18 kroků pipeline

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.

Změna stavu direct

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

Setup direct

Vytvoření samostatného pracovního adresáře pro danou issue na staging serveru.

Clone & Branch direct

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

📄 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í.

🏗 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.

🎨 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.

🖼 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.

🎮 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.

🔧 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.

📋 Reviewer Agent agent

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

🧪 Tester Agent agent

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

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.

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).

Proxy konfigurace direct

NPM API → proxy host pro staging URL dané issue (wildcard SSL), směřující na kontejner přes Docker bridge.

👁 Visual Tester Agent agent

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

📝 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.

Finalizace direct

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

Workflow Execution Log direct

JSONL záznam do centrálního logu běhů včetně telemetrie tokenů (agents_run[].tokens, top-level totals) a openrouter_cost_usd. Tokeny agentů doplňuje po dokončení běhu deterministický post-processor.

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í.

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

URL vlastní staging URL pro každou issue

SSL wildcard certifikát pro staging doménu

1 úroveň → pokrývá wildcard certifikát ✓

2+ úrovně → certifikát nepokrývá ✗

          // Wildcard cert pokrývá jen jednu úroveň subdomény

          // víceúrovňová subdoména → SSL error

          certifikát = wildcard("staging doména").pokrývá("1 úroveň")

🐳 Docker

Projekt samostatný Docker Compose projekt pro každou issue

Pracovní dir samostatný adresář pro každou issue

Forward host Docker bridge gateway

NPM API interní, nedostupné zvenku

          # Spuštění projektu

          docker compose -p <issue-id> 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 centrálního logu ve formátu JSONL. Telemetrii tokenů doplňuje po dokončení běhu deterministický post-processor.

          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 orchestrační skript pipeline detekuje jeho existenci, přidá do promptu INCREMENTAL_RERUN=true.

          {

            "last_run_at": // ISO 8601 UTC

            "pr_url": // existující PR

            "staging_url": // staging URL dané issue

            "commit_sha": // poslední commit

            "final_status": "To verify",

            "branch": // název větve

          }