kana: Instructions file for Codex

AGENTS.md

Scope and workflow

• Choose a change scope that matches the task and keep the result cohesive.
• Default to completing the task in one pass. Do not impose separate implementation, review, test, or documentation phases unless the user requests a checkpoint.
• Do not stop for routine approval. Ask for direction only when a missing choice would materially change the result, broaden the scope, or authorize a consequential action.
• Avoid unnecessary churn. For larger features or refactors, explain the important design tradeoffs and keep related changes together.
• Do not blindly follow a brittle or overly complex request. Explain the maintenance concern and suggest the simplest durable alternative.
• Before an unfamiliar or cross-module change, read docs/architecture.md and use docs/README.md to find the canonical owner; for a narrow change, read only the relevant owner document and avoid loading unrelated documentation.

Implementation

• Prefer clear names and code structure over comments.
• Add comments only for non-obvious invariants, design decisions, protocol semantics, ordering requirements, provider-specific behavior, and mutable state boundaries.
• Keep implementation comment blocks within four lines and 320 characters. Do not add comments that restate the code.
• Put longer explanations in documentation only when they describe a stable contract or design boundary that future contributors need.
• Do not add comment-check-ignore suppressions without maintainer approval.
• For imports under src, use relative imports within the same top-level src directory. Use the @/ alias only across top-level directories and prefer target barrels such as @/core or @/tools over deep aliases.

Trust boundaries and state

• Validate untrusted input once, at the edge where it enters: files, network and provider responses, tool arguments, CLI flags, and user input. Use parseWithSchema for structured formats.
• Trust typed values inside the system. Do not re-validate, re-normalize, or guard states that the types already rule out, and do not add fallbacks for branches that cannot happen.
• Treat data as immutable: declare readonly types, update by replacing values, and share them by reference. Copy only when handing a value to code that mutates it or when crossing a persistence or process boundary.
• Give each resource one owner that handles idempotent close and cleanup. Callers do not add their own flags or wrappers around it.
• The logger never throws, so do not wrap logging in try/catch. Isolate failures only around callbacks that a frontend or user supplies.
• Before writing a helper, search utils, core, and the module's own helpers for an existing one.