| name | forge |
| description | Tam otonom gelistirme dongusu — analysis, sprint, parallel tasks, PR/review loop, merge, summary. Focus mode ile belirli alanlara odaklanir. Kendi repeat'i dahil. Triggers: forge, forge all, tam dongü, full cycle. |
| argument-hint | [N=1] [proje] [-focus] |
/forge — Full Development Cycle
Projeyi analiz et, sprint plan, paralel task'lari calistir, PR/review/merge dongusu, ozet ve dersler cikar. Tek komutla uçtan uca.
Kullanim
/forge # tek run, CWD projesi, tüm kategoriler
/forge 3 # 3 run, CWD projesi
/forge CoinHQ # tek run, CoinHQ
/forge 5 CoinHQ # 5 run, CoinHQ
/forge all # tek run, tum projeler (projects.json)
/forge 2 all # 2 run, tum projeler
/forge choose # proje seçim menüsü — listeden seç, müsaitlik göster, forge et
# Unattended mode:
/forge auto # CWD, tüm kategoriler, soru sormadan
/forge auto 3 CoinHQ -backend # 3 run, CoinHQ, backend focus, unattended
/forge auto all # Tüm projeler, unattended
# Focus modları (-ile ayrilir, birden fazla verilebilir):
/forge -optimize # Performans ve teknik borç
/forge -feature # Yeni özellik geliştirme
/forge -backend # Sadece backend/API
/forge -frontend # Sadece UI/UX
/forge -security # Güvenlik açıkları ve hardening
/forge -test # Test coverage artırma
/forge -refactor # Kod temizliği ve yeniden yapılandırma
/forge -docs # Dokümantasyon
/forge 3 CoinHQ -backend -security # Kombinasyon: 3 run, iki focus
/forge all -frontend # Tüm projeler, sadece frontend
# Granularity modlari:
/forge -quick # Max 3 task, verify atla, hizli cycle
/forge -deep # XL task'lar dahil, tum verify calistir, detayli analiz
/forge CoinHQ -quick -security # Hizli guvenlik taramasi
Arguman cozumu
| Input | N | Proje | Focus |
|---|
/forge | 1 | CWD | tümü |
/forge 3 | 3 | CWD | tümü |
/forge CoinHQ | 1 | CoinHQ | tümü |
/forge 5 CoinHQ | 5 | CoinHQ | tümü |
/forge all | 1 | tüm projeler | tümü |
/forge 2 all | 2 | tüm projeler | tümü |
/forge -backend | 1 | CWD | backend |
/forge 3 CoinHQ -frontend -test | 3 | CoinHQ | frontend + test |
/forge choose | — | seçilen projeler | tümü |
/forge choose -backend | — | seçilen projeler | backend |
/forge -quick | 1 | CWD | tümü (max 3 task) |
/forge -deep | 1 | CWD | tümü (XL dahil) |
/forge auto | 1 | CWD | tümü (unattended) |
/forge auto 3 CoinHQ | 3 | CoinHQ | tümü (unattended) |
/forge auto all | 1 | tüm projeler (unattended) | |
Focus parsing: - ile başlayan her token focus flag'idir. Sayı token → N, bilinen proje adı → proje, geri kalan -xxx → focus listesi.
Focus Modları
| Flag | Kapsam | Phase 1'e etki | Phase 2'ye etki |
|---|
-optimize | Performans, cache, DB query, bundle size | Perf + Arch analizi | Task önceliği: hız metrikleri |
-feature | Yeni özellik, PRD'deki backlog | Growth + Biz analizi | Yeni feature task'ları |
-backend | API, DB, server logic, auth | Data + Arch + Sec analizi | Backend-only task'lar |
-frontend | UI, UX, responsive, animasyon | UI/UX + A11y + Content analizi | Frontend-only task'lar |
-security | Auth güvenliği, injection, secrets, deps | Sec analizi (Opus ile) | Security task'ları önce |
-test | Unit, widget, integration, e2e testler | Tüm kategorilerde test gaps | Test task'ları |
-refactor | Dead code, duplication, complexity | Arch + Perf analizi | Refactor task'ları |
-docs | README, API docs, in-code comments | Content analizi | Docs task'ları |
Kombinasyon: Birden fazla focus verilirse sadece o alanların kesişim task'ları seçilir.
Granularity Modlari
| Flag | Phase 1 | Phase 2 | Phase 4 |
|---|
-quick | Hizli scan (tek agent, 5dk max) | Max 3 task, sadece P0/P1 | Verify atla, review hizli |
| (default) | Standart (5 lead paralel) | Tum P0-P2, SP <= 35/sprint | Verify + review |
-deep | Detayli (12 lead + research) | Tum P0-P3, XL dahil | Verify + review + re-verify after merge |
Focus yok: Tüm kategoriler analiz edilir, öncelik metriklere göre doğal sıralanır.
Focus başlığı:
━━ Forge Run [1/3] — CoinHQ [-backend -security] ━━━━━━━━
Proje tespiti (CWD):
- CLAUDE.md veya .claude/index.md oku → proje adi
- Yoksa klasor adi kullan
projects.json'dan path dogrula
all modu:
~/Projects/ClaudeHQ/projects.json'dan aktif projeleri oku- Her projeyi paralel forge et — her proje bağımsız background agent olarak başlatılır (max 12 concurrent)
- Aktif session tespiti yapilir — kullanicinin baska terminalde calistigi projeler atlanir (bkz. "Aktif Session Tespiti" bolumu)
forge choose — Proje Seçim Modu
/forge choose çalıştırıldığında:
Adım 1 — Proje Listesi:
projects.json'dan projeleri oku, numaralı liste olarak göster:
━━ Forge — Proje Seç ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Proje Durum
─── ────────────────── ──────────────────────────────
1 ar-research ✅ boşta (session: 4sa önce)
2 ByteCraftHQ ✅ boşta (git: clean)
3 CoinHQ ⚠️ belirsiz (session: 18dk önce)
4 Gardirop ⏭ meşgul (forge.lock + dirty)
5 KnightOnlineAI ✅ boşta
6 ProjeBirlik ✅ boşta
7 trading-bot ✅ boşta
8 transcriptr ✅ boşta
9 VocabLearningApp ✅ boşta
10 Viralyze ✅ boşta
...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Seçim (örn: 1,3,5-8 veya hepsi için "all", iptal "0"):
Durum sütunu Aktif Session Tespiti'nden gelir — proje listesi gösterilmeden önce tüm projeler için müsaitlik skorları hesaplanır:
✅ boşta — skor 0⚠️ belirsiz — skor 1 (seçilebilir ama uyarı gösterilir)⏭ meşgul — skor ≥ 2 (seçilemez, gri gösterilir)
Adım 2 — Seçim Parse:
| Giriş | Anlamı |
|---|
1,3,5 | 1, 3, 5 numaralı projeler |
2-6 | 2'den 6'ya kadar |
1,4-7,9 | Kombine |
all | Tüm boşta projeler (meşgullar hariç) |
0 | İptal |
Adım 3 — Onay:
Seçilen projeler: ar-research, CoinHQ, transcriptr
⚠️ CoinHQ belirsiz durumda — dahil et? [Y/n]:
Forge edilecek: ar-research, CoinHQ (onaylandı), transcriptr
Focus? (boş bırak = tümü, ya da -backend -security gibi gir):
Adım 4 — Forge:
Seçilen projeleri forge all --only ile paralel olarak forge et. Bundan sonra normal forge all akışı geçerlidir.
Preset Menüsü
Argüman verilmeden /forge çalıştırıldığında aşağıdaki menüyü göster ve kullanıcının seçim yapmasını bekle:
━━ Forge — Focus Seç ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1) Quick Fix -security -optimize
2) Feature Sprint -feature
3) Full Cycle (tüm kategoriler)
4) Deep Clean -refactor -test
5) Backend Hardening -backend -security
6) Frontend Polish -frontend -docs
7) Custom… argüman gir (örn: -backend -test)
0) İptal
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Seçim (1-7, 0=iptal):
Kullanıcı seçim yapınca:
- 1-6: Focus flag'lerini uygula, proje = CWD, N = 1, Phase 0'a geç
- 7: "Focus flag'leri gir:" diye sor, parse et, Phase 0'a geç
- 0: İptal et, dur
Not: all modu ve run sayısı argümanla verilir — /forge all, /forge 3, /forge 2 all -backend gibi. Menü sadece focus seçimi içindir.
Argüman verilmişse (/forge 3 CoinHQ -backend gibi) menü gösterilmez, direkt Phase 0'a geç.
Forge Run Akisi
Her run 7 fazdan olusur:
━━ Forge Run [1/N] — CoinHQ ━━━━━━━━━━━━━━━━
Phase 0: Pre-flight Checks
Phase 1: Analysis
Phase 2: Sprint Plan
Phase 3: Sprint Creation
Phase 4: Parallel Task Execution
Phase 5: Summary & Lessons
Phase 7: Forge Analysis (otomatik — metrik + optimizasyon)
Phase 6: Handoff to next run
━━ Forge Run [1/N] Complete ✓ ━━━━━━━━━━━━━━━
Jira Mode Detection
Forge, calistigi projeyi ~/Projects/ClaudeHQ/projects.json uzerinden bulur ve jira alanina bakar:
jira alani | Mode | Davranis |
|---|
Set (orn. "CHQ") | Jira mode | Atlassian MCP uzerinden epic/task acilir, transition'lar yapilir |
null/false/yok | Jira-less mode | Tasklar forge/sprints/sprint-{N}.json icinde local ID ile (T-001, T-002...) tutulur, Jira cagrisi yapilmaz |
Ayni pipeline; sadece gorev kayit yeri farkli. Pre-flight check'leri, Phase 2/3 olusturma, Phase 4 status label'lari ve Phase 5 ozet hepsi mod'a gore uyarlanir. Bu karar Phase 0'in basinda alinir ve sonraki tum fazlara aktarilir.
Phase 0 — Pre-flight Checks
Run baslamadan once tum bagimliliklari kontrol et. Biri bile fail ederse durur ve kullaniciya bildirir.
all modunda ilk is: Aktif Session Tespiti — forge baslamadan once hangi projelerin atlanacagini belirle (detay asagida).
━━ Pre-flight Checks ━━━━━━━━━━━━━━━━━━
[✓] Git — clean working tree, on main
[✓] GitHub CLI — gh auth status OK
[✓] Jira — Jira mode'da MCP+KEY gecerli, Jira-less mode'da skip
[✓] Flutter/Node — proje stack'ine gore build tool mevcut
[✓] Secrets — secrets.env yuklu, gerekli key'ler var
[✓] Disk — min 1GB bos alan
[✓] Agent Models — Sonnet (kod) + Opus (review) erisilebilir
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
| Kontrol | Nasil | Fail durumu |
|---|
| Git clean | git status --porcelain bos mu | "Uncommitted changes var. Commit veya stash et." |
| Git branch | git branch --show-current = main/master | "main branch'te degilsin. git checkout main yap." |
| gh auth | gh auth status | "GitHub CLI giris yapmamis. gh auth login calistir." |
| Jira MCP (Jira mode'da) | Atlassian MCP tool'larini cagir (getVisibleJiraProjects) | "Jira baglantisi yok. MCP kontrol et." |
| Jira KEY (Jira mode'da) | Proje KEY'i Jira'da var mi | "Proje KEY '{KEY}' Jira'da bulunamadi." |
| Build tool | pubspec.yaml → flutter, package.json → node, vb. | "Flutter/Node bulunamadi. Yukle." |
| Secrets | source secrets.env, gerekli key'ler set mi | "SUPABASE_URL eksik. secrets.env kontrol et." |
| Disk | df -h . kontrol | "Disk alani yetersiz." |
| Models | Sonnet + Opus API erisilebilir mi (basit test) | "Model erisimi yok. API key kontrol et." |
Jira-less mode'da Jira MCP/KEY satirlari skip edilir; geri kalan kontroller aynen calisir.
Tum kontroller gecerse:
✅ Pre-flight OK — forge basliyor
Project Index (Pre-flight sonu):
Pre-flight geçtikten hemen sonra, Phase 1 başlamadan projeyi jCodeMunch ile indexle:
[CoinHQ] indexing…
mcp__jcodemunch__index_repo çağır — path: {proje_path}. Bu sayede Phase 1 analizinde ve task agentlarında sembol araması hızlı olur. Index zaten güncel bile olsa yenile (değişmiş dosyaları yakalar).
State Manifest (forge/state-manifest.json)
Forge her phase geçişinde state'ini diske yazar. Crash/timeout sonrası buradan devam eder.
{
"run": 1,
"total_runs": 3,
"project": "CoinHQ",
"focus": ["-backend", "-security"],
"current_phase": 4,
"current_sprint": 2,
"current_wave": 1,
"completed_tasks": ["KEY-101", "KEY-102", "KEY-103"],
"failed_tasks": ["KEY-104"],
"in_progress_tasks": ["KEY-105"],
"started_at": "2026-04-14T10:00:00Z",
"last_checkpoint": "2026-04-14T11:30:00Z"
}
Recovery akışı:
- Forge başlarken
forge/state-manifest.json kontrol et
- Varsa ve
last_checkpoint 1 saatten yeniyse:
⚠️ Önceki forge run kaldığı yerden devam edebilir:
Run 1/3, Phase 4, Sprint 2, Wave 1
Tamamlanan: 3 task, Başarısız: 1, Devam eden: 1
1) Devam et (kaldığı yerden)
2) Baştan başla (state sıfırla)
3) İptal
- "Devam et" seçilirse: completed_tasks atla, in_progress_tasks'tan devam et
- Her phase geçişinde state-manifest güncelle
Phase 1 — Project Analysis
Focus varsa /project-analysis {focus_flags} olarak calistir (ornek: /project-analysis -backend -security). Focus yoksa sadece /project-analysis. Interaktif sorulari otomatik cevapla:
| Soru | Otomatik cevap |
|---|
| compact onerisi | 2 (gec) |
| Agent atama modu | 1 (Lead Orchestrator) |
| Brief olustur mu | Y (evet) |
| Agent kullanilabilirlik | 4 (tum alternatifleri uygula) |
Analiz tamamlaninca analysis/MASTER_ANALYSIS.md olusur.
Önceki kararlar: forge/DECISIONS.md dosyasını oku — mevcut kararlarla çelişme.
Sonraki run'larda: Onceki run'in lessons_learned dosyasini analysis'e feed et:
Bu projenin onceki forge run'inda su dersler cikarildi:
[lessons_learned.md icerigi]
Bunlari goz onunde bulundurarak analiz et.
Phase 2 — Sprint Plan (Lead kararlari otomatik kabul)
/sprint-plan skill'ini calistir.
Lead'lerin tum onerilerini otomatik kabul et — soru sormadan:
- Task oncelikleri → kabul
- Sprint sirasi → kabul
- Efor tahminleri → kabul
- Gorev kaydi → Jira mode'da Jira'da epic/task ac, Jira-less mode'da
forge/sprints/sprint-{N}.json'a yaz
Cikti: analysis/SPRINT_PLAN.md + (Jira mode → Jira'da epic/task'lar) veya (Jira-less mode → forge/sprints/sprint-1.json)
Phase 3 — Sprint Creation
Sprint plan'daki task'lari mod'a gore olustur (Phase 2'de yapilmadiysa):
Jira mode:
- Epic olustur
- Task'lari olustur (summary, description, priority, story points)
- Sprint 1'i aktif yap
Jira-less mode:
forge/sprints/sprint-{N}.json dosyasina yaz:
{
"sprint": 1,
"epic": "Security & Critical Fixes",
"tasks": [
{"id": "T-001", "title": "...", "priority": "P0", "sp": 3, "status": "todo", "wave": 1, "depends_on": []},
{"id": "T-002", "title": "...", "priority": "P0", "sp": 5, "status": "todo", "wave": 1, "depends_on": []}
],
"started_at": null,
"completed_at": null
}
- Task ID semasi:
T-001, T-002... — sprint geneli artarak (her run global olarak devam eder, tekrar 1'den baslamaz)
- Sprint 1'i aktif yap (
started_at set et)
Phase 4 — Parallel Task Execution
Sprint sprint ilerle (Sprint 1 bitince Sprint 2, vs.):
━━ Sprint 1/3 — Security & Critical Fixes ━━━
Task 1: [KEY-101] ▶ branch → code → PR → review → merge ✓
Task 2: [KEY-102] ▶ branch → code → PR → review → fix → review → merge ✓
Task 3: [KEY-103] ▶ branch → code → PR → review → merge ✓
━━ Sprint 1 Complete ━━━━━━━━━━━━━━━━━━━━━━━━
Wave-based execution (SPRINT_PLAN.md'deki depends_on'a göre):
- SPRINT_PLAN.md'den wave'leri parse et
- Wave 1 task'larını paralel başlat
- Wave 1 tamamlanınca Wave 2'yi başlat
- Her wave içi max 5 concurrent task
Sprint baslamadan once dispatch tablosu goster:
━━ Sprint 1 — Task Pipeline ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Task Wave Agent Model Gorev
────────── ──── ────── ─────────── ──────────
KEY-101 W1 Coder Sonnet 4.6 Branch + code + PR
KEY-102 W1 Coder Sonnet 4.6 Branch + code + PR
KEY-104 W2 Coder Sonnet 4.6 Branch + code + PR (after 101)
...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Agent 1-Kelime Durum Etiketi:
Her agent (Coder ve Reviewer) aktif olarak çalışırken her adım başında tek satır durum etiketi yazar:
[KEY-101] branching
[KEY-101] coding
[KEY-101] testing
[KEY-101] pr
[KEY-101] reviewing
[KEY-101] fixing
[KEY-101] merging
[KEY-101] done ✓
Format: [{TASK_ID}] {eylem} — TASK_ID, Jira mode'da Jira KEY (orn. KEY-101), Jira-less mode'da local ID (orn. T-001). Eylem tam olarak 1 kelime. Proje forge agentı için:
[CoinHQ] indexing
[CoinHQ] analyzing
[CoinHQ] planning
[CoinHQ] coding
[CoinHQ] reviewing
[CoinHQ] done ✓
Bu etiketler her adım başında yazılır (bitmeden önce) — bu sayede paralel çalışan agentların durumu gerçek zamanlı izlenebilir.
Her task icin {TASK_ID} ile (Jira mode → Jira KEY, Jira-less mode → T-NNN) pipeline'i calistir. Jira mode'da /jira-start-new-task skill'i kullanilabilir; Jira-less mode'da pipeline dogrudan agent ile koşturulur:
- Branch olustur —
feat/{task-id-lower}-xxx (orn. feat/key-101-xxx veya feat/t-001-xxx)
- Kod yaz — Sonnet model (worktree izolasyonu)
- PR ac —
gh pr create
- Review — Opus model
- Sorun varsa → Fix Loop:
review fail → fix → commit → push → re-review
Max 5 iterasyon. 5'te cozulmediyse:
- PR'a yorum birak: "Forge: max retry reached, needs manual review"
- Sonraki task'a gec
- Merge —
gh pr merge --squash --delete-branch
- Verify — SPRINT_PLAN.md'deki verify komutunu çalıştır
- Pass → devam
- Fail → fix loop'a geri dön (max 3 retry)
- 3 retry sonra fail → PR'a yorum bırak, sonraki task'a geç
- Status update — Jira mode'da
transitionJiraIssue (Done); Jira-less mode'da forge/sprints/sprint-{N}.json icinde task'in status'ünü "done" yap, completed_at ekle
Paralel calisma:
- Ayni sprint icerisindeki task'lar wave sirasina gore paralel calisir (max 5 concurrent per wave)
- Farkli sprint'ler sirayla calisir
- Dosya lock sistemi cakismayi onler (
.jira-state/file-locks/)
Event Journal (forge/event-log.jsonl):
Her onemli adimda bir satir append edilir:
{"ts":"2026-04-14T10:30:00Z","run":1,"sprint":1,"wave":1,"task":"KEY-101","event":"branch_created","detail":"feat/key-101-rate-limiting"}
{"ts":"2026-04-14T10:35:00Z","run":1,"sprint":1,"wave":1,"task":"KEY-101","event":"code_complete","detail":"3 files changed"}
{"ts":"2026-04-14T10:36:00Z","run":1,"sprint":1,"wave":1,"task":"KEY-101","event":"pr_created","detail":"#42"}
{"ts":"2026-04-14T10:40:00Z","run":1,"sprint":1,"wave":1,"task":"KEY-101","event":"review_pass","detail":"score 9/10"}
{"ts":"2026-04-14T10:41:00Z","run":1,"sprint":1,"wave":1,"task":"KEY-101","event":"verify_pass","detail":"curl returned 429"}
{"ts":"2026-04-14T10:42:00Z","run":1,"sprint":1,"wave":1,"task":"KEY-101","event":"merged","detail":"squash into main"}
Event types: branch_created, code_complete, test_pass, test_fail, pr_created, review_pass, review_fail, fix_attempt, verify_pass, verify_fail, merged, skipped, error
Phase 5 — Summary & Lessons Learned
Tum sprint'ler tamamlaninca:
-
Ozet raporu olustur — forge/run-{N}-summary.md:
# Forge Run N Summary — CoinHQ
## Stats
- Sprints completed: 3/3
- Tasks completed: 12/14
- Tasks failed: 2 (manual review needed)
- Total commits: 34
- PRs merged: 12
## Agent Execution
- Coder agents: Sonnet 4.6 (12 tasks)
- Reviewer agents: Opus 4.6 (12 reviews, 3 fix loops)
- Analysis: Sonnet 4.6 (5 leads) + Opus 4.6 (master)
- Total agent time: 45m
## Completed Tasks
- [KEY-101] Add rate limiting to API endpoints ✓
- [KEY-102] Fix SQL injection in search ✓
...
## Failed Tasks
- [KEY-113] Migrate auth to OAuth2 — max retry reached
- [KEY-114] Add E2E tests — flutter test timeout
## Changes by Category
- Security: 4 tasks
- Performance: 3 tasks
- Architecture: 2 tasks
- UI/UX: 3 tasks
-
Lessons learned — forge/run-{N}-lessons.md:
# Lessons Learned — Run N
## What worked
- Worktree isolation prevented merge conflicts
- Security fixes were straightforward
## What failed and why
- OAuth2 migration too complex for single task — should be split
- E2E tests need running emulator — skip in CI-only env
## Recommendations for next run
- Split large tasks (XL) into smaller subtasks
- Add emulator setup to prerequisites
- Focus on test coverage gaps
Phase 5.5 — Per-Run Scoring (Otomatik, Atlanamaz)
Her run sonunda 0-10 arası puanlama zorunlu. Phase 5 bittikten hemen sonra, Phase 7'den önce çalışır. Skip edilemez. Çıktı: forge/run-{N}-score.md.
Ne zaman çalışır: Her run sonunda (run sayısına bakmaksızın). Auto/quick/deep tüm modlarda aktif.
Skorlama kategorileri (her biri 0-10):
| Kategori | Ölçüt | Nasıl ölçülür |
|---|
| Build | Bundle size, type check, build time | npm run build / proje build komutu, exit code + bundle size |
| GDD Compliance | GDD.md / PRD'deki maddelerle birebir uyum | GDD.md, analysis/MASTER_ANALYSIS.md ve kod karşılaştırması; eksik/yanlış implement = puan kırma |
| UI/UX Quality | Görsel polish, hata yok, akıcı | Playwright MCP ile live URL'de screenshot + browser_console_messages (hata var mı), interaksiyon testi |
| Functional | Çalışıyor mu, golden path + edge case | Playwright ile gameplay/feature testi: tıkla, bekle, snapshot al |
| Code Quality | PR review skorları ortalaması, fix loop oranı | Phase 4 review_pass event'lerinin score detail'inden; <5 review = N/A |
| Performance | FPS, memory, network | Playwright browser_evaluate ile performance.memory, FPS ölçümü |
Agregat: total = (build*2 + gdd*3 + ui*2 + functional*2 + code_quality*1 + performance*1) / 11
GDD ve build en ağır — GDD birebir uyum forge'un nihai amacı, build kırıksa hiçbir şey önemsiz değil.
Web projeleri için Playwright kontrolü (zorunlu adımlar):
mcp__playwright__browser_navigate → projenin live URL'i (memory'den oku — örn. reference_vercel_url.md). URL yoksa lokal dev server başlat (npm run dev background) ve http://localhost:5173 kullan.mcp__playwright__browser_snapshot → açılış görüntüsümcp__playwright__browser_console_messages → JS hatası var mı (her error -1 puan UI'dan)- GDD'deki ilk 3 ana feature için ayrı interaksiyon testi:
- Tıkla, bekle, snapshot, sonucu doğrula
- Çalışmıyorsa Functional'dan -2 puan
mcp__playwright__browser_evaluate → JSON.stringify({mem: performance.memory?.usedJSHeapSize, fps: window.__fps || null})
GDD Compliance kontrolü (zorunlu adımlar):
GDD.md, PRD.md veya analysis/MASTER_ANALYSIS.md dosyalarını oku (varsa)- GDD'deki feature listesi vs kod karşılaştır:
- Her implement edilmiş feature: +1 puan (max 10)
- Yanlış/eksik implement: -1 puan
- Hiç başlanmamış kritik feature: -2 puan
- Önceki run'ın GDD score'u ile karşılaştır → trend (yükseliş/düşüş)
Çıktı formatı (forge/run-{N}-score.md):
# Forge Run N Score — {proje}
**Tarih:** {ISO date}
**Toplam Skor:** 7.8/10
## Kategori Skorları
| Kategori | Skor | Ağırlık | Katkı |
|-----------------|------|---------|-------|
| Build | 9/10 | 2 | 18 |
| GDD Compliance | 8/10 | 3 | 24 |
| UI/UX Quality | 7/10 | 2 | 14 |
| Functional | 8/10 | 2 | 16 |
| Code Quality | 8/10 | 1 | 8 |
| Performance | 7/10 | 1 | 7 |
| **Toplam** | | 11 | **86/110 = 7.8** |
## GDD Compliance Detay
- ✅ Implement: Building system, save/load, day-night, audio
- ⚠️ Eksik: Multiplayer (GDD bölüm 4.2)
- ❌ Bug: Tutorial step 3 — buton tıklanmıyor
## UI/UX Detay
- Konsol: 0 error, 2 warning (deprecated API)
- Screenshot: ✅ Ana ekran temiz, ✅ HUD okunaklı, ⚠️ Mobile responsive değil
- İnteraksiyon: 5/5 buton çalışıyor
## Functional Detay
- ✅ Yeni oyun başlatma
- ✅ İlk bina inşası
- ⚠️ Achievement modal açılmıyor (P2)
## Performance
- Heap: 42 MB
- FPS: 58 avg
- Bundle: 149.85 kB / 45.70 kB gzip
## Trend (Önceki Run'larla)
| Run | Toplam | GDD | UI | Functional |
|-----|--------|-----|----|-----------:|
| N-2 | 7.2 | 7 | 7 | 7 |
| N-1 | 7.5 | 8 | 7 | 7 |
| **N** | **7.8** | **8** | **7** | **8** |
## Sonraki Run İçin Öneriler
- GDD bölüm 4.2 (multiplayer) — XL task
- Tutorial step 3 buton bug — P0 fix
- Mobile responsive — frontend focus next run
Skor eşikleri ve aksiyonlar:
| Skor aralığı | Aksiyon |
|---|
| 9.0-10.0 | "Polish bölgesi" — kullanıcıya bildir, devam etme önerisi (memory: feedback_diminishing_returns) |
| 7.0-8.9 | Sağlıklı — devam et |
| 5.0-6.9 | Uyarı — Phase 7 analysis'e "kritik gap" flag'i geç |
| 0-4.9 | Kritik — sonraki run otomatik durur, kullanıcıya escalate |
Aggregate trend: forge/scores-aggregate.json — her run sonunda append:
[
{"run": 1, "ts": "2026-04-26T10:00Z", "total": 7.2, "build": 9, "gdd": 7, "ui": 7, "functional": 7, "code_quality": 7, "performance": 8},
{"run": 2, "ts": "2026-04-26T11:30Z", "total": 7.5, ...}
]
Implementation notes:
- Web olmayan projeler (CLI, lib): UI/Functional yerine "API Surface" + "Test Coverage" kullan
- Playwright erişilebilir değilse: UI/Functional skorları
manuel-pending etiketiyle 0 yazılır, agregat'ta hariç tutulur
- GDD.md yoksa: GDD Compliance skorı yerine PRD.md veya
analysis/MASTER_ANALYSIS.md kullan; ikisi de yoksa skor "N/A" — agregat ağırlıktan düşülür
Score agent dispatch:
Skorlama Phase 4'teki Reviewer agent değil — ayrı dispatch edilir:
- Sonnet 4.6 model (hızlı + ucuz)
- Tools: Read, Bash (build), mcp__playwright__*, mcp__jcodemunch__search_text
- Süre limit: 8 dk; aşılırsa partial score yazılır
Decision Log (forge/DECISIONS.md)
Her forge run'ı boyunca alınan önemli kararlar append-only olarak kaydedilir:
## Run 1 — 2026-04-14
### D001: SQLite yerine PostgreSQL
- **Karar:** Veritabanı PostgreSQL olarak seçildi
- **Neden:** Concurrent write ihtiyacı + full-text search
- **Alternatifler:** SQLite (basit ama concurrent weak), MongoDB (overkill)
- **Etkisi:** Task KEY-103, KEY-107 bu karara bağlı
### D002: Auth middleware yeniden yazılacak
- **Karar:** Mevcut auth middleware tamamen değiştirilecek
- **Neden:** Legal compliance — session token storage uyumsuz
- **Risk:** 12 endpoint etkileniyor, regression riski yüksek
- **Etkisi:** Sprint 1'de P0 olarak öne alındı
Kurallar:
- Her önemli teknik karar (library seçimi, mimari değişiklik, scope kararı) loglanır
- Append-only — eski kararlar silinmez, üzeri çizilmez
- Sonraki run'larda Phase 1 DECISIONS.md'yi okur — çelişen karar almaz
- Agent'lar karar alırken DECISIONS.md'ye yazar (Coder ve Reviewer dahil)
Phase 7 — Forge Analysis (Otomatik)
Phase 5 tamamlanır tamamlanmaz /forge-analysis skill'ini çalıştır. Argüman olarak mevcut run'ın summary dosya yolunu geç:
/forge-analysis forge/run-{N}-summary.md {proje}
Bu phase:
- Run metriklerini ölçer (task success rate, fix loop ratio, vb.)
- Cross-run trend analizi yapar (birden fazla run varsa)
- Bottleneck'leri tespit eder
- Memory ve skill dosyalarını otomatik optimize eder
forge/analysis-{tarih}-run-{N}.md raporunu oluşturur
Forge Analysis sonucu Phase 6'ya feed edilir — handoff önerileri analysis raporundan gelir.
Phase 6 — Handoff (N > 1 ise)
Sonraki run icin:
lessons_learned dosyasini Phase 1'e feed et- Completed task'lari filtrele — ayni task tekrar yapilmaz
- Yeni analysis onceki run'in cikarimlarini icerir
━━ Forge Run [1/3] Complete ✓ ━━━━━━━━━━━━
12/14 tasks merged, 2 failed
Lessons saved → forge/run-1-lessons.md
Starting Run 2 with lessons fed back...
━━ Forge Run [2/3] Starting ━━━━━━━━━━━━━
Son run tamamlaninca (run N = toplam):
/forge-analysis --final {N} {proje} calistir — tum run'lari kapsayan Final Meta-Analiz baslatilir.
━━ All Runs Complete — Final Meta-Analysis ━━━━━━━━━
/forge-analysis --final 5 CoinHQ
→ forge/meta-analysis-2026-04-08-runs-1-to-5.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
forge all modu
Tum projeleri wave sırasıyla forge et — her wave paralel, wave'ler sıralı:
/forge all # her proje 1 run, wave sırasıyla
/forge 2 all # her proje 2 run, wave sırasıyla
Wave-ordered execution (projects.json forge_wave_order):
forge all artık projeleri rastgele değil, wave sırasıyla çalıştırır:
- Wave 1 projeleri paralel başlat (foundation — claude-config)
- Wave 1 tamamlanınca Wave 2'yi başlat (dependents)
- Wave 2 tamamlanınca Wave 3'ü başlat (independent projects)
- Wave 3 tamamlanınca Wave 4'ü başlat (plugins/tools)
Bu sıralama projects.json → forge_wave_order alanından okunur. Alan yoksa tüm projeler paralel çalışır (eski davranış).
Akis:
~/Projects/ClaudeHQ/projects.json oku — forge_wave_order alanını parse et- Aktif session tespiti yap — atlanacakları belirle
- Her wave'i sırayla işle: wave içindeki projeler paralel background agent olarak başlatılır:
- Her agent kendi projesini tam forge eder (analysis → tasks → PR → merge → Jira)
- Wave içi agent'lar birbirini beklemez; bir sonraki wave tüm önceki wave tamamlanınca başlar
- Max 12 concurrent agent (tüm wave'ler dahil)
- Tüm agent'lar tamamlanınca özet göster:
━━ Forge All Summary ━━━━━━━━━━━━━━━━━
CoinHQ: 3 sprints, 12/14 tasks ✓
ArtLift: 2 sprints, 8/8 tasks ✓
Viralyze: 3 sprints, 10/13 tasks ✓ (3 failed)
...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Dosya yapisi
{proje}/
├── analysis/
│ ├── MASTER_ANALYSIS.md # Phase 1 ciktisi
│ └── SPRINT_PLAN.md # Phase 2 ciktisi
├── forge/
│ ├── run-1-summary.md # Run ozeti (Phase 5)
│ ├── run-1-lessons.md # Cikarilan dersler (Phase 5)
│ ├── analysis-2026-04-08-run-1.md # Verimlilik analizi (Phase 7)
│ ├── run-2-summary.md
│ ├── run-2-lessons.md
│ ├── analysis-2026-04-09-run-2.md
│ ├── DECISIONS.md # Append-only karar logu (tüm run'lar)
│ ├── event-log.jsonl # Structured event journal (Phase 4)
│ ├── state-manifest.json # Recovery state — her phase geçişinde güncellenir
│ ├── auto-report-{tarih}.md # Unattended run özeti (auto mode)
│ └── ...
└── .jira-state/ # Lock dosyalari
forge/ klasorunu .gitignore'a ekle.
Aktif Session Tespiti (all modu)
forge all calistiginda her projeyi forge etmeden once kullanicinin o anda o projede calisip calismadigi kontrol edilir. Aktif projeler forge'dan cikarilir — o projede hata yapmaktan kacilir, cakisma olmaz.
Tespit Yontemi
Bir proje "aktif" sayilir eger asagidaki sinyallerden en az ikisi positif:
| Sinyal | Kontrol | Komut |
|---|
| Claude session | Son 30 dakikada .jsonl aktivitesi var mi | find ~/.claude/projects/{proje-slug}/ -name "*.jsonl" -newer /tmp/forge-check-ts 2>/dev/null |
| Git dirty | Uncommitted degisiklik var mi | git -C {path} status --porcelain |
| Git lock | .git/index.lock mevcut mu | test -f {path}/.git/index.lock |
| Forge lock | .jira-state/forge.lock mevcut mu (baska forge calisiyor) | test -f {path}/.jira-state/forge.lock |
| Recent file change | Son 15 dakikada kaynak dosya degisti mi | `find {path}/lib {path}/src -newer /tmp/forge-check-ts -name ".dart" -o -name ".ts" -o -name "*.py" 2>/dev/null |
Proje slug cikarsimi:
/Users/musabkara/Projects/CoinHQ → -Users-musabkara-Projects-CoinHQ~/.claude/projects/-Users-musabkara-Projects-CoinHQ/ dizini kontrol edilir
Ozel kural — Forge'u calistiran proje: forge all hangi CWD'den calisiyorsa o projeyi aktif tespitinden muaf tut — o session forge'un kendisidir, false positive olusur. (Ornek: ClaudeHQ'dan forge all calistirilinca ClaudeHQ kendini atlamamali.)
Kontrol Adımlari
touch /tmp/forge-check-ts
for proje in projects.json'daki aktif projeler:
skor = 0
skor += 1 if claude session aktif (son 30dk jsonl)
skor += 1 if git dirty
skor += 1 if git lock
skor += 1 if forge lock
skor += 1 if recent file change (son 15dk)
if skor >= 2:
→ SKIP (aktif proje)
elif skor == 1:
→ WARN (muhtemelen aktif, kullaniciya sor)
else:
→ FORGE (guvenli)
Cikti Formati
━━ Forge All — Aktif Session Tespiti ━━━━━━━━━━━━━━━━━━━━━━━
CoinHQ → ✅ Guvenli (session: 3sa once, git: clean)
ArtLift → ⏭ Atlaniyor (session: 2dk once + git dirty)
Gardirop → ⏭ Atlaniyor (forge.lock mevcut)
Viralyze → ⚠️ Belirsiz (session: 18dk once)
→ Viralyze'i forge etsek mi? [Y/n]:
RefinUp → ✅ Guvenli (session: 45dk once, git: clean)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Forge edilecek: CoinHQ, Viralyze (onay bekleniyor), RefinUp
Atlanan: ArtLift, Gardirop
"Belirsiz" projeler (skor=1): Kullaniciya sor. Cevap:
- Y → forge et
- N → atla
--force flag verilmisse → sor, direkt forge et
--force ve --skip Flags
/forge all --force # Aktif tespiti atla, hepsini forge et
/forge all --skip ArtLift # Belirli projeyi manuel atla
/forge all --only CoinHQ,Viralyze # Sadece bu projeleri forge et
Forge Lock
Her forge baslayinca o projeye lock koy, bitince kaldir:
mkdir -p {path}/.jira-state && touch {path}/.jira-state/forge.lock
rm -f {path}/.jira-state/forge.lock
Bu sayede iki ayri forge all ayni projeye cakismaz.
Kurallar
- Lead kararlari otomatik kabul — forge sifir soru sorar (analysis haric: orada sadece oto-cevap)
all modunda projeler paralel — her proje bağımsız background agent, max 12 concurrent proje
2a. Tek projede max 5 concurrent task — sprint içi paralel task limiti- Max 5 fix retry per PR — sonsuz dongu onlemi
- Max 10 run —
/forge 10 max, daha fazlasi icin uyari
- Secret'lar koda yazilmaz —
.env.example + fallback
- Destructive git islemleri yasak —
push --force, reset --hard, rm -rf yok
- Her task worktree'de calisir — main branch'e direkt commit yok
- Sprint sirasi korunur — Sprint 1 bitmeden Sprint 2 baslamaz
- Baska projeden cagirilabilir — proje adi veya
all ile herhangi bir dizinden calistir
- Phase 7 atlanamazz — her forge run'inda
/forge-analysis otomatik calisir, skip edilemez
10a. Phase 5.5 atlanamazz — her run sonunda per-run scoring (browser test + GDD compliance + UI + functional + perf) zorunlu; skor < 5.0 ise sonraki run otomatik durur
- Verimlilik skoru < 50 ise dur — kullaniciya bildir, sonraki run'i baslatma
all modunda aktif session tespiti zorunlu — skor ≥ 2 projeyi forge etme, kullaniciya bildir- Forge lock — her forge baslayinca
.jira-state/forge.lock yaz, bitince sil
- forge choose —
choose argümanı verilince önce müsaitlik kontrolü yap, sonra kullanıcı proje seçsin, seçilenleri paralel forge et
- Project index zorunlu — Phase 0 sonunda
mcp__jcodemunch__index_repo ile projeyi indexle; bu adım atlanamaz
- Agent 1-kelime durum etiketi — her agent her adım başında
[PROJE/KEY] eylem formatında tek satır yazar (branching, coding, reviewing, merging, done); sessiz çalışma yasak
- Jira mode otomatik tespit —
projects.json jira alanından mod belirlenir; Jira-less mode'da Jira çağrıları skip edilir, gorevler forge/sprints/sprint-{N}.json'a yazilir
- 9+ puan eşiği — başta sor, 9'da dur:
- Forge başlamadan önce (Phase 0 sonrası, Phase 1 öncesi) şunu sor:
Proje skoru tahmini ≥9/10 görünüyor. Seçenek:
1) 9.0 puana ulaşınca dur (verimli, polish değil gerçek iş)
2) Sonuna kadar git (küçük kazanımlar da olsa devam)
Seçim (1/2):
- Bu soru sadece önceki run summary'de skor ≥ 8.5 ise veya analysis'te "diminishing returns" / "polish" ifadeleri geçiyorsa gösterilir. İlk run'da veya skor belli değilse gösterilmez.
- Kullanıcı 1 seçerse: her run sonunda Phase 5'te skor ≥ 9.0 ise loop'u durdur, kullanıcıya bildir:
⏹ Forge durdu — proje skoru 9.2/10 eşiği aştı.
Kalan açıklar polish/OSS formality kategorisinde — gerçek kullanıcı değeri düşük.
Devam etmek için: /forge 1 --force-continue
- Kullanıcı 2 seçerse veya
--force-continue flag'i varsa: normal akış, skor limiti yok.
Auto Mode (Unattended)
auto argümanı verildiğinde forge tamamen otonom çalışır — hiç soru sormaz:
| Normalde sorulan | Auto modda cevap |
|---|
| Compact önerisi | Geç (2) |
| Agent atama modu | Lead Orchestrator (1) |
| Brief oluştur mu | Evet (Y) |
| Agent kullanılabilirlik | Tüm alternatifleri uygula (4) |
| Belirsiz proje (forge all) | Dahil et (Y) |
| Recovery: devam mı baştan mı | Devam et (1) |
| Focus menüsü | Full Cycle (3) |
Kullanım senaryoları:
- Gece boyu çalıştırma:
tmux new -d '/forge auto 5 CoinHQ'
- CI/CD: schedule trigger ile periyodik forge
- Toplu bakım:
tmux new -d '/forge auto all -security'
Güvenlik:
--force flag'i olmadan destructive git operasyonları atlanır- Quota limit'e ulaşılırsa durur, sonraki run'a geçmez
- Max 8 saat çalışma süresi — aşılırsa state kaydet ve dur
- Sonuç:
forge/auto-report-{tarih}.md — unattended run özeti
When NOT to Use
- Tek satirlik basit soru/cevap ise
- Skill'in scope'u disindaysa
- Riskli/destructive is ise (ayri onay gerekir)
Red Flags
- Belirsiz hedef/kabul kriteri
- Gerekli dosya/izin/secret eksik
- Ayni adim 2+ kez tekrarlandi
Error Handling
- Gerekli kaynak yoksa → dur, blocker'i raporla
- Komut/akıs hatasi → en yakin guvenli noktadan devam et
- 3 basarisiz deneme → daha uygun skill/agent'a yonlendir
Verification
