zesdex/AGENTS.md

# AGENTS.md

This file provides guidance to AI agents (Kilo / Hermes) working in the zesdex repository.

## Overview

Zesdex is an **AI-native autonomous coding agent**, implemented in **TypeScript / Bun**.
It was rebuilt to be a **pure CLI/TUI tool** — there are **no network server interfaces**
(REST API / WebSocket / gRPC / web / daemon were all removed). The only two entry points:

- `zesdex` — interactive **OpenTUI** (primary interface, wired to the real agent).
- `zesdex --headless "<prompt>"` — one-shot non-interactive turn (headless mode).

## Best Practice Conventions

1. **Clean Architecture** — strict `domain` / `application` / `infrastructure` layering
   under `src/`, with thin `interfaces/` for the TUI + CLI.
   - `domain` has zero I/O and zero framework dependencies.
   - `application` depends only on `domain` (ports + turn service).
   - `infrastructure` implements domain ports (LLM client, tool executor, file repos).
   - DTOs/value objects cross layer boundaries, not entities.

2. **Clean Code** — functions under ~40 lines, one level of abstraction per function,
   descriptive names, no flag arguments, no commented-out dead code.

3. **Documentation** — every exported `function`, `class`, `interface`, and `type`
   needs a `/** */` doc comment explaining what, flow, why, and return value.

4. **Commit Convention** — Conventional Commits in Bahasa Indonesia:
   `feat(scope):`, `fix(scope):`, `chore:`, `docs:`.

5. **Error Handling** — throw `Error` with clear messages; the turn loop wraps LLM
   errors and recovers. Log with `console.*` (redirected to `~/.local/share/zesdex/zesdex.log`).

6. **Testing** — Bun tests (`bun test`) using `describe/test/expect`. Tests are
   F.I.R.S.T. Logic-pure modules (TUI state/action/command/controller) are unit-tested.

7. **No Compiler Bypasses** — no `@ts-ignore` / `any` where a real type exists.

8. **Boy Scout Rule** — leave every module cleaner than you found it.

## Stack

- Bun 1.3.14 (packageManager pinned in `package.json`).
- TypeScript strict mode, `tsconfig.json` uses `paths` aliases (`@zesdex/*`) →
  `src/*`. `bun build ... --compile` bundles into a single `dist/zesdex` binary.

## Commands

- `bun run check` — `tsc --noEmit` typecheck.
- `bun run test` — run all Bun tests.
- `bun run build` — compile `dist/zesdex` binary.
- `bun run tui` — run the interactive TUI.
- `bun run headless "<prompt>"` — one-shot agent turn.
- `bun run bootstrap` — seed default settings/app_config.