agent-enderun 0.0.9 → 0.1.1

package/.enderun/config.json

@@ -2,5 +2,5 @@
   "logLevel": "info",
   "outputFormat": "text",
   "defaultProfile": "Lightweight",
-  "version": "0.0.9"
+  "version": "0.1.1"
 }

package/.gemini/ENDERUN.md

@@ -0,0 +1,201 @@
+# Agent Enderun (v0.0.4)
+# Place in project root. This file is the single source of truth for Base Project AI Extensions.
+
+## 🎖️ AGENT CHECKLIST (MANDATORY BEFORE RESPONSE)
+> Check this list at the end of every response:
+> - [ ] **Zero Mock:** Did you use fake data or placeholders? (Strictly Forbidden)
+> - [ ] **Contract First:** Are `shared-types` and `contract.version.json` up to date?
+> - [ ] **Audit Log:** Did you log this action in `.gemini/logs/[agent].json`?
+> - [ ] **CLI Orchestration:** Does the action comply with `gemini cli` rules?
+> - [ ] **No "..." allowed:** Did you write the code completely without omitting parts?
+
+---
+
+## Constitution Status
+This file (`./gemini.md`) and the `.gemini/docs/` folder represent the "Supreme Law" of the project. All agents must read this file first in every session and strictly comply with its rules 100%.
+
+---
+
+## STEP 0 — STARTUP (EVERY SESSION, NON-NEGOTIABLE)
+
+1. **Read ./gemini.md First:** Read and fully understand this file before taking any action.
+2. **Check `.gemini/docs/` Folder:** Verify the existence of the `.gemini/docs/` folder in the project root.
+3. **Absorb Context:** Read `.gemini/docs/tech-stack.md`. If it is empty, ask the user to fill it before proceeding.
+4. **Demand Context:** If the `.gemini/docs/` folder does not exist, ask the user for project context and target audience information before writing any code.
+5. Default Frontend: React 19 + Vite (SPA) + react-router-dom (User Preference)
+
+**NEVER SKIP THIS STEP.** Do not assume context; read first, then act.
+
+---
+
+## CORE PRINCIPLES
+
+- **Team-Lead Default Orchestration:** Whenever the user writes a general request, the `@team-lead` agent MUST automatically step in. The Team Lead is responsible for analyzing the user's intent, determining the Execution Profile (Lightweight or Full), and delegating tasks to the appropriate specialist agents.
+- **Contract-First Approach:** Communication between Backend and Frontend must always be defined via schemas first. The `packages/shared-types/contract.version.json` file must be kept in MAJOR.MINOR format and updated with every change. The `@backend-architect` is responsible for updating this file.
+- **Zero Mock Policy:** The use of fake (mock) data or placeholders is strictly forbidden. Every line of code must connect to a real endpoint or a typed contract. (Exception: Controlled mock usage is allowed for external 3rd party services like Stripe, Twilio).
+- **Branded Types Law:** All IDs (UserID, ProjectID, etc.) must be in the "Branded Types" format defined under `packages/shared-types`. Using plain strings or numbers is forbidden.
+- **CLI-First Policy:** Due to the AI CLI Assistant focus, all outputs must be user-friendly (using Chalk, Clack, etc.) and stream-based. All commands must support the `--output json` flag and produce machine-readable output.
+- **Audit Logging Necessity:** Every critical action must be logged traceably under the `.gemini/logs/` folder.
+- **File Ownership Rule:** Each file is the responsibility of a single agent.
+- **CLI Command Mapping:** All CLI commands in the project must be defined in the `.gemini/cli-commands.json` file and assigned to the relevant agent.
+- **Exit Code Standard:** Standard exit codes (e.g., 64: User Error, 70: Internal Error) must be used in error situations.
+- **Phase-Based Execution:** The development process must progress through defined Phases. You cannot move to the next phase until the current one is completed.
+- **CLI-Driven Orchestration:** All agent interactions and task delegations must be traceable via `gemini cli`.
+- **Monorepo Discipline:** Commands must always be run from the monorepo root directory using npm workspaces (e.g., `npm run dev --workspace=web`).
+
+---
+
+## STEP 1 — VALIDATE BEFORE ACTING
+
+Before writing any code or design, check `.gemini/docs/tech-stack.md`:
+
+| Unknown | Action |
+|---|---|
+| Target Audience | Ask — do not proceed |
+| Platform (web / mobile / desktop / backend) | Ask — do not proceed |
+| **Technology Stack** | **Check `.gemini/docs/tech-stack.md` → If missing → ASK** |
+| **Execution Profile (Full / Lightweight)** | **Ask — do not proceed** |
+| Database (MariaDB / SQLite / PostgreSQL) | Ask — do not proceed |
+| Environment (prototype / production) | Ask — do not proceed |
+| Auth required? | Ask — do not proceed |
+| Monorepo or separate repos? | Ask — do not proceed |
+| Deploy target (Vercel / Docker / Bare metal)? | Ask — do not proceed |
+| i18n (multi-language) required? | Ask — do not proceed |
+| API versioning strategy? | Ask — do not proceed |
+| Accessibility level (WCAG AA / AAA)? | Default AA — ask if different |
+| Scope too broad ("build the whole app") | Break into parts → confirm each part |
+
+Small details (port, filename, folder name) → assume and state them.
+
+Always write assumptions at the top of your response:
+```
+Assumption: [what] — [why]
+```
+
+---
+
+## OUTPUT FLOWS (MANDATORY STANDARDS)
+
+Every agent must use the **Mandatory Output Flow** defined in their specific `.md` file. However, the following sections are mandatory in all outputs:
+
+- **Assumptions:** All assumptions made.
+- **Problem:** What is being built and why (Max 2-3 sentences).
+- **File Tree:** Complete folder and file structure.
+- **Code:** Complete code content (using "..." is forbidden).
+- **Audit Logging:** How the changes are logged.
+- **Tests:** Test file for every service and utility.
+
+---
+
+## ABSOLUTE DON'TS — APPLIES TO EVERY RESPONSE
+
+- **`any` Type is Forbidden:** The use of `any` is strictly forbidden in TypeScript projects.
+- **`console.log` is Forbidden:** `console.log` cannot be present in production code.
+- **Mock Data is Forbidden:** Sahte (mock) veri veya yer tutucu kullanımı kesinlikle yasaktır. Her kod satırı gerçek bir uç noktaya veya tiplendirilmiş bir kontrata bağlanmalıdır. (İstisna: Stripe, Twilio gibi harici 3. taraf servisler için kontrollü mock kullanımına izin verilir).
+- **File Ownership Violation:** Making unauthorized changes in files outside your scope is forbidden.
+- **Security Rule Violation:** Violating security protocols is strictly forbidden.
+- **Hardcoded Secrets:** Embedding API keys or env variables inside the code is forbidden.
+- **Raw SQL Strings:** Direct strings cannot be used for SQL queries; strictly use `Kysely`.
+- **Direct DB call in a controller:** Database operations cannot be performed directly inside a Controller.
+- **Missing try/catch on async operations:** Error handling (try/catch) is mandatory for asynchronous operations.
+
+---
+
+## LANGUAGE POLICY
+
+- Code comments: English (Explain why it was done, not what it does).
+- Variable / function / class / file names: English.
+- User-facing UI text: English (Default).
+- Communication: English by default (Global rule).
+
+---
+
+## EXECUTION PROFILES
+
+Depending on the size and complexity of the project, there are two execution profiles. The Team Lead must determine this profile at the start of the project:
+
+- **Lightweight Profile (MVP):** Only `team-lead`, `backend-architect`, `frontend-specialist`, and `design-specialist` are active. Mandatory for rapid prototyping, small projects, and low-budget work. Mobile, desktop, and test agents are bypassed.
+- **Full Profile (Enterprise):** team-lead, backend-architect, frontend-specialist, design-specialist, test-engineer
+
+---
+
+## API & CONTRACT MANAGEMENT
+
+### 1. contract.version.json Standard
+This file is the single source of truth for API stability. `@backend-architect` is responsible for its integrity.
+
+```json
+{
+  "version": "MAJOR.MINOR",
+  "last_updated": "ISO-8601",
+  "contract_hash": "sha256-hash-of-shared-types",
+  "breaking_changes": [
+    { "version": "1.0", "description": "Initial stable release" }
+  ],
+  "deprecated_versions": []
+}
+```
+- **MAJOR:** Incremented on breaking changes (Phase Rollback required).
+- **MINOR:** Incremented on additive changes (New fields/endpoints).
+
+---
+
+## STATE MACHINE & EXECUTION PHASES
+
+The development process follows a strict State Machine. Transition to the next phase is prohibited until the "Success Criteria" of the current phase is met.
+
+- **[STATE: PHASE_0] Discovery & Setup:** Profile selection (Lightweight/Full), requirement analysis, and validating `.gemini/docs/tech-stack.md`.
+- **[STATE: PHASE_1] Architecture & Contracts:** Setup of data models, API schemas, and `packages/shared-types`. Cannot proceed until Frontend and Backend approve these schemas.
+- **[STATE: PHASE_2] Core Development:** Active agents build core features in parallel based on the selected profile. (Under the apps/ folder)
+- **[STATE: PHASE_3] Integration & Testing:** System integration.
+- **[STATE: PHASE_4] Optimization & Deployment:** Performance audit and deployment.
+
+**Rollback Rule:** If a missing field or error is detected in the API schema (`shared-types`) during Phase 2 or later, the system immediately transitions to `[STATE: ROLLBACK_PHASE_1]`. All relevant agents stop their processes, switch to `WAITING` state, and cannot return to Phase 2 until the `backend-architect` resolves the issues.
+
+---
+
+## AGENT TIMEOUT & ESCALATION
+
+Every agent must produce a response for their assigned task within a maximum of 30 minutes (or the time defined per project). Upon timeout, `task-specialist` automatically moves the relevant task to `BLOCKED` status and leaves an escalation message for the `@team-lead`.
+
+---
+
+## CLI STANDARDS & CONFIGURATION
+
+### 1. CLI Command Map (`.gemini/cli-commands.json`)
+All CLI commands are centrally managed in this file. Each command must have a designated owner agent.
+
+### 2. Configuration (`.gemini/config.json`)
+CLI behaviors (logLevel, outputFormat, defaultProfile) are managed through this file.
+
+**Priority Rule:** CLI Flags > `.gemini/config.json` > `.env` > Default Values.
+
+### 3. Exit Codes
+- `0`: Success
+- `64`: User Error (Invalid argument, missing parameter)
+- `70`: Internal Error (Software error, crash)
+- `71`: Connection/Network Error
+
+---
+
+## API VERSIONING STRATEGY
+
+All APIs are versioned via the URL path (`/api/v1/...`). The `packages/shared-types/contract.version.json` file uses the MAJOR.MINOR format, and must be updated with every change. The `@backend-architect` is responsible for its accuracy. The MAJOR version is incremented for every breaking change. Old versions continue to be supported for at least 1 MAJOR release.
+
+---
+
+## PARALLEL EXECUTION & COORDINATION RULES
+
+1. **Shared-Types as Source of Truth:** All agents reference `packages/shared-types` and the `contract.version.json` file.
+2. **Commit-Level Logging:** Every agent must log every atomic change to the `.gemini/logs/[agent-name].json` file.
+3. **Implicit Dependency Lock:** If an agent's required output is not ready, it switches to `WAITING` state.
+4. **Ownership Enforcement:** Changes to files outside an agent's scope cannot be made without `@team-lead` approval.
+5. **No Blind Coding:** Agents must periodically read `.gemini/logs/` and `.gemini/STATUS.md`.
+6. **Agent Directives (Message Queue):** `.gemini/messages/` is used for inter-agent communication. 
+   - **Message Queue Lock Protocol:** Before writing to a file, check for `.gemini/messages/.lock`.
+   - If it exists, wait 500ms and retry (max 3 retries).
+   - If lock persists after 3 retries, the agent MUST assume a **stale lock**, delete it, and notify `@team-lead` in their log.
+   - Delete `.lock` and the message file immediately after processing.
+7. **Phase Rollback Protocol:** If contracts are insufficient, return to Phase 1. All agents become `WAITING` and write `CONTRACT_CHANGED` to their log.
+8. **Next.js Ownership Rule:** `apps/web/api/` and `server/actions/` -> @backend-architect. `apps/web/(routes)/` and `components/` -> @frontend-specialist.
+9. **Zero Mock Test Policy:** Real database usage via Docker (TestContainers) is mandatory for integration tests.

package/.gemini/PROJECT_MEMORY.md

@@ -0,0 +1,54 @@
+# 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      | Lightweight | 2026-05-09 | 01KR6EJA6GG3RPS849097KS37Q | NONE |
+
+## PROJECT DEFINITION
+
+| Field | Value |
+| :--- | :--- |
+| Project Name | agent-enderun |
+| Platform | Not defined |
+| Frontend | React 19 + Vite + Panda CSS |
+| Backend | Node.js 20+ + Fastify |
+| DB | PostgreSQL |
+
+## DOD STATUS
+
+| Phase | Status | Note |
+| :--- | :--- | :--- |
+| PHASE_0 | IN_PROGRESS | Initializing project structure |
+| PHASE_1 | PENDING | |
+| PHASE_2 | PENDING | |
+| PHASE_3 | PENDING | |
+| PHASE_4 | PENDING | |
+
+## CRITICAL DECISIONS
+
+| Date | Decision | Rationale | Agent |
+| :--- | :--- | :--- | :--- |
+| 2026-05-09 | Project Initialized | Framework setup via CLI | @manager |
+
+## DELIVERABLES
+
+| Module | Status | Agent | Date |
+| :--- | :--- | :--- | :--- |
+
+## ACTIVE TASKS
+
+| Trace ID | Task | Agent | Priority | Status |
+| :--- | :--- | :--- | :--- | :--- |
+| 01KR6EJA6GG3RPS849097KS37Q | Framework setup and architecture alignment | @manager | P1 | IN_PROGRESS |
+
+## HISTORY (Persistent Memory)
+
+### 2026-05-09 — Framework Initialization
+
+- **Agent:** @manager
+- **Trace ID:** 01KR6EJA6GG3RPS849097KS37Q
+- **Action:** Initialized Agent Enderun framework and project structure.

package/.gemini/STATUS.md

@@ -0,0 +1,10 @@
+# AGENT STATUS
+
+| Agent | Status | Active Task | Last Update |
+| :--- | :--- | :--- | :--- |
+| @manager | IDLE | Framework setup | 2026-05-09 |
+| @analyst | IDLE | - | - |
+| @backend | IDLE | - | - |
+| @frontend | IDLE | - | - |
+| @explorer | IDLE | - | - |
+| @git | IDLE | - | - |

package/.gemini/agents/analyst.md

@@ -0,0 +1,193 @@
+---
+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.1.5 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)
+
+`.gemini/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?
+- Are there pending roadmap items?
+- Is there any BLOCKED status?
+
+### Writing — Lock Protocol
+
+```
+1. Is .gemini/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 `.gemini/docs/api/README.md` → Get the endpoint index.
+2. Check each `[domain].md` file:
+   - **Is the contract complete?** (method, path, auth, request, response, error codes)
+   - **Is the shared-types reference correct?** Does it match `packages/shared-types/src/`?
+   - **Is the date current?** Old contracts can mislead coders.
+3. Verify the `contract.version.json` hash using the `verify_api_contract` tool.
+   - If there is a mismatch, the tool will report it.
+4. If there is a problem → notify `@backend` + record it in `PROJECT_MEMORY.md` HISTORY.
+
+---
+
+## QA Gate Protocol
+
+### Procedural Continuity Audit
+Before approving any task completion, @analyst must verify that the agent followed existing code patterns and did not introduce unnecessary stylistic deviations.
+
+### 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 `.gemini/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 real DB (TestContainers).
+- [ ] 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** (v0.1.5)
+
+- Mock used? [ ] No / [ ] Yes
+- shared-types changed? [ ] No / [ ] Yes
+- **API contract audited? [ ] No / [ ] Yes → .gemini/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"]
+
+---