agent-enderun 1.0.1 → 1.0.3
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/framework-mcp/package.json +1 -1
- package/package.json +2 -2
- package/src/cli/adapters.ts +37 -4
- package/src/cli/commands/init.ts +143 -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`.
|
|
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.
|
|
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.3 (Singularity)
|
|
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.3** 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.3 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.3**, 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.3 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.3**
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agent-enderun",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.3",
|
|
4
4
|
"description": "The Supreme AI Governance & Orchestration Framework for Enterprise Development",
|
|
5
5
|
"author": "Yusuf BEKAR",
|
|
6
6
|
"license": "MIT",
|
|
@@ -82,7 +82,7 @@
|
|
|
82
82
|
"zod": "^3.24.2"
|
|
83
83
|
},
|
|
84
84
|
"enderun": {
|
|
85
|
-
"version": "1.0.
|
|
85
|
+
"version": "1.0.3",
|
|
86
86
|
"initializedAt": "2026-05-31T09:58:25.773Z"
|
|
87
87
|
},
|
|
88
88
|
"dependencies": {}
|
package/src/cli/adapters.ts
CHANGED
|
@@ -39,7 +39,7 @@ export const ADAPTERS: Record<AdapterId, AdapterConfig> = {
|
|
|
39
39
|
frameworkDir: ".grok",
|
|
40
40
|
shimFile: "grok.md",
|
|
41
41
|
templateDir: ".enderun",
|
|
42
|
-
nestedDirs: ["plugins", "knowledge"],
|
|
42
|
+
nestedDirs: ["plugins", "agents", "knowledge"],
|
|
43
43
|
},
|
|
44
44
|
antigravity: {
|
|
45
45
|
id: "antigravity",
|
|
@@ -63,6 +63,7 @@ export const ADAPTERS: Record<AdapterId, AdapterConfig> = {
|
|
|
63
63
|
*/
|
|
64
64
|
export const FRAMEWORK_DIR_CANDIDATES = [
|
|
65
65
|
".agent",
|
|
66
|
+
".agents",
|
|
66
67
|
".gemini",
|
|
67
68
|
".claude",
|
|
68
69
|
".grok",
|
|
@@ -73,11 +74,43 @@ const SHIM_FILES = ADAPTER_IDS.map((id) => ADAPTERS[id].shimFile);
|
|
|
73
74
|
|
|
74
75
|
export function resolveAdapter(input?: string): AdapterConfig {
|
|
75
76
|
const normalized = (input || "gemini").toLowerCase() as AdapterId;
|
|
77
|
+
let config: AdapterConfig;
|
|
76
78
|
if (ADAPTER_IDS.includes(normalized)) {
|
|
77
|
-
|
|
79
|
+
config = { ...ADAPTERS[normalized] };
|
|
80
|
+
} else {
|
|
81
|
+
console.warn(`⚠️ Unknown adapter "${input}". Falling back to gemini (.gemini/).`);
|
|
82
|
+
config = { ...ADAPTERS.gemini };
|
|
78
83
|
}
|
|
79
|
-
|
|
80
|
-
|
|
84
|
+
|
|
85
|
+
// Dynamic Unified Mode Check:
|
|
86
|
+
// If a root `.enderun` folder exists, --unified flag is passed, or configured in package.json,
|
|
87
|
+
// we override `frameworkDir` to be `.enderun` to avoid folder clutter!
|
|
88
|
+
// We bypass the folder exists check if running unit tests (Vitest) to preserve test integrity.
|
|
89
|
+
const targetDir = process.cwd();
|
|
90
|
+
const enderunExists = fs.existsSync(path.join(targetDir, ".enderun"));
|
|
91
|
+
const hasUnifiedFlag = process.argv.includes("--unified");
|
|
92
|
+
const isTesting = process.env.VITEST === "true" || process.env.NODE_ENV === "test";
|
|
93
|
+
|
|
94
|
+
let forceEnderun = (enderunExists && !isTesting) || hasUnifiedFlag;
|
|
95
|
+
try {
|
|
96
|
+
const pkgPath = path.join(targetDir, "package.json");
|
|
97
|
+
if (fs.existsSync(pkgPath)) {
|
|
98
|
+
const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
|
|
99
|
+
if (pkg.enderun && (pkg.enderun.frameworkDir === ".enderun" || pkg.enderun.frameworkDir === "unified")) {
|
|
100
|
+
forceEnderun = true;
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
} catch {
|
|
104
|
+
// ignore
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
if (forceEnderun) {
|
|
108
|
+
config.frameworkDir = ".enderun";
|
|
109
|
+
// Ensure standard folder names inside .enderun for universal access
|
|
110
|
+
config.nestedDirs = ["agents", "skills", "knowledge"];
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
return config;
|
|
81
114
|
}
|
|
82
115
|
|
|
83
116
|
export function isAdapterShimFile(fileName: string): boolean {
|
package/src/cli/commands/init.ts
CHANGED
|
@@ -202,6 +202,22 @@ export async function initCommand(adapterInput?: string, dryRun = false) {
|
|
|
202
202
|
adapter.id,
|
|
203
203
|
dryRun,
|
|
204
204
|
);
|
|
205
|
+
|
|
206
|
+
if (item === templateDir && adapter.id === "grok") {
|
|
207
|
+
const grokAgentsDest = path.join(targetDir, frameworkDir, "agents");
|
|
208
|
+
ensureDir(grokAgentsDest, dryRun);
|
|
209
|
+
copyDir(
|
|
210
|
+
path.join(src, "agents"),
|
|
211
|
+
grokAgentsDest,
|
|
212
|
+
new Set(skipFiles),
|
|
213
|
+
nonDestructive,
|
|
214
|
+
frameworkDir,
|
|
215
|
+
targetScope,
|
|
216
|
+
sanitizeJson,
|
|
217
|
+
adapter.id,
|
|
218
|
+
dryRun,
|
|
219
|
+
);
|
|
220
|
+
}
|
|
205
221
|
} else {
|
|
206
222
|
if (item === "package.json") continue;
|
|
207
223
|
|
|
@@ -291,6 +307,133 @@ describe("Initial Setup", () => {
|
|
|
291
307
|
console.warn(`[DRY RUN] Would run post-init steps for ${adapter.id}`);
|
|
292
308
|
}
|
|
293
309
|
|
|
310
|
+
// Always scaffold Antigravity (.agents/) workspace directory for cross-compatibility with agy CLI
|
|
311
|
+
if (adapter.id === "antigravity" || adapter.id === "antigravity-cli") {
|
|
312
|
+
const agentsFrameworkDir = path.join(targetDir, ".agents");
|
|
313
|
+
if (!dryRun) {
|
|
314
|
+
try {
|
|
315
|
+
fs.mkdirSync(agentsFrameworkDir, { recursive: true });
|
|
316
|
+
const agentsSubdir = path.join(agentsFrameworkDir, "agents");
|
|
317
|
+
fs.mkdirSync(agentsSubdir, { recursive: true });
|
|
318
|
+
|
|
319
|
+
// Write the 12 agent folders and agent.json files
|
|
320
|
+
const allAgents = [
|
|
321
|
+
{
|
|
322
|
+
name: "manager",
|
|
323
|
+
displayName: "Orchestration & Governance (Team-Lead)",
|
|
324
|
+
description: "CTO, Lead Architect, and Orchestrator for Agent Enderun.",
|
|
325
|
+
instructions: "You are the manager agent. Orchestrate workspace tasks, manage DAG dependency graphs, handle phase transitions, and enforce architectural standards.\n\n🛑 NON-NEGOTIABLE CORE RULES:\n- Single Point of Authority: You are the sole entry point. No specialist acts without your briefing.\n- Traceability: Every action MUST inherit the active Trace ID.\n- Memory Discipline: MUST update PROJECT_MEMORY.md and log actions at the end of EVERY turn."
|
|
326
|
+
},
|
|
327
|
+
{
|
|
328
|
+
name: "backend",
|
|
329
|
+
displayName: "Domain Logic & Databases Specialist",
|
|
330
|
+
description: "Responsible for core business logic, database migrations, security standards, API contracts, and server architecture.",
|
|
331
|
+
instructions: "You are the backend agent. Build secure, high-performance, and consistent server architecture.\n\n🛑 NON-NEGOTIABLE CORE RULES:\n- No UI: Never implement UI or frontend logic.\n- Contract-First: Define shared contracts/branded types BEFORE any consumer code.\n- Branded Types Law: ALL IDs must use branded types (e.g., UserID). Plain strings are forbidden.\n- Zero Mock Policy: Use real endpoints/contracts only.\n- Surgical Edits: Use replace_text for all code changes."
|
|
332
|
+
},
|
|
333
|
+
{
|
|
334
|
+
name: "frontend",
|
|
335
|
+
displayName: "Fluid Responsive UI Specialist",
|
|
336
|
+
description: "Builds responsive fluid user interfaces, manages styling tokens with Panda CSS, and implements state machines.",
|
|
337
|
+
instructions: "You are the frontend agent. Build original, high-performance, and responsive user interfaces.\n\n🛑 NON-NEGOTIABLE CORE RULES:\n- Responsive-First: Mobile-First (320px) is mandatory. Fixed-width is forbidden.\n- Zero UI Library Policy: No shadcn/ui, MUI, etc. Build everything with Panda CSS.\n- Zero Mock Policy: Use real endpoints/contracts only.\n- Contract-First: Use branded types from apps/backend/src/types.\n- No Native Alerts: Use integrated Toaster/Modal components."
|
|
338
|
+
},
|
|
339
|
+
{
|
|
340
|
+
name: "quality",
|
|
341
|
+
displayName: "Automated Testing & Quality Specialist",
|
|
342
|
+
description: "Verifies test coverage, audits compliance with the constitution, conducts AST scanning, and verifies CI/CD status.",
|
|
343
|
+
instructions: "You are the quality agent. Ensure no code is merged or deployed without meeting standards.\n\n🛑 NON-NEGOTIABLE CORE RULES:\n- Final Gate: No code merges or deploys proceed without quality sign-off.\n- Verification-First: Audit lint, typecheck, contract drift, and branded types before sign-off.\n- Never Implement: Audit and assess only. Never write application features.\n- Zero Mock Policy: Integration tests must use real/service-compatible backends.\n- Coverage Gate: Reject approvals if coverage falls below >80% threshold in core."
|
|
344
|
+
},
|
|
345
|
+
{
|
|
346
|
+
name: "database",
|
|
347
|
+
displayName: "Database Migrations & Tuning Specialist",
|
|
348
|
+
description: "Designs SQL schemas, manages migration scripts via Kysely, optimizes queries, indexes, and seeding logic.",
|
|
349
|
+
instructions: "You are the database agent. Build secure, optimized, and scalable data layers.\n\n🛑 NON-NEGOTIABLE CORE RULES:\n- Self-Contained DB: Every backend application MUST manage its own schema/migrations/seeds in its own src/database/ directory.\n- Contract-First: All schemas MUST be derived from branded types.\n- Kysely Standard: Use Kysely for application queries. Raw SQL is forbidden.\n- Zero Mock Policy: Realistic, contract-aware seed data only.\n- Surgical Edits: Use replace_text for all schema/migration changes."
|
|
350
|
+
},
|
|
351
|
+
{
|
|
352
|
+
name: "devops",
|
|
353
|
+
displayName: "Infrastructure & CI/CD Specialist",
|
|
354
|
+
description: "Handles deployment pipelines, environment variables, system containerization, logging & telemetry integrations.",
|
|
355
|
+
instructions: "You are the devops agent. Ensure reliable execution in every environment with strict quality gates.\n\n🛑 NON-NEGOTIABLE CORE RULES:\n- Gate Approvals: NEVER deploy to production without quality gate approval.\n- No Docker Policy: Prefer native Node.js unless explicitly overridden by manager.\n- Environment Parity: Identical configs across dev/staging/prod (except secrets).\n- Secrets Security: NEVER hardcode secrets. Use environment variables.\n- Rollback First: Deployment is BLOCKED if no documented rollback plan exists."
|
|
356
|
+
},
|
|
357
|
+
{
|
|
358
|
+
name: "explorer",
|
|
359
|
+
displayName: "Codebase Discovery Specialist",
|
|
360
|
+
description: "Maps code dependencies, performs project scans, identifies architectural gaps, and supports legacy onboarding.",
|
|
361
|
+
instructions: "You are the explorer agent. Map project structure and provide deep context to other agents.\n\n🛑 NON-NEGOTIABLE CORE RULES:\n- Read-Only: Never write production code. Only discover, map, and report.\n- Search-First: Always use search_codebase before reading large files.\n- Surgical Discovery: Focus on entry points and core domain logic.\n- Zero Mock Policy: Analyze real system state only.\n- Traceability: All findings must be linked to a Trace ID."
|
|
362
|
+
},
|
|
363
|
+
{
|
|
364
|
+
name: "git",
|
|
365
|
+
displayName: "Version Control Specialist",
|
|
366
|
+
description: "Manages commit histories, branches, Trace ID alignment, semantic tagging, and merge conflicts.",
|
|
367
|
+
instructions: "You are the git agent. Ensure a clean, atomic, and traceable repository history.\n\n🛑 NON-NEGOTIABLE CORE RULES:\n- Trace ID Tagging: EVERY commit must include the active Trace ID in the message.\n- Atomic Integrity: Every commit must represent exactly one logical change.\n- Health-First: Never commit code that fails build or basic tests.\n- No Push: Do not run git push without explicit USER approval.\n- No Force: Never use git push --force on public branches."
|
|
368
|
+
},
|
|
369
|
+
{
|
|
370
|
+
name: "mobile",
|
|
371
|
+
displayName: "Mobile App Specialist",
|
|
372
|
+
description: "Develops cross-platform mobile apps using React Native and Expo with clean component states.",
|
|
373
|
+
instructions: "You are the mobile agent. Build high-performance, responsive mobile apps (React Native/Expo).\n\n🛑 NON-NEGOTIABLE CORE RULES:\n- Zero UI Library: Same discipline as web. Build UI from scratch.\n- Contract-First: Use shared types from apps/backend/src/types.\n- Responsive-First: Mobile-First approach is mandatory.\n- Safe Area: Handle iOS/Android safe area insets on every screen.\n- Performance: Target 60 FPS."
|
|
374
|
+
},
|
|
375
|
+
{
|
|
376
|
+
name: "native",
|
|
377
|
+
displayName: "Native OS Integration Specialist",
|
|
378
|
+
description: "Builds lightweight desktop wrappers and system integrations using Tauri or Electron.",
|
|
379
|
+
instructions: "You are the native agent. Build secure, efficient desktop apps (Tauri/Electron).\n\n🛑 NON-NEGOTIABLE CORE RULES:\n- Security-First: No remote code execution. Mandatory sandboxing and strict CSP.\n- Secure Storage: Use Keychain/Credential Manager for sensitive data.\n- IPC Contract: All communication between frontend and native MUST be typed.\n- Contract-First: Define IPC and data contracts before implementation.\n- Surgical Edits: Use replace_text for all code changes."
|
|
380
|
+
},
|
|
381
|
+
{
|
|
382
|
+
name: "security",
|
|
383
|
+
displayName: "Security & Cryptography Specialist",
|
|
384
|
+
description: "Enforces authentication flows, CSP policies, credential rotation, RLS constraints, and cryptographic safety.",
|
|
385
|
+
instructions: "You are the security agent. Ensure all endpoints, database connections, and authentication flows satisfy strict enterprise compliance policies.\n\n🛑 NON-NEGOTIABLE CORE RULES:\n- Sandboxed Security First: Enforce Row Level Security (RLS) on all database tables.\n- Credential Rotation Policy: Credentials, keys, and tokens must never be hardcoded. Use vault/env variables.\n- CSP & CORS Strictness: Never open wildcards (*) for CORS or CSP policies.\n- Surgical Edits: Use replace_text for all security patches."
|
|
386
|
+
},
|
|
387
|
+
{
|
|
388
|
+
name: "analyst",
|
|
389
|
+
displayName: "Contract Verification & Business Analyst",
|
|
390
|
+
description: "Validates business specifications, tests database contract integrity, and audits constitutional compliance.",
|
|
391
|
+
instructions: "You are the analyst agent. Independently verify compliance with contracts and specifications between frontend, backend, and the constitution.\n\n🛑 NON-NEGOTIABLE CORE RULES:\n- Independent Stance: Act as an objective verification gate.\n- Contract-First Law: Ensure contract.version.json perfectly matches types.\n- Escalation Priority: Report all contract drift to manager immediately.\n- Surgical Edits: Use replace_text for all document updates."
|
|
392
|
+
}
|
|
393
|
+
];
|
|
394
|
+
|
|
395
|
+
for (const ag of allAgents) {
|
|
396
|
+
const agentDir = path.join(agentsSubdir, ag.name);
|
|
397
|
+
fs.mkdirSync(agentDir, { recursive: true });
|
|
398
|
+
|
|
399
|
+
const payload = {
|
|
400
|
+
name: ag.name,
|
|
401
|
+
displayName: ag.displayName,
|
|
402
|
+
description: ag.description,
|
|
403
|
+
hidden: false,
|
|
404
|
+
customAgentSpec: {
|
|
405
|
+
customAgent: {
|
|
406
|
+
systemPromptSections: [
|
|
407
|
+
{
|
|
408
|
+
title: "Instructions",
|
|
409
|
+
content: ag.instructions
|
|
410
|
+
}
|
|
411
|
+
],
|
|
412
|
+
toolNames: [
|
|
413
|
+
"view_file",
|
|
414
|
+
"replace_file_content",
|
|
415
|
+
"write_to_file",
|
|
416
|
+
"run_command",
|
|
417
|
+
"grep_search",
|
|
418
|
+
"list_dir"
|
|
419
|
+
]
|
|
420
|
+
}
|
|
421
|
+
}
|
|
422
|
+
};
|
|
423
|
+
|
|
424
|
+
fs.writeFileSync(
|
|
425
|
+
path.join(agentDir, "agent.json"),
|
|
426
|
+
JSON.stringify(payload, null, 2),
|
|
427
|
+
"utf8"
|
|
428
|
+
);
|
|
429
|
+
}
|
|
430
|
+
console.warn(`✅ Scaffolding ${allAgents.length} Antigravity agents under .agents/agents/...`);
|
|
431
|
+
} catch (e) {
|
|
432
|
+
// fallback
|
|
433
|
+
}
|
|
434
|
+
}
|
|
435
|
+
}
|
|
436
|
+
|
|
294
437
|
console.warn(`\n♊ ${adapter.id.toUpperCase()}: Setup complete.`);
|
|
295
438
|
console.warn(` • Framework runtime: ${frameworkDir}/`);
|
|
296
439
|
console.warn(` • Entrypoint shim: ${shimFile}`);
|
package/src/cli/utils/memory.ts
CHANGED
|
@@ -7,6 +7,23 @@ import { FRAMEWORK_DIR_CANDIDATES } from "../adapters.js";
|
|
|
7
7
|
const targetDir = process.cwd();
|
|
8
8
|
|
|
9
9
|
export function getFrameworkDir(): string {
|
|
10
|
+
// 1. Check if configured in package.json to force a single, unified framework directory
|
|
11
|
+
try {
|
|
12
|
+
const pkgPath = path.join(targetDir, "package.json");
|
|
13
|
+
if (fs.existsSync(pkgPath)) {
|
|
14
|
+
const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
|
|
15
|
+
if (pkg.enderun && typeof pkg.enderun.frameworkDir === "string") {
|
|
16
|
+
const customDir = pkg.enderun.frameworkDir;
|
|
17
|
+
if (fs.existsSync(path.join(targetDir, customDir))) {
|
|
18
|
+
return customDir;
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
} catch {
|
|
23
|
+
// ignore
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
// 2. Fall back to dynamic candidate scanning
|
|
10
27
|
for (const dir of FRAMEWORK_DIR_CANDIDATES) {
|
|
11
28
|
const dirPath = path.join(targetDir, dir);
|
|
12
29
|
if (!fs.existsSync(dirPath)) continue;
|