agent-enderun 0.8.7 → 0.9.0

package/README.md

@@ -1,10 +1,4 @@
-# 🏛️ Agent Enderun (v0.8.7) — The Supreme AI Governance & Orchestration Framework
-
-**The Supreme AI Governance & Orchestration Framework for Enterprise Development**
-
-**Author:** Yusuf BEKAR
-**Version:** 0.8.7
-**License:** MIT
+# 🏛️ Agent Enderun — Supreme Enterprise AI Governance Framework (v0.9.0)
 
 [English](#english) | [Türkçe](#türkçe)
 
@@ -12,334 +6,138 @@
 
 # English
 
-## Executive Summary
-
-**Agent Enderun** is a production-grade constitutional governance and multi-agent orchestration framework designed for engineering teams that need to use AI assistants at scale while maintaining control, traceability, auditability, and professional discipline.
-
-Most AI coding tools optimize for speed and generation volume. Agent Enderun optimizes for **risk-aware, auditable, and continuously improving software development processes**. It converts chaotic AI output into structured, enterprise-ready work through mandatory rules, specialized agents, persistent memory, and a living risk management system.
-
-> [!NOTE]
-> **v0.7.0 Strategic Consolidation:**
-> The active runtime folder in user projects is `.enderun/`. The framework ships its templates from `.enderun/`. All specialist agent configurations live as strongly-typed `agent.json` under `.enderun/agents/{agent_name}.md`. Duplicate or staging structures have been retired.
-
----
-
-## 🎯 Core Philosophy & Key Concepts
-
-Agent Enderun is built on a set of non-negotiable principles enforced by its core components.
-
-### 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 `.enderun/`, 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.
-
-### 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.
-
----
-
-## 🤖 The Agent Army & Core Folders
-
-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.
-
-### Workspace Agent Path:
-👉 `[project-root]/.enderun/agents/{agent_name}.md`
-
-### 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. |
-
----
-
-### 📂 Core Directories Analysis & Operational Purposes
+**Agent Enderun** is not just a code generator; it is a high-discipline **AI Governance & Autonomous Command System** designed for complex, scalable, and fully auditable enterprise software projects. 
 
-The Agent Enderun framework organizes agent actions and runtime intelligence through highly structured directories remapped to `.enderun/` (or `.claude/` / `.cursor/`) inside user workspaces:
+With v0.9.0, the framework has evolved into a **"Living Engineering Organism"** that manages its own memory, performs surgical codebase modifications, and unifies diverse AI ecosystems under a single constitutional discipline.
 
-* **`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.
+## 💎 Strategic Platform Synergy (The Core Four)
 
----
-
-### 🏛️ Enterprise-Grade Architecture Standards (v0.8.7 Upgrades)
-
-Agent Enderun is armored out-of-the-box with six advanced, high-scale engineering gates required by corporate and enterprise-level production platforms:
-
-1. **⚡ Server-State Caching (TanStack Query / SWR)**: Enforces Query-Key-based caching, request deduplication, and automatic invalidation on mutations natively inside `@frontend`.
-2. **🗄️ Zero-Downtime Database Migrations**: Strictly forbids destructive raw SQL changes on live production database environments. Mandates a 4-step dual-write soft deprecation pattern in `@backend` to prevent migration downtime.
-3. **📊 Telemetry & JSON Logging**: Mandates structured Pino JSON logs and automatic **OpenTelemetry trace context propagation** (`trace_id` correlation) from API requests down through downstream database layers in `@backend`.
-4. **🧪 Strict 80% Coverage Quality Gate**: Imposes a non-negotiable **80% minimum unit/integration test coverage gate** on core domain repositories and critical paths, verified by `@qa`.
-5. **🛡️ Playwright E2E Integration**: Standards for automated End-to-End user journey test runs are enforced before deploy approvals.
-6. **🔗 Feature Flag Toggles & Type-Sync**: Enforces feature toggles (`features.isEnabled(...)`) to gate complex developments, and automates OpenAPI-to-TypeScript type sync to prevent API contract drift.
-
----
-
-## ⚡ Quick Start & Workflow
-
-### 1. Installation
-
-Install the package and initialize the framework inside your project folder:
-
-```bash
-# 1. Initialize the framework for Gemini CLI
-npx agent-enderun init gemini
+Agent Enderun integrates the world's most powerful AI ecosystems, mapping each to a specific strategic role within the project:
 
-# 2. Install dependencies (as prompted)
-npm install
+1.  **🚀 Claude Code (Operational Surgery):** The project's **Field Engineer**. With unrivaled file-system speed and the `patch_file` tool, it manages autonomous code edits with surgical precision.
+2.  **♊ Gemini & Vertex AI (Strategic Brain):** The **Command Center**. Utilizing a 2M+ token context window, it analyzes the entire project history and architectural map simultaneously to make high-level decisions.
+3.  **🛸 Antigravity (Internal Discipline):** The **Military Academy**. A high-discipline, isolated environment designed to enforce internal project standards and rigorous AI training.
+4.  **🤖 Grok / X.ai (Reconnaissance Unit):** The **Autonomous Vision**. Used for testing futuristic agent protocols and pushing the boundaries of AI-native development.
 
-# 3. Build the framework's internal tools (as prompted)
-npm run enderun:build
+## 🛡️ The Five Pillars of Enderun Discipline
 
-# 4. Verify installation and project health
-npx agent-enderun check
-```
-
-### 2. Example Workflow: Adding a New Feature
-
-Here’s how to use Agent Enderun to develop a new feature:
+1.  **Absolute Traceability (Trace ID):** Every decision, commit, and line of code is stamped with a ULID-based Trace ID. Full enterprise auditability is achieved in seconds.
+2.  **Contract-First Law:** No implementation is permitted without verified type contracts. Type safety between `@backend` and `@frontend` is the project's supreme law.
+3.  **Surgical Edit Standard:** Overwriting entire files is prohibited. The system mandates `replace_text` and `patch_file` via MCP for precise, non-destructive modifications.
+4.  **Autonomous Memory Pruning:** `PROJECT_MEMORY.md` never bloats. Histories exceeding 10 entries are auto-archived to keep the context window fresh and cost-efficient.
+5.  **Constitutional SSOT:** All platforms (Claude, Gemini, etc.) are 100% loyal to a single source of truth: the `.enderun/ENDERUN.md` constitution.
 
-**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.
+## 🛠️ Installation & Deployment
 
-**Step 2: Create a New Trace**
-Use the CLI to create a new task in `PROJECT_MEMORY.md`. This generates a unique Trace ID.
+Initialize the framework for your preferred platform with a single command:
 
 ```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`.
+# For Gemini CLI and Antigravity (Standard)
+agent-enderun init gemini
 
-**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.
+# For Claude Code (CLI & Desktop) — Optimized for Surgery
+agent-enderun init claude
 
-**Step 5: Monitor Progress**
-You can check the progress at any time with the `status` command:
+# For Antigravity IDE/CLI Independent Setup
+agent-enderun init antigravity
 
-```bash
-npx agent-enderun status
+# For Grok Build / X.ai Autonomous Agents
+agent-enderun init grok
 ```
-This will show the active phase, blockers, and the status of all active tasks.
 
----
-
-## 🛠️ CLI Commands
-
-Agent Enderun comes with a powerful set of CLI tools for managing the project.
+## 📋 CLI Command Registry
 
 | 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`. |
+| `status` | Shows the active phase, Trace ID, and real-time agent health scores. |
+| `check` | Audits system health, MCP connectivity, and constitutional integrity. |
+| `trace:new` | Starts a new task chain with a unique ID and briefs the Army. |
+| `create-app` | Generates an enterprise monorepo (Fastify/React) from natural language. |
+| `verify-contract` | Seals the type alignment between backend and frontend modules. |
+
+## 📂 Architecture Map
+
+```text
+├── .enderun/               <-- The Framework Brain
+│   ├── agents/             <-- 12 Specialist Directives (Manager, Architect, QA...)
+│   ├── knowledge/          <-- Enterprise Standards (ESLint, API, Security)
+│   ├── memory-graph/       <-- Shared Facts & Agent Private Contexts
+│   ├── queue/              <-- Hermes Messaging & Task Queue
+│   └── ENDERUN.md          <-- The Supreme Constitution
+├── apps/                   <-- Enterprise Application Space
+├── docs/                   <-- Project Architectural Portal (ADRs, Tech-Stack)
+└── framework-mcp/          <-- Autonomous Operations Server
+```
 
 ---
 
 # Türkçe
 
-## Yönetici Özeti
-
-**Agent Enderun**, AI asistanlarını yüksek ölçekte kullanırken kontrolü, izlenebilirliği, denetlenebilirliği ve profesyonel disiplini korumak isteyen mühendislik ekipleri için tasarlanmış, **Anayasal Yönetişim** ve **Çoklu Ajan Orkestrasyonu** odaklı kurumsal düzeyde bir framework’tür.
+**Agent Enderun**, sıradan bir kod üreticisi değil; karmaşık, ölçeklenebilir ve mutlak denetlenebilir kurumsal yazılım projeleri için tasarlanmış bir **Yapay Zeka Yönetişim ve Otonom Ordu Komuta Sistemidir**.
 
-Çoğu yapay zeka kodlama aracı hız ve üretim hacmine odaklanırken, Agent Enderun **risk farkındalıklı, denetlenebilir ve sürekli iyileştirilen yazılım geliştirme süreçlerine** odaklanır. Kaotik yapay zeka çıktılarını; zorunlu kurallar, özel ajanlar, kalıcı bellek ve yaşayan bir risk yönetim sistemi aracılığıyla yapılandırılmış kurumsal standartlara dönüştürür.
+v0.9.0 sürümüyle birlikte sistem; kendi hafızasını yönetebilen, kod tabanına cerrahi müdahaleler yapabilen ve farklı YZ ekosistemlerini tek bir anayasal disiplin altında birleştiren **"Yaşayan bir Mühendislik Organizması"** haline gelmiştir.
 
-> [!NOTE]
-> **v0.7.0 Stratejik Konsolidasyon:**
-> Çalışma zamanı klasörü kullanıcı projelerinde `.enderun/` olarak oluşturulur. Ajan yapılandırmaları `.enderun/agents/{agent_name}.md` altında yer alır. Eski veya mükerrer yapılar tamamen kaldırılmıştır.
+## 💎 Stratejik Platform Sinerjisi (Dörtlü Güç)
 
----
-
-## 🎯 Temel Felsefe ve Anahtar Kavramlar
-
-Agent Enderun, temel bileşenleri tarafından uygulanan, tavizsiz ilkeler üzerine kurulmuştur.
-
-### 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`)
-`.enderun/` 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.
-
----
-
-## 🤖 Ajan Ordusu
-
-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]/.enderun/agents/{agent_name}.md`
-
-### 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.7)
-
-Ç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:
-
-### 📂 1. Kapsamlı Klasör ve Dosya Yapısı Analizi
-
-* **🧠 Çekirdek Komuta Klasörü (`.enderun/`):** 
-  * Ajanların şablon kaynak dosyalarının yer aldığı ve hedef projede `.enderun/` (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
+Agent Enderun, sektördeki en güçlü YZ ekosistemlerini bir araya getirerek her birini proje içinde stratejik bir rolle görevlendirir:
 
-* **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.
+1.  **🚀 Claude Code (Operasyonel Cerrahi):** Projenin **Saha Mühendisi**dir. Dosya sistemi üzerindeki rakipsiz hızı ve `patch_file` aracıyla otonom kod düzenlemelerini cerrahi hassasiyetle yönetir.
+2.  **♊ Gemini & Vertex AI (Stratejik Akıl):** Sistemin **Komuta Merkezi**dir. 2M+ token bağlam kapasitesiyle projenin tüm geçmişini ve mimari yapısını aynı anda analiz ederek üst düzey kararlar alır.
+3.  **🛸 Antigravity (İç Disiplin):** Projenin **Askeri Akademisi**dir. İç standartlarımızı korumak için tasarlanmış, dış dünyadan izole ve yüksek disiplinli geliştirme ortamıdır.
+4.  **🤖 Grok / X.ai (Keşif Birliği):** Projenin **Otonom Vizyonu**dur. Gelecek odaklı ajan protokollerini test etmek ve YZ tabanlı geliştirme sınırlarını zorlamak için kullanılır.
 
-### 👑 3. Ajan Ordusu Hiyerarşisi ve Çalışma Akışı
+## 🛡️ Enderun Disiplininin Beş Sarsılmaz Sütunu
 
-* **Ü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.
+1.  **Mutlak İzlenebilirlik (Trace ID):** Her karar, her commit ve her kod satırı ULID tabanlı bir Trace ID ile damgalanır. Kurumsal denetim (audit) saniyeler içinde yapılabilir.
+2.  **Önce Sözleşme (Contract-First):** Backend ve Frontend arasındaki veri kontratları mühürlenmeden kod yazılamaz. Tip güvenliği projenin kutsal yasasıdır.
+3.  **Cerrahi Düzenleme Standardı:** Dosyaların tamamını üzerine yazmak yasaktır. Sistem, sadece değişen satırları güncelleyen `replace_text` ve `patch_file` araçlarını zorunlu kılar.
+4.  **Otonom Hafıza Arşivleme (Auto-Prune):** `PROJECT_MEMORY.md` asla şişmez. 10 kayıt sınırını geçen tarihçeler otomatik arşivlenir; sistem her zaman taze ve ekonomik kalır.
+5.  **Anayasal SSOT:** Tüm platformlar (Claude, Gemini vb.) tek bir üst otoriteye, `.enderun/ENDERUN.md` anayasasına %100 sadakatle bağlıdır.
 
----
-
-
-## ⚡ Hızlı Başlangıç ve İş Akışı
-
-### 1. Kurulum
-
-Framework'ü projenize kurmak ve başlatmak için aşağıdaki adımları takip edin:
-
-```bash
-# 1. Framework'ü Gemini CLI için başlatın
-npx agent-enderun init gemini
-
-# 2. Bağımlılıkları yükleyin (istendiği gibi)
-npm install
-
-# 3. Framework'ün dahili araçlarını derleyin (istendiği gibi)
-npm run enderun:build
-
-# 4. Kurulumu ve proje sağlığını doğrulayın
-npx agent-enderun check
-```
+## 🛠️ Kurulum ve Dağıtım
 
-### 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.
+Kullandığınız platforma göre tek komutla Agent Enderun'u başlatın:
 
 ```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.
+# Gemini CLI ve Antigravity için (Standart)
+agent-enderun init gemini
 
-**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.
+# Claude Code (CLI & Desktop) için — Cerrahi Odaklı
+agent-enderun init claude
 
-**Adım 5: İlerlemeyi İzleyin**
-`status` komutuyla ilerlemeyi istediğiniz zaman kontrol edebilirsiniz:
+# Antigravity IDE/CLI Bağımsız Kurulumu
+agent-enderun init antigravity
 
-```bash
-npx agent-enderun status
+# Grok Build / X.ai Otonom Ajanları İçin
+agent-enderun init grok
 ```
-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.
+## 📋 CLI Komut Rehberi
 
 | 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. |
+| `status` | Aktif fazı, Trace ID'yi ve ajanların anlık sağlık skorlarını gösterir. |
+| `check` | Sistemin anayasal sağlığını ve dosya bütünlüğünü denetler. |
+| `trace:new` | Yeni bir görev zinciri başlatır ve orduyu görevlendirir. |
+| `create-app` | Doğal dilden kurumsal monorepo (Fastify/React) üretir. |
+| `verify-contract` | Backend ve Frontend arasındaki tip uyumluluğunu mühürler. |
+
+## 📂 Sistem Mimarisi
+
+```text
+├── .enderun/               <-- Sistemin Beyni
+│   ├── agents/             <-- 12 Uzman Ajan Direktifi (Manager, Architect, QA...)
+│   ├── knowledge/          <-- Kurumsal Akıl (ESLint, API, Güvenlik Standartları)
+│   ├── memory-graph/       <-- Ortak Hafıza ve Ajan Bağlamları
+│   ├── queue/              <-- Hermes Mesajlaşma ve Görev Kuyruğu
+│   └── ENDERUN.md          <-- Proje Anayasası (Üst Yasa)
+├── apps/                   <-- Kurumsal Uygulama Alanı
+├── docs/                   <-- Proje Mimari Portalı (ADRs, Tech-Stack)
+└── framework-mcp/          <-- Otonom Operasyon Sunucusu
+```
+
 ---
 
-**Agent Enderun is not just a tool. It is a complete operating system for professional, risk-aware, AI-assisted software development.**
+**Geliştiren / Developed by:** Yusuf BEKAR  
+**Sürüm / Version:** v0.9.0  
+**Lisans / License:** MIT

package/agent.md

@@ -0,0 +1,25 @@
+# Agent Enderun — Antigravity Adapter
+
+This is the primary entry point when using Agent Enderun within the Antigravity (IDE & CLI) ecosystem.
+
+The framework operates under a unified governance structure located in the `.enderun/` directory.
+
+### Primary Constitution
+All governance rules, agent checklists, and project memory live here:
+
+👉 **[.enderun/ENDERUN.md](.enderun/ENDERUN.md)**
+
+### 🤖 Agent Directive
+You are operating under the Agent Enderun governance framework.
+
+At the **start of every session**, before any work:
+1. **Restore Memory:** Read `.enderun/PROJECT_MEMORY.md` to restore state, active Trace ID, and history.
+2. **Load Identity:** Read the relevant agent definition under `.enderun/agents/{agent}.md` (default to `@manager`).
+3. **Internalize Knowledge:** Reference the `.enderun/knowledge/` base for architectural and coding standards.
+
+### 🛡️ Core Mandates
+- **Surgical Edits:** Use `replace_text` or `patch_file` via MCP for precise changes.
+- **Traceability:** Every action must inherit the active Trace ID from memory.
+- **Contract First:** No implementation without verified types.
+
+All paths and references inside the project must comply with the Supreme Constitution located at `.enderun/ENDERUN.md`.

package/bin/cli.js

@@ -1,19 +1,19 @@
 #!/usr/bin/env node
-import { spawn } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-const cliPath = join(__dirname, '../src/cli/index.ts');
+const cliPath = join(__dirname, "../src/cli/index.ts");
 
 // shell: false kullanarak argümanların (tırnakların) bozulmasını önle
-const child = spawn('npx', ['tsx', cliPath, ...process.argv.slice(2)], {
-  stdio: 'inherit',
-  shell: false 
+const child = spawn("npx", ["tsx", cliPath, ...process.argv.slice(2)], {
+    stdio: "inherit",
+    shell: false 
 });
 
-child.on('exit', (code) => {
-  process.exit(code ?? 0);
+child.on("exit", (code) => {
+    process.exit(code ?? 0);
 });

package/bin/update-contract.js

@@ -1,8 +1,5 @@
 #!/usr/bin/env node
 
-/* global console, process */
-/* eslint-disable no-console */
-
 import fs from "fs";
 import path from "path";
 import crypto from "crypto";
@@ -16,51 +13,51 @@ const contractPath = path.join(projectRoot, "apps/backend/contract.version.json"
 const sharedTypesDir = path.join(projectRoot, "apps/backend/src/types");
 
 function collectTypeFiles(dir) {
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
-  const files = [];
-
-  for (const entry of entries) {
-    const fullPath = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...collectTypeFiles(fullPath));
-    } else if (entry.name.endsWith(".ts")) {
-      files.push(fullPath);
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const files = [];
+
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...collectTypeFiles(fullPath));
+        } else if (entry.name.endsWith(".ts")) {
+            files.push(fullPath);
+        }
     }
-  }
 
-  return files;
+    return files;
 }
 
 function calculateHash(dir) {
-  const hash = crypto.createHash("sha256");
-  const files = collectTypeFiles(dir).sort();
+    const hash = crypto.createHash("sha256");
+    const files = collectTypeFiles(dir).sort();
   
-  files.forEach(file => {
-    const content = fs.readFileSync(file);
-    hash.update(path.relative(projectRoot, file));
-    hash.update("\0");
-    hash.update(content);
-    hash.update("\0");
-  });
+    files.forEach(file => {
+        const content = fs.readFileSync(file);
+        hash.update(path.relative(projectRoot, file));
+        hash.update("\0");
+        hash.update(content);
+        hash.update("\0");
+    });
   
-  return hash.digest("hex");
+    return hash.digest("hex");
 }
 
 try {
-  console.log("🔍 Calculating shared-types contract hash...");
-  const newHash = calculateHash(sharedTypesDir);
+    console.log("🔍 Calculating shared-types contract hash...");
+    const newHash = calculateHash(sharedTypesDir);
   
-  const contract = JSON.parse(fs.readFileSync(contractPath, "utf-8"));
+    const contract = JSON.parse(fs.readFileSync(contractPath, "utf-8"));
   
-  if (contract.contract_hash === newHash) {
-    console.log("✅ Contract hash is already up to date.");
-  } else {
-    contract.contract_hash = newHash;
-    contract.last_updated = new Date().toISOString();
-    fs.writeFileSync(contractPath, JSON.stringify(contract, null, 2));
-    console.log(`🚀 Contract updated with new hash: ${newHash.slice(0, 10)}...`);
-  }
+    if (contract.contract_hash === newHash) {
+        console.log("✅ Contract hash is already up to date.");
+    } else {
+        contract.contract_hash = newHash;
+        contract.last_updated = new Date().toISOString();
+        fs.writeFileSync(contractPath, JSON.stringify(contract, null, 2));
+        console.log(`🚀 Contract updated with new hash: ${newHash.slice(0, 10)}...`);
+    }
 } catch (error) {
-  console.error("❌ Failed to update contract hash:", error.message);
-  process.exit(1);
+    console.error("❌ Failed to update contract hash:", error.message);
+    process.exit(1);
 }