tillerhand 3.42.1 → 3.47.0

package/docs/workflow/skills.md

@@ -1,11 +1,11 @@
-# Skill Yönlendirme
+# Skill Routing
 
-> Hangi işte hangi skill kullanılır? Skill'i Skill aracıyla yükle, talimatlarını uygula.
-> Bu proje `.claude/settings.json` içinde aşağıdaki plugin'leri tanımlar; Claude Code projeyi açınca kurmayı önerir. Çekirdek dışındakiler paket olarak kapalı gelir (aşağıda "Bağlam paketleri").
-> Bir skill yüklü değilse işi skill'siz yap, durum bloğunda "skill eksik: X" yaz ve kullanıcıya kurulum komutunu ver:
-> `/plugin install <plugin>@<marketplace>` (örn. `/plugin install impeccable@impeccable`).
+> Which skill to use for which job? Load the skill with the Skill tool and apply its instructions.
+> This project defines the plugins below in `.claude/settings.json`; Claude Code suggests installing them when it opens the project. Those outside the core come switched off as packages (see "Context packages" below).
+> If a skill is not installed, do the job without it, write "skill missing: X" in the status block and give the user the install command:
+> `/plugin install <plugin>@<marketplace>` (e.g. `/plugin install impeccable@impeccable`).
 
-| Plugin | Marketplace | Skill önekleri |
+| Plugin | Marketplace | Skill prefixes |
 |---|---|---|
 | caveman | caveman | `caveman:` |
 | impeccable | impeccable | `impeccable:` |
@@ -14,143 +14,143 @@
 | humanizer | humanizer | `humanizer:` |
 | ponytail | ponytail | `ponytail:` |
 | mattpocock-skills | mattpocock | `mattpocock-skills:` |
-| gsap-skills (GreenSock, resmi) | gsap-skills | `gsap-skills:` (`tasarim` paketi) |
-| understand-anything | understand-anything | `/understand --language en`, `/understand-dashboard`, `/understand-onboard` (`yayin` paketi; `--auto-update` kullanılmaz). Açıkken oturum başı hook'u graf eskiyse sormadan günceller ve token harcar: iş bitince `/tools` ile paketi kapat |
-| security-guidance, claude-security, hookify, claude-md-management, session-report | claude-plugins-official (Anthropic) | otomatik hook / `/claude-security`, `/hookify`, `/revise-claude-md`, `/session-report` |
-| typescript-lsp (web, mobil) · pyright-lsp (backend) | claude-plugins-official | Dil sunucusu: tip hatası ve tanıma gitme. `npm i -g typescript-language-server typescript` veya `npm i -g pyright` gerekir |
-| supabase, postgres-best-practices | supabase-agent-skills | `supabase:`, `postgres-best-practices:` (web, mobil; backend'de sadece postgres) |
-| web-quality-skills | addy-web-quality-skills | Core Web Vitals, erişilebilirlik, SEO (web) |
-| expo | expo-plugins | Expo build, yükseltme, dağıtım + Expo MCP (mobil) |
-
-**Vercel skill'leri** (`react-best-practices`, `composition-patterns` web'de; `react-native-guidelines` mobilde) plugin değildir. `/start` stack kararından sonra projeye kopyalar:
+| gsap-skills (GreenSock, official) | gsap-skills | `gsap-skills:` (`tasarim` package) |
+| understand-anything | understand-anything | `/understand --language en`, `/understand-dashboard`, `/understand-onboard` (`yayin` package; `--auto-update` is not used). While on, the session-start hook updates the graph without asking when it is stale and spends tokens: switch the package off with `/tools` when the job is done |
+| security-guidance, claude-security, hookify, claude-md-management, session-report | claude-plugins-official (Anthropic) | automatic hook / `/claude-security`, `/hookify`, `/revise-claude-md`, `/session-report` |
+| typescript-lsp (web, mobile) · pyright-lsp (backend) | claude-plugins-official | Language server: type errors and go to definition. Needs `npm i -g typescript-language-server typescript` or `npm i -g pyright` |
+| supabase, postgres-best-practices | supabase-agent-skills | `supabase:`, `postgres-best-practices:` (web, mobile; only postgres in backend) |
+| web-quality-skills | addy-web-quality-skills | Core Web Vitals, accessibility, SEO (web) |
+| expo | expo-plugins | Expo build, upgrade, distribution + Expo MCP (mobile) |
+
+**Vercel skills** (`react-best-practices`, `composition-patterns` for web; `react-native-guidelines` for mobile) are not plugins. After the stack decision `/start` copies them into the project:
 `npx -y skills@1.7.2 add vercel-labs/agent-skills --skill react-best-practices --skill composition-patterns -a claude-code -y --copy`
 
-**three.js skill'leri** (`threejs-fundamentals`, `threejs-performance`, React'te `threejs-react-three-fiber`; `CloudAI-X/threejs-skills`, MIT) plugin değildir. Sadece 3D seçilirse `/start` 3c sabit commit'ten kopyalar. Her biri ~6k token, çağrılınca yüklenir.
+**three.js skills** (`threejs-fundamentals`, `threejs-performance`, and `threejs-react-three-fiber` for React; `CloudAI-X/threejs-skills`, MIT) are not plugins. Only if 3D is chosen, `/start` 3c copies them from a pinned commit. Each is ~6k tokens, loaded when called.
 
-## Kitin kendi skill'leri (`.claude/skills/`)
+## The kit's own skills (`.claude/skills/`)
 
-| Skill | Ne zaman |
+| Skill | When |
 |---|---|
-| `source-research` | Değişebilen her bilgi (sürüm, fiyat, kota, mevzuat, rakip); teknoloji seçimi; business ve legal raporları |
-| `logo-design` | Logo, ikon, favicon, marka paketi (SVG, API gerektirmez) |
-| `ui-motion` | Uygulama içi animasyon ve geçişler |
-| `motion-video` | Tanıtım videosu, açılış sayfası döngüsü (renderAt(t) + Playwright + ffmpeg) |
+| `source-research` | Any information that can change (version, price, quota, regulation, competitor); technology choice; business and legal reports |
+| `logo-design` | Logo, icon, favicon, brand pack (SVG, needs no API) |
+| `ui-motion` | In-app animation and transitions |
+| `motion-video` | Promo video, landing page loop (renderAt(t) + Playwright + ffmpeg) |
 
-## Araçlar (MCP)
+## Tools (MCP)
 
-| Araç | Ne için | Not |
+| Tool | What for | Note |
 |---|---|---|
-| **Context7** | Kütüphanelerin güncel ve sürüme özel dokümanı | Her tipte açık, ücretsiz |
-| **Playwright CLI** | Arayüz kanıtı, konsol, ağ, ekran görüntüsü (`npx -y @playwright/cli@0.1.22`) | Web'de; MCP'den az token. Kabul testleri yine `npx playwright test` |
-| **Chrome DevTools**, **Playwright** MCP | Performans izi; keşif amaçlı uzun tarayıcı akışı | Varsayılan kapalı; komut sorup ekler (katalog) |
-| **Vercel CLI** | Önizleme ve prod deploy (`npx -y vercel@63.1.1`) | `/release`; `--prod`, `promote`, `rollback` sorulur |
-| **Sentry**, **Supabase** | Hata kayıtları, veritabanı uyarıları (salt-okunur) | `/maintain` |
-| **Firecrawl** | Site tarama | İsteğe bağlı, API anahtarı gerekir; `source-research` §5 |
-| **Maestro**, **Expo** | Mobil E2E testi, EAS build, çökme kayıtları | Mobilde |
-| GitHub, Stripe, Vercel, PostHog, Figma… | Servis seçilince | Katalog: `docs/workflow/mcp-catalog.md` |
+| **Context7** | Current, version-specific docs of libraries | On for every project type, free |
+| **Playwright CLI** | Interface evidence, console, network, screenshots (`npx -y @playwright/cli@0.1.22`) | In web; fewer tokens than the MCP. Acceptance tests still run with `npx playwright test` |
+| **Chrome DevTools**, **Playwright** MCP | Performance trace; long exploratory browser flows | Off by default; the command asks and adds it (catalog) |
+| **Vercel CLI** | Preview and prod deploy (`npx -y vercel@63.1.1`) | `/release`; `--prod`, `promote`, `rollback` are asked |
+| **Sentry**, **Supabase** | Error logs, database warnings (read-only) | `/maintain` |
+| **Firecrawl** | Site crawling | Optional, needs an API key; `source-research` §5 |
+| **Maestro**, **Expo** | Mobile E2E tests, EAS build, crash logs | In mobile |
+| GitHub, Stripe, Vercel, PostHog, Figma… | When the service is chosen | Catalog: `docs/workflow/mcp-catalog.md` |
 
-## Bağlam paketleri
+## Context packages
 
-Açık her plugin'in skill açıklamaları her oturumda bağlama yüklenir. Skill listesi bağlamın %1'iyle sınırlıdır; taşınca az kullanılan skill'lerin açıklaması düşer ve Claude onları tanımaz. Plugin içindeki skill'ler tek tek kapatılamaz. Bu yüzden eklentiler **çekirdek** ve **paket** olarak ayrılır. Paketler `.claude/settings.json`'da kapalı gelir; ilgili komut ilk adımda `node .claude/hooks/tools.mjs --required <paket>` ile bakar, kapalıysa maliyetiyle birlikte açmayı sorar. Açma sadece bu makineyi etkiler (`.claude/settings.local.json`). Yönetim: `/tools`. Tanımlar: `.claude/hooks/tools.mjs` → `PACKAGES`.
+The skill descriptions of every plugin that is on are loaded into the context in each session. The skill list is limited to 1% of the context; when it overflows, the descriptions of rarely used skills drop and Claude does not recognize them. Skills inside a plugin cannot be switched off one by one. So plugins are split into **core** and **packages**. Packages come switched off in `.claude/settings.json`; in its first step the related command checks with `node .claude/hooks/tools.mjs --required <paket>` and, if the package is off, asks to switch it on together with its cost. Switching on affects only this machine (`.claude/settings.local.json`). Management: `/tools`. Definitions: `.claude/hooks/tools.mjs` → `PACKAGES`.
 
-| Paket | Eklentiler | Açan komut |
+| Package | Plugins | Command that switches it on |
 |---|---|---|
-| Çekirdek (hep açık) | caveman, ponytail, mattpocock-skills, impeccable, humanizer, security-guidance, hookify, claude-md-management + stack eklentileri | - |
+| Core (always on) | caveman, ponytail, mattpocock-skills, impeccable, humanizer, security-guidance, hookify, claude-md-management + stack plugins | - |
 | `tasarim` | taste-skill, ui-ux-pro-max, gsap-skills | `/design` |
 | `guvenlik` | Trail of Bits (7), claude-security | `/findings-security`, `/findings-all`, `/release first` |
 | `yayin` | understand-anything, session-report | `/release`, `/handoff`, `/adopt` |
 | `video` | remotion | `motion-video` |
 
-- Paketi oturum ortasında açmak prompt önbelleğini bozar ve bütün bağlam yeniden okunur. En ucuzu faz sınırında, `/clear` ile birlikte açmaktır.
-- Kesin ölçüm: `/context` (Skills satırı), `/doctor`; kullanılmayan skill'ler: `/skill-doctor`. Kaba ölçüm: `/tools olc`. `/maintain monthly` bunu kontrol eder.
-- Bir eklentiyi çekirdeğe almak veya paketten çıkarmak `teknik` karardır.
+- Switching a package on in the middle of a session breaks the prompt cache and the whole context is read again. The cheapest time is at a phase boundary, together with `/clear`.
+- Exact measurement: `/context` (Skills line), `/doctor`; unused skills: `/skill-doctor`. Rough measurement: `/tools olc`. `/maintain monthly` checks this.
+- Moving a plugin into the core or out of a package is a `teknik` decision.
 
-**Komut listesi (Hafif/Tam):** Kitin komut açıklamaları da aynı listeye girer (~1.600 token). Hafif ve Standart profilde çekirdek dışı 19 komut `skillOverrides` → `name-only` ile sadece adıyla listelenir: `/` menüsünde durur, Claude adıyla çağırabilir, açıklaması bağlama girmez. Açıklamasıyla kalan çekirdek: start, adopt, build, fix-bug, plan-task, design, tools, review-changes, wrap-up, release. Tam profil: `node .claude/hooks/tools.mjs --commands full`; geri dönmek: `--commands light`. Ayar `.claude/settings.json`'dadır (ekip geneli); kendi `skillOverrides` değerlerin korunur. Codex ve Antigravity'de etkisi yoktur. Liste: `.claude/hooks/tools.mjs` → `CORE_COMMANDS`, `LIGHT_COMMANDS`.
+**Command list (Light/Full):** The kit's command descriptions go into the same list (~1,600 tokens). In the Light and Standard profile, the 20 commands outside the core are listed by name only with `skillOverrides` → `name-only`: they stay in the `/` menu, Claude can call them by name, their description does not enter the context. The core that keeps its description: start, adopt, build, fix-bug, plan-task, design, tools, review-changes, wrap-up, release. Full profile: `node .claude/hooks/tools.mjs --commands full`; to go back: `--commands light`. The setting is in `.claude/settings.json` (team-wide); your own `skillOverrides` values are kept. It has no effect in Codex and Antigravity. List: `.claude/hooks/tools.mjs` → `CORE_COMMANDS`, `LIGHT_COMMANDS`.
 
-## Skill bütçesi
+## Skill budget
 
-- Backend projelerinde arayüz tasarım plugin'leri (impeccable dahil) kapalı gelir (`kit/templates/backend/.claude/settings.merge.json`).
-- Stack'e özel skill'ler (Supabase, Expo, web kalitesi, LSP) sadece ilgili proje tipinde açılır.
-- security-guidance'ın tur sonu incelemesi kapalı gelir (`ENABLE_STOP_REVIEW=0`, kota). Düzenleme anındaki kalıp taraması (ücretsiz) ve commit incelemesi açıktır. Kota rahatsa `.claude/settings.json` → `env`'den açılabilir.
-- Yeni bir plugin eklemek `teknik` karardır: aynı işi yapan bir skill zaten var mı, kaynak güvenilir mi, bağlam maliyeti nedir? Üçüncü taraf skill'ler bir saldırı yüzeyidir: kurmadan önce SKILL.md içeriğini oku.
+- In backend projects the interface design plugins (including impeccable) come switched off (`kit/templates/backend/.claude/settings.merge.json`).
+- Stack-specific skills (Supabase, Expo, web quality, LSP) are switched on only in the related project type.
+- The end-of-turn review of security-guidance comes switched off (`ENABLE_STOP_REVIEW=0`, quota). The pattern scan at edit time (free) and the commit review are on. If the quota is comfortable, it can be switched on from `.claude/settings.json` → `env`.
+- Adding a new plugin is a `teknik` decision: is there already a skill that does the same job, is the source trustworthy, what is the context cost? Third-party skills are an attack surface: read the SKILL.md content before installing.
 
-## İletişim
+## Communication
 
-| Durum | Skill |
+| Situation | Skill |
 |---|---|
-| Durum bloğu, ilerleme notları, kod açıklamaları | `caveman:caveman` (oturum başında yükle). Sorular, seçenek açıklamaları ve dokümanlar bundan muaftır, tam cümle yazılır |
+| Status block, progress notes, code explanations | `caveman:caveman` (load at session start). Questions, option descriptions and documents are exempt; write full sentences |
 
-## Fikir, ürün ve mimari
+## Idea, product and architecture
 
-| Durum | Skill |
+| Situation | Skill |
 |---|---|
-| Fikri ve planı sorgulamak (`/start` 1. adım, büyük özellik planı) | `mattpocock-skills:grilling` (soruları AskUserQuestion ile sor) |
-| Kavramlar, sözlük, karar kaydı (`docs/product/glossary.md`, `docs/decisions/`) | `mattpocock-skills:domain-modeling` |
-| Modül sınırları, arayüz tasarımı, test edilebilir yapı (`docs/architecture/`) | `mattpocock-skills:codebase-design` |
-| Teknoloji karşılaştırma, güncel sürüm/fiyat/doküman araştırması | `mattpocock-skills:research` |
-| Bir durum modelini veya akışı denemek (atılacak prototip) | `mattpocock-skills:prototype` |
-| Kullanıcının elle yapması gereken kurulum (panel, DNS, anahtar, mağaza hesabı) | `mattpocock-skills:wizard` |
+| Questioning the idea and the plan (`/start` Step 1, big feature plan) | `mattpocock-skills:grilling` (ask the questions with AskUserQuestion) |
+| Concepts, glossary, decision record (`docs/product/glossary.md`, `docs/decisions/`) | `mattpocock-skills:domain-modeling` |
+| Module boundaries, interface design, testable structure (`docs/architecture/`) | `mattpocock-skills:codebase-design` |
+| Technology comparison, research on current version/price/docs | `mattpocock-skills:research` |
+| Trying out a state model or flow (throwaway prototype) | `mattpocock-skills:prototype` |
+| Setup the user must do by hand (panel, DNS, key, store account) | `mattpocock-skills:wizard` |
 
-## Tasarım (web ve mobil arayüz)
+## Design (web and mobile UI)
 
-Önce stil yönü seçilir (`/design`). Her yön bir skill'e eşlenir; önizlemeler ve uygulama o skill'le yapılır. Ürün bağlamı ve tasarım sistemi her zaman Impeccable'da (`PRODUCT.md`, `DESIGN.md`) tutulur.
+First the style direction is chosen (`/design`). Each direction maps to a skill; previews and implementation are done with that skill. Product context and the design system are always kept in Impeccable (`PRODUCT.md`, `DESIGN.md`).
 
-| Stil yönü (kullanıcıya sunulan seçenek) | Ne zaman iyi | Ana skill |
+| Style direction (option shown to the user) | When it is good | Main skill |
 |---|---|---|
-| **Premium / Apple tarzı:** bol boşluk, büyük ve ince tipografi, yumuşak geçişler, pahalı his | Tüketici ürünü, marka algısı önemli, fiyatı yüksek ürün | `taste-skill:high-end-visual-design` |
-| **Minimal editoryal:** sıcak monokrom, tipografi odaklı, düz yüzeyler | İçerik, portfolyo, sakin SaaS, güven veren hizmet | `taste-skill:minimalist-ui` |
-| **Cesur ve hareketli:** dev tipografi, kaydırmaya bağlı animasyonlar (GSAP), bento ızgaralar | Lansman sayfası, genç kitle, dikkat çekmesi gereken ürün | `taste-skill:gpt-taste` |
-| **Endüstriyel / brutalist:** ham ızgara, terminal estetiği, keskin kontrast | Geliştirici aracı, veri yoğun pano, sıra dışı marka | `taste-skill:industrial-brutalist-ui` |
-| **İşlevsel ürün arayüzü:** sade, yoğun bilgi, hızlı kullanım | Panel, admin, B2B araç, formlar | `impeccable:impeccable` + `ui-ux-pro-max:ui-styling` (shadcn/ui) |
-| **Kendi yönünü bul (anti-generic):** brief'ten yön çıkarır | Hiçbiri tam uymuyorsa | `taste-skill:design-taste-frontend` |
-
-| Tasarım işi | Skill |
+| **Premium / Apple style:** lots of white space, large and thin typography, soft transitions, expensive feel | Consumer product, brand perception matters, high-priced product | `taste-skill:high-end-visual-design` |
+| **Minimal editorial:** warm monochrome, typography-led, flat surfaces | Content, portfolio, calm SaaS, trust-building service | `taste-skill:minimalist-ui` |
+| **Bold and animated:** giant typography, scroll-linked animations (GSAP), bento grids | Launch page, young audience, product that must grab attention | `taste-skill:gpt-taste` |
+| **Industrial / brutalist:** raw grid, terminal aesthetic, sharp contrast | Developer tool, data-heavy dashboard, unconventional brand | `taste-skill:industrial-brutalist-ui` |
+| **Functional product UI:** plain, dense information, fast to use | Panel, admin, B2B tool, forms | `impeccable:impeccable` + `ui-ux-pro-max:ui-styling` (shadcn/ui) |
+| **Find your own direction (anti-generic):** derives a direction from the brief | If none fits exactly | `taste-skill:design-taste-frontend` |
+
+| Design job | Skill |
 |---|---|
-| Ürün bağlamını yazmak (`PRODUCT.md`), PRD'den beslenerek | `impeccable:impeccable` → `init` |
-| Görsel dünyayı kaydetmek (`DESIGN.md`), seçilen önizlemeden | `impeccable:impeccable` → yeni iş akışı |
-| Renk paleti ve yazı tipi çifti adayları, ürün tipine göre | `ui-ux-pro-max:ui-ux-pro-max` |
-| Tasarım belirteçleri ve bileşen kuralları | `ui-ux-pro-max:design-system` |
-| Ekran/bölüm üretmek | Seçilen yön skill'i + `impeccable:impeccable` |
-| Bitmiş ekranı değerlendirmek ve düzeltmek | `impeccable:impeccable` → `critique`, `audit`, `polish` (gerekirse `bolder`/`quieter`/`distill`/`harden`/`adapt`/`animate`) |
-| Var olan bir arayüzü yenilemek | `taste-skill:redesign-existing-projects` + `impeccable:impeccable` |
-| Logo, marka kimliği | `ui-ux-pro-max:design`, `ui-ux-pro-max:brand` |
-| Sosyal medya/reklam görselleri | `ui-ux-pro-max:banner-design` |
-| Mobil ekranlar | Seçilen yön skill'i + `impeccable:impeccable` (iOS/Android platform kılavuzu) + `ui-ux-pro-max:ui-ux-pro-max` (React Native) |
-
-## İçerik
-
-| Durum | Skill |
+| Write the product context (`PRODUCT.md`), fed from the PRD | `impeccable:impeccable` → `init` |
+| Record the visual world (`DESIGN.md`), from the chosen preview | `impeccable:impeccable` → new workflow |
+| Color palette and typeface pair candidates, by product type | `ui-ux-pro-max:ui-ux-pro-max` |
+| Design tokens and component rules | `ui-ux-pro-max:design-system` |
+| Produce a screen/section | Chosen direction skill + `impeccable:impeccable` |
+| Evaluate and fix a finished screen | `impeccable:impeccable` → `critique`, `audit`, `polish` (if needed `bolder`/`quieter`/`distill`/`harden`/`adapt`/`animate`) |
+| Redo an existing interface | `taste-skill:redesign-existing-projects` + `impeccable:impeccable` |
+| Logo, brand identity | `ui-ux-pro-max:design`, `ui-ux-pro-max:brand` |
+| Social media/ad visuals | `ui-ux-pro-max:banner-design` |
+| Mobile screens | Chosen direction skill + `impeccable:impeccable` (iOS/Android platform guidelines) + `ui-ux-pro-max:ui-ux-pro-max` (React Native) |
+
+## Content
+
+| Situation | Skill |
 |---|---|
-| Kullanıcıya görünen her metin: açılış sayfası, ekran metinleri, e-postalar, mağaza açıklaması, duyurular | Önce yaz, sonra `humanizer:humanizer` ile geçir (AI kokan kalıpları temizler) |
+| Every text the user sees: landing page, screen texts, emails, store description, announcements | Write first, then pass it through `humanizer:humanizer` (removes AI-sounding patterns) |
 
-## Bulgu raporları
+## Findings reports
 
-| Durum | Skill / dosya |
+| Situation | Skill / file |
 |---|---|
-| `/findings-<tür>` (tech, business, security, ux, perf, legal, all) | Yöntem `.claude/findings/protocol.md`, bakış açısı `.claude/findings/lenses/<tür>.md` |
-| Derin güvenlik taraması (`/findings-security`) | `/claude-security` (Anthropic, çok ajanlı, bulgular doğrulanmış) |
-| Güvenlik derinliği | Trail of Bits: `differential-review`, `insecure-defaults`, `sharp-edges`, `static-analysis`, `supply-chain-risk-auditor`, `agentic-actions-auditor`, `fp-check` |
-| Business ve legal araştırması | `source-research` + web araması |
-| Teknik ve performans taraması | `ponytail:ponytail-audit` |
-| UX taraması | `impeccable:impeccable` → `audit`, `critique` |
+| `/findings-<type>` (tech, business, security, ux, perf, legal, all) | Method `.claude/findings/protocol.md`, lens `.claude/findings/lenses/<type>.md` |
+| Deep security scan (`/findings-security`) | `/claude-security` (Anthropic, multi-agent, findings verified) |
+| Security depth | Trail of Bits: `differential-review`, `insecure-defaults`, `sharp-edges`, `static-analysis`, `supply-chain-risk-auditor`, `agentic-actions-auditor`, `fp-check` |
+| Business and legal research | `source-research` + web search |
+| Technical and performance scan | `ponytail:ponytail-audit` |
+| UX scan | `impeccable:impeccable` → `audit`, `critique` |
 
-## Kod
+## Code
 
-| Durum | Skill |
+| Situation | Skill |
 |---|---|
-| Her kod değişikliği (en küçük tam çözüm, gereksiz soyutlama yok) | `ponytail:ponytail` |
-| Kritik akış (auth, ödeme, veri yazma; `docs/quality/test-plan.md` K1-K5) | `mattpocock-skills:tdd` (kırmızı testi `test-writer` ajanı yazar, yeşile kod tarafı çevirir) |
-| Bozulan projeyi son çalışan hale döndürmek | `/rollback` (`checkpoint.mjs`) |
-| Yeni başlayan kullanıcıya her adımı anlatmak | Anlatıcı mod: `.claude/output-styles/anlatici.md` (`outputStyle: anlatici`) |
-| Hata ayıklama (`/fix-bug`) | `mattpocock-skills:diagnosing-bugs` + `/freeze <klasör>` |
-| Değişiklik incelemesi (`/review-changes`) | `ponytail:ponytail-review` + `code-reviewer` ajanı (+ `security-auditor`) |
-| Görev/spec'e uygunluk incelemesi (dal veya PR) | `mattpocock-skills:code-review` |
-| Tüm kod tabanı kalite denetimi (`/release ilk`, `/maintain quarterly`) | `ponytail:ponytail-audit` |
-| Ertelenen kısa yolların listesi (`/maintain monthly`) | `ponytail:ponytail-debt` |
-| PR açıklaması | `mattpocock-skills:pr` |
-| CLAUDE.md, komut veya skill düzenlemek (`/retro`) | `mattpocock-skills:writing-for-agents` |
-| CLAUDE.md denetimi, oturum dersleri (`/retro`, `/wrap-up`) | `claude-md-management`: `claude-md-improver`, `/revise-claude-md` |
-| "Bunu bir daha yapma" → kalıcı kural | `/hookify <kural>` (`.claude/hookify.*.local.md`) |
-| React/Next performans (web) · React Native (mobil) | `react-best-practices`, `composition-patterns` · `react-native-guidelines` (Vercel) |
-| Veritabanı şeması, sorgu, indeks | `postgres-best-practices:*`, `supabase:*` |
-| Token ve maliyet ayrıntısı | `/session-report` (HTML), pano için `node .claude/hooks/cost.mjs` |
+| Every code change (smallest complete solution, no needless abstraction) | `ponytail:ponytail` |
+| Critical flow (auth, payment, data writes; `docs/quality/test-plan.md` K1-K5) | `mattpocock-skills:tdd` (the `test-writer` agent writes the red test, the code side turns it green) |
+| Return a broken project to the last working state | `/rollback` (`checkpoint.mjs`) |
+| Explain every step to a new user | Narrator mode: `.claude/output-styles/anlatici.md` (`outputStyle: anlatici`) |
+| Debugging (`/fix-bug`) | `mattpocock-skills:diagnosing-bugs` + `/freeze <folder>` |
+| Change review (`/review-changes`) | `ponytail:ponytail-review` + `code-reviewer` agent (+ `security-auditor`) |
+| Conformance review against task/spec (branch or PR) | `mattpocock-skills:code-review` |
+| Quality audit of the whole codebase (`/release first`, `/maintain quarterly`) | `ponytail:ponytail-audit` |
+| List of deferred shortcuts (`/maintain monthly`) | `ponytail:ponytail-debt` |
+| PR description | `mattpocock-skills:pr` |
+| Edit CLAUDE.md, a command or a skill (`/retro`) | `mattpocock-skills:writing-for-agents` |
+| CLAUDE.md audit, session lessons (`/retro`, `/wrap-up`) | `claude-md-management`: `claude-md-improver`, `/revise-claude-md` |
+| "Don't do this again" → permanent rule | `/hookify <kural>` (`.claude/hookify.*.local.md`) |
+| React/Next performance (web) · React Native (mobile) | `react-best-practices`, `composition-patterns` · `react-native-guidelines` (Vercel) |
+| Database schema, query, index | `postgres-best-practices:*`, `supabase:*` |
+| Token and cost detail | `/session-report` (HTML), `node .claude/hooks/cost.mjs` for the dashboard |

package/docs/workflow/usage-limits.md

@@ -1,79 +1,79 @@
-# Limit Planı
+# Limit Plan
 
-> Claude aboneliğinin 5 saatlik ve haftalık kullanım limitleri iş planlanırken hesaba katılır.
-> Amaç: İşin yarıda kalıp bağlamın kaybolmaması ve kullanıcının limit konusunda şaşırmaması.
-> **Limit sadece uyarı sebebidir, durma sebebi değildir.** Kullanıcı "dur" demedikçe iş devam eder; uyarı tek satırdır ve onay beklemez.
+> The 5-hour and weekly usage limits of the Claude subscription are factored into work planning.
+> Goal: work is not cut off with context lost, and the user is not surprised by the limit.
+> **The limit is only a reason to warn, not a reason to stop.** Work continues unless the user says "stop"; the warning is one line and waits for no approval.
 
-## 1. Limit nereden okunur (sırayla)
+## 1. Where to read the limit (in order)
 
-1. **Masaüstü uygulaması:** `get_usage` aracı (ccd session management). Kesin yüzde ve sıfırlanma saati verir.
-2. **Terminal / IDE:** `node .claude/hooks/usage.mjs`. Durum çubuğu, Claude Code'un gönderdiği `rate_limits` bilgisini `.claude/state/usage.json`'a yazar; bu komut onu okur. İlk API yanıtından önce boş olabilir. 30 dakikadan eskiyse doğrula.
-3. **İkisi de yoksa:** Kullanıcıdan `/usage` çıktısındaki yüzdeleri iste.
+1. **Desktop app:** the `get_usage` tool (ccd session management). It gives the exact percentage and the reset time.
+2. **Terminal / IDE:** `node .claude/hooks/usage.mjs`. The status line writes the `rate_limits` data that Claude Code sends into `.claude/state/usage.json`; this command reads it. It may be empty before the first API response. If it is older than 30 minutes, verify it.
+3. **If neither exists:** Ask the user for the percentages from the `/usage` output.
 
-## 2. Seviyeler
+## 2. Levels
 
-| Seviye | 5 saatlik | Haftalık | Davranış |
+| Level | 5-hour | Weekly | Behavior |
 |---|---|---|---|
-| 🟢 yeşil | < %60 | < %70 | Normal çalış. Durum bloğunda limiti göster. |
-| 🟡 sarı | %60–84 | %70–89 | İş başlamadan tahmini maliyeti söyle. Kurul toplantılarında üye sayısını yarıya indir. |
-| 🔴 kırmızı | ≥ %85 | ≥ %90 | Yeni iş başlamadan tahmini maliyeti ve kalan payı tek satırla söyle, işe devam et. §3'teki seçenekleri sadece kullanıcı isterse sun. |
+| 🟢 green | < 60% | < 70% | Work normally. Show the limit in the status block. |
+| 🟡 yellow | 60–84% | 70–89% | Before work starts, state the estimated cost. In board meetings, halve the member count. |
+| 🔴 red | ≥ 85% | ≥ 90% | Before new work starts, state the estimated cost and the remaining share in one line, then continue. Offer the options in §3 only if the user asks. |
 
-Eşikler `.claude/hooks/usage.mjs` → `ESIKLER` içinde; değiştirirsen ikisini birlikte değiştir.
+The thresholds are in `.claude/hooks/usage.mjs` → `ESIKLER`; if you change them, change both together.
 
-## 3. İş planlanırken
+## 3. When planning work
 
-`/start`, `/plan-task`, `/build`, `/board convene` ve `/release` başlamadan önce:
+Before `/start`, `/plan-task`, `/build`, `/board convene` and `/release` begin:
 
-1. Limiti oku ve işin maliyetini tahmin et. Tahmin tablosu aşağıda; `docs/workflow/cost-log.md`'de en az 3 kayıt varsa onların ortalamasını kullan.
+1. Read the limit and estimate the cost of the work. The estimate table is below; if `docs/workflow/cost-log.md` has at least 3 records, use their average.
 
-| İş | Tahmini 5 saatlik kullanım (Pro plan, başlangıç tahmini) |
+| Work | Estimated 5-hour usage (Pro plan, starting estimate) |
 |---|---|
-| Küçük görev (1-2 dosya) | %3–6 |
-| Orta görev (3-6 dosya + test) | %8–15 |
-| Büyük görev (çok dosya, yeni modül) | %20+ (önce bölmeyi öner) |
-| Plan veya görev sonu kurul toplantısı | %2–5 |
-| Commit denetimi (hafif) | %1 |
-| Tam kurul toplantısı (faz sonu, canlıya alma) | %8–15 |
-| `/design` görsel önizleme turu | %5–10 |
-| `/start` Hızlı derinlik (kurul ve tasarım sonraya) | %25–35 |
-| `/start` Standart derinlik | %50–70 |
-| `/start` Ayrıntılı derinlik (tam akış) | %80–100 (Pro'da bir pencerenin tamamı) |
-| Karar konseyi (`/start` Adım 4, tek yönlü karar) | ~%12 (ölçüm: 3 danışman + başkan) |
-| Kurul kurulumu (`/start` Adım 6) | %5–10 |
-| Tasarım yönü (`/start` Adım 7, `/design genel`) | %15–30 |
-| `/research` hızlı · derin | %10–15 · %25–35 |
-
-Max planda yüzdeler daha düşüktür. Günlük doldukça tahmin kendini düzeltir.
-
-2. **Tahmin kalan payı aşıyorsa** veya seviye kırmızıysa bunu tek satırla söyle ("Tahmin %15, kalan %10: iş yarım kalabilir; istersen seçenekleri sunarım") ve işe başla. Soru sorma, onay bekleme. Kullanıcı isterse şu seçenekleri sun:
-   - **Limite sığanı yap, kalanı sıraya koy:** İşleri önceliğe göre sırala, sığanları yap, kalanları `docs/workflow/progress.md` → "Sıradaki adım"a yaz.
-   - **Hepsini başlat, kesilirse yenilenince devam:** §4'teki uyarılarla devam et. Yenilenince devam için:
-     - Masaüstü uygulamasında sıfırlanma saatine zamanlanmış görev kur (scheduled tasks). Görevin içeriği: "Bu projeyi aç, `docs/workflow/progress.md` → Kaldığı yer'den `/build` ile devam et."
-     - Terminalde oturum açık kalacaksa sıfırlanma saatine tek seferlik bir hatırlatma/cron kur. Kalmayacaksa kullanıcıya sıfırlanma saatini söyle; tekrar açtığında oturum başı notu kaldığı yeri hatırlatır.
-   - **Ucuz modele geçerek devam:** Kod rolünü bir alt modele al (örn. `node .claude/hooks/models.mjs --set code=haiku:medium`; `docs/workflow/models.md`). Ana ajan sadece koordine eder ve sonucu doğrular. Güvenlik, veri modeli ve mimari kararlar planlama rolünde kalır.
-   - **Kurulu hafiflet:** Plan ve görev sonu toplantılarına sadece `security-auditor` + `board-architect` katılır. Commit denetimini sadece kod dosyalarında yap, tek üyeyle.
-3. **Haftalık limit sarı veya kırmızıysa** ayrıca tek satırla uyar: Haftalık limit geç yenilenir.
-4. Kullanıcı bir seçenek seçtiyse kararı `docs/decisions/log.md` günlüğüne `maliyet` konusu olarak yaz.
-5. **Görev = oturum.** Her tur, oturumdaki bütün bağlamı yeniden okur; önceki görevin dosyaları ve çıktıları sonraki görevde boşuna para tutar. Görev bitip commit atılınca `/clear` öner (bağlam yüzdesinden bağımsız). Yeni oturum `docs/workflow/progress.md`'den devam eder.
-
-## 4. Çalışırken limit uyarıları
-
-İş durmaz; her eşikte bir kez, tek satır uyarı verilir:
-
-| 5 saatlik | Ne yapılır |
+| Small task (1-2 files) | 3–6% |
+| Medium task (3-6 files + tests) | 8–15% |
+| Large task (many files, new module) | 20%+ (suggest splitting first) |
+| Board meeting at plan or task end | 2–5% |
+| Commit review (light) | 1% |
+| Full board meeting (phase end, go-live) | 8–15% |
+| `/design` visual preview round | 5–10% |
+| `/start` Quick depth (board and design later) | 25–35% |
+| `/start` Standard depth | 50–70% |
+| `/start` Detailed depth (full flow) | 80–100% (a whole window on Pro) |
+| Decision council (`/start` Step 4, one-way decision) | ~12% (measured: 3 advisors + chair) |
+| Board setup (`/start` Step 6) | 5–10% |
+| Design direction (`/start` Step 7, `/design general`) | 15–30% |
+| `/research` quick · deep | 10–15% · 25–35% |
+
+On the Max plan the percentages are lower. As the log fills day by day, the estimate corrects itself.
+
+2. **If the estimate exceeds the remaining share** or the level is red, say so in one line ("Estimate 15%, remaining 10%: the work may be left unfinished; I can offer the options if you want") and start the work. Do not ask a question and do not wait for approval. If the user wants, offer these options:
+   - **Do what fits the limit, queue the rest:** Order the tasks by priority, do those that fit, and write the rest to `docs/workflow/progress.md` → "Sıradaki adım" (next step).
+   - **Start everything; if cut off, continue after the reset:** Continue with the warnings in §4. To continue after the reset:
+     - In the desktop app, set up a scheduled task for the reset time (scheduled tasks). Task text: "Open this project and continue with `/build` from `docs/workflow/progress.md` → "Kaldığı yer" (where we left off)."
+     - In the terminal, if the session will stay open, set a one-time reminder/cron for the reset time. If it will not stay open, tell the user the reset time; when they reopen, the session-start note reminds them where they left off.
+   - **Continue with a cheaper model:** Move the code role to a lower model (e.g. `node .claude/hooks/models.mjs --set code=haiku:medium`; `docs/workflow/models.md`). The main agent only coordinates and verifies the result. Security, data model and architecture decisions stay in the planning role.
+   - **Lighten the board:** Only `security-auditor` + `board-architect` join plan-end and task-end meetings. Run the commit review only on code files, with a single member.
+3. **If the weekly limit is yellow or red,** also warn in one line: the weekly limit resets late.
+4. If the user chose an option, write the decision to the `docs/decisions/log.md` decision log as topic `maliyet`.
+5. **Task = session.** Every turn re-reads the whole session context; the files and outputs of the previous task cost money in the next one for nothing. When a task is done and committed, suggest `/clear` (regardless of the context percentage). The new session continues from `docs/workflow/progress.md`.
+
+## 4. Limit warnings while working
+
+Work does not stop; a one-line warning is given once at each threshold:
+
+| 5-hour | What to do |
 |---|---|
-| %90 | Hatırlat: "Limit %90, sıfırlanma HH:MM." İşe devam. |
-| %95 | Uyar: "Limit çok azaldı (%95)." `docs/workflow/progress.md` → **Kaldığı yer**'i sessizce güncelle (iş kesilirse oradan devam edilsin). İşe devam. |
-| %99 | Uyar: "Limit bu işe yetmeyebilir, iş yarım kalabilir." Adımları küçük tut ve yarım dosya bırakma; uygun noktada WIP commit öner. Kullanıcı "dur" demedikçe devam. |
+| 90% | Remind: "Limit 90%, resets at HH:MM." Continue the work. |
+| 95% | Warn: "Limit is very low (95%)." Quietly update `docs/workflow/progress.md` → **Kaldığı yer** (where we left off), so work can resume from there if it is cut off. Continue the work. |
+| 99% | Warn: "The limit may not be enough for this work; it may be left unfinished." Keep steps small and leave no half-written files; suggest a WIP commit at a suitable point. Continue unless the user says "stop". |
 
-**Kullanıcı "dur" derse** güvenli dur:
+**If the user says "stop",** stop safely:
 
-1. Yarım dosya bırakma; mevcut adımı tamamla veya geri al.
-2. Testleri çalıştır. Kırmızıysa bunu not et.
-3. WIP commit öner (`wip: <görev> - limit nedeniyle durdu`).
-4. `docs/workflow/progress.md` → **Kaldığı yer** bölümünü doldur: görev, tamamlanan adımlar, sıradaki adım, açık dosyalar, bekleyen kararlar, yenilenme saati.
-5. Durum bloğuyla raporla.
+1. Leave no half-written file; finish the current step or undo it.
+2. Run the tests. If they are red, note it.
+3. Suggest a WIP commit (`wip: <task> - stopped because of the limit`).
+4. Fill in the `docs/workflow/progress.md` → **Kaldığı yer** section: task, completed steps, next step, open files, pending decisions, reset time.
+5. Report with the status block.
 
-## 5. Maliyet günlüğü (tahmini kalibre etmek için)
+## 5. Cost log (to calibrate the estimate)
 
-`/build` ve tam kurul toplantıları başlangıçta ve sonda 5 saatlik yüzdeyi okur ve `docs/workflow/cost-log.md`'ye bir satır ekler: başta `node .claude/hooks/progress.mjs --start`, sonda `--cost "<iş>" <boyut>` (yüzdeler, fark ve süre hesaplanır; pencere arada yenilendiyse fark `?`; masaüstünde iki çağrıya da `--limit <%>`). Yüzdeler elle de verilebilir: `--cost "<iş>" <boyut> <başlangıç %> <bitiş %> <dk>`. Limit okunamıyorsa satır eklenmez.
+`/build` and full board meetings read the 5-hour percentage at the start and at the end and add one row to `docs/workflow/cost-log.md`: `node .claude/hooks/progress.mjs --start` at the start, `--cost "<job>" <size>` at the end (percentages, difference and duration are computed; if the window reset in between, the difference is `?`; on the desktop pass `--limit <%>` to both calls). The percentages can also be given by hand: `--cost "<job>" <size> <start %> <end %> <min>`. If the limit cannot be read, no row is added.