docs: add AGENTS.md (#93)

* docs: add AGENTS.md

* docs: address AGENTS review

AGENTS.md

@@ -0,0 +1,95 @@
+# AGENTS.md
+
+Operational guidance for coding agents working in this repository. Keep changes small, match the current rewrite architecture, and prefer the documented daemon/API boundaries over behavior from the old TypeScript implementation.
+
+## Repo layout
+
+- `backend/` — Go rewrite of Agent Orchestrator: Cobra `ao` CLI, loopback HTTP daemon, services, SQLite storage, lifecycle/reaper, runtime/workspace/agent/tracker adapters, terminal mux, and tests.
+- `frontend/` — placeholder Electron + TypeScript shell. Treat it as a thin supervisor/UI surface; do not move daemon logic into it.
+- `docs/` — current architecture/status notes. Start here before changing lifecycle, CLI, agents, storage, or daemon behavior.
+- `test/` — external smoke/e2e assets, including the CLI fresh-install container check.
+- `.github/workflows/` — CI definitions. Mirror these commands locally when possible.
+
+## Commands
+
+From the repo root unless noted:
+
+```bash
+npm run lint                         # backend go test ./... + golangci-lint v2.12.2
+npm run frontend:typecheck           # frontend TypeScript check
+npm run sqlc                         # regenerate backend/internal/storage/sqlite/gen from queries/schema
+npx @redwoodjs/agent-ci run --all    # local workflow validation; requires Docker socket
+```
+
+Backend-specific checks:
+
+```bash
+cd backend
+go build ./...
+go test ./...
+go test -race ./...
+go vet ./...
+go run ./cmd/ao start
+```
+
+Frontend-specific checks:
+
+```bash
+cd frontend
+npm run typecheck
+npm run build
+```
+
+## Where to look first
+
+- `README.md` — current run/config/test quickstart.
+- `docs/README.md` — docs index.
+- `docs/architecture.md` — backend mental model, package layout, lifecycle/session/service boundaries, and load-bearing rules.
+- `docs/status.md` — current implementation state and next integration work.
+- `docs/cli/README.md` — intended CLI shape: thin Cobra client over daemon HTTP, never direct storage/runtime access.
+- `docs/agent/README.md` — agent adapter contract and hook behavior.
+- `CLAUDE.md` — compatibility pointer for Claude Code; it directs agents back to `AGENTS.md`.
+
+For code entry points:
+
+- CLI commands: `backend/internal/cli/*.go`; follow nearby command/test patterns before adding a new style.
+- HTTP controllers and DTOs: `backend/internal/httpd/controllers/`.
+- Service read/write boundaries: `backend/internal/service/`.
+- Domain vocabulary: `backend/internal/domain/`.
+- Port contracts: `backend/internal/ports/`.
+- SQLite queries/migrations/store: `backend/internal/storage/sqlite/`.
+- Generated sqlc code: `backend/internal/storage/sqlite/gen/`.
+
+## Coding conventions
+
+- Keep every change surgical and directly tied to the task. Avoid drive-by cleanup, broad renames, formatting churn, speculative abstractions, and architectural refactors unless the task explicitly asks for them.
+- Follow existing Go package boundaries. CLI code should call daemon HTTP routes through shared CLI client helpers; it should not open SQLite, spawn runtimes, or call adapters directly.
+- Keep Cobra commands in the relevant command file and table-test them in the style of `backend/internal/cli/*_test.go`.
+- Mirror existing response/request DTOs in the CLI instead of importing HTTP controller packages into CLI code, unless the package already establishes that dependency.
+- Return usage errors as `usageError` so CLI misuse exits 2; runtime/daemon failures should exit 1.
+- Preserve API error envelopes and request IDs when surfacing daemon errors.
+- Use `context.Context` as the first argument for functions that do I/O or blocking work.
+- Do not add abstractions for one-off use cases. Add helpers only when they remove duplication across real call sites.
+- Tests should cover the user-visible behavior and boundary being changed: happy path, validation/missing args, daemon error envelopes, and any destructive confirmation path.
+
+## Hard rules and boundaries
+
+- The daemon is a loopback-only sidecar. Do not make the bind host configurable or expose it beyond `127.0.0.1`.
+- The CLI is a thin client. Do not port old in-process TypeScript CLI behavior that bypasses daemon HTTP routes.
+- Do not store derived/display session status. Status is derived from durable facts (`activity_state`, `is_terminated`, PR/check/comment facts) at service read time.
+- Do not treat failed/unknown runtime probes as proof a session is dead.
+- Do not force-delete dirty registered worktrees.
+- Do not modify already-merged SQLite migrations. Add a new migration instead.
+- Do not hand-edit `backend/internal/storage/sqlite/gen/*`; change `backend/internal/storage/sqlite/queries/*` or migrations and run `npm run sqlc`.
+- SQLite change events come from DB triggers into `change_log`; do not add parallel manual CDC emission from store methods unless the architecture changes explicitly.
+- Keep generated OpenAPI/API DTO drift in mind: controller response shapes live in `backend/internal/httpd/controllers/dto.go` and tests may assert CLI/HTTP wire compatibility.
+- Do not add network calls to tests unless the package already has an integration/e2e pattern for them. Prefer `httptest`, fakes, and injected dependencies.
+- Do not commit local run state, daemon data, temporary worktrees, build outputs, or credentials.
+
+## PR hygiene
+
+- Branch from `main` unless explicitly continuing an existing PR.
+- Keep one issue per PR. If asked for separate work, create a separate branch and PR.
+- Use conventional commit messages (`feat:`, `fix:`, `docs:`, `test:`, `chore:`).
+- Explain intentional omissions in the PR body, especially when the TypeScript original had more behavior than the Go rewrite domain currently supports.
+- Run the narrowest relevant tests first, then the repo/CI commands that match the touched area.

CLAUDE.md

@@ -0,0 +1,3 @@
+# CLAUDE.md
+
+Read and follow [`AGENTS.md`](AGENTS.md) for repository layout, commands, coding conventions, and hard rules.