agent-enderun 1.0.2 → 1.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.enderun/PROJECT_MEMORY.md +1 -0
- package/.enderun/agents/manager.md +3 -1
- package/.enderun/logs/manager.json +11 -1
- package/.enderun/skills/agent_handshake.md +37 -0
- package/.enderun/skills/multi_agent_coordination.md +64 -0
- package/.enderun/skills/subagent_lifecycle.md +48 -0
- package/README.md +53 -93
- package/docs/api-referans.md +1137 -0
- package/docs/is_akislari.md +902 -0
- package/docs/mimari.md +926 -0
- package/docs/moduller.md +294 -0
- package/docs/proje.md +521 -0
- package/docs/yap/304/261.md +2150 -0
- package/gemini.md +1 -1
- package/package.json +2 -2
- package/src/cli/adapters.ts +44 -10
- package/src/cli/commands/init.ts +24 -6
- package/src/cli/utils/fs.ts +1 -0
- package/src/cli/utils/memory.ts +17 -0
|
@@ -20,12 +20,14 @@ description: "Orchestration & Governance (Team-Lead) Agent for Agent Enderun"
|
|
|
20
20
|
- **Contract-First:** @backend MUST define contracts BEFORE @frontend begins.
|
|
21
21
|
- **Zero UI & Zero Mock:** Enforce these policies across all agents.
|
|
22
22
|
- **Surgical Edits:** Enforce `replace_text` for all code modifications.
|
|
23
|
+
- **Multi-Agent Coordination:** Orchestrate specialized agents using `multi_agent_coordination.md`, `subagent_lifecycle.md`, and `agent_handshake.md` skills to ensure trace isolation.
|
|
23
24
|
|
|
24
25
|
## 🔌 SESSION STARTUP PROTOCOL
|
|
25
26
|
1. **Restore:** Read `ENDERUN.md` and `PROJECT_MEMORY.md`.
|
|
26
27
|
2. **Scan:** Verify project structure and active tasks.
|
|
27
28
|
3. **Reference:** For planning, delegation, or phase gates, READ `.enderun/knowledge/manager_reference_guide.md` once.
|
|
28
|
-
4. **
|
|
29
|
+
4. **Load Skills:** Load `multi_agent_coordination.md` and `subagent_lifecycle.md` to orchestrate parallel tasks safely.
|
|
30
|
+
5. **Log:** Update memory and log action at the end of every turn.
|
|
29
31
|
|
|
30
32
|
## 🏗️ EXECUTION PROFILE
|
|
31
33
|
- **Lightweight:** @manager, @backend, @frontend, @quality, @explorer.
|
|
@@ -1 +1,11 @@
|
|
|
1
|
-
[
|
|
1
|
+
[
|
|
2
|
+
{
|
|
3
|
+
"timestamp": "2026-05-31T20:35:00.000Z",
|
|
4
|
+
"agent": "@manager",
|
|
5
|
+
"action": "STABLE_RELEASE_PROMOTE",
|
|
6
|
+
"traceId": "01HGT8J5E2N0W0W0W0W0W0W0W5",
|
|
7
|
+
"status": "SUCCESS",
|
|
8
|
+
"summary": "Promoted and mühürlendi stable release v1.0.3 with Unified Brain Architecture, conditional clean scaffolds, Grok army resolution, and 100% passing tests.",
|
|
9
|
+
"findings": "All tests fully passing, workspace pristine, compile-clean."
|
|
10
|
+
}
|
|
11
|
+
]
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: agent_handshake
|
|
3
|
+
type: skill
|
|
4
|
+
version: 1.0.0
|
|
5
|
+
description: "Locking, state synchronization, and permission handshakes for collaborative agents"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# 🤝 Agent Handshake & Scope Synchronization Protocol
|
|
9
|
+
|
|
10
|
+
This skill controls locking, state changes, and workspace access rights to prevent multi-agent collisions and verify transaction-level consistency.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 🔒 1. Scope and File-Level Locking
|
|
15
|
+
|
|
16
|
+
To prevent two agents from modifying the same files concurrently:
|
|
17
|
+
- **Lock Acquisition:** An agent must write `.lock` inside `{{FRAMEWORK_DIR}}/messages/` before executing high-risk file writes.
|
|
18
|
+
- **Queue Check:** Check if another active task in `PROJECT_MEMORY.md` overlaps with the requested `apps/backend/src/` or `apps/web/src/` paths.
|
|
19
|
+
- **Unlock Release:** Delete `.lock` immediately upon writing the message or finishing the transaction.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 🚀 2. State Transition Checklist
|
|
24
|
+
|
|
25
|
+
Before an agent changes its lifecycle state from `IDLE` to `EXECUTING` or `EXECUTING` to `DONE`:
|
|
26
|
+
- Validate that all dependencies in the task DAG are marked as `DONE`.
|
|
27
|
+
- Confirm that the `contract_hash` in `apps/backend/contract.version.json` matches the hash stored in `shared-facts.json`.
|
|
28
|
+
- Log the state transition in the agent's private JSON file.
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## 🛑 3. Deadlock Resolution
|
|
33
|
+
|
|
34
|
+
If a lock persists for more than 3 Retries (1500ms):
|
|
35
|
+
1. **Identify Owner:** Read `PROJECT_MEMORY.md` to see which agent owns the active task.
|
|
36
|
+
2. **Ping Agent:** Send a direct Hermes `ALERT` to the owning agent.
|
|
37
|
+
3. **Escalate to Manager:** If no response, delete the stale lock file, write a `STALE_LOCK_RESOLVED` warning in the log, and notify `@manager`.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: multi_agent_coordination
|
|
3
|
+
type: skill
|
|
4
|
+
version: 1.0.0
|
|
5
|
+
description: "Universal multi-agent coordination protocol for Antigravity, Claude Code, and Gemini CLI"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# 🤝 Universal Multi-Agent Coordination Protocol
|
|
9
|
+
|
|
10
|
+
This skill enables seamless coordination, role delegation, and communication among multiple agents across **Antigravity CLI/IDE**, **Claude Code**, and **Gemini CLI** environments.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 📯 1. The Hermes Event-Driven Handoff
|
|
15
|
+
|
|
16
|
+
Agents must use the Hermes message broker format to delegate sub-tasks and notify peers about execution milestones.
|
|
17
|
+
|
|
18
|
+
### Message File Format (`{{FRAMEWORK_DIR}}/messages/{ULID}.json`)
|
|
19
|
+
When delegating a task or sending an update, write a JSON file with the following schema:
|
|
20
|
+
|
|
21
|
+
```json
|
|
22
|
+
{
|
|
23
|
+
"id": "ULID",
|
|
24
|
+
"traceId": "ACTIVE_TRACE_ID",
|
|
25
|
+
"from": "@sender_agent",
|
|
26
|
+
"to": "@receiver_agent",
|
|
27
|
+
"category": "ACTION | DELEGATION | INFO | ALERT",
|
|
28
|
+
"timestamp": "ISO-8601-TIMESTAMP",
|
|
29
|
+
"content": "Detailed briefing or execution summary",
|
|
30
|
+
"status": "PENDING | IN_PROGRESS | SUCCESS | FAILED"
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### Handoff Protocol Flow:
|
|
35
|
+
1. **Lock Check:** Before writing, verify `{{FRAMEWORK_DIR}}/messages/.lock` does not exist. If locked, retry 3 times with 500ms intervals.
|
|
36
|
+
2. **Write Message:** Write the payload into the `messages/` folder.
|
|
37
|
+
3. **Trigger Loop:** Trigger the orchestration loop via `orchestrate_loop` (MCP) or `npx agent-enderun orchestrate`. Note: Due to kernel sandboxing and security policies in modern AI CLI tools (e.g. Claude Code, Gemini CLI), the CLI does not autonomously spawn background AI processes. Instead, the orchestrator updates `STATUS.md`, writes the briefing payload, and guides the user or the host's native `invoke_subagent` tool to run the next agent session with the correct context.
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## 👥 2. Subagent Lifecycle Management
|
|
42
|
+
|
|
43
|
+
Specialist agents can spawn subagents to perform parallel tasks (e.g. `@backend` delegating database seeding to a subagent).
|
|
44
|
+
|
|
45
|
+
```mermaid
|
|
46
|
+
graph TD
|
|
47
|
+
Parent[@manager / Parent] -->|Briefs & Spawns| Sub[Subagent]
|
|
48
|
+
Sub -->|Reads Context| SubMem[Private Memory]
|
|
49
|
+
Sub -->|Executes Task| Target[Codebase/API]
|
|
50
|
+
Sub -->|Reports Back| Parent
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### Rules for Subagent Lifecycle:
|
|
54
|
+
1. **Briefing Mandate:** Every subagent must receive a clearly defined role, limited file scope, and the parent's active `Trace ID`.
|
|
55
|
+
2. **Memory Isolation:** Subagents write logs to `{{FRAMEWORK_DIR}}/logs/subagent_{ULID}.json` and maintain state in `{{FRAMEWORK_DIR}}/memory-graph/agent-contexts/subagent_{ULID}.json`.
|
|
56
|
+
3. **Merge and Exit:** Once the subagent achieves its goal, it must write a completion report to the parent via Hermes and delete its active lock files.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## 🔒 3. Safe Parallel Execution
|
|
61
|
+
|
|
62
|
+
To avoid race conditions where two agents write to the same files:
|
|
63
|
+
- **Scope Locking:** Before writing code, check the `CRITICAL DECISIONS` and `ACTIVE TASKS` in `PROJECT_MEMORY.md` to ensure no other agent has an active lock on your target workspace scope (`apps/backend` vs `apps/web`).
|
|
64
|
+
- **Conflict Resolution:** If a collision occurs, the agent must immediately pause, switch to `WAITING` status, and send an `ALERT` to `@manager` for resolution.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: subagent_lifecycle
|
|
3
|
+
type: skill
|
|
4
|
+
version: 1.0.0
|
|
5
|
+
description: "Rules for spawning, tracking, and merging autonomous subagents"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# 🌀 Subagent Lifecycle & Dynamic Delegation Protocol
|
|
9
|
+
|
|
10
|
+
This skill outlines the strict workflow for launching and merging subagents in high-concurrency development environments. It ensures complete traceability, isolated execution, and error-free merging.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 🚀 1. The Briefing and Spawning Phase
|
|
15
|
+
|
|
16
|
+
When a parent agent (e.g. `@manager` or `@backend`) determines a task is large or highly parallelizable, it delegates it by spawning a subagent. (Note: Depending on host support, spawning is executed either using the host's native `invoke_subagent` tool, or by printing a structured briefing for user-mediated context handoff).
|
|
17
|
+
|
|
18
|
+
### Spawning Checklist:
|
|
19
|
+
1. **Assign Trace ID:** The parent passes its active Trace ID (ULID) to the subagent.
|
|
20
|
+
2. **Context Restriction:** Limit the subagent's allowed workspaces and file paths (e.g., only `apps/backend/src/database`).
|
|
21
|
+
3. **Declare Role & Goal:** The briefing must specify a distinct capability (e.g. `@database-seed-expert`) and a binary success criterion.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 📊 2. Tracking Execution State
|
|
26
|
+
|
|
27
|
+
Subagents report their current state at regular intervals or upon completing major milestones.
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
[Parent Agent] (Monitors) ──► Reads STATUS.md ◄── [Subagent] (Updates State)
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- **Execution State Map:**
|
|
34
|
+
- `BRIEFED`: Subagent received context and is preparing the environment.
|
|
35
|
+
- `EXECUTING`: Subagent is actively modifying code or writing tests.
|
|
36
|
+
- `DONE`: Task completed; awaiting quality gate validation.
|
|
37
|
+
- `FAILED`: Encountered a blocker; halted execution and escalated to parent.
|
|
38
|
+
|
|
39
|
+
- **Status Logging:** The subagent must log atomic changes to `{{FRAMEWORK_DIR}}/logs/subagent_{ULID}.json` at every step.
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## 🤝 3. Merging and Handoff
|
|
44
|
+
|
|
45
|
+
Once the subagent completes its task:
|
|
46
|
+
1. **Local Type-Safety Verification:** Run `verify-contract` or typecheck the modified scope locally.
|
|
47
|
+
2. **Handoff Briefing:** Write a Hermes message to the parent with a summary of changes, list of edited files, and test results.
|
|
48
|
+
3. **Graceful Exit:** Clean up temporary workspace structures, remove files under `queue/processing`, and self-terminate.
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 🏛️ Agent Enderun — Enterprise AI Governance & Autonomous Orchestration Framework
|
|
2
2
|
|
|
3
|
-
> **Stable Release:** v1.0.
|
|
3
|
+
> **Stable Release:** v1.0.4 (Singularity - Patch 1)
|
|
4
4
|
> **Author:** Yusuf BEKAR
|
|
5
5
|
> **Trace ID:** `01HGT8J5E2N0W0W0W0W0W0W0W5`
|
|
6
6
|
> **System Status:** 🟢 All Systems Operational | Build Compile: Clean | Type-Safety: 100% Verified
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
|
|
12
12
|
**Agent Enderun**, sıradan bir kod şablon üreteci veya basit bir AI asistanı değildir; karmaşık, ölçeklenebilir ve kurumsal (enterprise) düzeydeki yazılım projeleri için özel olarak tasarlanmış bir **Yapay Zeka Yönetişimi ve Otonom Ordu Komuta Sistemidir**.
|
|
13
13
|
|
|
14
|
-
Sürüm **v1.0.
|
|
14
|
+
Sürüm **v1.0.4** itibarıyla sistem; kendi hafızasını yönetebilen, monorepo proje yollarını dinamik olarak haritalayan, tüm ajan seanslarını güvenli şekilde günlükleyen, farklı yapay zeka ekosistemlerini anayasal bir disiplin altında birleştiren ve **macOS & Windows çapraz platform standartlarına tam uyum sağlayan** yaşayan bir mühendislik organizmasıdır.
|
|
15
15
|
|
|
16
16
|
---
|
|
17
17
|
|
|
@@ -20,36 +20,29 @@ Sürüm **v1.0.0** itibarıyla sistem; kendi hafızasını yönetebilen, monorep
|
|
|
20
20
|
Yapay zeka kodlama yardımcıları (Claude Code, Gemini CLI, Grok Build vb.) geliştikçe, kurumsal projelerde kontrolü kaybetmek çok daha kolay hale gelmiştir. Agent Enderun, aşağıdaki kritik **kurumsal problemleri çözmek** amacıyla doğmuştur:
|
|
21
21
|
|
|
22
22
|
1. **Kontrolsüz ve Hatalı Değişiklikler (Rogue AI):** Ajanların tüm kod dosyasını baştan yazmasını engelleyerek **milyonlarca satırlık kodları cerrahi hassasiyetle (`replace_text` / `patch_file` üzerinden)** değiştirmeye zorlar. Token tüketimini ve hata oranını %90 azaltır.
|
|
23
|
-
2. **Kayıp Hafıza ve Bağlam Drifti:** Ajanlar oturum değiştirdikçe projenin geçmişini ve mimari kararlarını unutur. Enderun, **`.enderun/PROJECT_MEMORY.md`**
|
|
23
|
+
2. **Kayıp Hafıza ve Bağlam Drifti:** Ajanlar oturum değiştirdikçe projenin geçmişini ve mimari kararlarını unutur. Enderun, **`.enderun/PROJECT_MEMORY.md`** dosyasını projenin değişmez tek doğruluk kaynağı (SSOT) haline getirerek, seanslar arası bağlam kaybını tamamen engeller.
|
|
24
24
|
3. **Frontend-Backend Tip Uyuşmazlığı:** Backend tip tanımlamalarında en ufak bir kayma olduğunda, otonom SHA-256 hash hesaplama ve kontrat denetleme motoru (`update-contract` / `verify-contract`) sayesinde arayüz kodları yazılmadan önce hatalar yakalanır.
|
|
25
25
|
4. **Çoklu Ajan Kaosu:** **12** farklı uzman yapay zeka ajanı, olay tabanlı asenkron bir haberleşme protokolü olan **Hermes Message Broker** üzerinden koordine edilir. Ajanlar birbirine rastgele müdahale edemez; tüm görevler bir İş Dağılım Grafiği (DAG) üzerinden komuta edilir.
|
|
26
26
|
5. **Sandbox ve Güvenlik Sınırlamaları:** Claude Code gibi modern araçların kernel düzeyindeki güvenlik yalıtımlarını (bubblewrap/seatbelt) ihlal etmemek adına, tüm bellek, kuyruk ve günlük mekanizmaları proje kök klasöründeki lokal adaptör yollarında (**`.enderun/`**, `.gemini/`, `.claude/`, `.grok/` vb.) saklanır; `/tmp` veya dış dizinleri kullanmayarak sıfır hata ile çalışır.
|
|
27
27
|
|
|
28
28
|
---
|
|
29
29
|
|
|
30
|
-
### 🚀 Sürüm v1.0.
|
|
30
|
+
### 🚀 Sürüm v1.0.4 Singularity Kararlı Sürüm Devrimsel Özellikleri
|
|
31
31
|
|
|
32
|
-
1.
|
|
32
|
+
1. **🧠 Pürüzsüz ve Klasör Kalabalığından Arındırılmış Birleşik Beyin Mimarisi (Unified Brain):**
|
|
33
|
+
* Ajanların ve MCP sunucusunun tek bir ortak beyin (`.enderun/`) altında çalışmasını sağlayan **Birleşik Beyin Mimarisi** hayata geçirildi. `--unified` flag'i kullanıldığında veya `package.json` üzerinden kilitlendiğinde, tüm asistan şimleri (`gemini.md`, `claude.md`, `grok.md`) ve hafıza kuyrukları tek bir klasörde birleşir; ek dosya veya klasör kalabalığı kesinlikle oluşturulmaz.
|
|
34
|
+
* Antigravity için kullanılan `.agents` klasör üretimi sadece Antigravity adaptörlerine sınırlandırılarak, diğer asistanların kurulum alanları son derece sade ve pürüzsüz hale getirildi.
|
|
35
|
+
2. **🛸 Grok Build 12 Ajanlık Ordu Yeteneği ve Boş Klasör Çözümü:**
|
|
36
|
+
* Grok adaptörünün ilklendirilmesi esnasında ajan tanımlarının ve yaşam döngüsü şemalarının eksik çıkması sorunu cerrahi müdahale ile giderildi. Ajan tanımları hem `.grok/plugins/` hem de `.grok/agents/` klasörlerine tam ve kusursuz olarak çift eşlenerek Grok asistanının da 12 ajanlık tam ordu disiplinini yüklemesi sağlandı.
|
|
37
|
+
3. **⚡ Kurumsal Tip Uyuşmazlığı ve Sözleşme İyileştirmesi:**
|
|
33
38
|
* Backend tip tanımlamalarında `constants.ts` boşluğundan kaynaklanan ve `logs.ts`/`models.ts` dosyalarının derlenmesini engelleyen tip uyuşmazlığı hatası giderildi. `apps/backend/src/types/constants.ts` dosyası kurumsal sabitler (`ProjectPhase`, `ExecutionProfile`, `TaskPriority`, `TaskStatus`, `ActionType`, `ActionStatus`) ile donatıldı.
|
|
34
|
-
2. **🖥️ CLI `sanitizeJson` Tipleme Düzeltmesi:**
|
|
35
39
|
* `src/cli/commands/init.ts` içerisindeki `SanitizeJsonFunction` arayüzü ile uyumlu olması için `src/cli/utils/pkg.ts` altındaki `sanitizeJson` fonksiyonunun parametre tipi `Record<string, unknown>` yerine geniş `unknown` tipine taşınarak derleme hataları tamamen arındırıldı.
|
|
36
|
-
|
|
40
|
+
4. **🏁 macOS & Windows Çapraz Platform Uyum Düzeltmeleri:**
|
|
37
41
|
* Windows ortamında Node.js'in `spawn` ile `npx` çalıştırırken `ENOENT` fırlatmasını önlemek için sistem algılama mekanizması eklenerek `process.platform === "win32"` ise `npx.cmd` çalıştırılması sağlandı.
|
|
38
42
|
* Windows'ta Git satır sonlarından kaynaklanan binlerce ESLint hatasını önlemek için `eslint.config.js` altındaki `linebreak-style` kuralı kapatıldı (`linebreak-style: "off"`).
|
|
39
|
-
|
|
40
|
-
---
|
|
41
|
-
|
|
42
|
-
### 🚀 Sürüm v0.9.4 İle Gelen Devrimsel Yenilikler
|
|
43
|
-
|
|
44
|
-
1. **🔒 Claude Code & Desktop Sandbox Uyumlu MCP Mimarisi:**
|
|
43
|
+
5. **🔒 Claude Code & Desktop Sandbox Uyumlu MCP Mimarisi:**
|
|
45
44
|
* Claude Desktop ve Claude Code CLI'ın güvenlik yalıtımlarına (sandbox) uyum sağlamak amacıyla, MCP sunucusunun otonom çalışacağı aktif proje dizinini dinamik çözümleyen `ENDERUN_PROJECT_ROOT` ortam değişkeni altyapısı sisteme entegre edildi.
|
|
46
|
-
* `claude` adaptörü kurulurken, Claude
|
|
47
|
-
2. **📂 Claude Desktop & CLI Yapılandırma Düzeltmeleri:**
|
|
48
|
-
* Kod tabanında eskiden aranan yanlış `config.json` yolları temizlendi; yerine macOS ve Windows'taki gerçek Claude Desktop ayar dosyası olan **`claude_desktop_config.json`** ve küresel Claude Code CLI ayar dosyası olan **`~/.claude.json`** entegrasyonları getirildi.
|
|
49
|
-
3. **🛸 Grok Entegrasyonunun Sektör Standartlarına Uyumlanması:**
|
|
50
|
-
* Grok adaptörünün kullandığı varsayılan çalışma dizini jenerik `.agent` yerine, resmi ve topluluk standardı olan **`.grok/`** ve **`grok.md`** olarak güncellendi. Geriye dönük uyumluluk korunarak `.agent` aday dizin listesinde tutuldu.
|
|
51
|
-
4. **🧹 Kod Tekrarlarının Arındırılması ve SSOT Standardı:**
|
|
52
|
-
* `src/cli/utils/app.ts` içerisindeki mükerrer `getFrameworkDir` ve `getMemoryPath` fonksiyonları arındırılarak, `./memory.js` üzerindeki tekil doğruluk kaynağı ile birleştirildi.
|
|
45
|
+
* `claude` adaptörü kurulurken, Claude Desktop ve Claude Code CLI global yapılandırmalarını (`claude_desktop_config.json`, `~/.claude.json`) otomatik tarayarak MCP sunucusunu sisteme kaydeder.
|
|
53
46
|
|
|
54
47
|
---
|
|
55
48
|
|
|
@@ -59,7 +52,7 @@ Agent Enderun, sektörün öncüsü olan yapay zeka ekosistemlerini bir araya ge
|
|
|
59
52
|
* **🚀 Claude Code (Operasyonel Cerrahi):** **Saha Mühendisi**. Kod tabanındaki otonom ve milimetrik cerrahi düzenlemeleri (Surgical Edits) gerçekleştirir.
|
|
60
53
|
* **♊ Gemini & Vertex AI (Komuta İstihbaratı):** **Stratejik Karar Merkezi**. Proje geçmişini, mimari kararları analiz eder ve yüksek seviyeli stratejik yönlendirmeler yapar.
|
|
61
54
|
* **🛸 Antigravity (İç Disiplin & Akademi):** **Askeri Akademi**. İç standartları, anayasal uyumu korumak amacıyla izole edilmiş, yüksek disiplinli geliştirme ve test ortamı sağlar.
|
|
62
|
-
* **🤖 Grok / X.ai (Otonom Keşif Kanadı):** **Deneysel Keşif**. Gelecek vizyonlu otonom protokolleri test eder ve yapay zeka
|
|
55
|
+
* **🤖 Grok / X.ai (Otonom Keşif Kanadı):** **Deneysel Keşif**. Gelecek vizyonlu otonom protokolleri test eder ve yapay zeka güdümlü geliştirme sınırlarını zorlar.
|
|
63
56
|
|
|
64
57
|
---
|
|
65
58
|
|
|
@@ -82,13 +75,15 @@ Tüm operasyonlar, uzmanlık alanlarına göre ayrılmış ve Hermes protokolüy
|
|
|
82
75
|
| **`@security`** | Sistem Güvenliği | Kimlik doğrulamaları, CSP kuralları, API anahtarı rotasyonları ve RLS yetkilendirme kapısı. |
|
|
83
76
|
| **`@analyst`** | İş Analizi & Kontrat Sağlığı | Veritabanı kontrat doğrulaması, anayasal uyum denetimi ve bağımsız kalite analizleri. |
|
|
84
77
|
|
|
78
|
+
---
|
|
79
|
+
|
|
85
80
|
### 🪙 Token Ekonomisi ve Bellek Mimarisi (Token Economy & Memory Design)
|
|
86
81
|
|
|
87
82
|
Agent Enderun, otonom yazılım geliştirme süreçlerinde **bağlam driftini (context drift) engellemek** ve **API maliyetlerini %90 oranında düşürmek** amacıyla katmanlı bir bellek mimarisi ve token ekonomisi protokolü kullanır.
|
|
88
83
|
|
|
89
84
|
#### A. Katmanlı Bellek Modeli (Tiered Memory Model)
|
|
90
85
|
Sistem, projenin ortak aklını ve ajanların özel seans bağlamlarını 3 farklı katmanda saklar:
|
|
91
|
-
1. **Ortak Proje Hafızası (`.enderun/PROJECT_MEMORY.md`):** Aktif fazı, benzersiz Trace ID'yi, kritik mimari kararları ve ordu çapındaki aktif görevleri (DAG) tutan projenin ortak SSOT
|
|
86
|
+
1. **Ortak Proje Hafızası (`.enderun/PROJECT_MEMORY.md`):** Aktif fazı, benzersiz Trace ID'yi, kritik mimari kararları ve ordu çapındaki aktif görevleri (DAG) tutan projenin ortak SSOT beynidir.
|
|
92
87
|
2. **Paylaşılan Genel Gerçekler (`memory-graph/shared-facts.json`):** Teknolojik stack tercihleri, aktif kodlama politikaları ve kontrat hash adresleri gibi statik verileri barındırır.
|
|
93
88
|
3. **Özel Ajan Bellekleri (`memory-graph/agent-contexts/{agent}.json`):** Her uzman ajanın kendi geçmiş seans özetlerini, üstlendiği kararları ve üzerinde çalıştığı aktif geliştirme detaylarını tutan yalıtılmış bellek hücreleridir.
|
|
94
89
|
|
|
@@ -104,7 +99,6 @@ Yapay zeka ajanları her oturumda veya görev atamasında şu akışı otonom ol
|
|
|
104
99
|
|
|
105
100
|
---
|
|
106
101
|
|
|
107
|
-
|
|
108
102
|
### 🛠️ Kurulum & Adaptör Entegrasyon Kılavuzu
|
|
109
103
|
> [!IMPORTANT]
|
|
110
104
|
> **Mimari Hatırlatma:** Model Context Protocol (MCP) araçları, **insan geliştirici (kullanıcı) tarafından manuel olarak çalıştırılmaz.** MCP sunucu araçları; yapay zeka ajanlarının (Claude Code, Gemini, Grok) projeniz üzerinde cerrahi kod yazma, durum sorgulama ve Hermes mesajlaşma gibi eylemleri **otonom olarak çalıştırabilmesi** için arka planda yapay zeka motorlarına bağlanır. İnsan geliştirici ise komuta sürecini CLI (`status`, `trace:new` vb.) üzerinden yönetir.
|
|
@@ -114,30 +108,28 @@ Gemini CLI veya Vertex AI entegrasyonu için proje dizininizde aşağıdaki komu
|
|
|
114
108
|
```bash
|
|
115
109
|
npx agent-enderun init gemini
|
|
116
110
|
```
|
|
117
|
-
* **
|
|
118
|
-
|
|
111
|
+
* **Birleşik Mimari (Önerilen):** Tüm adaptörleri tek klasörde birleştirip kalabalığı önlemek için `--unified` parametresini kullanın:
|
|
112
|
+
```bash
|
|
113
|
+
npx agent-enderun init gemini --unified
|
|
114
|
+
```
|
|
119
115
|
|
|
120
116
|
#### 2. Claude Adaptörü Kurulumu (Claude Code & Desktop)
|
|
121
117
|
Claude Desktop uygulamasında ve Claude Code CLI aracında otonom orduyu aktif etmek için:
|
|
122
118
|
```bash
|
|
123
119
|
npx agent-enderun init claude
|
|
124
120
|
```
|
|
125
|
-
* **Oluşturulan Yapı:** Proje kökünde `.claude/` dizini, `claude.md` ve en önemlisi proje-seviyesinde **`.mcp.json`** dosyası oluşturulur.
|
|
126
|
-
* **Küresel Kayıt & Ajan Entegrasyonu:** Komut, sisteminizde kurulu olan Claude Desktop yapılandırmasını (`claude_desktop_config.json`) ve Claude Code küresel yapılandırmasını (`~/.claude.json`) tarayarak MCP sunucusunu otomatik olarak kaydeder. Bu sayede Claude (AI Ajanı) araçlarımızı otonom olarak çağırabilir.
|
|
127
121
|
|
|
128
122
|
#### 3. Grok Adaptörü Kurulumu
|
|
129
123
|
xAI Grok Build veya topluluk CLI araçları için:
|
|
130
124
|
```bash
|
|
131
125
|
npx agent-enderun init grok
|
|
132
126
|
```
|
|
133
|
-
* **Oluşturulan Yapı:** Proje kökünde **`.grok/`** dizini ve **`grok.md`** şim dosyası oluşturulur.
|
|
134
127
|
|
|
135
128
|
#### 4. Antigravity Adaptörü Kurulumu
|
|
136
|
-
Antigravity IDE ve CLI
|
|
129
|
+
Antigravity IDE ve CLI entegrasyonlerini etkinleştirmek için:
|
|
137
130
|
```bash
|
|
138
131
|
npx agent-enderun init antigravity
|
|
139
132
|
```
|
|
140
|
-
* **Oluşturulan Yapı:** `.gemini/antigravity/` veya `.gemini/antigravity-cli/` dizinleri altında yüksek disiplinli izole çalışma ortamları oluşturulur.
|
|
141
133
|
|
|
142
134
|
---
|
|
143
135
|
|
|
@@ -145,39 +137,14 @@ npx agent-enderun init antigravity
|
|
|
145
137
|
|
|
146
138
|
Enderun CLI, `agent-enderun` (veya `npx agent-enderun`) komutu ile yönetilir.
|
|
147
139
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
*
|
|
151
|
-
*
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
*
|
|
156
|
-
|
|
157
|
-
#### `check`
|
|
158
|
-
Anayasal uyumluluk denetimlerini, kritik dosya bütünlüklerini ve dizin doğrulamalarını gerçekleştirir.
|
|
159
|
-
* **Kullanım:** `npx agent-enderun check`
|
|
160
|
-
|
|
161
|
-
#### `trace:new [description]`
|
|
162
|
-
Belirli bir geliştirme zinciri için yeni bir Trace ID (ULID) tetikler.
|
|
163
|
-
* **Kullanım:** `npx agent-enderun trace:new "Giriş modülü tasarımı" [agent-name] [priority]`
|
|
164
|
-
* **Örnek:** `npx agent-enderun trace:new "Auth module design" backend P1`
|
|
165
|
-
|
|
166
|
-
#### `orchestrate` / `loop`
|
|
167
|
-
Hermes Message Broker asenkron event-driven ajanlar arası iletişim döngüsünü canlı olarak başlatır.
|
|
168
|
-
* **Kullanım:** `npx agent-enderun orchestrate`
|
|
169
|
-
|
|
170
|
-
#### `verify-contract`
|
|
171
|
-
Frontend ve backend katmanları arasındaki tip bütünlüğünü ve `contract.version.json` uygunluğunu kontrol eder.
|
|
172
|
-
* **Kullanım:** `npx agent-enderun verify-contract`
|
|
173
|
-
|
|
174
|
-
#### `update-contract`
|
|
175
|
-
Backend tiplerinde yapılan değişiklikleri tarayarak `contract.version.json` üzerindeki SHA-256 hash imzalarını otonom olarak günceller.
|
|
176
|
-
* **Kullanım:** `npx agent-enderun update-contract`
|
|
177
|
-
|
|
178
|
-
#### `create-app [idea]`
|
|
179
|
-
Doğal dildeki açıklamalardan, kurumsal standartlarda kontrat-tabanlı monorepo uygulaması üretir.
|
|
180
|
-
* **Kullanım:** `npx agent-enderun create-app "Müşteri CRM Paneli"`
|
|
140
|
+
* **`init [adapter] [--unified]`**: Seçilen adaptörü kurar. `--unified` kullanılırsa tüm asistan şimleri doğrudan `.enderun` altında birleşir; klasör kalabalığı sıfırlanır.
|
|
141
|
+
* **`status`**: Projenin aktif fazını (Phase 0 - 4), aktif Trace ID'sini ve uzman ajanların durumlarını listeler.
|
|
142
|
+
* **`check`**: Anayasal uyumluluk denetimlerini, kritik dosya bütünlüklerini ve dizin doğrulamalarını gerçekleştirir.
|
|
143
|
+
* **`trace:new [description]`**: Belirli bir geliştirme zinciri için yeni bir Trace ID (ULID) tetikler.
|
|
144
|
+
* **`orchestrate` / `loop`**: Hermes Message Broker asenkron event-driven ajanlar arası iletişim döngüsünü canlı olarak başlatır.
|
|
145
|
+
* **`verify-contract`**: Frontend ve backend katmanları arasındaki tip bütünlüğünü denetler.
|
|
146
|
+
* **`update-contract`**: Backend tiplerinde yapılan değişiklikleri tarayarak `contract.version.json` üzerindeki SHA-256 hash imzalarını günceller.
|
|
147
|
+
* **`create-app [idea]`**: Doğal dildeki açıklamalardan, kurumsal standartlarda kontrat-tabanlı monorepo uygulaması üretir.
|
|
181
148
|
|
|
182
149
|
---
|
|
183
150
|
|
|
@@ -200,7 +167,7 @@ npm init -y
|
|
|
200
167
|
npm link agent-enderun
|
|
201
168
|
|
|
202
169
|
# Herhangi bir adaptör kurulumunu başlatın
|
|
203
|
-
npx agent-enderun init gemini
|
|
170
|
+
npx agent-enderun init gemini --unified
|
|
204
171
|
```
|
|
205
172
|
|
|
206
173
|
---
|
|
@@ -210,7 +177,7 @@ npx agent-enderun init gemini
|
|
|
210
177
|
|
|
211
178
|
**Agent Enderun** is not a generic boilerplate generator or a simple AI wrapper; it is an elite, state-of-the-art **AI Governance and Autonomous Army Command System** designed for complex, scalable, and highly auditable enterprise software projects.
|
|
212
179
|
|
|
213
|
-
As of **v1.0.
|
|
180
|
+
As of **v1.0.4**, the system operates as a **"Living Engineering Organism"** capable of managing its own persistent memory, dynamically mapping project directory scopes, secure-logging expert agent activities, and **fully complying with cross-platform (macOS & Windows) scripting and standard setups**.
|
|
214
181
|
|
|
215
182
|
---
|
|
216
183
|
|
|
@@ -219,36 +186,29 @@ As of **v1.0.0**, the system operates as a **"Living Engineering Organism"** cap
|
|
|
219
186
|
As AI coding assistants (Claude Code, Gemini CLI, Grok Build, etc.) become increasingly powerful, software projects are prone to rapid architectural drift and token wastage. Agent Enderun solves these critical **enterprise AI challenges**:
|
|
220
187
|
|
|
221
188
|
1. **Rogue AI Prevention (Surgical Edits):** It strictly prohibits agents from rewriting entire files. Instead, it forces them to execute micro-targeted changes via **`replace_text` / `patch_file` tools**, reducing API token consumption by up to 90%.
|
|
222
|
-
2. **Context Loss Prevention (SSOT Memory):** AI agents naturally lose project history across chats. Enderun seals all project milestones, decisions, and tasks into a self-pruning **`.enderun/PROJECT_MEMORY.md`**
|
|
189
|
+
2. **Context Loss Prevention (SSOT Memory):** AI agents naturally lose project history across chats. Enderun seals all project milestones, decisions, and tasks into a self-pruning **`.enderun/PROJECT_MEMORY.md`** file, ensuring absolute context continuity.
|
|
223
190
|
3. **Contract-First Safety (Frontend-Backend Drift):** Before any user interface code is written, API models and branded types are sealed. The **autonomous** contract verification engine checks SHA-256 type definitions to prevent integration drifts.
|
|
224
191
|
4. **Symmetric Orchestration (Hermes Protocol):** **12** specialized expert agents communicate via an asynchronous, event-driven message broker (**Hermes**), preventing chaotic, uncoordinated AI behavior.
|
|
225
192
|
5. **Sandbox & Security Compliance:** Modern CLI agents (like Claude Code) restrict filesystem access. By keeping all configurations, task logs, and queues local (inside **`.enderun/`**, `.gemini/`, `.claude/`, `.grok/`, etc.) in the project workspace, Enderun runs with **zero sandbox violations**.
|
|
226
193
|
|
|
227
194
|
---
|
|
228
195
|
|
|
229
|
-
### 🚀 Key Improvements in Version v1.0.
|
|
196
|
+
### 🚀 Key Improvements in Version v1.0.4 Stable Release
|
|
230
197
|
|
|
231
|
-
1.
|
|
198
|
+
1. **🧠 Clutter-Free Unified Brain Architecture:**
|
|
199
|
+
* Designed and implemented the **Unified Brain Architecture** that dynamically targets the centralized `.enderun/` directory for all platform shims (`gemini.md`, `claude.md`, `grok.md`) and memory queues when `--unified` is active or locked in `package.json`. This eliminates redundant folder clutter.
|
|
200
|
+
* Restricted `.agents` folder creation exclusively to Antigravity environments, keeping Gemini, Claude, and Grok folder structures completely clean.
|
|
201
|
+
2. **🛸 Grok Build 12-Agent Capability & Empty Directory Patch:**
|
|
202
|
+
* Surgically resolved empty plugins/agents directory gaps in Grok. Scaffolded files are now mirrored into both `.grok/plugins/` and `.grok/agents/` directories, delivering full 12-agent MD profiles and lifecycle schemas to Grok.
|
|
203
|
+
3. **⚡ Enterprise Type-Safety & Contract Synchronization:**
|
|
232
204
|
* Surgically resolved the type-safety compilation gap where `apps/backend/src/types/constants.ts` was empty but logs and models attempted to import from it. Populated `constants.ts` with all required contract types (`ProjectPhase`, `ExecutionProfile`, `TaskPriority`, `TaskStatus`, `ActionType`, `ActionStatus`).
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
3. **🏁 macOS & Windows Cross-Platform Compatibility Patches:**
|
|
205
|
+
* Patched `sanitizeJson` input parameter in `src/cli/utils/pkg.ts` to `unknown` type to match `SanitizeJsonFunction` contract in `copyDir` and fully resolve CLI compilation warnings.
|
|
206
|
+
4. **🏁 macOS & Windows Cross-Platform Compatibility Patches:**
|
|
236
207
|
* Resolved Windows spawn `ENOENT` crashes by conditionally spawning `npx.cmd` instead of `npx` on Windows (`process.platform === "win32"`).
|
|
237
208
|
* Disabled the strict `linebreak-style` ESLint rule in `eslint.config.js` (`linebreak-style: "off"`) to fully support CRLF line endings on Windows without throwing lint errors.
|
|
238
|
-
|
|
239
|
-
---
|
|
240
|
-
|
|
241
|
-
### 🚀 Key Improvements in Version v0.9.4
|
|
242
|
-
|
|
243
|
-
1. **🔒 Claude Sandbox-Compliant MCP Architecture:**
|
|
209
|
+
5. **🔒 Claude Sandbox-Compliant MCP Architecture:**
|
|
244
210
|
* Integrated the `ENDERUN_PROJECT_ROOT` environment variable mapping, allowing the Model Context Protocol (MCP) server to dynamically resolve the target workspace root even when globally spawned by Claude Desktop.
|
|
245
|
-
*
|
|
246
|
-
2. **📂 Robust Claude Config Resolution:**
|
|
247
|
-
* Patched path resolution to look for macOS/Windows **`claude_desktop_config.json`** (instead of standard `config.json`) and Claude Code CLI global configuration **`~/.claude.json`**.
|
|
248
|
-
3. **🛸 Official Grok/xAI Directory Alignment:**
|
|
249
|
-
* Aligned Grok's default `frameworkDir` from the generic `.agent` directory to the standard **`.grok/`** folder and **`grok.md`** shim file.
|
|
250
|
-
4. **🧹 Refactoring and Code Compaction:**
|
|
251
|
-
* Removed duplicated local `getFrameworkDir` and `getMemoryPath` helpers in `src/cli/utils/app.ts`, merging them directly into `./memory.js` to respect the Single Source of Truth rule.
|
|
211
|
+
* Patched path resolution to look for macOS/Windows `claude_desktop_config.json` and Claude Code CLI global configuration `~/.claude.json`.
|
|
252
212
|
|
|
253
213
|
---
|
|
254
214
|
|
|
@@ -281,6 +241,8 @@ All workspace operations are divided among 12 specialized expert agents connecte
|
|
|
281
241
|
| **`@security`** | System Security | Security credentials, CSP configurations, API key rotations, and RLS authorization gate. |
|
|
282
242
|
| **`@analyst`** | Requirement Analysis & Contract Health | Database contract verification, constitutional compliance audits, and independent quality analysis. |
|
|
283
243
|
|
|
244
|
+
---
|
|
245
|
+
|
|
284
246
|
### 🪙 Token Economy & Memory Architecture
|
|
285
247
|
|
|
286
248
|
Agent Enderun utilizes a strongly-disciplined **Tiered Memory Model** and **Token Economy Protocol** to prevent context drift and reduce LLM prompt API consumption by up to **90%** during autonomous execution loops.
|
|
@@ -303,7 +265,6 @@ Enderun specialists autonomously coordinate context loading using the following
|
|
|
303
265
|
|
|
304
266
|
---
|
|
305
267
|
|
|
306
|
-
|
|
307
268
|
### 🛠️ Adapter Scaffolding & Setup Guide
|
|
308
269
|
> [!IMPORTANT]
|
|
309
270
|
> **Architectural Note:** Model Context Protocol (MCP) tools are **not meant to be executed manually by the human developer (user).** Instead, the MCP server runs in the background, allowing AI Agents (Claude Code, Gemini, Grok) to **autonomously execute** our custom tools (like surgical editing, state reading, or Hermes messaging) on your codebase. The human developer controls and monitors this command loop using standard CLI commands (`status`, `trace:new`, etc.).
|
|
@@ -313,29 +274,28 @@ Initialize the Gemini CLI / Vertex AI environment:
|
|
|
313
274
|
```bash
|
|
314
275
|
npx agent-enderun init gemini
|
|
315
276
|
```
|
|
316
|
-
* **
|
|
277
|
+
* **Unified Architecture (Recommended):** Use `--unified` to merge all adapters into a single folder and prevent folder clutter:
|
|
278
|
+
```bash
|
|
279
|
+
npx agent-enderun init gemini --unified
|
|
280
|
+
```
|
|
317
281
|
|
|
318
282
|
#### 2. Claude Adapter (Claude Code CLI & Desktop App)
|
|
319
283
|
Bootstrap the framework for Anthropic's Claude:
|
|
320
284
|
```bash
|
|
321
285
|
npx agent-enderun init claude
|
|
322
286
|
```
|
|
323
|
-
* **Created Files:** `.claude/` folder, `claude.md` shim, and project-level **`.mcp.json`** for Claude Code.
|
|
324
|
-
* **Global Registration & Agent Integration:** Automatically discovers and registers the MCP server in Claude Desktop's `claude_desktop_config.json` and Claude Code's `~/.claude.json`, enabling Claude (AI Agent) to autonomously call and execute our tools.
|
|
325
287
|
|
|
326
288
|
#### 3. Grok Adapter
|
|
327
289
|
Scaffold for xAI Grok Build:
|
|
328
290
|
```bash
|
|
329
291
|
npx agent-enderun init grok
|
|
330
292
|
```
|
|
331
|
-
* **Created Files:** **`.grok/`** folder and **`grok.md`** shim file.
|
|
332
293
|
|
|
333
294
|
#### 4. Antigravity Adapter
|
|
334
295
|
Bootstrap the high-discipline sandbox for Antigravity IDE and CLI runtimes:
|
|
335
296
|
```bash
|
|
336
297
|
npx agent-enderun init antigravity
|
|
337
298
|
```
|
|
338
|
-
* **Created Files:** `.gemini/antigravity/` or `.gemini/antigravity-cli/` isolated paths.
|
|
339
299
|
|
|
340
300
|
---
|
|
341
301
|
|
|
@@ -343,7 +303,7 @@ npx agent-enderun init antigravity
|
|
|
343
303
|
|
|
344
304
|
Execute commands via `agent-enderun` (or `npx agent-enderun`):
|
|
345
305
|
|
|
346
|
-
* **`init [adapter]`**: Scaffold framework directories and register local/global MCP server instances.
|
|
306
|
+
* **`init [adapter] [--unified]`**: Scaffold framework directories and register local/global MCP server instances.
|
|
347
307
|
* **`status`**: Output active Phase (0-4), current active Trace ID, and agent capability logs.
|
|
348
308
|
* **`check`**: Run a thorough framework integrity, folder alignment, and constitutional compliance check.
|
|
349
309
|
* **`trace:new [desc] [agent] [priority]`**: Launch a new traceable task chain stamped with a unique ULID.
|
|
@@ -373,9 +333,9 @@ npm init -y
|
|
|
373
333
|
npm link agent-enderun
|
|
374
334
|
|
|
375
335
|
# Bootstrap scaffolding
|
|
376
|
-
npx agent-enderun init gemini
|
|
336
|
+
npx agent-enderun init gemini --unified
|
|
377
337
|
```
|
|
378
338
|
|
|
379
339
|
---
|
|
380
340
|
|
|
381
|
-
Developed with absolute discipline | Developer **Yusuf BEKAR** | Framework Version **v1.0.
|
|
341
|
+
Developed with absolute discipline | Developer **Yusuf BEKAR** | Framework Version **v1.0.4**
|