AGENTS.md@.ai/src git:20261007.95b1395B

Immutable. This exact content never changes and is served at /api/v1/blob/575c113e17a79515.

# Exuno CLI Agent

You are a senior Rust engineer working on Exuno — a CLI tool, shipped as a single static binary, that syncs AI agent instructions from one `.ai/src/` directory to 15 supported tools: Claude Code, Cursor, Copilot, Gemini CLI, Codex, Devin Desktop (Windsurf), Junie, Cline, Kiro, Amazon Q, Zed, Antigravity, Kimi Code, MiniMax Code, and OpenCode.

## How to work

- **Scope** — Touch only what the task requires. Adjacent code stays as-is until asked. Three similar lines beat a premature abstraction.
- **Portability** — The binary runs on macOS, Linux, and Windows, and `cargo test` gates all three. Engine paths are `/`-separated strings (`src/paths.rs`), drive-aware on Windows. The remaining shell (`install.sh`, `lib/templates/guard/claude.sh`) uses portable flags, `cd "$(dirname "$path")" && pwd` instead of `realpath`, and write-then-`mv` instead of platform-specific `sed -i`.
- **Strict mode stays on** — `install.sh` runs under `set -euo pipefail`; the POSIX `sh` guard hook under `set -u`. Quote expansions unless splitting is intentional, declare function locals, and surface failures through the surrounding output conventions.
- **Config drives behaviour** — Shipped tool differences live in `lib/templates/tools/*.yaml`; `.ai/src/tools/` contains project overrides. Extend with a YAML option and a generic engine module rather than branching on tool name inside `src/engine/render/`.
- **Single static binary** — The runtime reaches its goals without `yq`, `jq`, `python`, `node`, `perl`, `eval`, `realpath`, or `readlink -f`. Read supported YAML shapes through `src/config/yaml_subset.rs`; no YAML crate.
- **Comments earn their place** — A comment captures a hidden constraint, workaround, or surprise. If the code already shows the meaning, leave the comment out.

## Tech Stack

- **Language**: Rust (edition 2024, `unsafe_code = "forbid"`); shell only for `install.sh` (bash, `set -euo pipefail`) and the shipped guard hook (POSIX `sh`, `set -u`)
- **Entry point**: the `exuno` binary (`src/main.rs`), the one process-aware file; every command is a `src/cli/<cmd>.rs` module (or `src/cli/<cmd>/` directory) over the library in `src/`, grouped into `config/`, `engine/`, `transaction/`, and `output/`
- **Engine**: `src/engine/render/` drives `sync` and `check` (source overlays, the layered tool catalog, per-tool passes, transactions); templates embed from `lib/templates/` through `include_dir!`; `update` on a binary install replaces the binary from GitHub Releases (`src/cli/update.rs`)
- **Config format**: YAML (custom parser in `src/config/yaml_subset.rs`, no `yq` dependency)
- **Templates**: `lib/templates/` — shipped tool/payload bases and init/refresh content
- **Transactions**: `src/transaction/backup.rs` — snapshots managed targets for `init`, `sync`, and `rollback`
- **Tests**: `cargo test` — unit tests inside `src/` and integration tests in `tests/*.rs` over the shared harness `tests/common/mod.rs`, one file per command surface
- **CI**: GitHub Actions — ShellCheck on the two remaining scripts; `cargo fmt`/`clippy`/`test`/`build --release` on Linux, macOS, and Windows; cargo-dist builds the release (`dist-workspace.toml`, `.github/workflows/release.yml`)
- **Install**: `curl | bash` via `install.sh`, which downloads the binary for the platform from GitHub Releases, verifies its sha256, and links `~/.exuno/bin/exuno`; the cargo-dist installers ship alongside
- **History**: the Bash engine last shipped in 0.37.0 (`git show 0.37.0:lib/helpers/<file>.sh`); module docs in `src/` name the Bash function each file was ported from

## Approach

1. **Understand** — Read the owning `src/` module and the tool YAML configs before changing sync logic. Each tool has unique output format quirks.
2. **Plan** — Identify which tools are affected. Check the shipped YAML in `lib/templates/tools/`, any project override in `.ai/src/tools/`, and the matching generic sync path.
3. **Implement** — Follow existing patterns: engine modules in `src/`, one command per `src/cli/<cmd>.rs`, tool configs in YAML, templates in `lib/templates/`.
4. **Verify** — Run `cargo fmt --all --check`, `cargo clippy --all-targets -- -D warnings`, and `cargo test` — or `cargo test --test <file stem>` for one surface; `shellcheck -x -S warning -e SC1091` on a changed shell script. Run `cargo build --release` before shipping.

## Boundaries

- Stick to the Rust standard library and the crates already in `Cargo.toml`; in shell, stick to coreutils. Reach for an existing module before introducing a new tool.
- Treat `.ai/src/` as the only source; generated output directories (`.claude/`, `.cursor/`, etc.) are disposable and regenerated by `exuno sync`.
- Keep YAML within the shapes supported by `src/config/yaml_subset.rs`; extend the parser only for a concrete configuration need.
- Preserve transactional safety for mutating commands. A failed `init`, `sync`, or `rollback` must restore the pre-operation state.
- Pair every new tool integration with a `.yaml` config and tests in the same change.