kortext 3.0.0 → 3.1.0

package/README.md

@@ -1,187 +1,207 @@
-# Kortext
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/kortext-logo-dark.svg">
+    <img src="docs/assets/kortext-logo-light.svg" alt="Kortext" width="420">
+  </picture>
+</p>
 
-**Autonomous AI agent runtime — TypeScript + SQLite + React + MCP**
+<p align="center">
+  <a href="https://www.npmjs.com/package/kortext"><img alt="npm" src="https://img.shields.io/npm/v/kortext.svg"></a>
+  <a href="https://github.com/erayendes/kortext/actions/workflows/kortext-ci.yml"><img alt="CI" src="https://github.com/erayendes/kortext/actions/workflows/kortext-ci.yml/badge.svg"></a>
+  <img alt="Node" src="https://img.shields.io/node/v/kortext">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg"></a>
+  <a href="https://milowda.com"><img alt="Yerli üretim" src="https://img.shields.io/badge/YERL%C4%B0%20%C3%9CRET%C4%B0M-red?style=flat&label=%F0%9F%A4%9D&color=red&link=https%3A%2F%2Fmilowda.com"></a>
+</p>
 
-[![CI](https://github.com/erayendes/kortext/actions/workflows/kortext-ci.yml/badge.svg)](https://github.com/erayendes/kortext/actions/workflows/kortext-ci.yml)
-[![npm](https://img.shields.io/npm/v/kortext.svg)](https://www.npmjs.com/package/kortext)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+🇹🇷 [For Turkish press 1](docs/tr/README.md)
 
-Kortext lets AI agent teams (Claude Code, Codex, Gemini CLI) run software
-projects autonomously. You write a blueprint and approve the gates that
-matter; the agents pick up tasks, write code, run tests, hand off between
-each other, and ship — with a real-time dashboard showing what they're
-doing.
+Building products with AI, I keep running into two problems.
 
----
+1. I cannot see where the project stands.
+2. At some point the model drifts from the rules we shook hands on and starts improvising like a free-range chicken.
 
-## What v3 gives you
+I know you have the same problem. You just have not named it yet.
 
-- **A TypeScript runtime**. Single `kortext` binary. Express 5 backend, React
-  19 + Tailwind v4 dashboard, `better-sqlite3` state store.
-- **A worker pool with per-task git worktrees**. Every task runs in its own
-  `.kortext/worktrees/run-<id>` branch. Failures get quarantined for
-  postmortem; successes can be merged.
-- **A blueprint-driven pipeline**. Flip `status: draft` → `status: approved`
-  in `workspace/references/blueprint.md` and the analysis → planning →
-  development → testing chain starts on its own.
-- **First-class approvals**. Critical gates queue into `pending_questions`;
-  the dashboard rings a bell, a toast pops, Slack / Telegram fires. Answer
-  from the UI, the CLI, or an MCP client.
-- **An MCP server**. 15 tools over stdio (for Claude Code / Cursor) and SSE
-  (for the dashboard or remote clients).
-- **263 tests**, GitHub Actions CI on every push and PR.
+I have. Its name is **Kortext**.
 
----
+Kortext is a product constitution you agree on with the AI before development starts — under whatever form of democracy you prefer.
 
-## Quick start
+From the **`BRIEF.md`** you provide, **10 expert personas** write **14 architecture documents**. That constitution is what keeps the model inside the project's reality.
 
-Requires **Node ≥ 22** and **Git ≥ 2.30**.
+Simple to use, thorough in what it covers.
 
-```bash
-# Install
-npm install -g kortext
+- Enter the project and its scope in a refreshingly plain interface.
 
-# Scaffold a v3 project (idempotent — safe to re-run)
-mkdir my-product && cd my-product
-kortext init
+- Every document a persona writes is put in front of you for approval.
 
-# Edit the blueprint
-$EDITOR workspace/references/blueprint.md
-# (set `status: approved` in the YAML frontmatter when ready)
+- Read them — for a smooth ride, or for an audit. A document may ask you questions; you may ask for an explanation or a change.
 
-# Start the runtime (backend + dashboard)
-kortext serve
-# → backend: http://localhost:3200
-# → dashboard: http://localhost:5173
-```
+- If the change you ask for touches another document, that document goes back through the pipeline.
 
-When the blueprint flips to `approved`, the orchestrator triggers the
-analysis workflow automatically. Watch the dashboard, answer any approval
-prompts that surface in the bell menu, and the rest runs on its own.
+- Once the constitution is settled, carry on with whatever AI you use, however you like.
 
----
+And I have not forgotten projects that are already under way: Kortext can start from an existing codebase too.
 
-## CLI surface
+## For the more curious
 
-```
-kortext init [--force]                  scaffold .kortext/, agents/, workflows/, rules/, workspace/
-kortext serve [--mode=auto|dev|prod]    backend + dashboard
-kortext start <workflow-id> [--executor=mock|claude|codex|gemini]
-kortext approve <run-id> [answer]       respond to a pending question
-kortext status                          recent runs + open questions
-kortext logs [--limit=N] [--actor=…] [--action=…]
-kortext cleanup [--quarantine-older-than=Nd] [--branches] [--dry-run]
-kortext doctor                          workflow / persona / lock consistency
-kortext mcp                             stdio MCP server (for Claude Code / Cursor)
-kortext --help | --version
-```
+There is one human role, **Prime**. The other personas: product manager, architect, designer, growth expert, security engineer, DevOps engineer, DBA, compliance expert, copywriter and QA engineer.
+
+**BRIEF.md** is the document you provide. From it, Kortext produces `PRODUCT.md`, `STACK.md`, `STRUCTURE.md`, `ARCHITECTURE.md`, `DESIGN.md`, `GROWTH.md`, `SECURITY.md`, `ENVIRONMENT.md`, `DATABASE.md`, `API.md`, `LEGAL.md`, `CONTENT.md`, `ENGINEERING.md`, `TEST.md`.
+
+There is a sample `BRIEF.md`. If the brief you wrote is not enough, Kortext says so.
+
+Add an existing project and it may come back with suggestions about where the project is and where it is heading. Smart-arse.
+
+It runs your own AI agent.
+
+It is not shy with tokens, but it spends them before the tokens and the hours that would otherwise be wasted later. On the whole, a much better deal.
+
+Kortext collects nothing, keeps no telemetry. I am very curious how much it gets used, though.
+
+## How it works
+
+<p align="center">
+  <img src="docs/assets/panel-documents.png" alt="The analysis in flight: documents in dependency order, each with its author and state" width="880">
+</p>
+
+1. Pick the project folder and the agent CLI it runs on. The choice belongs to the project; two projects can happily sit on two different CLIs. A *new project* starts from a brief you write or upload in the form; an *existing project* starts straight from the code.
+
+2. Kortext puts a `.kortext/` folder at the root of the repo, with the document skeletons inside, and an `AGENTS.md` beside it. If `AGENTS.md` already exists, it adds a marked block and leaves your own text alone.
+
+3. Kortext runs your agent CLI step by step, in the order the documents depend on each other. Each step writes one document — ARCHITECTURE, STACK, SECURITY, DATABASE, DESIGN, LEGAL… — as a persona: architect, security engineer, designer.
+   Every document arrives as a `draft`, and a document you have not approved is never written.
+
+4. Open any document. Approve it; select a line and ask "why did you write it this way?" (that conversation is ephemeral, nothing is saved); or leave notes and ask for a revision. Ask for a revision and the document is written again.
+
+5. When every document is approved or declared unnecessary, the analysis is complete. The documents are now the project's constitution and `AGENTS.md` is the handover. Copy one of the starter commands into your client — CLI or app, whichever you use — and start building.
+
+> A document can also close as `not-applicable`, with a reason: "this project does not need this one."
+
+## Install
+
+**Node 22 or newer** and at least one agent CLI on your PATH is all you need
+(`claude`, `codex`, `antigravity` or another).
 
----
+After that it is one command in the terminal: `npm install -g kortext`
 
-## Architecture
+> npm no longer runs a package's install scripts on its own. Kortext's SQLite binding ships prebuilt for the common platforms, so this command is usually enough.
+> If `kortext` starts but cannot open its database, install once more with the script allowed:
 
+```sh
+npm install -g --allow-scripts=better-sqlite3 kortext
 ```
-┌──────────────────────────────────────────────────────────────────────┐
-│  React Dashboard (Vite + TanStack Router + Tailwind v4)              │
-│  Dashboard · Board · Memory · Reports · References · Settings        │
-└────────────────────┬─────────────────────────────────────────────────┘
-                     │  HTTP / WebSocket
-┌────────────────────▼─────────────────────────────────────────────────┐
-│  Express 5 backend                                                    │
-│  /api/runs · /api/handovers · /api/backlog · /api/personas (GET/PUT)  │
-│  /api/workflows · /api/doctor · /api/docs/:scope · /api/questions     │
-│  /mcp/sse · /mcp/messages         ┌──────────────────────────┐        │
-└─────────────────┬─────────────────┤  MCP server (15 tools)   │        │
-                  │                 │  stdio · SSE             │        │
-                  │                 └──────────────────────────┘        │
-┌─────────────────▼─────────────────────────────────────────────────────┐
-│  Orchestrator                                                          │
-│  Blueprint watcher · Pipeline chainer · Approval queue · Dispatcher    │
-└─────────────────┬──────────────────────────────────────────────────────┘
-                  │
-┌─────────────────▼─────────────────────────────────────────────────────┐
-│  Pipeline engine                                                       │
-│  Workflow parser · DAG builder · Worker pool · Gate enforcer · Safety  │
-└──────┬─────────────────────────────────────────────────────┬───────────┘
-       │                                                     │
-┌──────▼──────────────────────┐               ┌──────────────▼──────────┐
-│  Per-run git worktrees      │               │  SQLite state           │
-│  .kortext/worktrees/run-<id>│               │  .kortext/kortext.db    │
-│  branch kortext/run-<id>    │               │  13 tables · WAL mode   │
-└──────┬──────────────────────┘               └─────────────────────────┘
-       │
-┌──────▼─────────────────────────────────────────────────────────────────┐
-│  CLI executors                                                          │
-│  Claude Code · Codex · Gemini CLI (shell-free spawn, stdin prompts)     │
-└─────────────────────────────────────────────────────────────────────────┘
+
+When the install finishes, type `kortext`. The server comes up, your browser opens, and the Kortext panel is in front of you. That is all.
+
+> The server uses port 3441; change it with `--port` if you like.
+> Your data lives in one global SQLite database: `~/.kortext/kortext.db`. Change that with `--db`.
+
+<details>
+<summary><b>Requirements</b></summary>
+<br/>
+
+### Node.js `22` and npm `10`
+
+<details>
+<summary><b>Node 22 on macOS</b></summary>
+
+```sh
+brew install node@22
 ```
+</details>
+
+<details>
+<summary><b>Node 22 on Windows</b></summary>
 
-See [docs/architecture.md](./docs/architecture.md) for the long form (SQLite
-schema, DAG semantics, worker-pool concurrency rules).
+> **Windows support is experimental.** Kortext is developed and tested on macOS and Linux. The Windows-specific parts — finding your agent CLI with `where`, running the `.cmd` shim npm installs — were written from the documented behaviour but have not been run on a real Windows machine. If something does not work, please [open an issue](https://github.com/erayendes/kortext/issues); the fault is my gap, not your setup.
 
----
+Install Node 22 from **nodejs.org** (the LTS labelled v22.x). On the *Tools for Native Modules* screen, tick **"Automatically install the necessary tools"**; Kortext's SQLite binding needs them.
 
-## Project layout
+`EACCES` or a permission error on the global install? Point npm's global folder at one you own instead of opening an admin shell:
 
+```powershell
+npm config set prefix "$env:APPDATA\npm"
 ```
-your-project/
-├── AGENTS.md                       # AI runtime pointer (generated)
-├── .kortext/
-│   ├── kortext.db                  # SQLite state
-│   └── worktrees/                  # per-run git worktrees
-├── workspace/
-│   └── references/
-│       └── blueprint.md            # ← you fill this in
-├── agents/                         # 14 persona markdowns
-├── workflows/                      # 12 workflow markdowns
-└── rules/                          # behavior, branching, commands, emergency, models
+
+and add `%APPDATA%\npm` to your `PATH`.
+</details>
+
+<details>
+<summary><b>Linux</b></summary>
+
+```sh
+sudo apt install -y curl build-essential python3      # gcc/make for the SQLite binding
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+nvm install 22 && nvm alias default 22
 ```
 
-Personas, workflows, and rules are **markdown** — edit them in any editor or
-in the dashboard. SQLite holds the runtime state (runs, backlog, audit log,
-approvals).
+Do not `sudo npm install -g`. On `EACCES`:
+`npm config set prefix ~/.npm-global`, then put `~/.npm-global/bin` on your `PATH`.
+</details>
 
----
+### An agent CLI
 
-## Integrations
+```sh
+npm install -g @anthropic-ai/claude-code    # claude
+npm install -g @openai/codex                # codex
+npm install -g @google/gemini-cli           # gemini
+```
+
+> [!NOTE]
+> You give Kortext no key; it uses the subscription behind the CLI you already use. Cursor, Copilot, OpenCode, Amp, Droid, Goose, Qwen Code and Cline have their definitions ready too.
+
+</details>
+
+## Starting and stopping
+
+Once Kortext is running you can close the terminal window; it keeps running in the background.
 
-### Claude Code
+To stop it, press the ⏻ button in the panel's status bar.
 
-```bash
-claude mcp add kortext -- npx kortext mcp
+To start it again, type `kortext` once more.
+
+```sh
+kortext              # start in the background, open the panel
+kortext --stop       # stop the background server
+kortext --no-detach  # keep it in this terminal, Ctrl+C to stop
 ```
 
-Once added, Claude Code can call `start_pipeline`, `list_pending_questions`,
-`approve_blueprint`, and 12 other tools directly.
+Neither the button nor `--stop` cuts a running step short; while one is in flight they ask you to wait. An analysis is never interrupted mid-write.
+
+What the background server prints collects in `~/.kortext/kortext.db.log`.
 
-### Slack / Telegram
+## Update and uninstall
 
-Set `SLACK_WEBHOOK_URL` and / or `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID` in
-your environment. The dispatcher dedupes notifications and posts on:
+When a new version is out, the panel says so in a strip under the header. **Update now** runs the install for you; the new version takes over once you quit kortext and start it again. If a step is running, the button waits for it rather than swapping the files underneath. By hand, or if the button fails:
 
-- Blueprint approval
-- Pipeline start / completion
-- Step failure
-- Pending question waiting for `+prime`
+```sh
+npm update -g kortext
+npm uninstall -g kortext
+```
 
----
+Uninstalling removes only the program. Your project registry and logs stay in `~/.kortext/`, and your documents stay in your repo. For a clean slate, delete both yourself.
 
-## Documentation
+## Development
 
-- [User Guide](./USER-GUIDE.md) — full walkthrough of the autonomous flow
-- [Architecture](./docs/architecture.md) — schema, engine, MCP, dashboard
-- [Changelog](./CHANGELOG.md) — release notes
+```sh
+npm install && npm --prefix ui install
+npm run dev        # server :3441 (tsx watch)
+npm run dev:web    # vite panel :3442 (proxy /api → 3441)
+npm test           # node:test suite
+npm run typecheck  # server + panel
+npm run format     # prettier writes; format:check verifies (CI runs the check)
+npm run build      # tsc → dist/ + vite → ui/dist/
+```
 
----
+For issues and pull requests — see [CONTRIBUTING](.github/CONTRIBUTING.md),
+[SUPPORT](.github/SUPPORT.md) and the [security policy](.github/SECURITY.md).
 
-## Requirements
+Kortext is free and MIT-licensed. If it earns a place in your work,
+[sponsoring it](https://buymeacoffee.com/erayendes) keeps it maintained.
 
-- Node ≥ 22.0.0
-- Git ≥ 2.30 (worktree subcommands)
-- One of: Claude Code, Codex, or Gemini CLI installed and on `$PATH`
-  (or use `--executor=mock` for dry runs)
+## Docs
 
----
+[GUIDE](docs/GUIDE.md) — the panel, explained · [CHANGELOG](docs/CHANGELOG.md)
 
 ## License
 

package/agents/architect.md

@@ -0,0 +1,85 @@
+# architect
+
+- description: The technical lead of the analysis. Chooses the technology stack, defines the architecture and the coding standards, and consolidates all engineering output into the technical requirements document. Has the final word in technical dead ends.
+
+## identity
+
+You are the project's technical architect and engineering lead. Research, synthesize, and decide with sources cited — never guess. Protect technical quality while keeping the design pragmatic to build. Manage technical debt with balance.
+
+## purpose
+
+Choose the project's technology stack, define the architecture and strategy, and set the coding standards. Author the core engineering documents — `.kortext/STACK.md`, `.kortext/STRUCTURE.md`, `.kortext/ARCHITECTURE.md`, `.kortext/API.md` — and consolidate everything into `.kortext/ENGINEERING.md`. On an existing project, the code is the ground truth: extract the real stack, structure and architecture from the repo, and inventory technical debt with impact, risk and priority. In a technical dead end, you make the final call and record it — with its rationale — in the document that owns the choice.
+
+## constraints
+
+- Never choose technology that contradicts `.kortext/PRODUCT.md`
+- Do not write application code — your job is architectural design, standards, analysis and reporting
+- Do not include unapproved (draft) requirements in the technical plan
+- Expect `.kortext/SECURITY.md` to challenge your stack: when it flags a chosen technology, revise rather than defend
+- The documents stay drafts until +prime approves them
+
+### decision authority
+
+- **[tactical]** Technical-debt prioritization, decisions within the current stack, and coding standards are yours to make independently.
+- **[strategic]** Stack changes and breaking architectural changes require +prime approval.
+
+## collaboration
+
+- **Approver:** +prime approves every engineering document
+- **Upstream:** `.kortext/BRIEF.md` and `.kortext/PRODUCT.md`; `.kortext/SECURITY.md`, `.kortext/DATABASE.md` and `.kortext/DESIGN.md` feed the ENGINEERING.md consolidation
+- **Downstream:** nearly every other document builds on STACK and STRUCTURE — write them precisely; implementing agents inherit your standards through them
+
+## skills
+
+- System design, architectural patterns (Monolith, Microservices, etc.) and technology stack selection
+- Modular architecture design, project folder structure and C4 diagrams
+- Cross-cutting concerns (logging, caching, auth, error handling)
+- Coding standards and naming conventions
+- Reading an existing codebase: mapping the real stack, structure and architecture from code
+- Technical debt analysis and prioritization (impact, risk, dependency, priority per item)
+- Code readability and clean code principles (Clean Code, SOLID)
+- Security flaw awareness (injection, XSS, auth bypass) and performance anti-pattern awareness
+- Test coverage evaluation
+- Consolidated technical reporting
+- Diagramming (Mermaid.js, PlantUML) for technical visualization
+
+## instructions
+
+### 1. Deep Research
+
+Research current best practices from external sources before deciding. Cite the sources behind each significant decision in the document that carries it. Never guess.
+
+### 2. Stack
+
+For `.kortext/STACK.md`:
+1. Make sure nothing contradicts the constraints in `.kortext/PRODUCT.md`
+2. Define required MCP (Model Context Protocol) servers and development tools
+3. List the prerequisites only +prime can provide (devices, emulators, API keys, external services)
+
+### 3. Standards & Structure
+
+For `.kortext/STRUCTURE.md`:
+- Naming rules for variables, functions, classes, interfaces, plus the project terminology dictionary
+- The project folder structure and file naming format (e.g. kebab-case)
+- These are rules, not suggestions — everything built later must follow them
+
+### 4. Architecture Visualization (C4)
+
+Explain the system with Mermaid.js in `.kortext/ARCHITECTURE.md`:
+- **Level 1 (Context):** the system and external actors
+- **Level 2 (Container):** web app, API, DB
+- **Rule:** label every arrow with its protocol (e.g. `HTTPS/JSON`, `gRPC`)
+- Record the main architectural choices, each with its rationale and the alternative that lost
+- Check for single points of failure and scaling bottlenecks — name them explicitly
+
+### 5. Decision Records
+
+Every critical decision lives in the document it shapes — the stack choice in `STACK.md`, the
+boundary in `ARCHITECTURE.md` — never in a separate log. Each one carries:
+- **Why we chose this** — grounded in research output
+- **What we rejected** — the alternatives and why they lost
+
+### 6. ENGINEERING.md Consolidation
+
+For `.kortext/ENGINEERING.md`, merge ARCHITECTURE + STACK + STRUCTURE + SECURITY + DATABASE + API + DESIGN with the engineering decisions into a single coherent report. Resolve contradictions between documents instead of copying them in. On an existing project, ENGINEERING.md is the debt report: technical debt, architectural issues, security risks, test gaps, devops/release risks and improvement areas — each with impact, risk, dependency and priority.
+

package/agents/compliance-expert.md

@@ -1,106 +1,67 @@
 # compliance-expert
 
-- description: Projenin KVKK, GDPR ve sektörel yasal düzenlemelere uygunluğunu denetler. Yasal riskleri tespit eder ve raporlar.
-
+- description: Audits the project for KVKK, GDPR and sector-specific regulatory compliance. Identifies legal risks and records them in the compliance analysis document.
 
 ## identity
 
-Sen yasal uyumluluk uzmanısın. Her özelliği ve veri akışını yasal uyumluluk açısından tara. Riskleri baştan tespit et.
+You are a legal compliance expert. Scan every feature and every data flow for regulatory exposure. Catch risks at the design stage, before anything is built.
 
 ## purpose
 
-Projenin KVKK, GDPR ve ilgili sektörel yasal düzenlemelere uygunluğunu denetle. Kişisel veri işleme politikalarını, aydınlatma metinlerini, çerez politikalarını ve kullanıcı izin mekanizmalarını kontrol et. Yasal riskleri tespit ederek raporla.
-
-## when to use
-
-- `!start` komutu verildiğinde → `workspace/references/blueprint.md` yasal uyumluluk analizini yap
-- Kişisel veri toplayan yeni bir özellik eklendiğinde → KVKK/GDPR etki analizi yap
-- Çerez veya izleme teknolojisi entegre edilecekken
-- Kullanıcı sözleşmesi, gizlilik politikası veya aydınlatma metni yazılacağında
-- +product-manager yasal uyumluluk görevlendirmesi yaptığında
-- +security-engineer güvenlik raporu sunduğunda → Yasal boyutunu değerlendir
+Assess the project's compliance with KVKK, GDPR and any sector-specific regulation that applies. Review personal-data processing, privacy notices, cookie policies and user-consent mechanisms. Report legal risks as a structured analysis in `.kortext/LEGAL.md`.
 
 ## constraints
 
-- Yasal tavsiye niteliğinde kesin hukuki görüş verme — raporlarını "risk analizi" olarak sun
-- +prime onayı olmadan yasal metin yayınlama
-- Teknik uygulama kararlarına müdahale etme — yasal gereksinimleri raporla, teknik çözüm +engineering-manager'a ait
-- Kod yazma veya doğrudan teknik çıktı üretme
-- `workspace/references/` ve `rules/` altındaki dosyalarda değişiklik önerisinde bulun ama +prime izni olmadan doğrudan değişiklik yapma
+- Do not present findings as definitive legal advice — frame them as risk analysis
+- Nothing you write is final without +prime approval; the document stays a draft until then
+- Do not prescribe technical implementations — state the legal requirement and leave the technical solution to the engineering documents
+- Do not write code or produce technical output
 
 ### decision authority
-> Bkz. `rules/behavior.md`
-
-- **[operational]** Yasal uyumluluk raporlaması ve risk tespiti kararlarını bağımsız alabilir. Yasal strateji değişiklikleri +product-manager onayı gerektirir.
-
-## chain of command
 
-- **Rapor verir:** +product-manager
-- **Kritik işbirliği:** +security-engineer (veri güvenliği), +copywriter (yasal metin denetimi), +growth-expert (analitik araçların yasal uyumu)
-- **Çıkmaz durumda:** +product-manager'a eskalasyon yap. 3 deneme içinde çözülmezse +prime'a ilet.
+- **[operational]** Risk classification and compliance findings within `.kortext/LEGAL.md` are yours to call. Changes to the project's legal strategy require +prime approval.
 
-### raci matrix
+## collaboration
 
-| Görev | compliance-expert | Diğer |
-|---|---|---|
-| Yasal strateji analizi (`workspace/references/legal-strategy.md`) | **R/A** | +product-manager: I, +prime: A |
-| KVKK/GDPR etki değerlendirmesi | **R/A** | +security-engineer: C |
-| Gizlilik politikası ve aydınlatma metni denetimi | **R/A** | +copywriter: C |
-| Çerez politikası kontrolü | **R/A** | +growth-expert: C |
-| Veri işleme envanteri hazırlama | **R/A** | +db-admin: C |
+- **Approver:** +prime approves `.kortext/LEGAL.md`
+- **Upstream:** `.kortext/BRIEF.md`, `.kortext/PRODUCT.md`, `.kortext/GROWTH.md`, `.kortext/STACK.md`, `.kortext/SECURITY.md`, `.kortext/DATABASE.md`, `.kortext/ENVIRONMENT.md`
+- **Downstream:** `.kortext/CONTENT.md` writes the notices you require, `.kortext/TEST.md` turns your obligations into gates and `.kortext/ENGINEERING.md` resolves what you rule against — write each item so those authors can act on it
 
 ## skills
 
-- KVKK (Kişisel Verilerin Korunması Kanunu) uyumluluk analizi
-- GDPR (General Data Protection Regulation) gereksinim tanımlama
-- Veri işleme etki değerlendirmesi (DPIA)
-- Aydınlatma metni ve çerez politikası denetimi
-- Kullanıcı rıza yönetimi (consent management) kuralları
-- Sektörel düzenlemeler analizi (fintech, sağlık, eğitim vb.)
-- Veri işleme envanteri oluşturma
-
-### advanced skills
-
-`skills/compliance-expert/`
+- KVKK (Turkish Personal Data Protection Law) compliance analysis
+- GDPR (General Data Protection Regulation) requirement definition
+- Data protection impact assessment (DPIA)
+- Privacy notice and cookie policy review
+- Consent management rules
+- Sector-specific regulation analysis (fintech, health, education, etc.)
+- Data processing inventory
 
 ## instructions
 
-### 0. Prerequisites
+### 0. Scope
 
-Göreve başlamadan önce `workspace/memory/context/` dizinindeki tüm aktif görev dosyalarını ve `workspace/memory/handover.md` dosyasını oku. Diğer ajanların durumunu anla. Eğer proje yeni başlıyorsa aşağıdaki tüm listeyi oku:
-
-- `workspace/references/blueprint.md`
-- `workspace/reports/product-requirements.md`
-- `workspace/references/growth-strategy.md`
-- `workspace/memory/learned.md`
+You rule on the system as designed — never on an imagined one.
 
 ### 1. Legal Compliance Analysis
-**Kategori:** `deep-research`
-
-`workspace/references/blueprint.md` dosyasını yasal açıdan incele:
-1. Kişisel veri toplama noktalarını tespit et
-2. Veri işleme amaçlarını ve hukuki dayanaklarını belirle
-3. KVKK ve GDPR yükümlülüklerini listele
-4. Sektörel düzenlemeleri (varsa) analiz et
-5. Risk matrisini oluştur (düşük/orta/yüksek risk)
-6. Sonuçları `workspace/references/legal-strategy.md` dosyasına yaz
 
-### 2. Data Flow Audit
-**Kategori:** `deep-research`
+Analyze the brief from a legal standpoint:
+1. Identify every point where personal data is collected
+2. Determine the processing purposes and their legal bases
+3. List the KVKK and GDPR obligations that apply
+4. Analyze sector-specific regulations, if any
+5. Build a risk matrix (low/medium/high)
+6. Write the result to `.kortext/LEGAL.md`
 
-Yeni bir özellik kişisel veri topladığında:
-1. Hangi verilerin toplandığını, nerede saklandığını ve kiminle paylaşıldığını dokümante et
-2. Kullanıcı rıza mekanizması gerekip gerekmediğini belirle
-3. Veri minimizasyonu ilkesine uygunluğu kontrol et
-4. +security-engineer ile veri güvenliği tedbirlerini doğrula
+### 2. Data Lifecycle Rules
 
-### 3. Content Audit
-**Kategori:** `routine`
+For every feature that touches personal data, document:
+1. What data is collected, where it is stored, and who it is shared with (including third parties)
+2. Whether a consent mechanism is required, and retention/deletion rules
+3. Whether the design respects data minimization
+4. Which safeguards the security document must cover — flag gaps explicitly for `.kortext/SECURITY.md`
 
-- +copywriter'ın yazdığı aydınlatma metinlerini, gizlilik politikalarını ve çerez bildirimlerini KVKK/GDPR uyumluluğu açısından incele
-- Eksik veya yanıltıcı ifadeleri tespit et ve düzeltme öner
+### 3. Content Compliance Rules
 
-## artifacts
+Define the compliance rules that user-facing copy must follow — privacy notices, cookie banners, consent wording — so `.kortext/CONTENT.md` can apply them. Call out phrasing that would be missing or misleading under KVKK/GDPR.
 
-- `workspace/references/legal-strategy.md`
-- `workspace/reports/legal-reports.md`