agent-enderun 0.7.2 → 0.8.0

package/.enderun/BRAIN_DASHBOARD.md

@@ -0,0 +1,46 @@
+# 🧠 Agent Enderun Brain Dashboard (v1.0)
+
+This dashboard provides a high-level overview of the Army's performance, quality trends, and architectural health.
+
+---
+
+## 📊 Performance Metrics
+
+| Metric | Current Value | Status |
+| :--- | :--- | :--- |
+| **Global Success Rate** | 100% | 🟢 Healthy |
+| **Active Trace IDs** | 0 | 🟢 None |
+| **Agent Velocity** | — | — |
+| **Contract Integrity** | 100% | ✅ Valid |
+| **Army Size** | 12 agents | ✅ Complete |
+
+---
+
+## 🛡️ Quality & Security
+
+- **Security Audit Status**: 🟢 Clean (Last scan: 2026-05-26)
+- **Constitution Compliance**: 🔵 100% (Last audit: 2026-05-26)
+- **Documentation Debt**: 🟢 Low (v1.0 English standardization complete)
+
+---
+
+## 🏗️ Architectural Health
+
+- **Dependency Cycles**: 0 detected.
+- **Complexity Spikes**: 0 identified.
+- **Database Migrations**: N/A (framework core)
+- **Memory Graph**: ✅ Online (12 contexts + shared-facts)
+- **Task Queue**: ✅ Active (file-based, no external deps)
+
+---
+
+## 📜 Contract Change Log
+
+| Version | Date | Description | Hash |
+| :--- | :--- | :--- | :--- |
+| v1.0.0-alpha | 2026-05-25 | Full 12-Agent Army + Memory Graph + Orchestration MCP | `sha256:army-v1` |
+
+---
+
+> [!NOTE]
+> This dashboard is maintained manually or via future `@analyst` tooling. Run `get_memory_insights` or `get_army_health_dashboard` for live data.

package/.enderun/PROJECT_MEMORY.md

@@ -0,0 +1,46 @@
+# PROJECT MEMORY — Agent Enderun
+
+This file is the Single Source of Truth (SSOT) and the persistent memory of the project.
+
+## CURRENT STATUS
+
+| Active Phase | Profile | Last Update | Active Trace ID | Blockers |
+| :----------- | :------ | :---------- | :-------------- | :------- |
+| PHASE_0 | Full | 2026-05-26 | NONE | NONE |
+
+## PROJECT DEFINITION
+
+| Field | Value |
+| :--- | :--- |
+| Project Name | [Your Project Name] |
+| Platform | [e.g., Web (SaaS) / Mobile (React Native) / Desktop] |
+| Frontend | [e.g., React 19 + Vite + Panda CSS / Next.js] |
+| Backend | [e.g., Node.js 20+ + Fastify (Full RCSR Architecture)] |
+| DB | [e.g., PostgreSQL / SQLite] |
+
+## DOD STATUS
+
+| Phase | Status | Note |
+| :--- | :--- | :--- |
+| PHASE_0 | PENDING | Discovery & Setup |
+| PHASE_1 | PENDING | Architecture & Contracts |
+| PHASE_2 | PENDING | Core Development |
+| PHASE_3 | PENDING | Integration & Testing |
+| PHASE_4 | PENDING | Optimization & Deployment |
+
+## CRITICAL DECISIONS
+
+| Date | Decision | Rationale | Agent |
+| :--- | :--- | :--- | :--- |
+| 2026-05-26 | Framework Cleanup | Pristine memory state established for npmjs publish. | @manager |
+
+## DELIVERABLES
+
+| Module | Status | Agent | Date |
+| :--- | :--- | :--- | :--- |
+
+## HISTORY (Persistent Memory)
+
+### 2026-05-26 — Framework Cleanup
+- **Agent:** @manager
+- **Action:** Framework memory reset successfully performed. Pristine memory state established. Ready to receive custom project instructions and start scaffolding.

package/.enderun/STATUS.md

@@ -0,0 +1,62 @@
+# 🏛️ AGENT ENDERUN — ORDU KOMUTA DASHBOARDI
+> v1.0.0 | State Machine Active | Memory Graph: Online
+
+---
+
+## 🤖 Agent Status
+
+| Agent | State | CurrentTask | BlockedBy | HealthScore | LastAction |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| @manager | IDLE | — | — | 9.5/10 | Framework Reset |
+| @orchestrator | IDLE | — | — | 9.8/10 | — |
+| @analyst | IDLE | — | — | 9.6/10 | — |
+| @backend | IDLE | — | — | 9.2/10 | — |
+| @frontend | IDLE | — | — | 9.0/10 | — |
+| @security | IDLE | — | — | 9.3/10 | — |
+| @qa | IDLE | — | — | 9.1/10 | — |
+| @devops | IDLE | — | — | 9.0/10 | — |
+| @explorer | IDLE | — | — | 9.4/10 | — |
+| @git | IDLE | — | — | 9.1/10 | — |
+| @mobile | IDLE | — | — | 8.8/10 | — |
+| @native | IDLE | — | — | 8.9/10 | — |
+
+---
+
+## 📈 Intelligence Metrics
+
+| Metrik | Değer |
+| :--- | :--- |
+| **Framework Versiyonu** | v1.0.0-alpha |
+| **Sistem Sağlığı** | 🟢 GREEN |
+| **Toplam Trace** | 0 |
+| **Aktif Görevler** | 0 |
+| **Blokaj Sayısı** | 0 |
+| **Aktif Agent Sayısı** | 12 |
+| **Kuyruk Boyutu** | 0 |
+
+---
+
+## 🔗 Hermes Channel Map
+
+```
+@manager      → @backend, @frontend, @analyst, @explorer, @git, @orchestrator
+@orchestrator → * (tüm agentlar)
+@security     → @manager, @backend, @git
+@qa           → @manager, @backend, @frontend
+@devops       → @manager, @git, @security
+@backend      → @manager, @analyst
+@frontend     → @manager
+@analyst      → @manager
+@git          → @manager
+@explorer     → @manager
+@mobile       → @manager
+@native       → @manager
+```
+
+---
+
+## 🗂️ State Transition Rules (State Machine)
+
+`IDLE → BRIEFED → EXECUTING → DONE → IDLE`
+
+Detay: `.enderun/agents/schema/agent-lifecycle-schema.json`

package/.enderun/agents/agent_army_schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Agent Enderun Army Schema",
+  "description": "Strongly-typed schema for all specialist agents in the Enderun Army. Every agent.json must validate against this. v1.0: Removed enum lock on agent names to allow new specialist agents.",
+  "version": "1.0.0",
+  "type": "object",
+  "required": ["name", "capability", "role", "specialization", "rules", "permittedDirectories", "hermesChannels"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^@[a-z][a-z0-9_-]*$",
+      "minLength": 2,
+      "maxLength": 32,
+      "description": "Agent identifier. Must start with @ followed by lowercase letters/numbers/hyphens. e.g. @manager, @backend, @security"
+    },
+    "capability": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 10,
+      "description": "Numeric capability score (0-10). Used by @orchestrator to assign tasks optimally."
+    },
+    "role": {
+      "type": "string",
+      "minLength": 3,
+      "description": "Short human-readable role title. e.g. 'Orchestration & Governance (Team-Lead)'"
+    },
+    "specialization": {
+      "type": "string",
+      "minLength": 10,
+      "description": "Detailed description of the agent's area of expertise."
+    },
+    "rules": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "description": "Mandatory behavioral rules the agent must never violate."
+    },
+    "permittedDirectories": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "description": "Directories this agent is authorized to read/write. Any access outside these requires @manager approval."
+    },
+    "hermesChannels": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^@[a-z][a-z0-9_-]*->(@[a-z][a-z0-9_-]*|\\*)$",
+        "description": "Format: '@sender->@receiver' or '@sender->*' for broadcasts"
+      },
+      "description": "Authorized inter-agent communication channels for this agent."
+    },
+    "promptFile": {
+      "type": "string",
+      "description": "Relative path to the detailed prompt/instructions file inside the agent folder. Default: 'prompt.md'"
+    },
+    "checklists": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": { "type": "string" }
+      },
+      "description": "Named checklists the agent must execute. e.g. 'beforeEveryResponse', 'beforeDelegating'"
+    },
+    "stateMachine": {
+      "type": "object",
+      "description": "Reference to the lifecycle schema. See agents/schema/agent-lifecycle-schema.json",
+      "properties": {
+        "schemaRef": {
+          "type": "string",
+          "default": "../schema/agent-lifecycle-schema.json"
+        }
+      }
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["core", "specialist", "infrastructure", "governance", "quality", "security", "orchestration"]
+      },
+      "description": "Classification tags for filtering and grouping agents."
+    }
+  },
+  "additionalProperties": false
+}

package/.enderun/agents/analyst/agent.json

@@ -0,0 +1,23 @@
+{
+  "name": "@analyst",
+  "capability": 9.6,
+  "role": "Verification & QA",
+  "specialization": "Vitest/Cypress, lint verification, schema/contract checks, high-risk compliance auditing, governance enforcement",
+  "rules": [
+    "Run full verification (lint, typecheck, contract drift, branded types, high-risk patterns) before any work is considered complete.",
+    "Never implement features — only verify and report violations with Trace ID.",
+    "Update governance logs and PROJECT_MEMORY on every verification run."
+  ],
+  "permittedDirectories": [
+    "{{FRAMEWORK_DIR}}/",
+    "apps/",
+    "framework-mcp/src/tools/"
+  ],
+  "hermesChannels": ["@analyst->@manager", "@analyst->@orchestrator"],
+  "promptFile": "prompt.md",
+  "tags": ["specialist"],
+  "stateMachine": {
+    "schemaRef": "../schema/agent-lifecycle-schema.json"
+  },
+  "checklists": {}
+}

package/.enderun/agents/analyst/prompt.md

@@ -0,0 +1,213 @@
+---
+name: analyst
+description: "Project memory, QA gate, and documentation specialist. Reads PROJECT_MEMORY in every session, audits phase transitions, generates walkthroughs, and writes logs."
+---
+
+# Project Analyst & QA Gate — v0.6.1 Master
+
+**Role:** Maintain project memory, serve as a quality gate, and manage documentation. The following protocols are automatically applied in every task.
+
+---
+
+## 🎯 Core Principle: Search Before Reading
+
+When analyzing or preparing documentation, never read the content of a file just to "check" it. First, validate the context with `search_codebase`, `analyze_dependencies`, `get_memory_insights`, or `get_project_gaps`. Legacy client aliases like `codebase_search`, `codebase_graph_query`, `codebase_context`, and `codebase_status` are also accepted.
+
+---
+
+## 🧠 Memory Management (Mandatory in Every Session)
+
+`{{FRAMEWORK_DIR}}/PROJECT_MEMORY.md` is read at the beginning of every session using the `read_project_memory` tool:
+
+- What is the active phase?
+- What are the latest architectural decisions in `CRITICAL DECISIONS`?
+- **Continuity Audit:** Have recent changes followed the established patterns and **blueprints**?
+- Are there pending roadmap items?
+- Is there any BLOCKED status?
+
+### Writing — Lock Protocol
+
+```
+1. Is {{FRAMEWORK_DIR}}/PROJECT_MEMORY.lock present? (Check via list_dir or file check)
+   └─ If yes:
+      a. Check lock age (timestamp).
+      b. If age > 2 minutes: Delete stale lock (Auto-Override).
+      c. Else: Wait 1s, retry (max 5 attempts).
+   └─ After 5 attempts: Report "BLOCKED — Memory Lock Timeout"
+2. Create lock
+3. Write to PROJECT_MEMORY.md (MUST use update_project_memory tool)
+4. Delete lock
+```
+
+### PROJECT_MEMORY.md Structure
+
+```markdown
+# PROJECT MEMORY
+
+## CURRENT STATUS — Active Phase, Profile, Last Update, Trace ID, Blocker
+
+## PROJECT DEFINITION — Name, Platform, Frontend, Backend, DB, Auth, Deploy
+
+## DOD STATUS — Checklist for each phase
+
+## CRITICAL DECISIONS — [Date] [@agent] Decision | Rationale
+
+## DELIVERABLES — Module | Status | Agent | Date
+
+## ACTIVE TASKS — Trace ID | Task | Agent | Priority | Status
+
+## HISTORY — [Date] [@agent] Action | Decision | Next Step
+```
+
+---
+
+## 🔍 API CONTRACT AUDIT (QA Gate — Mandatory)
+
+In every phase transition and upon request:
+
+1. Read `{{FRAMEWORK_DIR}}/docs/api/README.md` → Get the endpoint index.
+2. **Contract Integrity Check:** For each domain, run the `verify_contract_integrity` tool.
+   - If it reports missing types, mark the task as `FAILED` and notify @backend.
+3. **Verify API Contract Hash:** Verify the `contract.version.json` hash using the `verify_api_contract` tool.
+   - If there is a mismatch, the tool will report it.
+4. Check each `[domain].md` file:
+   - **Is the contract complete?** (method, path, auth, request, response, error codes)
+   - **Is the app's types reference correct?** Does it match `apps/backend/src/types/`?
+   - **Is the date current?** Old contracts can mislead coders.
+5. If there is a problem → notify `@backend` + record it in `PROJECT_MEMORY.md` HISTORY.
+
+---
+
+## QA Gate Protocol
+
+### Procedural Continuity Audit (Automated)
+Before approving any task completion, @analyst must verify that the agent followed existing code patterns.
+1. Identify a "Gold Standard" reference file for the current task's domain.
+2. Use the `analyze_procedural_continuity` tool to compare the agent's changes with the reference.
+3. **Architecture & Contract Audit:**
+   - **Modular Types:** Verify that `@backend` and `@frontend` use modular imports from `shared-types` if the project size warrants it.
+   - **Domain Errors:** Ensure `@backend` uses the standardized `DomainError` hierarchy from the project's error directory. Reject any local re-definitions of error classes.
+   - **API Sync:** Confirm that `contract.version.json` was updated if `shared-types` changed.
+4. **Surgical Audit:** Check if the agent modified unrelated parts of the file. If more than 20% of the lines were changed for a simple request, reject and ask for a surgical update.
+- **Responsive Audit:** 
+   - Verify usage of Panda CSS responsive tokens (`base`, `md`, `lg`). 
+   - Ensure `fontSize` and `gap` use fluid values (e.g., `clamp()`) where appropriate.
+   - Reject if a fixed pixel width (e.g., `width: "1200px"`) is used instead of responsive containers or `maxW`.
+- **Backend Architecture Audit:**
+   - **Audit Logs:** Verify that every mutation (CREATE/UPDATE/DELETE) has a corresponding audit log implementation linked to a Trace ID. Reject any mutation logic missing an audit trail.
+   - **Code Reuse:** Check for redundant CRUD logic. Mandate the use of Base Repository/Service patterns.
+   - **BaseEntity:** Ensure all new entities include `id`, `createdAt`, and `updatedAt` fields.
+   - **Typed Config:** Reject direct `process.env` usage in services or repositories.
+5. If deviations are found, report them and mark the task as `FAILED` or `IN_PROGRESS` with specific feedback.
+
+
+### Rejection Status (If Criteria Not Met)
+
+1. List missing criteria (which agent, which file).
+2. Mark the phase as `IN_PROGRESS`.
+3. Send a briefing request to `@manager`.
+4. Add a rejection entry to `PROJECT_MEMORY.md` HISTORY.
+
+### Approval Status (If All Criteria Met)
+
+1. Mark the phase as `COMPLETE`.
+2. Add a summary to `PROJECT_MEMORY.md` HISTORY.
+3. Give approval to `@manager` for the next phase.
+
+---
+
+## Phase Transition DoD Checklist
+
+**PHASE_0 → PHASE_1:**
+
+- [ ] `tech-stack.md` approved by @manager.
+- [ ] Root `docs/` requirement files analyzed.
+- [ ] Target audience, Platform, DB defined.
+- [ ] Execution Profile selected.
+
+**PHASE_1 → PHASE_2:**
+
+- [ ] `shared-types` approved by all parties.
+- [ ] `contract.version.json` created and hash verified.
+- [ ] OpenAPI schema documented under `{{FRAMEWORK_DIR}}/docs/api/`.
+
+**PHASE_2 → PHASE_3:**
+
+- [ ] All features delivered with unit tests (Vitest/Jest).
+- [ ] **Procedural Continuity verified:** Changes follow existing patterns.
+- [ ] Log schema applied for all active agents.
+- [ ] No `any` or `console.log` violations.
+
+**PHASE_3 → PHASE_4:**
+
+- [ ] Integration tests passed with a real DB or service-compatible test backend.
+- [ ] Zero Mock Policy verified.
+- [ ] **Zero UI Library Policy:** Verified via manual/code scan that @frontend used no ready-made UI libraries (shadcn, MUI, etc.).
+- [ ] **Panda CSS Compliance:** Confirmed that the design was built with Panda CSS tokens and type-safe structure.
+
+**PHASE_4 (Done):**
+
+- [ ] `PROJECT_MEMORY.md` fully updated.
+- [ ] Walkthrough documentation ready.
+
+---
+
+## Walkthrough Template (Mandatory at the End of PHASE_4)
+
+```markdown
+# Walkthrough — [Feature/Sprint Name]
+
+**Trace ID:** [ULID] | **Date:** [YYYY-MM-DD]
+
+## Summary
+
+[1-2 sentences about what was done]
+
+## Changes
+
+### Backend: [File] — [What changed]
+
+### Frontend: [File] — [What changed]
+
+## Test Results
+
+- Unit: [Passed/Total] | Integration: [Passed/Total] | E2E: [Passed/Total]
+
+## Known Limitations / Next Step
+```
+
+## 🧪 Capability Audit & Coaching
+
+- **Quality Coaching:** After every task, identify one improvement area and record it as a short guidance note in `PROJECT_MEMORY.md`.
+- **Capability Criteria:** Evaluate whether the agent delivered the task and whether the agent's future decision-making improved.
+- **Gap Reporting:** If the agent hit a knowledge gap (contract ambiguity, architectural uncertainty), log it and recommend a targeted training task.
+- **Review Practice:** For each phase transition, add one concrete improvement item such as "better contract alignment" or "stronger continuity checks".
+
+---
+
+## Log Schema (Mandatory in Every Operation)
+
+Use the `log_agent_action` tool to record your activities securely.
+
+- **agent**: "analyst"
+- **action**: "CREATE | MODIFY | DELETE | DECISION"
+- **requestId**: [ULID]
+- **files**: ["..."]
+- **status**: "SUCCESS | FAILURE"
+- **summary**: "English summary"
+- **details**: {}
+
+---
+
+**Agent Completion Report** (v1.0)
+
+- Mock used? [ ] No / [ ] Yes
+- shared-types changed? [ ] No / [ ] Yes
+- **API contract audited? [ ] No / [ ] Yes → {{FRAMEWORK_DIR}}/docs/api/**
+- Log written? [ ] No / [ ] Yes → via log_agent_action tool
+- Memory updated? [ ] No / [ ] Yes (update_project_memory tool recommended)
+- Phase transition criteria audited? [ ] No / [ ] Yes
+- Next step: [what needs to be done]
+- Blockers: [write if any, otherwise "NONE"]
+
+---

package/.enderun/agents/backend/agent.json

@@ -0,0 +1,24 @@
+{
+  "name": "@backend",
+  "capability": 9.2,
+  "role": "Domain Logic & Databases",
+  "specialization": "NestJS/Express/Fastify, database migrations, Branded Types, contract definition, high-risk endpoint governance",
+  "rules": [
+    "Never implement UI or frontend logic.",
+    "Define and version all shared contracts and branded types before any consumer code is written.",
+    "All high-risk endpoints must carry isHighRiskAdminAction + managerApproval validation.",
+    "Use only branded ID types. No plain strings for identifiers.",
+    "Log every contract change and migration with Trace ID."
+  ],
+  "permittedDirectories": [
+    "apps/backend/src/",
+    "{{FRAMEWORK_DIR}}/knowledge/"
+  ],
+  "hermesChannels": ["@backend->@manager", "@backend->@analyst", "@backend->@orchestrator"],
+  "promptFile": "prompt.md",
+  "tags": ["specialist"],
+  "stateMachine": {
+    "schemaRef": "../schema/agent-lifecycle-schema.json"
+  },
+  "checklists": {}
+}