# AGENTS.md

## Overview
clnkr is a coding agent CLI that queries LLMs and executes bash commands in a loop. Core library is stdlib only. Talks to the Anthropic Messages API and any OpenAI-compatible endpoint. Ships `clnkr` (plain CLI) and `clnkrd` (stdio JSONL adapter). Evals run through the standalone `clankerval` project.

## Commands
```
make build       # Build shipped binaries (default target)
make test        # Run all tests
make check       # Run the full quality suite
make man         # Generate staged man pages from doc/*.1.md
make docs        # Build the documentation site
make docs-serve  # Run the documentation site locally
make _fmt        # Format source
make _hooks      # Configure repo-local Git hooks
```
Run `make _fmt` then `make check` before committing. Do not commit if either fails.

## Rules
- No external deps in root go.mod. Stdlib only.
- Assume Unix (`bash`, process groups, `/usr/bin/env`). Windows unsupported.
- Root `clnkr` is the only public import surface. `internal/` is allowed when it clarifies ownership.
- Output goes through typed events. Do not add `io.Writer` parameters.
- Policy logic in `Run()`, shared logic in `Step()`. No policy in `Step()`.
- CLI config resolution stays in `cmd/internal/providerconfig`: env/flag precedence, `CLNKR_*`, API keys, base URL parsing, provider detection, and user-facing config errors.
- Provider request semantics stay in `internal/providers/providerconfig`: provider/API constants, request options, model capability checks, and provider-specific validation.
- Provider adapters serialize validated options; they do not resolve CLI config.
- Wrap errors: `fmt.Errorf("context: %w", err)`. No bare returns or third-party error packages.
- Adapter tests use external packages (`package anthropic_test`). Core tests use internal (`package clnkr`). CLI tests use internal (`package main`). Match the existing pattern.
- `exhaustive` linter is enabled. Switch on sealed types must cover all cases. `default` counts as exhaustive.
- Do not manually edit `CHANGELOG.md`; generated by the release pipeline.
- Do not hand-edit generated files in `build/docs/`, `site/content/docs/clnkr.md`, `site/content/docs/clnkrd.md`, or `site/public/`.
- Public-facing docs describe current behavior, not implementation history. No `in this pass`, `for now`, `currently deferred`.
- SLOC gates count non-test Go only. Treat them as invariants and honesty constraints: do not shrink counted CLI help, diagnostics, UX, or error clarity to satisfy them, and do not weaken tests or docs to normalize that kind of regression. Agents must not raise SLOC limits unless the user explicitly gives a target number. If raising a gate is the only reasonable path, stop and ask for clarification.
- For changes that touch clnkr's agent design, read `doc/clnkr.7.md` for current architecture context: act protocol, transcript, provider boundary, command execution, and 12-factor mapping. It is descriptive, not prescriptive. Verify behavior in code and follow this file for rules.
- Repo-maintenance helpers live under `scripts/`. Read `scripts/README.md` before adding new ones.

## Architecture
Core importable library at module root. Two command adapters. `evaluations/` consumed by external `clankerval` runner.
```
clnkr/                  # core: types, Agent, events (stdlib only)
├── internal/providers/ # Anthropic/OpenAI adapters
├── cmd/clnkr/          # Plain CLI (root go.mod, no external deps)
├── cmd/clnkrd/         # Stdio JSONL adapter
└── evaluations/        # Eval suites for clankerval
```

**Agent API:** `Step()` = one typed-turn cycle, no policy. `ExecuteTurn()` = run an act turn, update state, emit events. `Run()` = full-send policy loop (3 consecutive protocol failures = exit).

**Act protocol:** Three turn types: `act`, `clarify`, `done`. Providers own wire translation. Root `ParseTurn` validates canonical internal JSON for replay/tests only.

**Events:** Sealed interface, five types: `EventResponse`, `EventCommandStart`, `EventCommandDone`, `EventProtocolFailure`, `EventDebug`. Nil `Notify` = silent.

**Command results (host→model):** JSON with `stdout`, `stderr`, `outcome`, and optional `feedback`. Exit outcomes include `exit_code`; non-exit outcomes include timeout, cancelled, denied, skipped, and error.

## Release
Tag-driven. Push feature to `main`, wait for CI/evals/site to go green, then push the plain semantic version tag. Release workflow triggers from semver tags, updates `debian/main`, and generates Debian changelog. Remote `main` may move. Fetch and rebase before follow-up pushes.

## Evals
Optimize for live runs that measure actual agent behavior. Fixture evals exist for harness determinism in CI, not as the primary signal. `clankerval` requires a clean checkout. Make a temporary commit from a dirty worktree, run, then unroll.

## Site
Hugo site under `site/`. Source of truth for reference docs is `doc/*.1.md`. Run `make docs` to regenerate. Do not commit `site/public/`. Deployment to `gh-pages` is automatic from `main`.

## Testing
- Provider adapters: `httptest.NewServer`, external test packages, no real API calls
- Agent loop: `fakeModel`/`fakeExecutor` in `agent_test.go`
- CLI: inject via narrowest local interface, not concrete structs
- Executor: real shell integration tests; handles macOS `/private/tmp` symlink

## CI
GitHub Actions on push to `main` and PRs. Runs lint, tests (`-race`), build, docs, and evals. `make check` also enforces architecture edges and core SLOC accounting. Run `make _hooks` for local pre-commit. golangci-lint required.