agent-enderun 0.4.7 → 0.5.1

package/.enderun/ENDERUN.md

@@ -1,205 +0,0 @@
-# Agent Enderun (v0.4.7)
-# 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 `{{FRAMEWORK_DIR}}/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 (`./{{ADAPTER}}.md`) and the `{{FRAMEWORK_DIR}}/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%. All framework-specific documentation is stored within `{{FRAMEWORK_DIR}}/docs/`.
-
----
-
-## STEP 0 — STARTUP (EVERY SESSION, NON-NEGOTIABLE)
-
-1. **Read ./{{ADAPTER}}.md First:** Read and fully understand this file before taking any action.
-2. **Check `{{FRAMEWORK_DIR}}/docs/` Folder:** Verify the existence of the `{{FRAMEWORK_DIR}}/docs/` folder (located within the framework directory).
-3. **Absorb Context:** Read `{{FRAMEWORK_DIR}}/docs/tech-stack.md`. If it is empty, ask the user to fill it before proceeding.
-4. **Demand Context:** If the `{{FRAMEWORK_DIR}}/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
-
-- **Agent Academy Focus:** This repository is dedicated to the development and evolution of AI Agents. All actions must aim to improve agent intelligence, autonomy, and procedural continuity.
-- **Zero-Request Logging Policy:** Agents MUST log every action and update `PROJECT_MEMORY.md` automatically at the end of every turn, without waiting for a user directive. This is the "Operating Mode" of the framework.
-- **Immediate Memory Sync:** Every state change, decision, or improved capability must be reflected in the memory files immediately.
-- **Contract-First Agent Evolution:** Tools and SOPs used by agents must be defined via schemas and contracts first.
-- **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 `{{FRAMEWORK_DIR}}/logs/` folder.
-- **Design Continuity & Response Policy:** All UI changes MUST be responsive (Mobile-First + Fluid) and surgical. Unnecessary overhauls of existing layouts are strictly forbidden.
-- **Shared Component First Policy:** Defining common UI elements (Button, Input, Card, etc.) inside page files is FORBIDDEN. All atomic UI components must be created in a shared directory (e.g., `apps/web/src/components/ui/`) and reused across the project.
-- **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 `{{FRAMEWORK_DIR}}/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 `{{FRAMEWORK_DIR}}/docs/tech-stack.md`:
-
-| Unknown | Action |
-|---|---|
-| Target Audience | Ask — do not proceed |
-| Platform (web / mobile / desktop / backend) | Ask — do not proceed |
-| **Technology Stack** | **Check `{{FRAMEWORK_DIR}}/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 `{{FRAMEWORK_DIR}}/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 (`{{FRAMEWORK_DIR}}/cli-commands.json`)
-All CLI commands are centrally managed in this file. Each command must have a designated owner agent.
-
-### 2. Configuration (`{{FRAMEWORK_DIR}}/config.json`)
-CLI behaviors (logLevel, outputFormat, defaultProfile) are managed through this file.
-
-**Priority Rule:** CLI Flags > `{{FRAMEWORK_DIR}}/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 `{{FRAMEWORK_DIR}}/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 `{{FRAMEWORK_DIR}}/logs/` and `{{FRAMEWORK_DIR}}/STATUS.md`.
-6. **Agent Directives (Message Queue):** `{{FRAMEWORK_DIR}}/messages/` is used for inter-agent communication. 
-   - **Message Queue Lock Protocol:** Before writing to a file, check for `{{FRAMEWORK_DIR}}/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.