agent-enderun 0.8.8 → 0.9.1

package/docs/getting-started.md

@@ -1,263 +1,13 @@
-# 🚀 Getting Started — Sıfırdan Agent Enderun ile Proje Kurma Rehberi / Quickstart Guide
+# Quickstart Guide for New Agent Enderun Projects
 
-[English](#english) | [Türkçe](#türkçe)
+This guide is prepared for developers who want to set up Agent Enderun in a new project from scratch.
 
----
+> **As of v0.9.1, the primary initialization command is:** `npx agent-enderun init`
 
-# English
+### Installation Steps
+- Initialize the framework with `npx agent-enderun init`.
+- Fill in the `docs/tech-stack.md` and `docs/project-docs.md` files.
+- Create the first task with `npx agent-enderun trace:new`.
+- `@manager` manages the project automatically in every session.
 
-This guide is prepared for developers and engineering teams who want to set up Agent Enderun **from scratch** on a new project. It provides a step-by-step, practical walkthrough.
-
-> **Primary recommended installation command from v0.6.6:** **`npx agent-enderun init` (generic framework setup)**
-
----
-
-## 1. Introduction
-
-Agent Enderun is a yapay zeka/AI governance framework that provides **control, discipline, and traceability** in software development processes.
-
-By completing this guide, you will:
-- Install the framework in your project
-- Configure the basic components and environment
-- Create your first tracked task and start working with specialist agents
-
----
-
-## 2. Prerequisites
-
-- **Node.js** 20+ (LTS recommended)
-- **npm** 9+
-- **Git** (must be initialized in the project directory)
-
-To check your local environment:
-
-```bash
-node --version
-npm --version
-git --version
-```
-
----
-
-## 3. Step-by-Step Installation
-
-### Step 1: Create a New Project Directory
-
-```bash
-mkdir my-new-project
-cd my-new-project
-git init
-```
-
-### Step 2: Initialize the Framework
-
-To initialize the core framework cleanly (without hardcoding any AI/adapter-specific files before installation):
-
-```bash
-npx agent-enderun init
-```
-
-This command:
-- Creates the `.enderun/` directory by default
-- Installs all core governance files (`ENDERUN.md`, `PROJECT_MEMORY.md`, agents, knowledge, etc.)
-- Adds the default framework configuration files
-
-#### 💡 Gemini Adapter (Only Supported Path)
-
-```bash
-npx agent-enderun init
-# or explicitly
-npx agent-enderun init gemini
-```
-
-This creates the `.enderun/` runtime folder + `gemini.md` shim at the root for Gemini CLI users.
-
-Other legacy adapters (`claude`, `cursor`, `codex`) may still work for editor-specific workflows.
-
----
-
-### Step 3: Install Dependencies and Build
-
-```bash
-npm install
-npm run enderun:build
-```
-
-### Step 4: Verify the Installation
-
-```bash
-npx agent-enderun check
-```
-
-Expected output:
-
-```
-✅ Framework active (v0.6.6)
-✅ MCP Server ready
-✅ Shared types compiled
-✅ Agent logs initialized
-✅ PROJECT_MEMORY.md found
-```
-
----
-
-## 4. Basic Configuration (Most Critical Step)
-
-Once initialized, you **must** update the following files to describe your project. Ajanlar (agents) learn your technology stack and target domain from here.
-
-### 4.1 `docs/tech-stack.md`
-
-This file is **mandatory**. Agents rely on it to make technical decisions.
-
-Example:
-
-```markdown
-# TECH STACK
-
-## Platform
-- Web (React + Vite)
-- Backend (Node.js + Fastify)
-
-## Database
-- PostgreSQL + Kysely
-
-## Auth
-- JWT + Refresh Token
-
-## Deployment
-- Vercel (Frontend) + Railway (Backend)
-```
-
-> **Warning:** If this file is empty, the agents will not be able to operate.
-
-### 4.2 `docs/project-docs.md`
-
-Write your project's goals, business requirements, and primary features here.
-
-### 4.3 `.enderun/PROJECT_MEMORY.md`
-
-Automatically created during initial setup inside `.enderun/PROJECT_MEMORY.md`. The Gemini adapter uses the `.enderun/` runtime folder.
-
----
-
-## 5. Creating Your First Task
-
-You are now ready to create your first real task:
-
-```bash
-npx agent-enderun trace:new "User Registration and Login System" backend P1
-```
-
-This command:
-- Generates a unique Trace ID
-- Updates the **ACTIVE TASKS** section in `PROJECT_MEMORY.md`
-- Assigns the `@manager` agent to lead the task
-
----
-
-## 6. Basics of Working with Agents
-
-### Automatic @manager Behavior
-
-At the start of every session (when a conversation begins), agents will automatically:
-
-1. Read `ENDERUN.md`
-2. Read `PROJECT_MEMORY.md`
-3. Load the active phase and current Trace ID
-
-### How to Direct Specialist Agents
-
-- Normally, **`@manager`** coordinates the process.
-- If you need to address a specialist agent directly, include their tag:
-
-```markdown
-@backend Implement the user model and auth services using Kysely.
-```
-
-### Critical Rules
-
-- Keep `docs/tech-stack.md` updated at all times.
-- When new key decisions are made, update the **CRITICAL DECISIONS** table in `PROJECT_MEMORY.md`.
-- Use a unique Trace ID for every task.
-
----
-
-## 7. First Real-World Scenario Example
-
-Try this quick workflow:
-
-1. Populate `docs/tech-stack.md`
-2. Write a simple requirement in `docs/project-docs.md`
-3. Run the following command:
-
-```bash
-npx agent-enderun trace:new "User Registration and Login" backend P1
-```
-
-4. Then write to the assistant:
-
-> @manager Please analyze this requirement and propose the backend architecture.
-
-The agents will automatically:
-- Scan your codebase
-- Propose type contracts
-- Scaffold code using blueprints if necessary
-
----
-
-## 8. Common Mistakes and Tips
-
-| Mistake | Consequence | Solution |
-| :--- | :--- | :--- |
-| Leaving `docs/tech-stack.md` empty | Agents will not know how to proceed | Ensure it is populated immediately |
-| Prompting for direct code generation | Messy and unmonitored code | Always have `@manager` plan first |
-| Not using Trace ID | Chaos and lost traceability | Use `trace:new` for every new feature |
-| Not updating `PROJECT_MEMORY.md` | Agents remember old state | Update memory with every key decision |
-
----
-
-## 9. Next Steps
-
-After completing the guide, explore:
-
-- **Contract-First Development** → Check `apps/backend/src/types`
-- **Blueprint Scaffolding** → Look inside `.enderun/blueprints/`
-- **Security & Compliance** → Run `npx agent-enderun check:security`
-- **Inter-Agent Communication** → Hermes protocol (`messages/` directory)
-
----
-
-## 10. Help and Support
-
-If you encounter issues:
-
-1. Run `npx agent-enderun status`
-2. Check `PROJECT_MEMORY.md`
-3. Inspect the error logs and the last 3 HISTORY entries
-
----
-
-**Congratulations!** You can now develop software with discipline, structure, and governance using Agent Enderun.
-
-As a next step, we recommend defining **the core contracts of your first real project**.
-
----
-
-# Türkçe
-
-Bu rehber, Agent Enderun'u **sıfırdan** yeni bir projeye kurmak isteyen geliştiriciler için hazırlanmıştır.
-
-> **v0.6.6 itibarıyla önerilen birincil başlatma komutu:** `npx agent-enderun init`
-
-Tüm teknik adımlar, ön gereksinimler, yapılandırma ve ajanlarla çalışma kuralları **İngilizce bölümde** detaylı olarak açıklanmıştır.
-
-Türkçe kısa özet:
-
-- `npx agent-enderun init` ile framework'ü kurun.
-- `docs/tech-stack.md` ve `docs/project-docs.md` dosyalarını doldurun.
-- `npx agent-enderun trace:new` ile ilk görevi oluşturun.
-- Her oturumda @manager otomatik olarak yönetir.
-
-Detaylı kurulum adımları, adaptör seçenekleri, hata önleme ipuçları ve örnek akışlar için lütfen İngilizce bölümü okuyun.
-
-**Tebrikler!** Artık Agent Enderun ile disiplinli yazılım geliştirmeye başlayabilirsiniz.
+**Congratulations!** You can now start developing professional software with Agent Enderun.

package/docs/user/README.md

@@ -0,0 +1,35 @@
+# Agent Enderun — Governance and Architecture Portal
+
+This portal is the **Central Knowledge Source** for enterprise projects developed under the Agent Enderun framework. The project's architectural decisions, standards, and governance protocols are sealed here.
+
+Unlike ordinary projects, Agent Enderun projects are built on a structure where AI agents operate autonomously but are bound by a rigid, human-authored constitution. This documentation is the **Immutable Guide** for both AI agents (Army) and human developers.
+
+### 📋 Documentation Guide
+
+#### [1. Architecture & Governance](architecture/)
+*   **[Architecture Decision Records (ADRs)](architecture/decisions/)**: Answers to "Why" and "How" questions at critical project milestones.
+*   **[Approval & High-Risk Workflows](architecture/approval-flows.md)**: Explains how tokens are generated, audited, and how high-risk actions (e.g., database deletion, privilege escalation) are sealed.
+*   **[Notification Strategy](architecture/notification-strategy.md)**: Dynamic and corporate notification patterns that do not disrupt the user experience.
+
+#### [2. Frontend Standards](frontend/)
+*   **[Component Patterns](frontend/component-patterns.md)**: Zero-UI-Library policy, guide on how all components are hand-crafted and type-safe using Panda CSS.
+*   **[Form Validations](frontend/forms.md)**: Zero-error form management systems managed with Zod and React hooks.
+*   **[Toaster Configuration](frontend/notifications.md)**: Integration of tools like Sonner with the corporate theme.
+
+#### [3. Backend Standards](backend/)
+*   **[Error Handling](backend/error-handling.md)**: Professional error management hierarchy that does not leak to the front-end and is traceable in logs.
+*   **[Audit Logging](backend/audit-logging.md)**: Contracts for how every operation is permanently processed into the database with a Trace ID.
+
+## 🛰️ Phase-Based Development Life Cycle
+All projects must pass the following 5 phases sequentially and completely:
+
+1.  **PHASE_0 (Discovery):** Tech-stack (`tech-stack.md`) sealed, risk analysis performed.
+2.  **PHASE_1 (Architecture & Contract):** First, types and API contracts are written. Contracts must be approved before a single line of application code is written.
+3.  **PHASE_2 (Core Development):** Backend and Frontend are built in parallel. Branded Types usage is mandatory.
+4.  **PHASE_3 (Integration & Test):** @quality agent takes over. 80% Test Coverage threshold must be met before proceeding to the next phase.
+5.  **PHASE_4 (Optimization & Deployment):** Security scans and performance tests are completed.
+
+> **Agent Directive:** The documents under this folder define the operational boundaries of the agents. An agent cannot deviate from a rule defined here. If a rule needs to be updated, this can only be done with @manager approval and ADR registration.
+
+**Version:** v0.9.0  
+**Status:** Active Governance

package/docs/user/action-plan-2026.md

@@ -0,0 +1,9 @@
+# Action Plan 2026 - Agent Enderun (v0.6.6+)
+
+This strategic document contains the concrete weekly action plan prepared to close critical gaps identified in the v0.6.6 Gap Analysis.
+
+**Summary:**
+- Phase 1: Reference application + Corporate CRUD Governance + Hermes proof.
+- Phase 3: @frontend and @backend professionalization + quality gates.
+
+Detailed plan and technical scope are provided in this document.

package/docs/user/getting-started.md

@@ -0,0 +1,13 @@
+# Quickstart Guide for New Agent Enderun Projects
+
+This guide is prepared for developers who want to set up Agent Enderun in a new project from scratch.
+
+> **As of v0.6.6, the primary initialization command is:** `npx agent-enderun init`
+
+### Installation Steps
+- Initialize the framework with `npx agent-enderun init`.
+- Fill in the `docs/tech-stack.md` and `docs/project-docs.md` files.
+- Create the first task with `npx agent-enderun trace:new`.
+- @manager manages the project automatically in every session.
+
+**Congratulations!** You can now start developing professional software with Agent Enderun.

package/docs/user/roadmap.md

@@ -0,0 +1,13 @@
+# Agent Enderun — Development Roadmap (v0.6.6+)
+
+**Last Updated:** May 23, 2026
+
+This document contains the development roadmap for the Agent Enderun framework post-v0.6.6.
+
+- **System Health:** 🟢 GREEN (build and test infrastructure under repair)
+- **v0.6.6 Focus:** Translating the entire framework to professional English and analyzing governance gaps honestly.
+
+## Summary
+The Agent Maturity Program is ongoing. @frontend continues to be the highest-risk agent. Live testing of the Hermes protocol and producing a reference application are the main goals for the coming period.
+
+Detailed plan and risk tracking are provided in this document.

package/eslint.config.js

@@ -0,0 +1,68 @@
+import globals from "globals";
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+const styleRules = {
+    indent: ["error", 4],
+    "linebreak-style": ["error", "unix"],
+    quotes: ["error", "double"],
+    semi: ["error", "always"],
+    "no-constant-condition": "warn",
+};
+
+export default tseslint.config(
+    {
+        ignores: [
+            "**/node_modules/**",
+            "**/dist/**",
+            "framework-mcp/dist/**",
+            "apps/*/dist/**",
+            ".agent/**",
+            ".gemini/**",
+            ".claude/**",
+            ".cursor/**",
+            ".enderun/**",
+            "panda.config.ts",
+        ],
+    },
+    js.configs.recommended,
+    ...tseslint.configs.recommended,
+    {
+        files: ["**/*.{ts,tsx}"],
+        languageOptions: {
+            ecmaVersion: 2022,
+            sourceType: "module",
+            globals: {
+                ...globals.node,
+                ...globals.es2021,
+            },
+            parserOptions: {
+                project: ["./tsconfig.json", "./apps/*/tsconfig.json", "./framework-mcp/tsconfig.json"],
+                tsconfigRootDir: import.meta.dirname,
+            },
+
+        },
+        rules: {
+            ...styleRules,
+            "no-unused-vars": "off",
+            "@typescript-eslint/no-explicit-any": "warn",
+            "@typescript-eslint/explicit-module-boundary-types": "off",
+            "@typescript-eslint/no-unused-vars": ["warn", { argsIgnorePattern: "^_" }],
+        },
+    },
+    {
+        files: ["**/*.js"],
+        languageOptions: {
+            ecmaVersion: 2022,
+            sourceType: "module",
+            globals: {
+                ...globals.node,
+                ...globals.es2021,
+            },
+        },
+        rules: {
+            ...styleRules,
+            "no-unused-vars": ["warn", { argsIgnorePattern: "^_" }],
+        },
+    },
+);

package/framework-mcp/dist/index.js

@@ -1,41 +1,195 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { allTools, allHandlers } from "./tools/index.js";
-import { FRAMEWORK_VERSION } from "./utils.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
 const server = new Server({
-    name: "ai-enderun-mcp",
-    version: FRAMEWORK_VERSION,
+    name: "agent-enderun-mcp",
+    version: "0.9.0",
 }, {
     capabilities: {
         tools: {},
     },
 });
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return {
-        tools: allTools,
-    };
+const TOOLS = [
+    {
+        name: "read_file",
+        description: "Read the content of a file within the project.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to the file relative to project root" },
+            },
+            required: ["path"],
+        },
+    },
+    {
+        name: "write_file",
+        description: "Write content to a file. Creates directories if missing.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to the file relative to project root" },
+                content: { type: "string", description: "Complete content of the file" },
+            },
+            required: ["path", "content"],
+        },
+    },
+    {
+        name: "replace_text",
+        description: "Surgically replace a string in a file with another string.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to the file" },
+                oldText: { type: "string", description: "The exact text to find" },
+                newText: { type: "string", description: "The text to replace it with" },
+            },
+            required: ["path", "oldText", "newText"],
+        },
+    },
+    {
+        name: "patch_file",
+        description: "Safely update a file by replacing a specific line range with new content.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to the file" },
+                startLine: { type: "number", description: "Starting line number (1-indexed)" },
+                endLine: { type: "number", description: "Ending line number (inclusive)" },
+                newContent: { type: "string", description: "The new lines to insert" },
+            },
+            required: ["path", "startLine", "endLine", "newContent"],
+        },
+    },
+    {
+        name: "get_framework_status",
+        description: "Get the current project phase, active traces, and agent states.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "update_project_memory",
+        description: "Update a specific section in PROJECT_MEMORY.md.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                section: { type: "string", description: "Section name (e.g., HISTORY, ACTIVE TASKS)" },
+                content: { type: "string", description: "Markdown content to append or set" },
+            },
+            required: ["section", "content"],
+        },
+    },
+    {
+        name: "orchestrate_loop",
+        description: "Process the pending Hermes messages and trigger dynamic state transitions.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "send_agent_message",
+        description: "Send a Hermes protocol message to another agent.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                to: { type: "string", description: "Target agent (e.g., @backend, @qa)" },
+                category: { type: "string", enum: ["ACTION", "DELEGATION", "INFO", "ALERT"] },
+                content: { type: "string", description: "Message content" },
+                traceId: { type: "string", description: "Active Trace ID" },
+            },
+            required: ["to", "category", "content", "traceId"],
+        },
+    },
+];
+server.onRequest(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
 });
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+server.onRequest(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     const projectRoot = process.cwd();
-    // Handle compatibility for context search
-    let effectiveArgs = args;
-    if (name === "codebase_context_search") {
-        effectiveArgs = { extension: "md", ...(args ?? {}) };
+    try {
+        switch (name) {
+            case "read_file": {
+                const filePath = path.join(projectRoot, args?.path);
+                const content = fs.readFileSync(filePath, "utf8");
+                return { content: [{ type: "text", text: content }] };
+            }
+            case "write_file": {
+                const filePath = path.join(projectRoot, args?.path);
+                fs.mkdirSync(path.dirname(filePath), { recursive: true });
+                fs.writeFileSync(filePath, args?.content);
+                return { content: [{ type: "text", text: `✅ File written: ${args?.path}` }] };
+            }
+            case "replace_text": {
+                const filePath = path.join(projectRoot, args?.path);
+                let content = fs.readFileSync(filePath, "utf8");
+                const oldText = args?.oldText;
+                const newText = args?.newText;
+                if (!content.includes(oldText)) {
+                    throw new Error(`Text not found in file: ${oldText}`);
+                }
+                content = content.replace(oldText, newText);
+                fs.writeFileSync(filePath, content);
+                return { content: [{ type: "text", text: `✅ Surgical edit successful in ${args?.path}` }] };
+            }
+            case "patch_file": {
+                const filePath = path.join(projectRoot, args?.path);
+                const lines = fs.readFileSync(filePath, "utf8").split("\n");
+                const start = args?.startLine - 1;
+                const end = args?.endLine;
+                const newContent = (args?.newContent).split("\n");
+                if (start < 0 || start > lines.length)
+                    throw new Error("Invalid start line.");
+                lines.splice(start, end - start, ...newContent);
+                fs.writeFileSync(filePath, lines.join("\n"));
+                return { content: [{ type: "text", text: `✅ File patched successfully: ${args?.path}` }] };
+            }
+            case "get_framework_status": {
+                const output = execSync("npx agent-enderun status").toString();
+                return { content: [{ type: "text", text: output }] };
+            }
+            case "update_project_memory": {
+                const section = args?.section;
+                const content = args?.content;
+                // Escape quotes for shell
+                const safeContent = content.replace(/"/g, "\\\"");
+                execSync(`npx agent-enderun update_project_memory "${section}" "${safeContent}"`);
+                return { content: [{ type: "text", text: `✅ Section ${section} updated.` }] };
+            }
+            case "orchestrate_loop": {
+                const output = execSync("npx agent-enderun orchestrate").toString();
+                return { content: [{ type: "text", text: output }] };
+            }
+            case "send_agent_message": {
+                const { to, category, content, traceId } = args;
+                const frameworkDir = fs.existsSync(path.join(projectRoot, ".enderun")) ? ".enderun" : ".gemini";
+                const messagePath = path.join(projectRoot, frameworkDir, "messages", `${to.replace("@", "")}.json`);
+                const message = {
+                    timestamp: new Date().toISOString(),
+                    from: "@mcp",
+                    to,
+                    category,
+                    traceId,
+                    content,
+                    status: "PENDING"
+                };
+                fs.mkdirSync(path.dirname(messagePath), { recursive: true });
+                fs.appendFileSync(messagePath, JSON.stringify(message) + "\n");
+                return { content: [{ type: "text", text: `✅ Message sent to ${to}` }] };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
     }
-    const handler = allHandlers[name];
-    if (handler) {
-        return await handler(effectiveArgs, projectRoot);
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error occurred";
+        return {
+            isError: true,
+            content: [{ type: "text", text: message }],
+        };
     }
-    throw new Error(`Tool not found: ${name}`);
 });
-async function main() {
+async function run() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("Framework MCP Server running on stdio");
 }
-main().catch((error) => {
-    console.error("Fatal error in main():", error);
-    process.exit(1);
-});
+run().catch(console.error);