agent-enderun 0.0.1

package/ENDERUN.md

@@ -0,0 +1,72 @@
+# Agent Enderun Constitution — v0.0.1
+
+# Place in project root. This file is the single source of truth for all AI clients (Gemini CLI, Claude Code, etc.).
+
+## 🎖️ I. Git Discipline Protocol (The Law of Origin)
+
+- **Atomic Commits:** Each commit must represent a single, logical unit of change. No "fix" or "wip" commits allowed.
+- **Commit Message Format:** `[Type](Scope): Description` (e.g., `feat(api): add auth header validation`).
+- **Phase Snapshots:** Every transition between `STATE MACHINE` phases must be marked with a git tag corresponding to the phase name (e.g., `git tag -a v0.1.5-phase1`).
+- **Branching:** Use `feature/trace-id-short-description` for all task-based work.
+
+---
+
+## 🧠 II. Procedural Continuity (The Law of Style)
+
+- **Style Inheritance:** Agents MUST read and follow existing code patterns and stylistic standards. NEVER impose a new style (e.g., changing from Arrow Functions to Function Declarations) unless explicitly asked.
+- **Proactive Engineering:** Autonomously implement professional standards (Pagination, Search, Validation, Loading States, Error UI) without waiting for explicit user instructions.
+- **Search-Before-Reading:** Always use `search_codebase` or `analyze_dependencies` before opening files to minimize token usage and maximize context accuracy.
+
+---
+
+## ⚖️ III. State Machine (The Law of Phase)
+
+### PHASE 0: Discovery & Setup
+- **DoD:** `tech-stack.md` defined, `project-docs.md` updated, `shared-types` initialized.
+
+### PHASE 1: Architecture & Contract
+- **DoD:** All API endpoints documented in `{{FRAMEWORK_DIR}}/docs/api/`, shared-types match the contract hash.
+
+### PHASE 2: Core Implementation
+- **DoD:** Backend logic complete, unit tests passing, mobile/web scaffolded.
+
+### PHASE 3: Integration & UI
+- **DoD:** Frontend linked to backend, E2E tests passing, mobile features verified.
+
+### PHASE 4: Hardening & Launch
+- **DoD:** Security audit passed, performance optimized, project tagged for release.
+
+---
+
+## 👥 IV. The 8 Specialist Protocol
+
+All agent interactions are governed by 8 specialized roles found in `{{FRAMEWORK_DIR}}/agents/`:
+
+1. **@manager:** CTO & Controller. Orchestrates the team and manages memory.
+2. **@analyst:** QA & Memory Gate. Audits DoD and generates walkthroughs.
+3. **@backend:** Backend Architect. Master of Contracts, DB, and Type Safety.
+4. **@frontend:** UI/UX Architect. Enforcer of "Zero UI Library" and Panda CSS.
+5. **@explorer:** Investigator. Scans codebase and maps dependencies.
+6. **@mobile:** App Specialist. Expert in React Native and Expo.
+7. **@native:** Desktop Architect. Expert in Tauri and Electron.
+8. **@git:** Version Control Specialist. Guardian of atomic commits and snapshots.
+
+---
+
+## 💾 V. Memory Management (The Law of Truth)
+
+- **PROJECT_MEMORY.md:** The SINGLE SOURCE OF TRUTH. Agents MUST read this file at the start of every session.
+- **CURRENT STATUS Update:** Update the `Active Phase`, `Last Update`, and `Active Trace ID` fields in the `CURRENT STATUS` table at the end of every session.
+- **Trace ID Protocol:** Generate a ULID for every new task chain. All agents working on the same feature use the same Trace ID.
+
+---
+
+## 🎨 VI. Design Philosophy (The Law of Aesthetics)
+
+- **Zero UI Library Policy:** Forbidden to use `shadcn/ui`, `MUI`, `Tailwind` or other generic libraries.
+- **Panda CSS Standard:** All styling must use Panda CSS tokens and original components.
+- **Premium Aesthetics:** Every interface must feel premium, state-of-the-art, and characterful. Avoid MVP-level simplicity.
+
+---
+
+_Generated by Agent Enderun Framework v0.0.1_

package/README.md

@@ -0,0 +1,293 @@
+# Agent Enderun (v0.0.1)
+
+[English](#english) | [Türkçe](#türkçe)
+
+---
+
+# English
+
+Agent Enderun is a purpose-built, enterprise-grade AI orchestration framework for software teams who want to use AI inside a repository without losing engineering discipline. It turns AI assistants into specialized collaborators by enforcing rules, preserving context, and coordinating multi-agent workflows.
+
+## Why Agent Enderun exists
+
+Most AI assistants are powerful but inconsistent in code repositories. Agent Enderun solves this by making the repository itself the source of truth:
+
+- Enforce a single architecture and style guide.
+- Keep every decision recorded in persistent project memory.
+- Separate AI guidance from production code with hidden adapter directories.
+- Prevent backend/frontend contract drift using shared types and API documentation.
+- Enable engineers to work with AI without giving up traceability, auditability, or quality.
+
+## Core Concepts
+
+### Constitution — `ENDERUN.md`
+A built-in lawbook for your AI helpers. Every agent must read it first and follow its rules, including phase gates, code style policies, and forbidden actions.
+
+### Project Memory — `PROJECT_MEMORY.md`
+A persistent project brain that records active phase, trace IDs, decisions, and history. It keeps the project state machine coherent across sessions and agents.
+
+### Agent Academy
+A team of specialized agents, each with a strict SOP and a unique domain:
+
+- `@manager`: orchestration, phase gating, trace IDs
+- `@analyst`: QA, documentation, memory auditing
+- `@backend`: backend architecture, contracts, security
+- `@frontend`: UI/UX, Panda CSS, frontend continuity
+- `@explorer`: codebase research, dependency mapping
+- `@mobile`: mobile strategy and performance
+- `@native`: desktop integration and OS constraints
+- `@git`: git hygiene, atomic commits, traceable history
+
+### Clean Root Policy
+All AI-specific logic, agent instructions, and memory live in adapter directories such as `.gemini/`, `.claude/`, `.cursor/`, or `.codex/`. Your repository root stays clean for production assets, docs, and source code.
+
+### Contract-First Architecture
+Backend and frontend communicate through `packages/shared-types` and documented API contracts in `{{FRAMEWORK_DIR}}/docs/api/`. This prevents mismatched expectations and ensures both sides implement the same contract.
+
+### Zero UI Library Policy
+The frontend must use Panda CSS and no third-party UI kits. This gives you original visuals, better performance, and zero runtime UI dependencies.
+
+## What makes Agent Enderun different
+
+- Persistent, audited project memory for every decision.
+- Multi-agent orchestration instead of a single general-purpose assistant.
+- Strict phase transitions from discovery to delivery.
+- Built-in contract verification and shared typed APIs.
+- Hidden adapter directories to keep CI-friendly repository roots.
+- Explicit package manager intelligence in the CLI.
+
+## Project structure
+
+```
+/README.md
+/CHANGELOG.md
+/.enderun/
+/.gemini/ or /.claude/
+/apps/backend/
+/apps/web/
+/packages/framework-mcp/
+/packages/shared-types/
+/docs/
+```
+
+### Key folders
+
+- `apps/backend/` — server implementation and business logic.
+- `apps/web/` — frontend interface and Panda CSS UI.
+- `packages/shared-types/` — shared contract types for all agents.
+- `packages/framework-mcp/` — MCP server tools for AI-assisted workflows.
+- `.enderun/` — framework rules, memory, agent SOPs, and hidden configuration.
+
+## Installation and setup
+
+Agent Enderun detects the package manager automatically, but you can also force it using an environment variable:
+
+```bash
+AGENT_ENDERUN_PACKAGE_MANAGER=npm npx agent-enderun init gemini
+AGENT_ENDERUN_PACKAGE_MANAGER=yarn npx agent-enderun init gemini
+AGENT_ENDERUN_PACKAGE_MANAGER=pnpm npx agent-enderun init gemini
+```
+
+> Legacy environment variables `AI_ENDERUN_PACKAGE_MANAGER` and `AGENT_ENDERUN_PM` are still accepted for compatibility.
+
+### Recommended install flow
+
+```bash
+npx agent-enderun init gemini
+npm install && npm run enderun:build
+agent-enderun check
+```
+
+If you already use `pnpm` or `yarn`, the CLI will prefer the correct lockfile and runtime environment.
+
+## CLI Quick Reference
+
+| Command | Purpose |
+| --- | --- |
+| `npx agent-enderun init <adapter>` | Scaffold the framework and hidden adapter files |
+| `agent-enderun check` | Validate framework health, memory, contracts and build artifacts |
+| `agent-enderun trace:new "desc"` | Create a new task Trace ID |
+| `agent-enderun verify-contract` | Verify shared type contract hash |
+| `npm run enderun:build` | Build shared-types and framework-mcp packages |
+
+## Typical workflow
+
+1. Initialize with `npx agent-enderun init gemini`.
+2. Add project requirements in `docs/project-docs.md`.
+3. Confirm stack and architecture in `docs/tech-stack.md`.
+4. Use `agent-enderun trace:new` to start a new task.
+5. Let the manager agent delegate work to specialized agents.
+6. Keep every change logged in `.enderun/PROJECT_MEMORY.md`.
+
+## Onboarding new engineers
+
+Share these project truths:
+
+- Always read `ENDERUN.md` before editing.
+- Every task belongs to a trace ID.
+- Use `shared-types` instead of hand-writing API types.
+- No third-party UI libraries in the frontend.
+- Keep AI adapter config hidden under `.gemini/`, `.claude/`, `.cursor/`, or `.codex/`.
+
+## Troubleshooting
+
+- If `agent-enderun init` fails during install, rerun with the correct package manager override.
+- If `agent-enderun check` reports missing build artifacts, run `npm run enderun:build`.
+- If contract hashes drift, run `npm run verify-contract` and update `packages/shared-types/contract.version.json`.
+
+## Contribution and extension
+
+Agent Enderun is designed to be extended through:
+
+- new adapter directories (`.gemini/`, `.claude/`, `.cursor/`, `.codex/`)
+- additional agent SOPs under `.enderun/agents`
+- new project-specific API contracts in `.enderun/docs/api/`
+- shared type expansions in `packages/shared-types/src`
+
+If you add a new capability, document it in `CHANGELOG.md` and preserve the existing version header.
+
+---
+
+# Türkçe
+
+Agent Enderun, kod deposunda AI kullanırken mühendislik disiplini ve izlenebilirliği korumak isteyen ekipler için tasarlanmış bir AI orkestrasyon çerçevesidir. Yapay zeka yardımcılarını, profesyonel bir mühendis ekibinin parçası gibi çalışacak şekilde yapılandırır.
+
+## Neden Agent Enderun?
+
+Çoğu AI asistanı güçlü olsa da kod tabanlarında tutarlı davranmayabilir. Agent Enderun bu sorunu şu şekilde çözer:
+
+- Tek mimari ve stil rehberi uygular.
+- Her kararı kalıcı proje hafızasına kaydeder.
+- AI talimatlarını üretim kodundan gizli dizinlerde tutar.
+- Backend ve frontend sözleşmelerinin uyumunu `shared-types` ile sağlar.
+- AI ile çalışırken izlenebilirlik ve kalite kaybını engeller.
+
+## Temel Kavramlar
+
+### Anayasa — `ENDERUN.md`
+Tüm AI ajanlarının okumak ve uymak zorunda olduğu kural kitabı. Faz geçişleri, kod politikaları ve yasaklı hareketler burada tanımlanır.
+
+### Proje Hafızası — `PROJECT_MEMORY.md`
+Aktif fazı, trace ID'leri, kararları ve tarihsel kayıtları saklayan kalıcı beyin.
+
+### Ajan Akademisi
+Her biri kendi uzmanlık alanı ve SOP'u olan bir ajan takımı:
+
+- `@manager`: orkestrasyon, faz kapıları, trace ID yönetimi
+- `@analyst`: kalite, dokümantasyon, hafıza denetimi
+- `@backend`: backend mimarisi, sözleşmeler, güvenlik
+- `@frontend`: UI/UX, Panda CSS, frontend sürekliliği
+- `@explorer`: kod tabanı araştırması, bağımlılık haritalama
+- `@mobile`: mobil strateji ve performans
+- `@native`: masaüstü entegrasyonu ve işletim sistemi kısıtları
+- `@git`: git hijyeni, atomik commit'ler, izlenebilir tarihçe
+
+### Temiz Kök Politikası
+Tüm AI spesifik yapı `.gemini/`, `.claude/`, `.cursor/` veya `.codex/` gibi gizli dizinlerde saklanır. Depo kökü sadece üretim kodu, doküman ve yapılandırma için temiz kalır.
+
+### Sözleşme Öncelikli Mimari
+Backend ve frontend, `packages/shared-types` ve `{{FRAMEWORK_DIR}}/docs/api/` belgeleri üzerinden eşleşir. Bu, taraflar arasında yanlış anlaşılma ihtimalini azaltır.
+
+### Sıfır UI Kütüphanesi Politikası
+Frontend, Panda CSS kullanmalı ve üçüncü taraf UI kitleri yasaklanmalıdır. Böylece performans, özgünlük ve sıfır runtime bağımlılığı sağlanır.
+
+## Agent Enderun’u Öne Çıkaranlar
+
+- Kalıcı, denetlenebilir proje hafızası.
+- Tek bir genel asistan yerine uzman ajan orkestrasyonu.
+- Keşiften teslimata kadar sıkı faz geçişleri.
+- Paylaşılan tipler ve API sözleşme doğrulaması.
+- Gizli adaptör dizinleriyle temiz depo kökü.
+- CLI içinde paket yöneticisi akıllılığı.
+
+## Proje Yapısı
+
+```
+/README.md
+/CHANGELOG.md
+/.enderun/
+/.gemini/ veya /.claude/
+/apps/backend/
+/apps/web/
+/packages/framework-mcp/
+/packages/shared-types/
+/docs/
+```
+
+### Ana klasörler
+
+- `apps/backend/` — sunucu uygulaması ve iş mantığı.
+- `apps/web/` — frontend UI ve Panda CSS bileşenleri.
+- `packages/shared-types/` — ortak sözleşme tipleri.
+- `packages/framework-mcp/` — AI destekli MCP sunucu araçları.
+- `.enderun/` — çerçeve kuralları, hafıza, ajan SOP'ları ve gizli yapılandırma.
+
+## Kurulum ve Hazırlık
+
+Agent Enderun, paket yöneticisini otomatik algılar; ancak aşağıdaki değişken ile zorlayabilirsiniz:
+
+```bash
+AGENT_ENDERUN_PACKAGE_MANAGER=npm npx agent-enderun init gemini
+AGENT_ENDERUN_PACKAGE_MANAGER=yarn npx agent-enderun init gemini
+AGENT_ENDERUN_PACKAGE_MANAGER=pnpm npx agent-enderun init gemini
+```
+
+### Önerilen kurulum akışı
+
+```bash
+npx agent-enderun init gemini
+npm install && npm run enderun:build
+agent-enderun check
+```
+
+## CLI Hızlı Referans
+
+| Komut | Amaç |
+| --- | --- |
+| `npx agent-enderun init <adapter>` | Çerçeveyi ve gizli adaptör dosyalarını kurar |
+| `agent-enderun check` | Çerçeve sağlığını, hafızayı, kontratları ve build çıktısını doğrular |
+| `agent-enderun trace:new "desc"` | Yeni bir görev Trace ID'si oluşturur |
+| `agent-enderun verify-contract` | paylaşılan tip hash'ini doğrular |
+| `npm run enderun:build` | shared-types ve framework-mcp paketlerini derler |
+
+## Tipik iş akışı
+
+1. `npx agent-enderun init gemini` ile başlatın.
+2. `docs/project-docs.md` içinde gereksinimleri yazın.
+3. `docs/tech-stack.md` içinde teknoloji ve mimariyi doğrulayın.
+4. `agent-enderun trace:new` ile görev başlatın.
+5. `manager` ajanın işleri ilgili uzman ajanlara yönlendirmesini bekleyin.
+6. Her değişikliği `.enderun/PROJECT_MEMORY.md` içinde kaydedin.
+
+## Yeni gelenler için
+
+Her yazılımcıya şunu iletin:
+
+- Önce `ENDERUN.md` okuyun.
+- Her görev bir Trace ID gerektirir.
+- API veri tiplerini elle yazmayın; `shared-types` kullanın.
+- Frontend’de üçüncü taraf UI kütüphaneleri kullanmayın.
+- AI adaptör yapılandırmaları gizli dizinlerde tutulur.
+
+## Sorun giderme
+
+- `agent-enderun init` kurulum sırasında hata veriyorsa doğru paket yöneticisi ile yeniden çalıştırın.
+- `agent-enderun check` build artefaktları eksik diyorsa `npm run enderun:build` çalıştırın.
+- Kontrat hash'leri uyuşmuyorsa `npm run verify-contract` çalıştırın ve `packages/shared-types/contract.version.json` güncelleyin.
+
+## Katkıda bulunma ve genişletme
+
+Agent Enderun şu yollarla genişletilebilir:
+
+- yeni adaptör dizinleri ekleyerek (`.gemini/`, `.claude/`, `.cursor/`, `.codex/`)
+- `.enderun/agents` altına yeni ajan SOP'ları ekleyerek
+- `.enderun/docs/api/` altına yeni API sözleşmeleri ekleyerek
+- `packages/shared-types/src` içindeki paylaşılan tipleri genişleterek
+
+Yeni bir özellik ekliyorsanız, bunu `CHANGELOG.md` içinde belgeleyin ve mevcut sürüm başlığını koruyun.
+
+---
+
+## License
+
+MIT - (c) 2026 Yusuf BEKAR