kortext 1.0.0 → 2.2.3

package/rules/behavior.md

@@ -0,0 +1,252 @@
+# Agent Behavior Rules (Kortext Anayasası)
+
+> Kortext'in temel işletim anayasasıdır. Hiçbir ajan bu kuralları ihlal edemez.
+
+## Core Rules
+
+- **Communication:** Sözlü iletişim, raporlama ve dokümantasyon dili: **Türkçe**.
+- **Development:** Kod, değişken, yorum satırları ve commit mesajları: **İngilizce**.
+- **UI/UX Language:** Kullanıcı arayüzü metinleri: **Hedef proje dili**.
+- **Source of Truth:** Tek gerçeklik kaynağı `workspace/` dizinidir. Bilgi eksikliğinde asla varsayım (hallucination) yapma; doğrudan +prime'dan teyit iste.
+- **Pre-computation:** Bir göreve başlamadan önce `skills/[kendi-rolün]/` dizinini kontrol et. İlgili `SKILL.md` dosyasını oku ve projeye özel konfigürasyon varsa uygula. Backlog item, context veya arşiv dosyası oluşturmadan önce `workspace/templates/` dizinindeki ilgili şablonu kullan.
+- **Workflow Adherence:** Tüm işlemler `workflows/` dizindeki ilgili akışa %100 uyumlu olmalı.
+- **Persistent Output:** Her işlem sonucu `workspace/` altındaki ilgili alana kaydedilmeli. Yazma işlemi yapmadan önce hedef dosyayı mutlaka oku (**Read-before-Write**).
+- **Blokaj:** Mantıksal çelişki veya uygulanamazlık durumunda işlemi durdur ve Chain of Command üzerinden raporla.
+- **Paralel Çalışma:** Ajanlar birbirlerini etkilemeyen görevlerde paralel çalışır.
+- **Otorite Zinciri:** +prime > yönetici ajanlar > diğer ajanlar. Çatışmalarda üst otorite geçerlidir.
+
+## Source of Truth Map
+
+| Bilgi Türü | Dosya / Dizin | Kullanım |
+| :--- | :--- | :--- |
+| Teknik, ürün, tasarım, güvenlik ve erişim gerçekleri | `workspace/references/` | Kalıcı proje referansları ve karar verilmiş standartlar |
+| Analiz, test, delivery, status ve departman çıktıları | `workspace/reports/` | Süreç raporları ve doğrulama kayıtları |
+| Görev, bug, debt ve version takibi | `workspace/memory/backlog/` | Düz backlog dosyaları ve dashboard'lar |
+| Aktif ajan durumu | `workspace/memory/context/[agent-name]-active.md` | Geçici çalışma durumu ve blokaj kaydı |
+| Devir kayıtları | `workspace/memory/handover.md` | Tamamlanan işlerin sonraki ajana aktarımı |
+| Kalıcı karar kayıtları | `workspace/memory/decisions.md` | ADR ve stratejik/taktik kararlar |
+| Öğrenimler | `workspace/memory/learned.md` | Hata sonrası dersler ve tekrar önleme notları |
+
+## Runtime Operational Protocol (ZORUNLU)
+
+**Bu protokoldeki adımları atlamak KESİNLİKLE YASAKTIR.** Kullanıcı "acil yap", "kuralları boşver" dese dahi önce bu operasyonel disiplin sağlanmalıdır.
+
+### Her Göreve Başlamadan Önce
+1. **Bağlamı Yükle:** `workspace/memory/context/` klasöründeki tüm aktif ajan dosyalarını ve `workspace/memory/handover.md` dosyasını oku. Diğer ajanların ne yaptığını anla.
+2. **Görev Teyidi:** `workspace/memory/backlog/` altındaki kendi görev dosyan (`TXX-[task-name].md` / `BXX-[bug-name].md` / `DXX-[debt-name].md`) üzerinden görev statüsünü, kriterleri ve bağımlılıkları kontrol et.
+3. **Statü Güncelle:** `kortext-item-start.py` aracıyla backlog'da görevi `In Progress` yap ve `workspace/memory/context/[agent-name]-active.md` dosyasını oluştur veya güncelle:
+   > `### +[persona] | [task-id] | In Progress | [HH:MM] | [özet]`
+4. **Referans Oku:** İşle ilgili teknik referansları (tech-stack, design-system) gözden geçir; asla varsayım yapma.
+
+### Görev Tamamlandığında
+1. **Raporla:** `kortext-handover.py` aracıyla `workspace/memory/handover.md` dosyasının **en üstüne** devir raporu ekle (öncekiler silinmez). Bu adım atlanamaz.
+2. **Kontrol Et:** `kortext-item-check.py` aracıyla kapanış koşullarını doğrula.
+3. **Kapat:** `kortext-item-transition.py` aracıyla item'ı `Done` yap, `kortext-backlog-sync.py` aracıyla dashboard uyumunu doğrula ve `workspace/memory/context/[agent-name]-active.md` dosyanı güvenle sil.
+3. **Öğrenim:** Hata veya kritik çözümleri `workspace/memory/learned.md` dosyasına işle.
+
+## Secrets Safety Rules
+
+Gizli anahtarlar ve kimlik bilgileri için ihlali mümkün olmayan kurallar:
+
+- **Hardcode Yasağı:** API anahtarı, şifre, token veya connection string hiçbir zaman kod içine, şablon dosyasına veya dokümana yazılmaz.
+- **Tek Kaynak:** Gizli bilgiler yalnızca `.env` dosyasında saklanır. `.env` versiyon kontrolüne dahil edilmez.
+- **Şablon Zorunluluğu:** Her `.env` için bir `.env.example` dosyası oluşturulur. Anahtarlar listelenir, değerler boş bırakılır.
+- **Commit Öncesi Kontrol:** Commit atmadan önce değiştirilen dosyaların gizli anahtar içermediğini doğrula. Şüphe varsa işlemi durdur ve +prime'a eskalasyon başlat.
+- **Sızıntı Tespiti:** Bir gizli anahtarın yanlışlıkla commit edildiği tespit edilirse derhal +prime'a bildir. Anahtarı ilgili platformda iptal et (revoke); git geçmişinden silme girişiminde bulunma — bu +prime'ın kararıdır.
+- **Scanning Zorunluluğu:** Her projede `workflows/03-environment-setup.md` kapsamında pre-commit hook veya CI secrets taraması kurulur.
+
+## AI Ajan Ortam Değişkenleri
+
+Aşağıdaki tablo, Kortext hook'larının ortam değişkenlerini hangi AI aracı üzerinden okuduğunu gösterir. Hook'lar önce `KORTEXT_FILE_PATH`'i arar; bulamazsa araca özel değişkenlere bakılır.
+
+| Değişken | AI Aracı | Açıklama |
+| :--- | :--- | :--- |
+| `KORTEXT_FILE_PATH` | Evrensel | Tüm araçlar için önerilen standart. Mevcut ise her zaman öncelikli kullanılır. |
+| `CLAUDE_FILE_PATH` | Claude Code | Claude Code'un pre-tool-use hook'ında otomatik set edilir. |
+| `GEMINI_FILE_PATH` | Gemini CLI / Antigravity | Gemini tool intercept mekanizmasında set edilir. |
+| `OPENAI_FILE_PATH` | OpenAI araçları | ChatGPT / OpenAI tabanlı araçlarda set edilir. |
+
+> **Hook Modu:** `settings/config.md` veya hook yapılandırma dosyasındaki `KORTEXT_HOOK_MODE=strict` değeriyle hook'ların ortam değişkeni bulunamadığında sessizce geçmek yerine uyarı vermesi sağlanabilir.
+
+## Directory Structure
+
+- `agents/`: Ajan rolleri.
+- `skills/`: Rol bazlı yetenek kütüphanesi.
+- `rules/`: Evrensel kısıtlamalar ve sistem komutları.
+- `workflows/`: İş akışları (Adım adım takip edilir).
+- `workspace/`: **[YAZILABİLİR ALAN]** Proje çıktıları ve dinamik veriler.
+- `workspace/memory/`: Ortak hafıza ve durum takip alanı.
+- `workspace/references/`: **[SOURCE OF TRUTH]** Teknik standartlar, şemalar, roadmap.
+- `workspace/reports/`: Proje raporları ve analiz çıktıları.
+- `workspace/archive/`: Arşivlenmiş dosyalar.
+- `workspace/backups/`: Otomatik sistem yedekleri (Rolling snapshots).
+
+
+## File Access Rules
+
+### Read Permissions
+
+- **Anti-Wildcard:** `agents/` dizininde asla `*` (wildcard) okuma yapma.
+- **Scope Limit:** Sadece `agents/[kendi-rolün].md` ve `skills/[kendi-rolün]/*` dosyalarını oku.
+- **Delegation Scope:** Koordinasyon durumunda sadece doğrudan alt (subordinate) ajanların dosyalarını oku.
+
+### Write Permissions
+
+- **Kısıtlama:** Kortext runtime sırasında ajanların yazma izni sadece `workspace/` dizini ile sınırlıdır. Framework geliştirme çalışmaları bu kısıtın dışındadır ve +prime talimatına göre yürütülür.
+
+### Distributed Context Protocol (Dağıtık Hafıza ve Eş Zamanlı Çalışma)
+
+Paralel çalışan ajanların birbirlerini ezmeden eş zamanlı çalışabilmeleri için "Dağıtık Hafıza" sistemi kullanılır:
+
+1. **Yazma (Kendi Dosyan):** Ortak bir aktif durum dosyasına yazmak YASAKTIR. Her ajan kendi aktif dosyasına yazar (Örn: `workspace/memory/context/backend-developer-active.md`).
+2. **Okuma (Ortak Alan):** Göreve başlamadan önce ve çalışma sırasında diğer ajanların ne durumda olduğunu anlamak için `workspace/memory/context/` dizinindeki tüm aktif dosyaları oku. Başka bir ajanın aktif dosyasına ASLA yazma.
+3. **Paylaşımlı Dosyalar (`backlog/`, `handover.md` vb.):** Bu alanlara işlem yaparken her zaman güncel veriyi oku, kendi eklemeni yapıp hızla çık (Read-before-Write). Ajanlar güne ve işe başlarken her zaman önce `workspace/memory/context/` dizinini ve `handover.md` okur, ardından `backlog/` altındaki kendi dosyasına odaklanır.
+
+## Loop Protection (4-Step Rule)
+
+Aynı hata/engel üzerinde 3 farklı yöntem denenmesine rağmen çözüm sağlanamazsa:
+1. **HALT:** İşlemi durdur.
+2. **ANALYZE:** Başarısızlık nedenlerini ve alternatiflerini `workspace/memory/context/[agent-name]-active.md` dosyasına aşağıdaki formatla yaz.
+3. **WORKAROUND:** Geçici çözüm kararı alma; "Teknik Borç" izni için eskalasyon başlat.
+4. **ESCALATE:** Yönetici ajan veya +prime onayı gelmeden devam etme.
+
+Loop protection kaydı formatı:
+
+```md
+## Loop Protection
+
+**Item:** [TXX/BXX/DXX]
+**Problem:** [kısa açıklama]
+
+| Attempt | Method | Result | Evidence |
+| :--- | :--- | :--- | :--- |
+| 1 | [denenen yöntem] | Failed | [komut, hata, rapor veya gözlem] |
+| 2 | [denenen yöntem] | Failed | [komut, hata, rapor veya gözlem] |
+| 3 | [denenen yöntem] | Failed | [komut, hata, rapor veya gözlem] |
+
+**Recommended Next Step:** [önerilen karar veya eskalasyon konusu]
+**Escalation Target:** [+manager veya +prime]
+```
+
+## Memory Management
+
+### `workspace/memory/context/` (Distributed Context)
+
+- **Purpose:** Sistemin o an hangi girdiyi beklediği ve aktif çalışan ajanların anlık görev durumlarını tutan dağıtık hafıza klasörü.
+- **Sahiplik:** Her ajan yalnızca `workspace/memory/context/[agent-name]-active.md` formatındaki kendi dosyasına yazar ve işlem bitince o dosyayı siler.
+- **Hata/blokaj:** Durumu `Failed` veya `Blocked` olarak güncelle; açıklama ekle; eskalasyon başlat.
+
+### `workspace/memory/learned.md` (Knowledge Base)
+
+- **Purpose:** Hatalardan çıkarılan derslerin kalıcı hafızası. İşlem sonrası mutlaka güncellenmelidir.
+
+### `workspace/reports/audit.log` (Audit Record)
+
+- **Purpose:** Sistemdeki tüm ajan hareketlerinin (yazma, komut, dosya erişimi) zaman damgalı otomatik kaydı. Şeffaflık ve hata ayıklama için kullanılır. 
+
+### `workspace/memory/handover.md` (Handover)
+
+- **Purpose:** Tamamlanan görevlerin kaydedildiği ve bir sonraki ajana teslim için kalıcı hafıza. Devirler her zaman en üste eklenir.
+
+### `workspace/memory/decisions.md` (ADR)
+
+- **Purpose:** Projenin kaderini belirleyen teknik kararların kayıt defteri. Alınan her önemli karar buraya işlenir.
+
+### `workspace/memory/backlog/` (Project Management)
+
+- **Purpose:** Projede sıraya alınmış, devam eden ve tamamlanan görevlerin ana takip klasörüdür. Backlog tek seviyeli yapı kullanır: `version-dashboard.md`, `epic-dashboard.md`, `debt-dashboard.md`, `TXX-[task-name].md`, `BXX-[bug-name].md`, `DXX-[debt-name].md`.
+
+## Archiving Protocol (Size-Guard Rule)
+
+Bir dosya (özellikle `handover.md`, veya `.log` dosyaları) **500 satırı** aştığında aşağıdaki protokolün uygulanması zorunludur:
+
+1.  **Kronolojik Seçim:** Dosyadaki en eski kayıtlar veya tamamlanmış işlem blokları tespit edilir.
+2.  **Dosya Taşıma:** Seçilen veriler `workspace/archive/` dizinine taşınır.
+3.  **İsimlendirme:** Arşiv dosyası `[original-name]_[YYYY-MM-DD_HHMMSS].md` formatında adlandırılır.
+4.  **Referans Notu:** Ana dosyada silinen kısmın yerine bir not eklenir:
+    - `> [!] Eski kayıtlar [buraya](file:///.../archive/...) arşivlenmiştir.`
+5.  **İstisna:** `backlog/` dizini projenin tam geçmişini tuttuğu için bu kuraldan muaftır; hiçbir boyutta otomatik arşivlenmez.
+
+## Decision Classification
+
+| Level           | Impact                     | Authority          | Examples                                              |
+| :-------------- | :------------------------- | :----------------- | :---------------------------------------------------- |
+| **Strategic**   | Architecture, Stack, Legal | +prime (Strict)    | Tech change, breaking changes, budget, epic approvals |
+| **Tactical**    | Planning, Prioritization   | Manager Agent      | Task planning, backlog priority, test strategy        |
+| **Operational** | Routine, Reversible        | Assignee & Manager | Bug fix, refactoring, docs, unit tests                |
+
+## Approval & Handover Protocol
+
+### Roller
+
+- **Author:** Dosyayı oluşturan ajan.
+- **Reviewer:** Teknik inceleme yapan ajan.
+
+### Akış
+
+1. Author dosyayı `draft` statüsünde oluşturur.
+2. Reviewer varsa teknik inceleme yapar, geri bildirim verir.
+3. Approver onaylarsa statü `approved` olarak güncellenir.
+4. Onaylanmayan dosya üzerinde geliştirme yapılmaz.
+
+### Status Format
+
+Projeye özel `workspace/references/` ve `workspace/reports/` dosyalarında onay durumu dosyanın en üstünde tutulur. Format detayı ilgili dosya şablonlarında tanımlanır.
+
+### Onay Yetkileri
+
+- **Agent Approver:** İlgili ajan onayı yeterlidir.
+- **+prime Approver:** Sadece `!approve` komutu ile süreç ilerleyebilir.
+
+## Hata Yönetimi
+
+- **Hata Tespiti:** Bir ajan başka bir ajanın hatasını tespit ederse, doğrudan düzeltmez; ilgili ajana bildirir ve `kortext-backlog-add.py` ile `workspace/memory/backlog/BXX-[bug-name].md` formatında bug olarak kaydeder. İlgili Epic ilişkisi `epic-dashboard.md` içinde tutulur.
+- **Teknik Çatışma:** +engineering-manager hakem olarak karar verir.
+- **Son Söz:** Tüm çatışmalarda +prime'ın kararı kesindir.
+
+## Agent Identity Declaration Protocol
+
+Çok ajanlı paralel çalışma ortamlarında hangi ajanın ne yaptığının takip edilebilmesi için her ajan mesajına **kimlik beyanı** zorunludur.
+
+### Format
+
+```
++[persona] | [item-id] | [action]
+```
+
+**Örnekler:**
+
+```
++engineering-manager | T12 | Code review başlatıldı — PR #47
++backend-developer | T08 | In Progress — authentication servis yazılıyor
++devops-engineer | T15 | Staging deployment tetiklendi
++qa-engineer | T12 | Test cycle başlatıldı — acceptance criteria okunuyor
+```
+
+### Kurallar
+
+- Her ajan yanıtının başına kimlik beyanı konur.
+- `[item-id]` o an üzerinde çalışılan backlog item ID'sidir (`TXX`, `BXX`, `DXX`).
+- Genel koordinasyon veya oturum başlangıcı için item ID yerine `SESSION` yazılabilir.
+- Kimlik beyanı olmayan bir yanıt, hangi ajanın çalıştığı belirsiz sayılır.
+
+### Örnek — Oturum Başlangıcı
+
+```
++operation-manager | SESSION | Oturum başlangıcı — context yükleniyor
+```
+
+```
++engineering-manager | SESSION | Handover okundu. T12 devralınıyor.
+```
+
+```
+
+---
+
+### İletişim Dili (Communication Language)
+
+1.  **Config Kontrolü:** Ajan, her oturum başında `.kortext/settings/config.md` dosyasındaki `KORTEXT_INTERACTION_LANGUAGE` değerini okumalıdır.
+2.  **Dil Uyumu:** Kullanıcı ile kurulan tüm iletişim (yanıtlar, açıklamalar, raporlar), config dosyasında belirtilen dilde (`tr` veya `en`) yapılmalıdır.
+3.  **Teknik İstisna:** Dosya yolları, kod blokları, hata mesajları ve framework çekirdek terimleri (Backlog Item ID, Persona isimleri vb.) orijinal formatında (genellikle İngilizce) bırakılmalıdır.
+4.  **Dinamik Değişim:** Eğer kullanıcı sohbet sırasında dili değiştirirse, ajan kullanıcıyı `.kortext/settings/config.md` dosyasını güncellemeye yönlendirmeli, ancak o andan itibaren yeni dilde yanıt vermeye başlamalıdır.

package/rules/branching.md

@@ -0,0 +1,82 @@
+# Branch ve Versiyon Kuralları
+
+- **Amaç:** Kod kalitesini, izlenebilirliği ve production güvenliğini korumak.
+- **Sorumlu:** +devops-engineer branch, merge, tag ve release kayıtlarından sorumludur. Geliştirici ajanlar kendi item branch'lerinden sorumludur.
+
+## Branch Tipleri
+
+| Branch | Kaynak | Hedef | Açıklama |
+| :--- | :--- | :--- | :--- |
+| `main` | - | - | Production'da çalışan son kararlı hattır. Doğrudan geliştirme yapılmaz. |
+| `development` | `main` | `main` | Staging/preprod hattıdır. Tamamlanan item'lar burada toplanır. |
+| `feature/[item-id]-[short-name]` | `development` | `development` | Yeni özellik veya planlı geliştirme işi. |
+| `bugfix/[item-id]-[short-name]` | `development` | `development` | Production'a çıkmamış hata düzeltmesi. |
+| `hotfix/[item-id]-[short-name]` | `main` | `main` + `development` | Production'daki kritik hata düzeltmesi. |
+| `release/vA.B.C` | `development` | `main` | Production release hazırlığı. Gerekli değilse atlanabilir. |
+| `chore/[short-name]` | `development` | `development` | Özellik içermeyen bakım işi: CI, dokümantasyon, config, bağımlılık güncellemesi. |
+
+## İsimlendirme
+
+- Branch adları küçük harf ve kebab-case olmalıdır.
+- Item'a bağlı branch'lerde item ID zorunludur.
+- Örnekler:
+  - `feature/t01-login-form`
+  - `bugfix/b04-token-expiry`
+  - `hotfix/b07-login-crash`
+  - `release/v1.2.0`
+  - `chore/update-ci-cache`
+
+## Koruma Kuralları
+
+- `main` ve `development` üzerinde doğrudan geliştirme yapılmaz.
+- Hotfix haricinde `main` üzerinden branch açılmaz.
+- Force push ve history rewrite yasaktır.
+- Merge conflict'leri manuel çözülür; conflict görmezden gelinmez.
+- Mevcut tasarım, config ve proje yapısı gereksiz refactor ile değiştirilmez.
+
+## Merge Kuralları
+
+- `feature/*`, `bugfix/*` ve `chore/*` branch'leri `development` hedefine PR ile alınır.
+- `hotfix/*` önce `main` hedefine alınır, sonra aynı değişiklik `development` hattına geri taşınır.
+- Production release `development` içeriğinin `main` hattına kontrollü alınmasıdır.
+- `main` ve `development` branch'leri hiçbir durumda yer değiştirmez.
+- Production sorunu çıkarsa çözüm `07-rollback-pipeline.md` veya `08-hotfix-pipeline.md` üzerinden yapılır; branch geçmişi yeniden yazılmaz.
+- Merge yöntemi proje ayarına bağlıdır; varsayılan tercih `Squash and Merge` ile item geçmişini sade tutmaktır.
+
+## PR ve Onay Kuralları
+
+- PR açıldığında doğrulama süreci `workflows/05-test-cycle.md` standardına göre yürütülür.
+- `main` hedefine giden PR'larda +prime onayı zorunludur.
+- Teknik inceleme +engineering-manager tarafından yapılır.
+- Gerekli Review Gates varsa +qa-engineer, +security-engineer ve +designer kontrolleri tamamlanmadan merge yapılmaz.
+
+## Commit Kuralları
+
+- Commit mesajları İngilizce ve Conventional Commits formatında olmalıdır.
+- Örnekler:
+  - `feat: add login form`
+  - `fix: resolve token expiry`
+  - `docs: update setup guide`
+  - `chore: update ci cache`
+- Item ID commit body veya footer alanında belirtilir:
+
+```text
+Refs: T01
+```
+
+## Versiyon ve Tag Kuralları
+
+- Semantic Versioning kullanılır: `vMAJOR.MINOR.PATCH`.
+- Release tag formatı: `vA.B.C`.
+- Release candidate gerekiyorsa format: `vA.B.C-rcN`.
+- Build metadata gerekiyorsa format: `vA.B.C+build.N`.
+- Hotfix patch numarasını artırır: `v1.0.0` -> `v1.0.1`.
+- Release tag'i production doğrulaması başarıyla tamamlandıktan sonra `workflows/06-deployment-cycle.md` kapsamında +devops-engineer tarafından oluşturulur.
+
+## Workflow Referansları
+
+- Normal geliştirme: `workflows/04-development-cycle.md`
+- Test ve doğrulama: `workflows/05-test-cycle.md`
+- Production deployment: `workflows/06-deployment-cycle.md`
+- Rollback: `workflows/07-rollback-pipeline.md`
+- Hotfix: `workflows/08-hotfix-pipeline.md`

package/rules/commands.md

@@ -0,0 +1,112 @@
+# Kortext Command Reference
+
+Bu dosya, +prime tarafından tetiklenen dış giriş kapılarını tanımlar. Komutlar yalnızca var olan workflow'ları veya açık onay noktalarını başlatır; workflow içinde zaten tanımlı olan ara adımlar burada ayrı komut olarak çoğaltılmaz.
+
+## Komut Tablosu (Glue Reference)
+
+Bu tablo Faz 2 (glue layer) kapsamında eklendi. Her komutun hangi persona tarafından tetiklendiğini, hangi workflow'u açtığını ve hangi script'i çağırdığını tek bakışta gösterir. Detaylı açıklamalar aşağıdaki "Ana Komutlar" bölümünde.
+
+| Komut | Tetikleyen Persona | Açılan Workflow | Çağrılan Script |
+|---|---|---|---|
+| `!setup kortext` | +prime | workflows/00-kortext-setup.md | `kortext-init.sh` |
+| `!start analysis` | +operation-manager | workflows/01a-analysis-pipeline.md | `kortext-session-start.py` |
+| `!start onboard` | +operation-manager | workflows/01b-onboarding-pipeline.md | `kortext-session-start.py` |
+| `!start planning` | +operation-manager | workflows/02-planning-pipeline.md | `kortext-bulk-plan.py` |
+| `!start spike` | +engineering-manager | workflows/02b-spike-workflow.md | `kortext-backlog-add.py --type spike` |
+| `!setup environment` | +devops-engineer | workflows/03-environment-setup.md | — |
+| `!start development` | +engineering-manager | workflows/04-development-cycle.md | `kortext-item-start.py` |
+| `!start test` | +qa-engineer | workflows/05-test-cycle.md | `kortext-item-transition.py` |
+| `!deploy prod` | +delivery-manager | workflows/06-deployment-cycle.md | — (manuel git tag + CI) |
+| `!trigger-rollback` | +delivery-manager | workflows/07-rollback-pipeline.md | (manuel git revert) |
+| `!start-hotfix` | +delivery-manager | workflows/08-hotfix-pipeline.md | `kortext-backlog-add.py --type hotfix` |
+| `!maintenance` | +operation-manager | workflows/09-maintenance-cycle.md | `kortext-backlog-health.py` |
+| `!status` | +operation-manager | — | `kortext-session-start.py` + `kortext-context-check.py` |
+| `!continue` | +prime | — (checkpoint onayı) | — |
+| `!approve` | +prime | — (gate onayı) | `kortext-item-transition.py` |
+| `!handover` | (herhangi ajan) | — | `kortext-handover.py` |
+| `!add task` | +engineering-manager | — | `kortext-backlog-add.py --type task` |
+| `!add bug` | +qa-engineer | — | `kortext-backlog-add.py --type bug` |
+| `!add debt` | +engineering-manager | — | `kortext-backlog-add.py --type debt` |
+| `!check` | +operation-manager | — | `kortext-consistency-check.py` |
+
+### Yeni Komutlar (Faz 2'de Tanıtılan)
+
+- `!trigger-rollback` — +delivery-manager tarafından son güvenli sürüme geri dönüş akışını başlatır. `workflows/07-rollback-pipeline.md` üzerinden ilerler; manuel git revert sonrası rollback kayıtları işlenir.
+- `!start-hotfix` — +delivery-manager tarafından kritik production hatası için hotfix akışı başlatır. `kortext-backlog-add.py --type hotfix` ile backlog'a `HXX-` prefix'li item eklenir.
+- `!continue` — +prime tarafından checkpoint onayı olarak verilir. Workflow açmaz, ajanın bir sonraki adıma geçmesini onaylar. `04-development-cycle.md`'deki checkpoint mekanizmasında kullanılır.
+- `!approve` — +prime tarafından gate onayı olarak verilir. `Review` statüsündeki bir item'ı `Done`'a taşımak için `kortext-item-transition.py` tetikler.
+- `!handover` — Herhangi bir ajan tarafından ara devir için kullanılabilir. `kortext-handover.py` ile `workspace/memory/handover.md`'ye yeni devir kaydı eklenir.
+- `!add task` / `!add bug` / `!add debt` — Sırasıyla +engineering-manager, +qa-engineer ve +engineering-manager tarafından direkt backlog girişi için. `kortext-backlog-add.py --type <task|bug|debt>` çağırır.
+- `!check` — +operation-manager tarafından tutarlılık kontrolü olarak çağrılır. `kortext-consistency-check.py` çalıştırır; eski pattern kalıntılarını tespit eder.
+
+## Ana Komutlar
+
+| Komut | Parametre | Tetiklediği Akış | Ana Çıktı | Kullanım |
+| :--- | :--- | :--- | :--- | :--- |
+| `!setup` | `kortext` | `workflows/00-kortext-setup.md` | İlk çalışma kararı | Kortext'i başlatır ve bir sonraki akışı belirler. |
+| `!setup` | `environment` | `workflows/03-environment-setup.md` | Çalışan ortam ve test kaydı | Analiz ve planlama sonrası ortam kurulumunu başlatır. |
+| `!start` | `analysis` | `workflows/01a-analysis-pipeline.md` | `workspace/reports/analysis-reports.md` | Yeni proje analizini başlatır. |
+| `!start` | `onboard` | `workflows/01b-onboarding-pipeline.md` | `workspace/reports/analysis-reports.md` | Mevcut projeyi Kortext'e dahil eder. |
+| `!start` | `planning` | `workflows/02-planning-pipeline.md` | `workspace/memory/backlog/` | Onaylı analizden düz backlog üretir. |
+| `!start` | `spike` | `workflows/02b-spike-workflow.md` | `workspace/memory/decisions.md` ADR veya yeni Task | Teknik belirsizliği gidermek için time-boxed araştırma başlatır. |
+| `!start` | `development` | `workflows/04-development-cycle.md` | Aktif item akışı | Backlog'daki uygun item üzerinde geliştirmeyi başlatır. |
+| `!deploy` | `prod` | `workflows/06-deployment-cycle.md` | `workspace/reports/delivery-reports.md` | Production deployment akışını başlatır. |
+| `!rollback` | `[version]` | `workflows/07-rollback-pipeline.md` | Rollback kayıtları | Son güvenli sürüme geri dönüş akışını başlatır. |
+| `!hotfix` | `[issue-id]` | `workflows/08-hotfix-pipeline.md` | Hotfix kayıtları | Kritik production hatası için hotfix akışını başlatır. |
+| `!maintenance` | — | `workflows/09-maintenance-cycle.md` | `workspace/reports/status-reports.md` | Rutin bakım döngüsünü başlatır (bağımlılık, teknik borç, güvenlik). |
+| `!status` | — | `scripts/kortext-backlog-health.py` + `context-check.py` | Hızlı durum özeti | Backlog sağlığı, aktif ajanlar ve blokerları özetler. |
+| `!status` | `full` | Tüm rapor dosyaları | Tam sistem raporu | Deployment durumu, test coverage ve maliyet dahil tam rapor. |
+| `!request` | `[açıklama]` | Talep alım süreci | `workspace/memory/backlog/` adayı | Yeni feature, improvement, bug veya debt talebini sisteme alır. |
+| `!approve` | `[artifact]` | Onay noktası | İlgili artifact status kaydı | Bekleyen kararı onaylar ve akışı ilerletir. |
+| `!reject` | `[artifact] [sebep]` | Revizyon noktası | İlgili artifact status kaydı | Bekleyen çıktıyı revizyona geri gönderir. |
+
+## Yorumlama Kuralları
+
+- Komutlar yalnızca workflow giriş kapıları ve onay noktalarıdır.
+- Test, review, security check, handover, sync ve release note üretimi workflow içindeki adımlardır; ayrı komut olarak çağrılmaz.
+- `!start analysis` yalnız yeni projede; `!start onboard` yalnız mevcut projede kullanılır.
+- `!start spike` geliştirme başlamadan önce teknik belirsizlik varsa kullanılır; sprint kapsamını değiştirmez.
+- `!approve` ve `!reject` mutlaka hedef artifact veya item ile birlikte kullanılır.
+- `!status` hızlı özet için; `!status full` tüm rapor dosyalarını kapsayan tam rapor için kullanılır.
+- Dosya yolu yazılırken canonical workspace yolları kullanılır: `workspace/references/`, `workspace/reports/`, `workspace/memory/backlog/`, `workspace/memory/context/[agent-name]-active.md`.
+- Backlog item'ları düz yapıdadır: `TXX-[task-name].md`, `BXX-[bug-name].md`, `DXX-[debt-name].md`.
+- `skills/` ayrı bir çalışma alanıdır; komut referansı bu klasörün içeriğini yönetmez.
+- Görev yaşam döngüsü scriptlerle desteklenir:
+  - `kortext-session-start.py` — oturum başlangıcı (context yükleme ve SESSION_BRIEF)
+  - `kortext-context-check.py` — context bütünlük kontrolü
+  - `kortext-backlog-health.py` — backlog sağlık skoru
+  - `kortext-lock.py` — paylaşımlı dosya kilidi yönetimi
+  - `kortext-item-start.py`
+  - `kortext-item-transition.py`
+  - `kortext-handover.py`
+  - `kortext-item-check.py`
+  - `kortext-backlog-sync.py`
+
+## `!request` Akışı
+
+`!request [açıklama]` komutu geldiğinde +product-manager şu adımları izler:
+
+1. **Sınıflandır**
+   - **Feature:** Yeni özellik veya geliştirme
+   - **Improvement:** Mevcut özelliğin iyileştirilmesi
+   - **Bug:** Hata bildirimi → +engineering-manager'a yönlendirilir
+   - **Debt:** Teknik borç, refactor, test açığı veya operasyonel iyileştirme
+2. **Netleştir**
+   - Beklenen davranış ne?
+   - Hangi kullanıcıyı etkiliyor?
+   - Ne zaman gerekli? (`Acil / Bu versiyon / Gelecek versiyon`)
+3. **Backlog'a al**
+   - Uygun formatta (`TXX-[task-name].md`, `BXX-[bug-name].md`, `DXX-[debt-name].md`) düz backlog altında kayıt aç.
+   - Önceliği +prime'ın aciliyet belirtiminden çıkar.
+4. **Bildir**
+
+```text
+---
+TALEBİN ALINDI
++prime, "[talep özeti]" backlog'a eklendi.
+- Tip: [Feature / Improvement / Bug / Debt]
+- Öncelik: [Blocker / High / Medium / Low]
+- ID: [task-id]
+Komutunu bekliyorum.
+---
+```

package/rules/emergency.md

@@ -0,0 +1,160 @@
+# Acil Durum Prosedürleri
+
+Sistemin kararlılığını veya güvenliğini tehdit eden durumlarda uygulanacak prosedürler.
+
+## Kritik Hata Tanımları
+
+Aşağıdaki durumlar "Acil Durum" olarak kabul edilir:
+
+- **Sonsuz Döngü:** Bir görevin belirlenen adım sayısını (Loop Protection (4-Step Rule) — bkz. `rules/behavior.md`) aşması ve ilerleme kaydetmemesi.
+- **API Kesintisi:** Kritik bir servisin (LLM, Veritabanı vb.) retry ve fallback mekanizmaları tükendikten sonra da hata vermeye devam etmesi (bkz. Self-Healing Protocol).
+- **Yetki İhlali:** Bir personanın yetkisi olmayan bir dosyayı değiştirmeye çalışması.
+- **Veri Kaybı Riski:** Yanlışlıkla silme veya üzerine yazma girişimi tespiti.
+- **Yazma Çakışması:** İki ajanın Distributed Context kuralına uymayıp aynı dosyayı eş zamanlı güncellediğinin tespiti.
+
+## Severity Seviyeleri
+
+| Seviye | Kriter | Beklenen Aksiyon |
+| :--- | :--- | :--- |
+| `P0` | Sistem tamamen çöktü, tüm kullanıcılar etkileniyor veya veri kaybı riski var | Güvenli rollback veya hotfix hemen başlatılır; +prime eş zamanlı bilgilendirilir |
+| `P1` | Temel iş akışı bozuldu veya büyük kullanıcı grubu etkileniyor | Rollback/hotfix kararı hızlıca alınır; +prime bilgilendirilir |
+| `P2` | Sınırlı etki var, workaround mevcut veya kullanıcı etkisi düşük | Normal geliştirme döngüsüne alınabilir; gerekirse +prime kararı istenir |
+
+## Production Acil Durum Kararı
+
+Production ortamında kritik hata tespit edilirse aşağıdaki karar kuralı uygulanır:
+
+| Durum | Akış |
+| :--- | :--- |
+| Son deployment kaynaklı ve güvenli şekilde geri alınabilir | `workflows/07-rollback-pipeline.md` |
+| Rollback veri kaybı, irreversible migration veya daha büyük risk doğuruyorsa | `workflows/08-hotfix-pipeline.md` |
+| Hata eski sürümde de vardı veya izole bir modülde hızlı düzeltilebilir | `workflows/08-hotfix-pipeline.md` |
+| Etki sınırlı ve workaround varsa | `workflows/04-development-cycle.md` içinde Bug/Debt olarak planlanır |
+
+P0 durumda +devops-engineer veya ilgili sorumlu ajan +prime onayını beklemeden güvenli rollback/hotfix hazırlığını başlatabilir. +prime bilgilendirmesi eş zamanlı yapılır.
+
+## Self-Healing Protocol
+
+Sistem kesintilerinde ajan aşağıdaki adımları sırayla uygular. Adım tükenmeden bir sonraki aşamaya geçilmez.
+
+### API / LLM Kesintisi
+
+| Adım | Eylem | Bekleme |
+|---|---|---|
+| **1. Retry** | Aynı model ile isteği tekrarla | 5 sn |
+| **2. Retry** | İkinci deneme | 15 sn |
+| **3. Retry** | Üçüncü deneme | 30 sn |
+| **4. Fallback** | `rules/models.md` → Fallback modele geç, isteği tekrarla | — |
+| **5. Fallback Retry** | Fallback model ile ikinci deneme | 15 sn |
+| **6. HALT** | Tüm denemeler başarısız → işlemi durdur, eskalasyon başlat | — |
+
+> Fallback model `deep-research` görevde devreye girerse sonuç kalitesi düşebilir. Bu riski eskalasyon mesajında +prime'a bildir.
+
+### Git Komut Hataları
+
+| Adım | Eylem | Bekleme |
+|---|---|---|
+| **1. Retry** | Aynı komutu tekrar çalıştır | 3 sn |
+| **2. Retry** | İkinci deneme | 10 sn |
+| **3. Diagnose** | `git status` çalıştır; durumu `workspace/memory/context/[agent-name]-active.md` dosyasına yaz | — |
+| **4. Blocked** | Komutu ve çıktısını kaydet; görevi `Blocked` yap; +devops-engineer'a eskalasyon | — |
+
+**Kategori bazlı yönlendirme:**
+- **Network / auth hatası** (403, 401, SSH): +devops-engineer → credentials kontrol
+- **Merge conflict**: +devops-engineer → `07-rollback-pipeline.md`'ye bak, çözülmezse +engineering-manager
+- **Permission denied**: +prime → repo access kontrol
+- **Repository corrupt / object hatası**: +devops-engineer → +prime
+
+> [!WARNING]
+> `main` branch'te hiçbir git komutu self-healing kapsamında çalıştırılmaz. Force push ve reset --hard kesinlikle yasaktır.
+
+### CI/CD Pipeline Hataları
+
+| Adım | Eylem | Bekleme |
+|---|---|---|
+| **1. Log Oku** | Pipeline logunu oku, hata kategorisini belirle | — |
+| **2. Kategorize** | Tablo aşağıda — kategoriye göre sorumlu ajan belirlenir | — |
+| **3. Notify** | Sorumlu ajana hata kategorisini ve log referansını ilet | — |
+| **4. Blocked** | Sorumlu ajan 3 deneme içinde çözemezse görevi `Blocked` yap; +operation-manager'a eskalasyon | — |
+
+**Hata kategorileri:**
+
+| Hata Türü | İlk Sorumlu | Aksiyon |
+|---|---|---|
+| Test fail (unit/integration) | +qa-engineer | Test kodunu incele, düzelt |
+| Build fail (syntax/compile) | İlgili geliştirici ajan | Kodu incele, düzelt |
+| Environment/env var eksik | +devops-engineer | `.env.example` kontrol, +prime'a eksik key sor |
+| Docker/container hatası | +devops-engineer | Image ve Dockerfile incele |
+| Secrets scan fail | +security-engineer | Sızdırılan key tespit, acil eskalasyon |
+| Timeout | +devops-engineer | Kaynak kullanımı ve pipeline konfigürasyonunu kontrol et |
+
+
+
+1. Ardışık 3 hata → servisi devre dışı kabul et.
+2. İlgili görev dosyasını (`workspace/memory/backlog/[TXX|BXX|DXX]-[item-name].md`) **Blocked** olarak işaretle; blocker nedenini yaz.
+3. +operation-manager'a eskalasyon başlat.
+4. +operation-manager koordinasyonunda ilgili manager geçici çözüm (mock, stub, fallback servis veya bekleme) kararını verene kadar bekle.
+
+## Eskalasyon Zinciri
+
+Bir acil durum tespit edildiğinde aşağıdaki zincir takip edilir:
+
+1. **Durdur:** İşlemi derhal durdur.
+2. **Raporla:** Hatayı ve bağlamı ilgili yöneticiye bildir.
+3. **Bekle:** Yöneticinin talimatı gelene kadar yeni işlem başlatma.
+
+**Eskalasyon Sırası:**
+- Geliştirici personalar → +engineering-manager veya +product-manager (ilgili alana göre)
+- Manager personalar → +operation-manager
+- +operation-manager → +prime
+
+## Kullanıcı Bildirimi Protokolü
+
+P0/P1 sınıfındaki bir acil durumda (production kesintisi, veri kaybı riski) son kullanıcıların bilgilendirilmesi zorunludur. Bu karar +prime'a aittir; ajan sadece hazırlığı yapar.
+
+**Sorumluluk:** +operation-manager bildirimi hazırlar, +prime onaylar ve gönderir.
+
+**Bildirim Şablonu:**
+```
+[Hizmet Adı] — Teknik Kesinti Bildirimi
+Tarih / Saat: [UTC+3]
+
+Etkilenen özellik: [kısa açıklama]
+Beklenen etki: [kullanıcılar hangi işlemleri yapamıyor?]
+Tahmini çözüm süresi: [X dakika / saat]
+
+Çözüm tamamlandığında ikinci bir bildirim gönderilecektir.
+```
+
+**Çözüm Sonrası Bildirim:**
+```
+[Hizmet Adı] — Hizmet Normalüne Döndü
+Kesinti süresi: [başlangıç] → [bitiş] ([X dakika])
+Etkilenen alan: [kısa açıklama]
+Alınan önlem: [kısa teknik not]
+```
+
+## Acil Durum Sonrası
+
+- Olay ilgili manager persona tarafından `workspace/memory/learned.md` dosyasına kaydedilir:
+	- Ne oldu?
+	- Neden oldu?
+	- Nasıl çözüldü?
+	- Tekrarını önlemek için ne yapılmalı?
+- Manager persona +prime için `workspace/reports/status-reports.md` dosyasını hazırlar.
+
+## Bildirim
+
+Yukarıdaki adımlar tamamlandığında bildir. 
+
+```
+---
+ACİL DURUM PROTOKOLÜ UYGULANDI
++prime, [sebep] sebebiyle acil durum protokolüne geçildi.
+Durum: [başladı / devam ediyor / çözüldü]
+Durum raporu: workspace/reports/status-reports.md
+Komutunu bekliyorum.
+---
+```
+
+P0 dışındaki durumlarda komut gelene kadar hazırda bekle ve kuralları koru. P0 durumda güvenli rollback/hotfix hazırlığı durdurulmaz; +prime eş zamanlı bilgilendirilir.

package/rules/mcp.md

@@ -0,0 +1,47 @@
+# MCP Kılavuzu
+
+MCP kullanımı proje teknoloji yığınına göre belirlenir. Ajanlar MCP kurulumu yapmaz; ihtiyaçları belgeler, kurulum ve yetkilendirme +prime tarafından yapılır.
+
+## Sorumluluklar
+
+| Rol | Sorumluluk |
+| :--- | :--- |
+| `+engineering-manager` | Gerekli MCP adaylarını `workspace/references/tech-stack.md` içinde tanımlar |
+| `+devops-engineer` | Kurulum sonrası erişim ve ortam etkisini `workspace/references/access.md` içinde belgeler |
+| `+security-engineer` | MCP'nin yetki kapsamını, token/secret riskini ve güvenlik etkisini değerlendirir |
+| `+prime` | MCP kurulumu, yetkilendirme ve hesap erişimi kararını verir |
+
+## Temel Kurallar
+
+- MCP yalnızca proje ihtiyacı varsa önerilir.
+- MCP adı, kullanım amacı ve hangi ajanların kullanacağı açıkça yazılır.
+- Token, API key veya bağlantı bilgisi `workspace/references/access.md` içine gerçek değer olarak yazılmaz.
+- Gerçek secret değerleri yalnızca `.env` veya ilgili güvenli platform üzerinde tutulur.
+- Kurulan MCP'ler `workspace/references/access.md` dosyasındaki **MCP Sunucuları** bölümüne işlenir.
+- MCP gereksinimleri analysis veya environment setup sırasında netleştirilir.
+
+## Teknoloji → MCP Eşleşmesi
+
+| Teknoloji | MCP |
+| :--- | :--- |
+| Vercel | `@vercel/mcp-server` |
+| Firebase | `@firebase/mcp-server` |
+| Supabase | `@supabase/mcp-server-supabase` |
+| GitHub | `@modelcontextprotocol/server-github` |
+| Figma | `@figma/mcp` |
+| Playwright (E2E Test) | `@playwright/mcp` |
+| Slack | `@modelcontextprotocol/server-slack` |
+| PostgreSQL | `@modelcontextprotocol/server-postgres` |
+
+## Kayıt Formatı
+
+`workspace/references/access.md` içindeki MCP kaydı en az şu bilgileri içerir:
+
+| Alan | Açıklama |
+| :--- | :--- |
+| MCP adı | Kurulan veya önerilen MCP paketi |
+| Amaç | Hangi iş için gerektiği |
+| Kullanan ajanlar | MCP'yi kullanacak persona listesi |
+| Yetki kapsamı | Okuma/yazma, repo, database, deploy gibi izin alanları |
+| Secret gereksinimi | Gerekli env key adları; gerçek değer yazılmaz |
+| Durum | `planned`, `installed`, `blocked`, `removed` |