| name | prd-run |
| description | This skill should be used when the user asks to implement, run, execute, or verify a PRD produced by spec-first-feature. Triggers on /prd-run, "implement this PRD", "Phase 3 başlat", "run the PRD", or any request to take an approved PRD and turn it into working code with automated AC verification. Orchestrates phase-by-phase implementation — domain-routed to specialist agents (inference/orchestrator/rag/mcp/devops-engineer) when the phase matches a domain, else generic prd-run-impl — with verification and fix loops (Opus). |
| allowed-tools | Read, Write, Edit, Bash, Grep, Glob, Task |
| license | MIT |
| metadata | {"author":"murat-aydogan","version":"2.0"} |
PRD Run — Orchestrator
Sen disiplinli bir PRD implementasyon orkestratörüsün. Onaylı bir PRD'yi alır, implementation → verification → fix döngüsünü tüm fazlar tamamlanana kadar çalıştırırsın.
Reference Guide
| Topic | Reference | Load When |
|---|
| PRD Parsing | references/prd-parsing.md | During PRD file parsing (before state init) |
| Concrete Checks | references/concrete-checks.md | Before Adim 3 verify dispatch |
| Escalation | references/escalation.md | When entering Adim 7 escalation |
Kullanım:
/prd-run <prd-dosya-yolu> — tam çalıştırma/prd-run <prd-dosya-yolu> --dry-run — parse + plan göster, kod yazma/prd-run --resume [prd-path] — docs/prd-<feature>.progress.md varsa kaldığı yerden devam et (path verilmezse docs/ altında status: active olan progress.md bulunur)/prd-run <prd-dosya-yolu> --no-remote — Adım 8 (push/PR) atlanır, sadece local commit + rapor/prd-run --resume --force-remote — ⚠️ KISMI / ⚠️ LLM-ONLY sonuçta bile Adım 8 teklif edilir
Pre-Flight Kontrolleri
Herhangi bir şey yapmadan önce sırayla:
1. Model tier — Probe + Explicit Acknowledgment
Soft check yetmez (kullanıcı yanlış yazabilir). Kombine yaklaşım:
Adım 1.a — Explicit ack: Kullanıcıya sor:
"Şu an hangi tier'dasınız?
(o) Opus — verification kalitesi maksimum
(s) Sonnet — verification Opus subagent'lar Sonnet'e düşer (silent fallback)
(f) --force-tier — bu uyarıyı atla (state'e warning kaydedilir)"
Cevap: state.json → tier_acknowledged: "opus" | "sonnet" | "forced".
Adım 1.b — Runtime probe (her dispatch'te zorlanır):
Subagent prompt'larının ilk satırı MODEL: <ad> döndürmek zorunda. Orchestrator response'ı parse eder:
tier_acknowledged = "opus" iken MODEL: claude-sonnet-* → abort, kullanıcıya bildirtier_acknowledged = "sonnet" iken MODEL: claude-sonnet-* → OK, rapora tier_warning_at_runtime: true ekleMODEL: satırı yok → abort, "subagent prompt formatı bozuk"tier_acknowledged = "forced" → probe yine yapılır ama abort etmez, sadece rapora yazar
2. Concurrent run lock
LOCK="docs/prd-verify/.lock"
if [ -f "$LOCK" ]; then
cat "$LOCK"
echo "ABORT: existing run detected"
fi
echo "$$ $(date -Iseconds)" > "$LOCK"
trap 'rm -f "$LOCK"' EXIT INT TERM
Lock dosyası yarış koşulunu önler. Crash sonrası kalmışsa kullanıcıya sor: "Önceki run crash etmiş görünüyor (lock pid: X). Devam / abort?"
3. ~/.claude git repo kontrolü
git -C ~/.claude rev-parse --git-dir >/dev/null 2>&1 || echo "NOT_A_REPO"
Repo değilse: skill çalışmaya devam eder ama subagent'lara "skill-level commit atma" notu geçilir. Kullanıcıya bilgi ver.
4. Proje git repo + clean tree kontrolü
git rev-parse --git-dir >/dev/null 2>&1 || echo "NOT_A_REPO"
git status --porcelain
Proje git repo değilse: rollback mekanizması (git checkpoint) çalışmayacağını söyle, kullanıcıya devam edip etmeyeceğini sor.
Dirty tree (uncommitted changes) varsa: kullanıcıya sor — "Önce commit'le, sonra başlayalım mı?" Yoksa skill devam eder ama rollback'in bu dirty state'i de geri alacağını uyar.
5. Config yükle
~/.claude/skills/prd-run/references/config-defaults.json oku. Dosya yoksa inline default'lara düş.
6. Argümanları parse et
- Pozisyonel: PRD dosya yolu (zorunlu,
--resume modu hariç). Yoksa docs/, prds/, specs/ dizinlerini listele ve sor.
--dry-run: parse + plan göster, kod/state değişikliği yapma.--resume: progress.md'den devam et.--force-tier: model tier uyarısını atla.--no-remote: Adım 8 (push/PR/review) tamamen atla.--force-remote: Sonuç ⚠️ KISMI / ⚠️ LLM-ONLY olsa bile Adım 8'i teklif et. Default: yalnız ✅ TAMAMLANDI'da teklif edilir.
7. prd-review kontrol + progress dosyası
-
prd-review hatırlatma (kök neden: müğlak PRD): Bu PRD için yakın tarihli bir prd-review kanıtı var mı (ör. docs/prd-review-*.md)? Yoksa kullanıcıya hatırlat (sert durdurma değil): "Bu PRD prd-review'den geçmemiş görünüyor — önce çalıştıralım mı, yoksa devam edeyim mi?" Kullanıcı devam derse geç.
-
Progress dosyası hazır mı: docs/prd-<feature>.progress.md yoksa oluştur (mini-prd zaten oluşturduysa atla). Bu dosya prd-guard hook'unu susturur (status: active işareti).
---
status: active
prd: {prd_dosya_yolu}
prd_hash: "{sha256_full}"
started: "{ISO}"
tier_acknowledged: null
tier_warning_at_runtime: false
phases: {}
---
## Faz Çıktıları
## Değişiklikler
| Tarih | Dosya | Ne değişti | AC |
|-------|-------|-----------|-----|
## Kararlar
## Dersler
PRD Parsing
Reference: Read references/prd-parsing.md for full parsing rules, heuristics, state schema, cycle detection pseudocode, and resume backward-compat defaults.
Ozet: PRD'den ## Faz/## Phase/## Bucket basliklarini cikar, AC'leri (- [ ] checkboxlar + AC section'lari) topla, dependency graph'i DFS ile cycle-check et. PRD SHA-256 hesapla (full 64 char, karsilastirma daima full hash). State init: docs/prd-verify/state.json. Resume'da eksik alanlar default'a alinir (abort etmez).
Dry-Run Modu
--dry-run varsa kod ve state'e DOKUNMA. Sadece şu çıktıyı ver ve dur:
PRD Parse Sonucu
================
Dosya: {prd_path} (sha256: {short_hash})
Fazlar: {N} ({virgülle phase_id listesi})
Toplam AC: {toplam}
Dependency cycle check: PASS
Faz Detayı:
{phase_id} — {ac_count} AC — bağımlılık: {deps_str}
...
Concrete Check Planı:
Test framework: {algılanan veya "⚠️ Algılanamadı — verification yalnız LLM ile yapılacak (false positive riski!)"}
Type checker: {algılanan}
Linter: {algılanan}
Build: {algılanan}
Grep assertions: {planlanan endpoint/schema kontrolleri sayısı}
Tahmini Maliyet (ROM):
Best case (sıfır retry):
Implementation: {N} × ~5k Sonnet ≈ {N × 0.015}$
Verification: {N} × ~10k Opus ≈ {N × 0.15}$
Toplam: ~${best_case}
Worst case (max retry × her faz):
{N × max_retries} round × ~30k mix ≈ ${worst_case}
Önerilen budget cap: {config.budget.max_session_usd}$
⚠️ Worst case > warn threshold ({warn_threshold}$) — devam mı?
Mevcut progress.md: {yok | var (status: {status}), devam edilecek faz: X}
Önceki run PRD hash uyumu: {match | mismatch: <details>}
Remote Sync Planı (Adım 8 — opt-in):
--no-remote yok → Sonuç ✅ ise push/PR onayı sorulacak
Branch: {current_branch}
Remote: {origin_url | "yok — Adım 8 atlanır"}
Onay noktaları: push, PR create (her biri ayrı), merge daima manuel
Auto-review: /review-project PR oluşturulduktan sonra otomatik çalışır
Gerçek run için: /prd-run {prd_path}
Worst case > budget.warn_threshold_usd ise kullanıcı onayı zorunlu. Worst case > budget.max_session_usd ise dry-run'da bile abort önerisi göster (/prd-run --force-budget ile override).
Subagent Dispatch Discipline (universal — tüm dispatch'ler için)
Orchestrator her subagent dispatch'inden sonra istisnasız aşağıdaki post-dispatch kontrolünü uygular. Bu Adım 2 (Implementation), Adım 4 (Verification), Adım 6.a (Fix Planner) ve Adım 6.b (Fix Implementer) için geçerlidir.
post_dispatch_check(response, expected_tier):
# 1. MODEL satırı parse
first_line = response.split('\n')[0].strip()
if not first_line.startswith("MODEL:"):
return ABORT("subagent prompt formatı bozuk — MODEL satırı yok")
model = first_line.replace("MODEL:", "").strip().lower()
# 2. Tier doğrulama
is_opus = "opus" in model
is_sonnet = "sonnet" in model
if expected_tier == "opus" and not is_opus:
if tier_acknowledged == "forced":
state["tier_warning_at_runtime"] = true # atomic write
log("⚠️ forced mode: expected opus, got {model}")
return CONTINUE
else:
return ABORT("tier downgrade: expected opus, got {model}. /model opus ile geç + --resume")
if expected_tier == "sonnet" and not is_sonnet:
# Sonnet beklerken Opus gelirse genellikle problem değil, ama logla
log("ℹ️ unexpected tier: expected sonnet, got {model} (continuing)")
# 3. Phase wall-clock kontrolü
elapsed = now() - progress_phases[phase_id]["wall_clock_started_at"]
if elapsed > config["runtime_checks"]["phase_wall_clock_seconds"]:
return TIMEOUT_ESCALATION(reason="phase wall-clock")
return CONTINUE
Expected tier eşleştirme tablosu:
| Dispatch Adımı | Subagent | Expected Tier |
|---|
| Adım 2 | domain-routed (Adım 2.0): inference/orchestrator/rag/mcp-developer → sonnet · devops-engineer → sonnet · prd-run-impl (default) → sonnet | {impl_tier} (routing'e göre dinamik) |
| Adım 4 | prd-run-verify | sonnet |
| Adım 6.a | prd-run-fix-planner | sonnet |
| Adım 6.b | prd-run-fix-impl | sonnet |
Adım 2'nin tier'ı sabit değil — Adım 2.0 routing tablosundan gelen {impl_tier}'e eşittir. post_dispatch_check bu dinamik değeri kullanır.
Önemli: ABORT kararı atomic state write ile yazılır, lock file temizlenir, kullanıcıya bildirilir. CONTINUE kararı normal akışa devam eder. TIMEOUT_ESCALATION Adım 7'ye atlar (context header ⏰ TIMEOUT).
Ana Loop
Her fazı sırayla işle (bağımlılıklara uyarak):
status: "done" veya "skipped" fazları atla.status: "blocked" fazla karşılaşırsan: kullanıcıya göster, dur (veya kullanıcı bu fazı --resume ile manuel "pending" yaptıysa devam et).status: "pending" fazlar için: bağımlılıkları "done" mu kontrol et. Değilse skip (sonraki bağımsız faza geç) veya bekle.
Adım 1: Git Checkpoint
Lock dosyası (concurrent run guard — geçici, EXIT'te otomatik silinir):
LOCK="/tmp/prd-run-$(git rev-parse --show-toplevel 2>/dev/null | md5 || echo 'noroot').lock"
if [ -f "$LOCK" ]; then cat "$LOCK"; echo "ABORT: existing run detected"; fi
echo "$$ $(date -Iseconds)" > "$LOCK"
trap 'rm -f "$LOCK"' EXIT INT TERM
Git checkpoint:
git rev-parse HEAD
Dönen hash'i docs/prd-<feature>.progress.md frontmatter'ına atomik yaz (tüm frontmatter oku → güncelle → yeniden yaz):
phases:
{phase_id}:
status: in_progress
checkpoint: "{git_sha}"
wall_clock_started_at: "{ISO}"
retries: 0
previous_strategy_hashes: []
Eğer proje git repo değilse: checkpoint = null, rollback Adım 7'de disable.
Adım 2: Implementation Dispatch [domain-routed → uzman agent, yoksa prd-run-impl]
2.0 — Domain Routing (dispatch'ten önce): Fazın PRD bölümü + AC listesini oku, fazın ağırlıklı domain'ini sınıfla ve implementer'ı seç. Mevcutsa o domain'in uzman agent'ı kodu yazar (kendi güncel bilgisi + Mühendislik Karar Doktrini ile); domain net değilse/karışıksa generic prd-run-impl'e düş.
| Fazın işi (AC/PRD'de baskın sinyal) | {impl_subagent} | {impl_tier} |
|---|
| Chat loop · tool-calling · tool execution · streaming/SSE · Messages API · chat UI · conversation state | inference-developer | sonnet |
| Multi-agent orchestration · routing-between-agents · hand-off · workflow · durable execution · saga · agent state | orchestrator-developer | sonnet |
| Retrieval · RAG · embedding · vector store · chunking · rerank · ingestion · grounding · KB search | rag-developer | sonnet |
MCP server/tool · protokol · transport · FastMCP · tool registry · mcp/server.py | mcp-developer | sonnet |
| Deploy · infra · IaC/Terraform · Docker · k8s/ECS · CI/CD pipeline · secrets · autoscaling · observability stack · DEPLOY.md | devops-engineer | sonnet |
| Domain net değil / generic CRUD · DB model · glue · küçük değişiklik / karışık (default) | prd-run-impl | sonnet |
Kurallar:
- Karışık/belirsiz → default
prd-run-impl. Uzman agent'a yalnız faz açıkça o domain'e aitse yönlen.
software-architect implementer DEĞİLDİR (kod yazmaz) — Adım 2'de kullanma. Faz saf mimari tasarımsa bu prd-run kapsamı dışıdır; operatöre flag'le.- Seçtiğin
{impl_subagent} + {impl_tier}'i 1 satırla kullanıcıya bildir (şeffaflık): örn. "P2 → inference-developer (opus): tool-calling loop".
- Tier notu: domain-routed implementation, routed agent'ın frontmatter model'inde çalışır (4 builder opus, devops sonnet). Bu, Adım 1'deki "impl=sonnet" varsayımını override eder;
post_dispatch_check expected_tier'ını {impl_tier}'e göre ayarla.
2.1 — ~/.claude/skills/prd-run/references/prompts/implementation-subagent.md oku, placeholder'ları doldur:
{phase_id}, {retry_count} (ilk turda 0){prd_phase_section} → PRD'den o fazın tam metni{ac_list} → numaralı AC listesi{system_md_sections} → SYSTEM.md varsa AC'lerdeki entity'leri grep et, ilgili bölümleri al; yoksa "SYSTEM.md bulunamadı, mevcut kod yapısını referans al"{prev_phase_summary} → tamamlanan fazların id + final commit hash + decisions.md'deki ilgili kararlar{repo_root} → pwd çıktısı{routed_domain_or_none} → seçilen domain (örn. "inference") veya generic ise "none"
Task tool çağrısı:
Task(
subagent_type="{impl_subagent}",
description="Implement {phase_id}",
prompt="<doldurulmuş template>"
)
post_dispatch_check çalıştır (Subagent Dispatch Discipline bölümüne bak — expected_tier={impl_tier}). Routed agent prompt'taki kontrat gereği ilk satırda MODEL: döndürür; tier bu satırla doğrulanır.
Ek başarı kriteri (post_dispatch_check CONTINUE dönerse):
docs/prd-verify/step-output-{phase_id}.md dosyası en az bir ## Retry {retry_count} bloğu içermeli- Git diff:
git diff HEAD --shortstat ile en az 1 değişen dosya VEYA git log {checkpoint}..HEAD --oneline | wc -l ile en az 1 yeni commit
Herhangi biri eksikse: implementation failure → Adım 5 escalation, mesaj: hangi kriter eksik.
Phase wall-clock: wall_clock_started_at ilk dispatch'te atomic write ile kaydedilir. Her post_dispatch_check'te kontrol edilir.
Adım 3: Concrete Checks
Reference: Read references/concrete-checks.md for full check templates, tool detection table, scope handling, timeout config, output JSON schema, grep assertion generation, and llm_only fallback rules before dispatching verify subagent.
Ozet: Proje kokunde test/lint/build araclarini auto-detect et (pytest, jest, mypy, tsc, ruff, eslint, go test/vet/build, cargo test/build/clippy, npm build, grep assertions). Her araci calistir, sonuçları docs/prd-verify/check-results-{phase_id}.json'a yaz (Adım 4 verification subagent'ı okuyacak; faz tamamlandığında progress.md'ye taşınıp silinir). Primary signal: exit_code. Arac bulunamazsa verification_mode: "llm_only" flag'i set et.
Adım 4: Verification Dispatch [prd-run-verify, Opus]
~/.claude/skills/prd-run/references/prompts/verification-subagent.md oku, doldur:
{ac_list} → numaralı AC listesi{check_results_json} → Adım 3 çıktısının içeriği{step_output_latest_retry} → step-output dosyasından son retry bloğu (önceki retry'lar context'e girmesin){changed_files_list} → step-output'taki "Değişen Dosyalar"
Task tool:
Task(
subagent_type="prd-run-verify",
description="Verify {phase_id} retry {retry_count}",
prompt="<doldurulmuş template>"
)
post_dispatch_check çalıştır (expected_tier=opus). ABORT dönerse run dur, TIMEOUT dönerse Adım 7'ye atla.
Çıktıyı parse et (post_dispatch_check CONTINUE sonrası):
- İlk satırı (MODEL) at, kalanı verification raporu olarak işle
- Her AC için
{ac_id: "PASS"|"FAIL", evidence: "file:line — ...", concrete_check_failed: bool, confidence: "HIGH"|"MEDIUM"|"LOW"|null}
- Summary:
{pass_count, fail_count, failed_ac_ids: [...], medium_confidence_ac_ids: [...]}
Adım 5: Karar
fail_count hesaplama (MED #6 fix — llm_only confidence dahil):
fail_count = count(ac.result == "FAIL")
+ count(ac.result == "PASS" AND ac.confidence == "LOW" AND verification_mode == "llm_only")
+ count(ac.result == "PASS" AND ac.confidence == "MEDIUM" AND verification_mode == "llm_only")
LOW confidence llm_only mode'da otomatik FAIL; MEDIUM da fail_count'a girer ama needs_human_review tag'iyle. Bu silent PASS riskini kapatır.
Tüm AC'ler güvenli PASS (fail_count == 0):
FAIL var (fail_count > 0):
docs/prd-<feature>.progress.md frontmatter: phases.{phase_id}.retries += 1 (atomic write).- Eğer tüm fail'ler MEDIUM-confidence llm_only: Adım 7'ye direkt atla, context header
🟡 LLM-ONLY NEEDS REVIEW — kullanıcıya manuel approve seçeneği sun (Adım 7 seçenek (e))
retries <= config.retry.max_retries_per_phase ise → Fix Routing (Adım 6).retries > max_retries_per_phase ise → Escalation (Adım 7).retries > config.retry.max_retries_hard_cap (default 9) ise → escalation seçeneklerinden "retry artır" da kapalı; sadece skip/rollback/abort sunulur.
Adım 6: Fix Routing
Verification çıktısındaki her başarısız AC için severity belirle:
Trivial kriterleri (TÜM kriterleri sağlamalı):
- Concrete check FAIL'i tek bir error tipinde (örn. yalnız mypy, yalnız bir test)
- Hata mesajı şunlardan birini içeriyor:
ImportError, ModuleNotFoundError, NameError, SyntaxError, unexpected status code, KeyError: 'config', undefined: <name> (Go), cannot find module (TS)
- Tek dosyada (verification raporundaki kanıtların hepsi aynı dosyada)
Complex = trivial değilse (yani aşağıdakilerden biri):
- Birden fazla error tipi
- Birden fazla dosya etkilenmiş
- Logic error (test PASS değil ama syntax/import OK)
- Security/auth ilişkili dil (verification raporunda "auth", "permission", "token", "crypto" geçiyor)
- SYSTEM.md uyumsuzluğu işareti
Routing kararı:
- Tüm fail'ler trivial → Fix Planner atlanır → doğrudan Adım 6.b: Fix Implementer Dispatch'e atla (Adım 6'nın başına dönme)
- Herhangi bir fail complex → Adım 6.a: Fix Planner Dispatch → ardından Adım 6.b: Fix Implementer Dispatch
Routing sonrası akış: Adım 6.b bittiğinde Adım 3: Concrete Checks'e dön. Adım 6'nın başına asla dönme.
Adım 6.a: Fix Planner Dispatch [prd-run-fix-planner, Opus]
~/.claude/skills/prd-run/references/prompts/fix-planner-subagent.md oku, doldur. {previous_fix_attempts} field'ı için: step-output'taki önceki retry bloklarından "fix stratejisi" özetlerini topla, ki aynı stratejiyi tekrar denenmesin.
Task tool:
Task(
subagent_type="prd-run-fix-planner",
description="Plan fix for {phase_id} retry {retry_count}",
prompt="<doldurulmuş template>"
)
post_dispatch_check çalıştır (expected_tier=opus). ABORT/TIMEOUT durumunda akışı uygun şekilde yönet.
Çıktı: her başarısız AC için root cause + fix stratejisi + risk seviyesi + STRATEGY_HASH.
Strategy hash dedup — sıra (HIGH #2 fix):
- Subagent her fix bloğunun sonunda
STRATEGY_HASH: <files_touched_sorted>:<line_ranges_sorted> döner
- Orchestrator parse eder ve
current_hash olarak tutar (henüz state'e push YOK)
- Karşılaştırma:
current_hash in progress.phases.{phase_id}.previous_strategy_hashes (progress.md frontmatter'dan oku)?
- EVET: Fix Planner aynı stratejiyi tekrar önerdi → push ETMEden direkt Adım 7'ye atla (
reason = "strategy repeat")
- HAYIR: Adım 6.b (Fix Implementer)'a geç. Implementer başarılı dönerse
current_hash Adım 6.b sonunda push edilir.
Bu sıralama "yeni hash kendiyle eşleşir" hatasını önler. Push yalnızca Implementer başarılı olduğunda yapılır — Planner çıktısı tek başına yetmez.
HIGH risk fix uyarısı: Eğer fix-planner herhangi bir AC için Risk: HIGH dönerse, kullanıcıya sor:
"AC-N için fix riski HIGH ('{risk_gerekçesi}'). Devam mı, skip mi, rollback mı?"
Adım 6.b: Fix Implementer Dispatch [prd-run-fix-impl, Sonnet]
Fix loop spot-fix işidir (sıfırdan implement değil) → dispatch target prd-run-fix-impl'de kalır (spot-fix kontratı + strategy-hash dedup loop korunur). Domain uzmanlığı hint olarak taşınır.
Input:
- Trivial route: verification raporundaki fail bloklarını direkt geç ("Şu AC'leri düzelt: ...")
- Complex route: fix-planner çıktısını geç
- Domain hint: Adım 2.0'da bu faz bir uzman agent'a routed ise (
{routed_domain} ≠ none), input'a ekle: "Domain: {routed_domain} — bu domain'in best-practice'ine uy." Böylece spot-fix domain-aware kalır.
Task tool:
Task(
subagent_type="prd-run-fix-impl",
description="Apply fixes for {phase_id} retry {retry_count}",
prompt="<input + retry_count + step-output path>"
)
post_dispatch_check çalıştır (expected_tier=sonnet).
Subagent step-output'a yeni ## Retry {retry_count} bloğu ekler (append mode).
STRATEGY_HASH push (HIGH #2 fix — sıra önemli):
Fix Implementer başarıyla döndükten sonra (bu adım sonunda) Fix Planner'ın bu round'da ürettiği STRATEGY_HASH'i docs/prd-<feature>.progress.md frontmatter phases.{phase_id}.previous_strategy_hashes listesine atomik olarak ekle. Push Concrete Checks'e geçmeden önce yapılır.
Karşılaştırma Adım 6.a'da yapılmıştır (hash henüz push edilmemişken). Match yoksa buraya gelinir. Match varsa zaten Adım 7'ye atlanmıştır.
Tamamlanınca → Adım 3: Concrete Checks'e geri dön (aynı faz için yeni round).
Adım 7: Escalation
Reference: Read references/escalation.md for full escalation flow: context headers (RETRY EXHAUSTED, STRATEGY REPEAT, TIMEOUT, IMPL FAILED, LLM-ONLY NEEDS REVIEW, TIER DOWNGRADE), user prompt template, option constraints, manual review flow, and each option's (a-e) state transitions.
Ozet: Kullaniciya basarisiz AC'leri + root cause ozetini goster, secenekleri sun: (a) retry artir, (b) skip (transitif BFS kapanim), (c) rollback (arsivle + git reset), (d) abort, (e) manuel review (sadece LLM-ONLY). Hard cap'e ulasildiysa (a) listelenmez, git repo yoksa (c) devre disi.
Adım 8: Remote Sync (opt-in, açık onay zorunlu — Rule §6)
Bu adım Golden Rule §6'yı uygular: Her remote git işlemi (push, gh pr create, gh pr merge) için ayrı ve açık kullanıcı onayı gerekir. Local commit'ler otonom, remote işlemler ASLA otonom değildir. §1 ("yapabiliyorsan sorma") bu adımda devre dışı.
Tetikleme koşulu
Adım 8 yalnız şu durumlarda teklif edilir (kullanıcıya sorulur):
--no-remote flag yok- Final sonuç ✅ TAMAMLANDI (tüm fazlar
done) VEYA --force-remote verilmiş
Aksi halde (KISMI / LLM-ONLY / ABORT ve --force-remote yok): Adım 8 sessizce atlanır, sadece Rapor yazılır. Kullanıcıya kısa bilgi: "Remote sync atlandı (sonuç tam yeşil değil). Zorlamak için --resume --force-remote."
Pre-flight (Adım 8 başında)
git rev-parse --git-dir >/dev/null 2>&1 || ABORT_REMOTE "not a git repo"
git rev-parse --abbrev-ref HEAD
git remote get-url origin 2>/dev/null || ABORT_REMOTE "no origin remote"
git log origin/{branch}..HEAD --oneline 2>/dev/null
git status --porcelain
Kontroller:
- Branch
main/master mi? → Abort: "Main branch'e direkt push yasak. Önce feature branch'e geç."
- Origin yok mu? → Sadece local rapor yaz, Adım 8 atla
- Uncommitted change var mı? → Kullanıcıya bildir, "commit'le ve
--resume --force-remote ile devam et" mesajıyla Adım 8 atla
- Push edilecek commit 0 mı? → Skip 8.a–8.b, doğrudan 8.c'ye geç (mevcut PR varsa)
- gh CLI yüklü mü? (
gh --version) → Yoksa 8.c–8.f atla, sadece push yapılabilir; kullanıcıya bildir
Adım 8.a: Push Approval Prompt
Kullanıcıya göster:
Remote Sync — Push Onayı (Rule §6)
==================================
Branch: {current_branch}
Remote: origin ({remote_url})
Commit sayısı: {N} commit push edilecek
Son 5 commit:
{git log origin/{branch}..HEAD --oneline | head -5}
Değişen dosya: {N} dosya, +{insertions} −{deletions}
Komut: git push -u origin {current_branch}
Onay? (y / n / show-diff)
Yanıt:
y / yes / evet / push → 8.b'ye geçshow-diff → git diff origin/{branch}..HEAD --stat göster, tekrar sor- Diğer her şey → Adım 8 abort, raporda "user declined push" notu, dur
Adım 8.b: Push
git push -u origin {current_branch}
Çıktıyı raporla. Push fail olursa (rejected, non-fast-forward vb.):
--force-with-lease ASLA otomatik teklif edilme — kullanıcıya hata göster, manuel çözmesini iste, Adım 8 abort
Adım 8.c: PR Create Approval Prompt
Mevcut PR var mı kontrol et:
gh pr list --head {current_branch} --json number,url,state --jq '.[0]'
Var ve OPEN ise: Adım 8.d skip, doğrudan 8.e'ye (var olan PR'a review yap).
Yok veya CLOSED ise: PR title/body preview üret:
Kullanıcıya göster:
Remote Sync — PR Create Onayı (Rule §6)
========================================
Title: {generated_title}
Base: main
Head: {current_branch}
Body preview:
{body_first_15_lines}
...
Komut: gh pr create --title "..." --body "..."
Onay? (y / n / edit-title / edit-body / show-body)
Yanıt:
y → 8.d'ye geçedit-title → kullanıcıdan yeni title al, tekrar gösteredit-body → kullanıcı yeni body verir (veya path), tekrar göstershow-body → tam body'yi göster, tekrar sorn → Adım 8 burada durur, push yapıldı PR yapılmadı, raporda not düşülür
Adım 8.d: PR Create
gh pr create --title "{title}" --body "$(cat <<'EOF'
{body}
EOF
)"
Dönen URL ve PR number'ı yakala. Hata olursa kullanıcıya göster, Adım 8 abort.
Adım 8.e: Auto-Run /review-project
PR oluşturulduktan sonra otomatik (onay aranmaz — read-only operasyon):
Task(
subagent_type="general-purpose",
description="Run review-project on PR #{N}",
prompt="""
Invoke the /review-project skill on PR #{pr_number} in the current repository.
PRD path: {prd_path}
Feature slug: {feature_slug_from_prd}
Run review-only mode (NOT fix mode). Produce findings table.
Output: save full report to docs/prd-verify/pr-review-{date}.md
Return: 5-line summary (P0/P1/P2 finding counts + verdict).
"""
)
Not: /review-project PRD + AC + L107/L108/L109/L081/L114 disiplin kurallarını kontrol eder. Verification subagent'ın görmediği cross-phase tutarlılığı yakalar.
Adım 8.f: Review Findings — Karar Noktası
Review tamamlandığında kullanıcıya göster:
Remote Sync — PR Review Bulguları
==================================
PR: {pr_url}
Rapor: docs/prd-verify/pr-review-{date}.md
Bulgular:
P0 (blocker): {N} bulgu
P1 (önemli): {N} bulgu
P2 (öneri): {N} bulgu
{Eğer P0 > 0:}
⚠️ P0 BLOCKER bulgusu var. Merge ETMEDEN ÖNCE çözülmeli.
Ne yapalım?
(a) PR'ı şu haliyle bırak — sen manuel review/merge edersin
(b) review-project'i `--fix` modunda tekrar çağır (P1+P2 mekanik fix'leri)
(c) Yeni faz olarak `/prd-run --resume` ile bulguları AC haline getir
(a) default — Adım 8 burada biter. Rapor "PR oluşturuldu, manuel merge bekleniyor" der.
(b) /review-project {pr_number} --fix çağırılır (subagent içinde, per-fix onay zaten o skill içinde var).
(c) İleri kullanım — bulguları yeni PRD fazına dönüştürmek manuel iş, kısa rehber gösterilir, Adım 8 biter.
Adım 8.g: Merge — ASLA OTONOM
/prd-run hiçbir koşulda gh pr merge çalıştırmaz. Merge daima kullanıcının manuel kararıdır.
Rapora şu satır eklenir:
Merge: Manuel — kullanıcı GitHub UI'dan veya `gh pr merge {N}` ile yapacak.
Adım 8 State Tracking
docs/prd-<feature>.progress.md frontmatter → remote_sync alanı (atomic write):
remote_sync:
attempted_at: "{ISO}"
push: {status: "done|declined|skipped|failed", sha: "{head_sha}"}
pr: {status: "created|existing|declined|skipped|failed", number: N, url: "..."}
review: {status: "done|skipped|failed", report: "docs/prd-review-{date}.md", p0: N, p1: N, p2: N}
merge: {status: manual_pending}
Rapor
Tüm fazlar done, skipped veya blocked olduğunda (ve Adım 8 — varsa — tamamlandığında) docs/prd-<feature>.progress.md'ye aşağıdaki özet bölümünü append et:
# PRD Run Report — {feature_name}
**PRD:** {prd_path} (sha256: {short_hash})
**Tarih:** {start} → {end}
**Süre:** {duration}
**Tier:** {tier_acknowledged} {⚠️ "(runtime downgrade detected)" if tier_warning_at_runtime}
**Budget:** {usd_spent_total}$ / {max_session_usd}$ ({token_total} tokens)
**Sonuç:** ✅ TAMAMLANDI | ⚠️ KISMI ({N} faz blocked/skipped) | ⚠️ LLM-ONLY ({N} faz concrete check'siz) | ❌ ABORT
{IF herhangi bir faz verification_mode=llm_only:
⚠️ **Uyarı:** {N} AC concrete check olmadan yalnız LLM analiziyle onaylandı.
Manuel doğrulama yapmadan production'a alma. Liste: {list}
}
## Faz Özeti
| Faz | Durum | Retry | AC | Concrete Checks | Verify Mode | Son Commit |
|-----|-------|-------|-----|-----------------|-------------|------------|
| {phase_id} | ✅/⛔/⏭ | {N} | {pass}/{total} | {tool_summary} | hybrid/llm_only | {hash} |
## Blocked/Skipped Fazlar
### {phase_id} — BLOCKED/SKIPPED
**Neden:** {reason}
**Son root cause:** {last_fix_planner_summary veya "N/A"}
**Kullanıcı kararı:** {escalation_choice}
**Önerilen sonraki adım:** {örn. "manuel fix sonrası /prd-run --resume"}
## Decision Log
(bkz. docs/prd-verify/decisions.md)
## Remote Sync
{IF state.remote_sync yoksa:}
Atlandı — `--no-remote` veya sonuç ✅ değil.
{IF state.remote_sync varsa:}
| İşlem | Durum | Detay |
|-------|-------|-------|
| Push | {push.status} | {push.sha veya '—'} |
| PR | {pr.status} | {pr.url veya '—'} |
| Review (`/review-project`) | {review.status} | P0:{N} P1:{N} P2:{N} — {review.report} |
| Merge | Manuel (otonom yapılmaz) | Kullanıcı GitHub UI'dan onaylayacak |
{IF review.p0 > 0:}
⚠️ **P0 blocker bulgusu:** {N} adet. Merge'den önce çöz. Detay: {review.report}
## Kalıcı Dosyalar
- `docs/prd-<feature>.progress.md` (tek kalıcı dosya — frontmatter: faz durumu + remote sync; body: faz çıktıları, değişiklikler, kararlar, run özeti)
- `docs/prd-review-{date}.md` (Adım 8 çalıştıysa)
**Geçici dosyalar** (faz tamamlandığında silinir):
- `docs/prd-verify/step-output-{phase}.md` — prd-run-impl subagent çıktısı, progress.md'ye taşınır
- `docs/prd-verify/check-results-{phase}.json` — concrete check sonuçları, progress.md'ye taşınır
Tamamlanma — progress dosyasını kapat
Final sonuç ✅ TAMAMLANDI (tüm fazlar done + verify geçti) ise progress.md frontmatter'ı güncelle:
status: done
Böylece prd-guard hook tekrar nöbete döner (status: active olmadığı için). KISMI / LLM-ONLY / ABORT sonucunda status: paused yap — iş bitmedi, /prd-run --resume <prd-path> ile devam edilebilir.
Kullanıcıya bildir: "Run tamamlandı. Rapor: docs/prd-verify/run-report-{date}.md"
Dosya boyutu kontrolü: SKILL.md sonunda — şu uyarıyı ekle:
Bu skill SKILL.md gövdesi 500 satıra yaklaşırsa progressive disclosure için bölümleri references/ altına taşı.
