agent-enderun 0.7.2 → 0.8.0

package/.enderun/memory-graph/shared-facts.json

@@ -0,0 +1,52 @@
+{
+  "version": "1.0.0",
+  "description": "Shared facts available to ALL agents in the Enderun Army. This is the single source of truth for project-wide knowledge that every agent must know.",
+  "updatedAt": "2026-05-25T17:00:00Z",
+  "updatedBy": "@manager",
+  "techStack": {
+    "backend": "Node.js 20+ + Fastify (RCSR Architecture)",
+    "frontend": "React 19 + Vite + Panda CSS",
+    "mobile": "React Native CLI",
+    "database": "PostgreSQL (Multi-Tenant RLS + PostGIS)",
+    "orm": "Kysely",
+    "testing": "Vitest",
+    "typeSystem": "TypeScript 5 (strict mode, no any, branded types)",
+    "monorepo": "npm workspaces",
+    "cicd": "GitHub Actions (to be configured by @devops)"
+  },
+  "criticalDecisions": [
+    { "date": "2026-05-21", "decision": "No Docker Support", "rationale": "Direct system execution for performance", "decidedBy": "@manager" },
+    { "date": "2026-05-21", "decision": "Zero Mock Policy", "rationale": "All analytical and management UIs connected to real APIs", "decidedBy": "@manager" },
+    { "date": "2026-05-23", "decision": "PostgreSQL Unlogged Table Cache instead of Redis", "rationale": "Minimize external infrastructure dependencies", "decidedBy": "@manager" }
+  ],
+  "activePolicies": [
+    "Zero Mock Policy — no fake data anywhere in the codebase",
+    "Branded Types Law — all IDs must use branded types",
+    "Shared Component First — no UI elements defined in page files",
+    "Contract-First — @backend defines types before @frontend starts",
+    "No any Type — TypeScript strict mode enforced across all packages",
+    "No console.log in production code",
+    "Audit Log Mandatory — every agent action must be logged"
+  ],
+  "activeContracts": {
+    "contractVersionFile": "apps/backend/contract.version.json",
+    "currentVersion": "latest — check file",
+    "sharedTypesLocation": "apps/backend/src/types/"
+  },
+  "agentCapabilityRoster": [
+    { "agent": "@manager", "capability": 9.5, "primaryDomain": "governance" },
+    { "agent": "@orchestrator", "capability": 9.8, "primaryDomain": "orchestration" },
+    { "agent": "@analyst", "capability": 9.6, "primaryDomain": "analysis" },
+    { "agent": "@explorer", "capability": 9.4, "primaryDomain": "exploration" },
+    { "agent": "@security", "capability": 9.3, "primaryDomain": "security" },
+    { "agent": "@backend", "capability": 9.2, "primaryDomain": "backend" },
+    { "agent": "@git", "capability": 9.1, "primaryDomain": "git" },
+    { "agent": "@qa", "capability": 9.1, "primaryDomain": "qa" },
+    { "agent": "@frontend", "capability": 9.0, "primaryDomain": "frontend" },
+    { "agent": "@devops", "capability": 9.0, "primaryDomain": "devops" },
+    { "agent": "@native", "capability": 8.9, "primaryDomain": "native" },
+    { "agent": "@mobile", "capability": 8.8, "primaryDomain": "mobile" }
+  ],
+  "frameworkVersion": "1.0.0-alpha",
+  "constitutionFile": "ENDERUN.md"
+}

package/.enderun/queue/README.md

@@ -0,0 +1,36 @@
+# .enderun/queue — Agent Görev Kuyruğu
+
+Bu dizin, Agent Enderun Army'nin file-based asenkron görev kuyruğunu içerir.
+
+## Alt Dizinler
+
+| Dizin | İçerik |
+|---|---|
+| `pending/` | Atanmış ama henüz başlatılmamış görevler (`{traceId}.json`) |
+| `processing/` | Aktif olarak yürütülen görevler |
+| `completed/` | Başarıyla tamamlanan görevler (arşiv) |
+| `failed/` | Başarısız görevler (retry logic ile yönetilir) |
+| `pipelines/` | `create_execution_pipeline` MCP tool tarafından oluşturulan pipeline JSON dosyaları |
+
+## Görev Dosyası Formatı
+
+```json
+{
+  "id": "T001",
+  "traceId": "ENR-ARMY-001",
+  "assignedAgent": "@backend",
+  "priority": "HIGH",
+  "briefing": "...",
+  "createdAt": "ISO-8601",
+  "deadline": "ISO-8601",
+  "retryCount": 0,
+  "maxRetries": 3,
+  "status": "PENDING | RUNNING | COMPLETED | FAILED"
+}
+```
+
+## Kilitleme Protokolü
+
+Bir dosyaya yazmadan önce `.lock` dosyasını kontrol et.
+Varsa 500ms bekle, max 3 retry.
+3 retry sonrası stale lock sayılır ve @manager'a bildirilir.

package/ENDERUN.md

@@ -1,4 +1,4 @@
-# Agent Enderun (v0.6.6)
+# Agent Enderun (v0.7.5)
 # Place in project root. This file is the single source of truth for Base Project AI Extensions.
 
 ## 🎖️ AGENT CHECKLIST (MANDATORY BEFORE RESPONSE)
@@ -52,7 +52,7 @@ This file (`./{{ADAPTER}}.md`) and the `{{FRAMEWORK_DIR}}/docs/` folder represen
 3. **Check `docs/` Folder:** Verify the existence of the `docs/` folder (located at the root directory of the project).
 4. **Absorb Context:** Read `docs/README.md` and `docs/getting-started.md`. If they are missing, check if the architecture folder exists.
 5. **Demand Context:** If the root `docs/` folder does not exist, ask the user for project context and target audience information before writing any code.
-6. **Respect Boundaries:** Always distinguish between the user's project code and the Agent Enderun framework internals. Read `.antigravitycli/knowledge/framework_vs_user_project_boundary.md` if unsure. Never mix the two.
+6. **Respect Boundaries:** Always distinguish between the user's project code and the Agent Enderun framework internals. Read `{{FRAMEWORK_DIR}}/knowledge/framework_vs_user_project_boundary.md` if unsure. Never mix the two.
 6. **Automatic @manager Mode:** You are ALWAYS operating as `@manager` (Team-Lead). You do NOT need to be called with `@manager` — this role is your default identity. You analyze, delegate, and orchestrate on EVERY turn without exception.
 
 **NEVER SKIP THIS STEP.** Do not assume context; read first, then act as @manager.
@@ -89,9 +89,9 @@ This file (`./{{ADAPTER}}.md`) and the `{{FRAMEWORK_DIR}}/docs/` folder represen
 
 - **Documentation Ownership Rule (Enterprise Standard — Zero Tolerance):** 
   Agents are **mandatory** to write all documentation they produce for the user's project (architectural decisions, patterns, implementation details, toaster/approval flow documents, research findings, etc.) **exclusively into the user's own `docs/` folder**.
-  These documents must **never** be written into `.antigravitycli/knowledge/`, `{{FRAMEWORK_DIR}}/agents/`, or any framework folder.
+  These documents must **never** be written into `{{FRAMEWORK_DIR}}/knowledge/`, `{{FRAMEWORK_DIR}}/agents/`, or any framework folder.
   Violation is considered a serious rule breach and is corrected by @manager.
-  The detailed and binding rule is defined in `.antigravitycli/knowledge/documentation_ownership.md`.
+  The detailed and binding rule is defined in `{{FRAMEWORK_DIR}}/knowledge/documentation_ownership.md`.
 
 ---
 

package/README.md

@@ -1,10 +1,10 @@
-# 🏛️ Agent Enderun (v0.7.0) — The Supreme AI Governance & Orchestration Framework
+# 🏛️ Agent Enderun (v0.8.0) — The Supreme AI Governance & Orchestration Framework
 
 **The Supreme AI Governance & Orchestration Framework for Enterprise Development**
 
-**Author:** Yusuf BEKAR  
-**Version:** 0.7.0  
-**License:** MIT  
+**Author:** Yusuf BEKAR
+**Version:** 0.8.0
+**License:** MIT
 
 [English](#english) | [Türkçe](#türkçe)
 
@@ -20,114 +20,139 @@ Most AI coding tools optimize for speed and generation volume. Agent Enderun opt
 
 > [!NOTE]
 > **v0.7.0 Strategic Consolidation:**
-> The active runtime folder in user projects is `.agents/`. The framework ships its templates from `.enderun/`. All specialist agent configurations are migrated into a futuristic, strongly-typed JSON structure (`agent.json`) under `.agents/agents/{agent_name}/agent.json` (or `.antigravitycli/agents/` during framework staging) for absolute machine-readability. Duplicate structures (like `.enderun/` or `.antigravitycli/docs/`) have been completely retired.
+> The active runtime folder in user projects is `.gemini/`. The framework ships its templates from `.enderun/`. All specialist agent configurations live as strongly-typed `agent.json` under `.gemini/agents/{agent_name}/agent.json`. Duplicate or staging structures have been retired.
 
 ---
 
-## 🎯 Core Philosophy
+## 🎯 Core Philosophy & Key Concepts
 
-Agent Enderun is built on four non-negotiable principles:
+Agent Enderun is built on a set of non-negotiable principles enforced by its core components.
 
-1. **Single Point of Authority** — In enterprise projects, `@manager` is the only authorized entry point. No specialist agent may act without a formal briefing.
-2. **Risk-First Mindset** — Every significant action is preceded by risk assessment. High-risk operations require explicit approval and full audit trails.
-3. **Continuous Agent Improvement** — All agents have maturity targets (minimum 8.0/10). “Good enough” is not accepted in critical areas.
-4. **Zero Tolerance for Bypass** — Any attempt to circumvent governance (Hermes protocol, briefings, memory discipline, high-risk controls) is treated as a serious process violation.
+### 1. The Constitution (`ENDERUN.md`)
+This is the supreme law of the framework, dictating mandatory rules and protocols for all agents. Key principles include:
+- **Single Point of Authority:** In enterprise projects, `@manager` is the only authorized entry point. No specialist agent may act without a formal briefing.
+- **Contract-First Development:** The `@backend` agent MUST define and document API contracts and types before the `@frontend` agent begins implementation.
+- **Zero UI Library & Zero Mock Policy:** The `@frontend` agent MUST build components from scratch using the project's design system (Panda CSS) and MUST NOT use mock data. This ensures originality and quality.
+- **Procedural Continuity:** All agents MUST adhere to the existing architectural and stylistic patterns of the project.
 
----
+### 2. Project Memory (`PROJECT_MEMORY.md`)
+This file, located in `.gemini/`, is the **Single Source of Truth (SSOT)** for the project's state. It is a human-readable Markdown file that all agents read at the start of a session and update at the end. Its key sections are:
+- **`CURRENT STATUS`:** Tracks the active phase, Trace ID, and any blockers.
+- **`CRITICAL DECISIONS`:** A log of important architectural choices to ensure consistency.
+- **`ACTIVE TASKS`:** A table of all ongoing tasks, their status, priority, and assigned agent.
+- **`HISTORY`:** A persistent log of all actions taken by agents.
 
-## 🤖 JSON-First Agent Army & Maturity Program
+### 3. Traceability (Trace ID)
+Every task or logical unit of work is assigned a unique **Trace ID** (a 26-character ULID). This ID is used in commit messages, logs, and task tables, providing an unbroken chain of traceability from the initial request to the final code.
 
-Each agent in the Enderun Army is governed by a strongly-typed `agent.json` definition that defines their precise rules, permitted directories, Hermes communication channels, and capability ratings.
+---
 
-### Workspace Agent Path:
-👉 `[project-root]/.agents/agents/{agent_name}/agent.json`
+## 🤖 The Agent Army & Core Folders
 
-### Agent Army Overview:
+Each agent in the Enderun Army is governed by a strongly-typed `agent.json` definition that defines their precise rules, permitted directories, and capability ratings.
 
-| Agent | Capability | Role & Domain | Specialization |
-| :--- | :--- | :--- | :--- |
-| **@manager** | **9.5/10** | Orchestration & Governance | Team-Lead, intent analysis, risk audit, escalation |
-| **@backend** | **9.2/10** | Domain Logic & Databases | NestJS/Express, database migrations, Branded Types |
-| **@frontend** | **9.0/10** | Fluid Responsive UI | Panda CSS, Zero-UI-Library policy, accessibility |
-| **@analyst** | **9.6/10** | Verification & QA | Vitest/Cypress, lint verification, schema checks |
-| **@explorer** | **9.4/10** | Research & Discovery | API scanning, entry-point hunt, pattern mapping |
-| **@git** | **9.1/10** | DevOps & Version Control | Commit strategies, changelog audits, branch governance |
-| **@mobile** | **8.8/10** | Cross-Platform Mobile | React Native/Expo, responsive fluid mobile design |
-| **@native** | **8.9/10** | Native Capabilities | Swift/Kotlin, native integrations, deep links |
+### Workspace Agent Path:
+👉 `[project-root]/.gemini/agents/{agent_name}/agent.json`
+
+### Agent Army Overview (v1.0 - 12 Specialists):
+
+| Tier | Agent | Capability | Role & Domain | Primary Specialization |
+| :--- | :--- | :--- | :--- | :--- |
+| **Core** | **@orchestrator** | **9.8/10** | Task Pipeline Engine | Parallel execution, stateful queue controls, DAG execution. |
+| **Core** | **@manager** | **9.5/10** | Orchestration & Governance | Intent analysis, high-risk dynamic approval signing, escalation. |
+| **Analysis** | **@analyst** | **9.6/10** | Verification & QA Gate | Vitest/Cypress verification, API contract drift checking, Zero-UI enforcer. |
+| **Analysis** | **@explorer** | **9.4/10** | Research & Discovery | Pattern mapping, dependency graph discovery, onboarding analysis. |
+| **Engineering** | **@backend** | **9.2/10** | Domain Logic & Databases | Fastify, Kysely queries, branded types, DomainError hierarchy. |
+| **Engineering** | **@frontend** | **9.0/10** | Fluid Responsive UI | React 19, Panda CSS styling tokens, Zero-UI, WCAG 2.2 accessibility. |
+| **Engineering** | **@native** | **8.9/10** | Native Capabilities | Tauri/Electron shell guards, Rust bridges, secure IPC contracts. |
+| **Engineering** | **@mobile** | **8.8/10** | Cross-Platform Mobile | React Native/Expo fluid viewports, offline cache sync, safe areas. |
+| **Operations** | **@security** | **9.3/10** | Security & Compliance | OWASP threat detection, AST scans for secrets, CSP rules auditor. |
+| **Operations** | **@qa** | **9.1/10** | Quality Gate Enforcer | Unit/integration testing gates, coverage metrics check. |
+| **Operations** | **@git** | **9.1/10** | Version Control | Semantic commits formatting, atomic commit segregation, phase snapshots. |
+| **Operations** | **@devops** | **9.0/10** | Infrastructure | Deployment pipelines, container setups, environment variable validation. |
 
 ---
 
-## 🏗️ Architecture Overview
+### 📂 Core Directories Analysis & Operational Purposes
 
-Agent Enderun cleanly separates the framework's own engine from the user's project codebase:
+The Agent Enderun framework organizes agent actions and runtime intelligence through highly structured directories remapped to `.gemini/` (or `.claude/` / `.cursor/`) inside user workspaces:
 
-```
-agent-enderun/
-├── .agents/                <-- Antigravity CLI Agent configurations (Exclusive)
-│   ├── agent_army_schema.json
-│   └── agents/
-│       ├── analyst/agent.json
-│       ├── backend/agent.json
-│       └── ... (others)
-├── .agents/                <-- Active runtime folder created in user projects (agents, memory, knowledge copies)
-│   ├── assets/
-│   │   └── manager.png     <-- Majestic Headmaster Avatar
-│   ├── cli-commands.json
-│   ├── config.json
-│   ├── PROJECT_MEMORY.md
-│   └── STATUS.md
-├── docs/                   <-- Central Project Documentation Portal (Exclusive)
-│   ├── architecture/
-│   ├── backend/
-│   ├── frontend/
-│   └── README.md
-├── bin/                    <-- CLI Engines & Validators
-│   ├── cli.js
-│   └── validate-agent-army.js
-├── framework-mcp/          <-- Core MCP Server Source
-├── apps/                   <-- Project Workspaces
-```
+* **`skills/` (Dynamic Executables):** Serves as a folder for model-specific executable scripts and custom tools. Developers can inject project-specific helpers here, allowing agents to load and execute them dynamically on-demand during active briefs.
+* **`benchmarks/` (LLM Evaluation):** Dedicated folder for metrics, token consumption, and response accuracy logs comparing different LLM engines (e.g. Gemini 1.5 Pro vs Claude 3.5 Sonnet vs Codex). Helps evaluate the coding intelligence of the active army.
+* **`knowledge/` (Intelligence Database):** central knowledge hub of the framework containing 43 robust guidelines enforcing strict laws on Panda CSS coding, Fastify RCSR, Kysely schema creation, dynamic signature validations, and domain error hierarchies.
+* **`logs/` (Auditable Trails):** Active audit log repository. Every action performed by any agent is traceably logged in JSON format (`logs/{agent_name}.json`) with a specific timestamp and a unique 26-character Trace ID (ULID), satisfying enterprise compliance audits.
+* **`monitoring/` (Operational Telemetry):** Telemetry directory integrated with monitoring tools (`get_army_health_dashboard`, `calculate_agent_performance_score`) to analyze agent bottleneck states and QA rejection cycles.
+* **`queue/` (Asynchronous Task Engine):** File-based stateful task queue split into `pending/`, `processing/`, `completed/`, `failed/`, and `pipelines/` subdirectories. Feeds Orchestration MCP tools to schedule complex multi-agent assignments in parallel with complete rollback recovery.
 
 ---
 
-## ⚡ Quick Start
+## ⚡ Quick Start & Workflow
 
-### 1. Installation & Initialization
+### 1. Installation
 
-Install the package globally or initialize it inside your project folder:
+Install the package and initialize the framework inside your project folder:
 
 ```bash
-# 1. Initialize the framework (creates .agents/ structure + antigravity.md)
-npx agent-enderun init
+# 1. Initialize the framework for Gemini CLI
+npx agent-enderun init gemini
 
-# 2. Install dependencies
+# 2. Install dependencies (as prompted)
 npm install
 
-# 3. Build the framework
+# 3. Build the framework's internal tools (as prompted)
 npm run enderun:build
 
-# 4. Verify installation & health
+# 4. Verify installation and project health
 npx agent-enderun check
 ```
 
-### 2. Startup Step (Mandatory for Agents)
-At the start of every session, the active agent must:
-1. **Read `.agents/PROJECT_MEMORY.md`** immediately to restore project context, trace ID, and active tasks.
-2. **Read `.agents/agents/manager/agent.json`** to load specialist behavioral rules and checklists.
+### 2. Example Workflow: Adding a New Feature
+
+Here’s how to use Agent Enderun to develop a new feature:
+
+**Step 1: Define the Task**
+Create a new file in your project's `docs/` folder (e.g., `docs/new-feature-request.md`) describing the feature you want.
+
+**Step 2: Create a New Trace**
+Use the CLI to create a new task in `PROJECT_MEMORY.md`. This generates a unique Trace ID.
+
+```bash
+npx agent-enderun trace:new "Implement user profile page based on docs/new-feature-request.md" @manager P1
+```
+
+**Step 3: Agent Orchestration (Automatic)**
+The `@manager` agent (the default AI persona) will:
+1.  Read `PROJECT_MEMORY.md` and see the new task.
+2.  Analyze the request from `docs/new-feature-request.md`.
+3.  Create a plan and issue formal "briefings" to specialist agents like `@explorer`, `@backend`, and `@frontend`.
+
+**Step 4: Development & Verification (Automatic)**
+- The specialist agents execute their tasks according to the constitutional rules (e.g., `@backend` creates the API and types, then `@frontend` builds the UI).
+- `@analyst` automatically verifies the work against project standards.
+- `@git` creates atomic commits tagged with the Trace ID.
+
+**Step 5: Monitor Progress**
+You can check the progress at any time with the `status` command:
+
+```bash
+npx agent-enderun status
+```
+This will show the active phase, blockers, and the status of all active tasks.
 
 ---
 
-## 🧠 Current Status & Next Milestones
+## 🛠️ CLI Commands
 
-### Strong Areas:
-- **Flawless Constitutional Governance:** Constitutional checks and mandatory checklists prevent bad practices.
-- **Bilingual Documentation:** Pristine documentation structure under `/docs/`.
-- **JSON-First Precision:** Machine-readable agent configurations with detailed governance settings.
-- **Robust Linter and Build Pipelines:** Build and lint pipelines compile cleanly.
+Agent Enderun comes with a powerful set of CLI tools for managing the project.
 
-### Next Major Milestones:
-1. Produce a complete reference application proving Kurumsal CRUD + `managerApproval` + Hermes in live multi-agent flows.
-2. Perform a live Hermes multi-agent simulation test suite.
+| Command | Description |
+| :--- | :--- |
+| `npx agent-enderun init [adapter]` | Initializes the framework in the current project. `gemini` is the default and recommended adapter. |
+| `npx agent-enderun check` | Runs a health check on the project to ensure all required files and configurations are present. |
+| `npx agent-enderun status` | Displays the current project status, active tasks, and blockers from `PROJECT_MEMORY.md`. |
+| `npx agent-enderun trace:new "<desc>" [agent] [priority]` | Creates a new task with a unique Trace ID and adds it to the `PROJECT_MEMORY.md`. |
+| `npx agent-enderun create-app "<desc>"` | (Aliases: `new`, `start`) Scaffolds a new full-stack application (backend + web) from a natural language description. |
+| `npx agent-enderun verify-contract` | Verifies the integrity of the shared backend types by comparing the current code against the stored hash in `contract.version.json`. |
 
 ---
 
@@ -141,68 +166,167 @@ At the start of every session, the active agent must:
 
 > [!NOTE]
 > **v0.7.0 Stratejik Konsolidasyon:**
-> Çalışma zamanı klasörü kullanıcı projelerinde `.agents/` olarak oluşturulur. Ajan yapılandırmaları `.agents/agents/{agent_name}/agent.json` altında yer alır. Eski veya mükerrer yapılar (örneğin `.enderun/` veya `.antigravitycli/docs/`) tamamen kaldırılmıştır.
+> Çalışma zamanı klasörü kullanıcı projelerinde `.gemini/` olarak oluşturulur. Ajan yapılandırmaları `.gemini/agents/{agent_name}/agent.json` altında yer alır. Eski veya mükerrer yapılar tamamen kaldırılmıştır.
 
 ---
 
-## 🎯 Temel Felsefe
+## 🎯 Temel Felsefe ve Anahtar Kavramlar
 
-Agent Enderun, dört tavizsiz ilke üzerine inşa edilmiştir:
+Agent Enderun, temel bileşenleri tarafından uygulanan, tavizsiz ilkeler üzerine kurulmuştur.
 
-1. **Tek Yetki Noktası** — Kurumsal projelerde `@manager` tek yetkili giriş noktasıdır. Hiçbir uzman ajan, resmi bir brifing almadan kendi başına işlem yapamaz.
-2. **Risk Öncelikli Yaklaşım** — Her önemli işlem öncesinde risk değerlendirmesi yapılması zorunludur. Yüksek riskli işlemler açık onay ve eksiksiz denetim geçmişi gerektirir.
-3. **Sürekli Ajan Gelişimi** — Tüm ajanların olgunluk hedefleri (minimum 8.0/10) vardır. Kritik alanlarda "yeterince iyi" kabul edilmez.
-4. **Bypass Toleranssızlığı** — Yönetişimi (Hermes protokolü, brifingler, bellek disiplini, yüksek risk kontrolleri) atlatmaya yönelik her girişim ciddi süreç ihlali olarak kabul edilir.
+### 1. Anayasa (`ENDERUN.md`)
+Bu, tüm ajanlar için zorunlu kuralları ve protokolleri dikte eden, çerçevenin en üst yasasıdır. Temel ilkeler şunları içerir:
+- **Tek Yetki Noktası:** Kurumsal projelerde `@manager` tek yetkili giriş noktasıdır. Hiçbir uzman ajan, resmi bir brifing almadan kendi başına işlem yapamaz.
+- **Önce Sözleşme (Contract-First) ile Geliştirme:** `@backend` ajanı, `@frontend` ajanı uygulamaya başlamadan ÖNCE API sözleşmelerini ve tiplerini tanımlamak ve belgelemek ZORUNDADIR.
+- **Sıfır UI Kütüphanesi ve Sıfır Mock Veri Politikası:** `@frontend` ajanı, bileşenleri projenin tasarım sistemini (Panda CSS) kullanarak sıfırdan oluşturmalı ve mock (sahte) veri KULLANMAMALIDIR. Bu, özgünlüğü ve kaliteyi garanti eder.
+- **Prosedürel Devamlılık:** Tüm ajanlar, projenin mevcut mimari ve stilistik kalıplarına uymak ZORUNDADIR.
+
+### 2. Proje Hafızası (`PROJECT_MEMORY.md`)
+`.gemini/` içinde bulunan bu dosya, projenin durumu için **Tek Doğruluk Kaynağıdır (SSOT)**. Tüm ajanların bir oturumun başında okuduğu ve sonunda güncellediği, insan tarafından okunabilir bir Markdown dosyasıdır. Ana bölümleri şunlardır:
+- **`CURRENT STATUS`:** Aktif aşamayı, Trace ID'yi ve varsa engelleyicileri izler.
+- **`CRITICAL DECISIONS`:** Tutarlılığı sağlamak için önemli mimari seçimlerin bir kaydı.
+- **`ACTIVE TASKS`:** Devam eden tüm görevlerin, durumlarının, önceliklerinin ve atanan ajanın bir tablosu.
+- **`HISTORY`:** Ajanlar tarafından gerçekleştirilen tüm eylemlerin kalıcı bir kaydı.
+
+### 3. İzlenebilirlik (Trace ID)
+Her göreve veya mantıksal iş birimine benzersiz bir **Trace ID** (26 karakterlik bir ULID) atanır. Bu kimlik, commit mesajlarında, loglarda ve görev tablolarında kullanılarak ilk talepten nihai koda kadar kesintisiz bir izlenebilirlik zinciri sağlar.
 
 ---
 
-## 🤖 JSON-First Ajan Ordusu ve Olgunluk Programı
+## 🤖 Ajan Ordusu
 
-Enderun Ordusu'ndaki her ajan, kendilerine ait kuralları, izin verilen dizinleri, Hermes iletişim kanallarını ve yetenek derecelendirmelerini tanımlayan güçlü tipli bir `agent.json` dosyası tarafından yönetilir.
+Enderun Ordusu'ndaki her ajan, kendilerine ait kuralları, izin verilen dizinleri ve yetenek derecelendirmelerini tanımlayan güçlü tipli bir `agent.json` dosyası tarafından yönetilir.
 
 ### Çalışma Alanı Ajan Yolu:
-👉 `[proje-kök-dizini]/.agents/agents/{agent_name}/agent.json`
+👉 `[proje-kök-dizini]/.gemini/agents/{agent_name}/agent.json`
+
+### Ajan Ordusuna Genel Bakış (v1.0 - 12 Uzman Ajan):
+
+| Katman | Ajan | Yetenek | Rol & Alan | Ana Uzmanlık Alanı |
+| :--- | :--- | :--- | :--- | :--- |
+| **Core** | **@orchestrator** | **9.8/10** | Görev Kuyruğu Motoru | Paralel yürütme, stateful kuyruk kontrolleri, DAG yönetimi. |
+| **Core** | **@manager** | **9.5/10** | Orkestrasyon & Yönetişim | Talep analizi, yüksek riskli dinamik imza kontrolü, onay mekanizması. |
+| **Analiz** | **@analyst** | **9.6/10** | Kalite & Sözleşme Kapısı | Vitest/Cypress test denetimi, API kontrat sapma kontrolü, Sıfır-UI denetçisi. |
+| **Analiz** | **@explorer** | **9.4/10** | Araştırma & Keşif | Kod yapısı desen eşleme, bağımlılık grafiği çıkarma, onboarding analizi. |
+| **Geliştirme** | **@backend** | **9.2/10** | Domain Mantığı & DB | Fastify, Kysely veri tabanı sorguları, branded tipler, DomainError hiyerarşisi. |
+| **Geliştirme** | **@frontend** | **9.0/10** | Akıcı Duyarlı Arayüz | React 19, Panda CSS stil token'ları, Sıfır-UI, WCAG 2.2 AA erişilebilirlik. |
+| **Geliştirme** | **@native** | **8.9/10** | Native Yetenekler | Tauri/Electron kabuk koruması, Rust köprüleri, güvenli IPC kontratları. |
+| **Geliştirme** | **@mobile** | **8.8/10** | Çoklu Platform Mobil | React Native/Expo akıcı görünümler, offline önbellek senkronizasyonu. |
+| **Operasyon** | **@security** | **9.3/10** | Güvenlik & Uyum | OWASP tehdit tespiti, AST tabanlı statik sır taraması, CSP denetimi. |
+| **Operasyon** | **@qa** | **9.1/10** | Kalite Güvence Kapısı | Birim/entegrasyon test kontrolü, kapsama metrikleri denetçisi. |
+| **Operasyon** | **@git** | **9.1/10** | Versiyon Kontrolü | Semantik commit formatlama, atomik commit ayırma, faz snapshot'ları. |
+| **Operasyon** | **@devops** | **9.0/10** | Altyapı & Deployment | Deployment boru hatları, konteyner kurulumları, ortam değişkenleri denetimi. |
+
+---
+
+## 🏛️ Agent Enderun: Detaylı Kod Tabanı Denetim Raporu (v0.8.0)
+
+Çerçevenin (framework) çekirdek kod yapısı, operasyonel işleyişi, alt-üst ajan hiyerarşisi ve temizlenmiş mükerrer alanları en ince ayrıntısına kadar denetlenmiş ve belgelenmiştir:
 
-### Ajan Ordusuna Genel Bakış:
+### 📂 1. Kapsamlı Klasör ve Dosya Yapısı Analizi
 
-| Ajan | Yetenek | Rol & Alan | Uzmanlık |
-| :--- | :--- | :--- | :--- |
-| **@manager** | **9.5/10** | Orkestrasyon & Yönetişim | Takım Lideri, niyet analizi, risk denetimi, onay |
-| **@backend** | **9.2/10** | Domain Mantığı & Veri Tabanı | NestJS/Express, DB migrasyonları, Branded Types |
-| **@frontend** | **9.0/10** | Akıcı Duyarlı Arayüz | Panda CSS, Zero-UI-Library ilkesi, erişilebilirlik |
-| **@analyst** | **9.6/10** | Doğrulama & Kalite (QA) | Vitest/Cypress, linter doğrulamaları, şema kontrolü |
-| **@explorer** | **9.4/10** | Araştırma & Keşif | API tarama, başlangıç noktası avı, desen eşleme |
-| **@git** | **9.1/10** | DevOps & Sürüm Kontrolü | Commit stratejileri, değişiklik günlüğü, dal yönetimi |
-| **@mobile** | **8.8/10** | Çoklu Platform Mobil | React Native/Expo, akıcı duyarlı mobil arayüzler |
-| **@native** | **8.9/10** | Native Yetenekler | Swift/Kotlin, native entegrasyonlar, derin linkler |
+* **🧠 Çekirdek Komuta Klasörü (`.enderun/`):** 
+  * Ajanların şablon kaynak dosyalarının yer aldığı ve hedef projede `.gemini/` (veya `.claude/` / `.cursor/`) olarak yeniden adlandırılan ana zeka merkezidir.
+  * **`agents/` (Ajan Tanımları & SOP'lar)**: 12 uzman ajanın davranış kurallarını barındırır. Her ajanın altında bir `agent.json` ve prompt/SOP dosyaları (`prompt.md`) bulunur. Durum makinesi şeması `schema/agent-lifecycle-schema.json` ile yönetilir.
+  * **`knowledge/` (Bilgi Bankası)**: Projenin anayasasını, sıfır UI kütüphanesi politikasını ve veri tabanı/kod standartlarını içeren 26 adet Markdown kılavuzunu barındırır. `corporate-governance/` alt klasöründe onay mekanizmaları, branded types hukuku ve audit loglama standartları gibi kurumsal düzeydeki 17 katı yönetişim kılavuzu yer alır.
+  * **`memory-graph/` (Bellek Grafiği)**: Ajanların etkileşim ağını (`graph.json`), ortak paylaştıkları doğruları (`shared-facts.json`) ve her bir ajanın yerel bağlam belleklerini (`agent-contexts/`) saklar.
+  * **`queue/` (Dosya Tabanlı Görev Kuyruğu)**: Asenkron ve paralel görevlerin yönetildiği dizindir. `pending/`, `processing/`, `completed/` ve `failed/` alt dizinleri sayesinde Trace ID üzerinden asenkron görev takibi yapılır.
+  * **`logs/` (Aksiyon Günlükleri)**: Ajanların gerçekleştirdiği tüm mutasyonları Trace ID (ULID) ile damgalayarak JSON formatında saklar (Örn: `backend.json`, `analyst.json`).
+
+* **🔌 Model Context Protocol (MCP) Katmanı (`framework-mcp/`):** 
+  * Ajanların IDE (Gemini, Claude, Cursor) ile konuşmasını ve yerel sistemdeki dosyaları güvenle manipüle etmesini sağlayan ana entegrasyon paketidir.
+  * **`src/tools/`**: 13 adet çekirdek MCP araç modülünü (kod tabanı aramaları, bellek kilit protokolleri, kontrat doğrulamaları, statik AST analizli güvenlik taramaları vb.) barındırır.
+  * **`src/schemas.ts`**: MCP araçlarına gönderilen parametrelerin tip güvenliğini Zod şemalarıyla denetler (Gereksiz/pasif şemalar temizlenmiştir).
+  * **`src/index.ts`**: MCP sunucusunun stdio üzerinden IDE ile bağlantısını kuran ana giriş kapısıdır.
+
+* **🚀 Çalıştırılabilir Dizin & CLI (`bin/` ve `src/cli/`):**
+  * **`bin/cli.js`**: `npx tsx src/cli/index.ts` komutunu sarmalayan çalıştırılabilir binary giriş noktasıdır.
+  * **`src/cli/index.ts`**: Projeyi platformlara göre (`gemini`, `claude`, `cursor`) scaffold eden ve sağlık kontrollerini (`check`, `status`) koordine eden çekirdek CLI motorudur.
+  * **`bin/hermes-sandbox.js`**: Ajanlar arası Yüksek Riskli İşlem ve dynamic onay (`managerApproval`) mesajlaşma akışını yerel olarak simüle eden test sandbox'ıdır.
+
+### 🧹 2. Gerçekleştirilen v1.0 Kritik Temizlik ve Düzenlemeler
+
+* **Ajan Promptlarındaki Çöp Veriler Temizlendi:** `analyst`, `backend`, `mobile` ve `native` promptlarının sonundaki bozuk mükerrer satırlar ve generic raporlama blokları tamamen kaldırılmıştır.
+* **Ölü MCP Kodları / Araçları Ayıklandı:** `schemas.ts` içindeki 8 adet pasif/unimplemented araç şeması ayıklanmış ve promptlardaki ölü araç referansları temizlenmiştir.
+* **Olmayan Klasör Referansları Onarıldı:** Olmayan `.enderun/blueprints/` klasör referansları, `.enderun/knowledge/` altındaki aktif rehberlerle başarılı şekilde değiştirilmiştir.
+* **Çoklu Platform ve Kök Senkronizasyonu Sağlandı:** `gemini.md`, `claude.md` ve `cursor.md` dosyaları şablon ve kök dizinde senkronize edilerek CLI dağıtımına hazır hale getirilmiştir.
+
+### 👑 3. Ajan Ordusu Hiyerarşisi ve Çalışma Akışı
+
+* **Üst Ajan (Lead):** `@manager` her zaman varsayılan liderdir. Projedeki tüm alt görevler onun brifingi ile başlar.
+* **Alt Ajanlar (Specialists):** `@backend`, `@frontend`, `@security` vb. uzman ajanlar kendilerine atanan asenkron görevleri yapar.
+* **Kalite Kapısı:** `@analyst` ve `@security` yapılan geliştirmelerin anayasaya uygunluğunu denetlemeden hiçbir kod parçası staging/commit aşamasına geçemez.
 
 ---
 
-## ⚡ Hızlı Başlangıç
 
-### 1. Kurulum ve Başlatma
+## ⚡ Hızlı Başlangıç ve İş Akışı
 
-Framework'ü projenizde başlatmak için aşağıdaki adımları takip edin:
+### 1. Kurulum
+
+Framework'ü projenize kurmak ve başlatmak için aşağıdaki adımları takip edin:
 
 ```bash
-# 1. Framework'ü başlatın (.agents yapısını kurar)
-npx agent-enderun init
+# 1. Framework'ü Gemini CLI için başlatın
+npx agent-enderun init gemini
 
-# 2. Bağımlılıkları yükleyin
+# 2. Bağımlılıkları yükleyin (istendiği gibi)
 npm install
 
-# 3. Çekirdek MCP sunucusunu derleyin
+# 3. Framework'ün dahili araçlarını derleyin (istendiği gibi)
 npm run enderun:build
 
-# 4. Kurulumu ve sağlığı doğrulayın
+# 4. Kurulumu ve proje sağlığını doğrulayın
 npx agent-enderun check
 ```
 
-### 2. Ajanlar İçin Başlangıç Adımı (Zorunlu)
-Her oturumun başında, aktif ajan mutlaka:
-1. Proje bağlamını, izleme kimliğini (trace ID) ve aktif görevleri geri yüklemek için **derhal `.agents/PROJECT_MEMORY.md`** dosyasını okumalıdır.
-2. Rolüne özgü davranış kurallarını ve kontrol listelerini yüklemek için **derhal `.agents/agents/manager/agent.json`** dosyasını okumalıdır.
+### 2. Örnek İş Akışı: Yeni Bir Özellik Ekleme
+
+Agent Enderun'u yeni bir özellik geliştirmek için nasıl kullanacağınız aşağıda açıklanmıştır:
+
+**Adım 1: Görevi Tanımlayın**
+Projenizin `docs/` klasöründe yeni bir dosya oluşturun (örn. `docs/yeni-ozellik-isteği.md`) ve istediğiniz özelliği tanımlayın.
+
+**Adım 2: Yeni Bir İz (Trace) Oluşturun**
+`PROJECT_MEMORY.md`'de yeni bir görev oluşturmak için CLI'yi kullanın. Bu, benzersiz bir Trace ID oluşturur.
+
+```bash
+npx agent-enderun trace:new "docs/yeni-ozellik-isteği.md'ye göre kullanıcı profili sayfasını uygula" @manager P1
+```
+
+**Adım 3: Ajan Orkestrasyonu (Otomatik)**
+`@manager` ajanı (varsayılan AI kişiliği) şunları yapacaktır:
+1.  `PROJECT_MEMORY.md`'yi okuyacak ve yeni görevi görecektir.
+2.  `docs/yeni-ozellik-isteği.md`'deki talebi analiz edecektir.
+3.  Bir plan oluşturacak ve `@explorer`, `@backend` ve `@frontend` gibi uzman ajanlara resmi "brifingler" verecektir.
+
+**Adım 4: Geliştirme ve Doğrulama (Otomatik)**
+- Uzman ajanlar, anayasal kurallara göre görevlerini yerine getirir (örneğin, `@backend` API'yi ve tipleri oluşturur, ardından `@frontend` kullanıcı arayüzünü oluşturur).
+- `@analyst`, yapılan işi proje standartlarına göre otomatik olarak doğrular.
+- `@git`, Trace ID ile etiketlenmiş atomik `commit`'ler oluşturur.
+
+**Adım 5: İlerlemeyi İzleyin**
+`status` komutuyla ilerlemeyi istediğiniz zaman kontrol edebilirsiniz:
+
+```bash
+npx agent-enderun status
+```
+Bu, aktif aşamayı, engelleri ve tüm aktif görevlerin durumunu gösterecektir.
+
+---
+
+## 🛠️ CLI Komutları
+
+Agent Enderun, projeyi yönetmek için güçlü bir komut satırı araç seti ile birlikte gelir.
 
+| Komut | Açıklama |
+| :--- | :--- |
+| `npx agent-enderun init [adapter]` | Framework'ü mevcut projede başlatır. `gemini` varsayılan ve önerilen adaptördür. |
+| `npx agent-enderun check` | Gerekli tüm dosyaların ve yapılandırmaların mevcut olduğundan emin olmak için projede bir sağlık kontrolü çalıştırır. |
+| `npx agent-enderun status` | `PROJECT_MEMORY.md`'den mevcut proje durumunu, aktif görevleri ve engelleri gösterir. |
+| `npx agent-enderun trace:new "<açıklama>" [ajan] [öncelik]` | Benzersiz bir Trace ID ile yeni bir görev oluşturur ve bunu `PROJECT_MEMORY.md`'ye ekler. |
+| `npx agent-enderun create-app "<açıklama>"` | (Takma adlar: `new`, `start`) Doğal dil tanımından yeni bir tam yığın uygulama (backend + web) oluşturur. |
+| `npx agent-enderun verify-contract` | `contract.version.json`'da saklanan `hash` ile mevcut kodu karşılaştırarak paylaşılan backend tiplerinin bütünlüğünü doğrular. |
 ---
 
 **Agent Enderun is not just a tool. It is a complete operating system for professional, risk-aware, AI-assisted software development.**