Skip to content

AGENTS.md

Latest commit

 

History

History
115 lines (95 loc) · 5.85 KB

AGENTS.md

File metadata and controls

115 lines (95 loc) · 5.85 KB
Raw

Agent Instructions

Project Overview

go.kenn.io/kit is a Go module of reusable building blocks for Kenn CLI and developer tools. Keep packages small, app-neutral, and usable by more than one caller. Do not add product-specific config, database state, UI behavior, or provider workflows to this repo unless the package already owns that concern.

How To Work Here

  • Start from the package intent, not from a calling app's current needs. The reusable package should stay useful to future callers with similar mechanics.
  • Prefer the repo's existing helpers and test fixtures over recreating local variants in a caller.
  • Follow the Go version and dependency choices in go.mod; do not pin guidance here to a specific version unless the code requires that version for a reason.
  • Keep Unix and Windows behavior explicit when permissions, ownership, sockets, paths, or process behavior differ.
  • When behavior changes, update the package-level AGENTS.md nearest the change if it captures an invariant future agents need to preserve.
  • Let CI, go.mod, and tool config files define the exact verification commands. Do not duplicate command recipes here unless the command carries a repo-specific intent that is not encoded elsewhere.

Roborev

  • Never invoke the roborev review CLI command in any form unless the user explicitly asks for it. Use all other roborev CLI commands normally when they are appropriate for interacting with roborev. Never invoke a roborev skill (including roborev-fix or roborev-design-review-branch) unless the user explicitly asks for that skill.

Content Hygiene

  • Never name private downstream projects or other private codebases in public artifacts. Describe reusable requirements generically and scrub public surfaces before publishing.

Go Conventions

  • Use standard library APIs first and add dependencies only when they pay for themselves.
  • Keep public package APIs narrow and app-neutral. Callers should not need to import unrelated kit packages to use one package correctly.
  • Surface errors with enough context for callers to act on them. Do not turn failures into success-shaped fallbacks.
  • Use context.Context for subprocesses, network calls, update checks, probes, and other work that can block.
  • Avoid broad cleanup or mutation. Operate on exact paths, runtime records, and repositories that the caller supplied or the test created.

Tests

  • Use github.com/stretchr/testify for new and changed tests. Prefer require for setup, preconditions, and values used later; use assert for independent checks where more failures help diagnosis.
  • Do not add new t.Fatal, t.Fatalf, t.Error, t.Errorf, t.Fail, or t.FailNow calls. Existing tests still contain some stdlib assertions; when editing those checks, migrate the touched checks to testify if it keeps the test readable.
  • When a test repeats package-level testify calls, create local helpers such as assert := assert.New(t) or require := require.New(t) and use the helper methods for the repeated checks.
  • Prefer table tests when they make input and expected behavior clearer.
  • Use t.TempDir() for files created by tests unless the test specifically needs a fixed OS temp path to exercise permissions or runtime-dir behavior.
  • Tests must not depend on the user's git config, global credentials, real repositories, home directory state, or live provider availability.

Git Workflow

  • Do not change branches unless the user explicitly asks.
  • Do not amend commits unless the user explicitly asks.
  • Do not poll or watch CI or pull request checks after pushing unless the user explicitly asks. A one-time status lookup is allowed when diagnosing a user-identified CI failure.
  • Never revert user changes. If existing edits touch the same files, read them and work with them.
  • Keep pull request descriptions concise and rationale-first: explain the problem, the chosen approach, and consequences that matter to reviewers.
  • Do not add validation sections, command or check inventories, benchmark logs, caveats about unrelated pre-existing failures, or agent/tool attribution to pull request descriptions. Put verification evidence in CI, the kata issue, or a targeted review comment when it is useful.

kata issue tracker

This project uses kata as its shared issue ledger. Run kata quickstart at the start of each session for the full agent contract. The short version:

  • Search before creating: kata search "<keywords>" --agent.
  • Prefer updating existing issues over duplicates (kata comment, kata label add, kata edit).
  • Default to --agent for ordinary reads and mutations; use --json only when a script needs structured data.
  • Close only verified work: kata close <ref> --done --message "<scope + verification>" --commit <sha>.
  • If work is incomplete, label needs-review and comment what remains rather than closing.
  • Never kata delete or kata purge without explicit user authorization.

kata work.* conventions (agent orchestration)

When working a kata-tracked issue, keep its work.* metadata truthful (see docs/operations/agent-orchestration.md for the full recipe):

  • On claim/start: kata meta set <ref> work.attention ok; if the work has a dedicated branch, stamp it once with kata meta set <ref> work.branch <branch>.
  • Signal live state: kata meta set <ref> work.attention stuck|needs-human|ok plus a one-line work.attention_msg saying why. Raise stuck when you cannot proceed, needs-human when you want review; clear back to ok when unblocked.
  • Never stop with the signal stale: close the issue, or leave the attention pair reflecting the hand-off.
  • Coordinators read work.* on issues they delegated; only the working agent writes them. work.* on closed issues is meaningless.