# AGENTS.md

## Purpose

This file is the short entry protocol for agents working in this repo. It keeps only startup rules, hard stops, and links to the canonical contracts that contain the detailed rules.

## Start Here

When a task needs product, behavior, architecture, or implementation context, read the relevant entry points before proposing a design, plan, or code change:

- `SPECS.md` is the top-level product and engineering spec index.
- `docs/architecture-spec.md` defines target architecture direction.
- `docs/tech_design.md` maps the current implementation and code paths.
- `specs/repository/agent-working-contract.md` defines repo-wide agent execution, testing, PR, commit, and documentation-sync rules.
- `specs/repository/package-boundaries.md` defines current package-level dependency boundaries.
- `specs/repository/specs-and-guardrails-layout.md` defines canonical spec and guardrail layout.

Priority:

- Product and architecture behavior comes from `SPECS.md` and root `specs/**/*.md`.
- Target boundaries come from `docs/architecture-spec.md` and `specs/repository/package-boundaries.md`.
- Current implementation status comes from `docs/tech_design.md` and the code.
- Guides, dated design docs, implementation plans, and `docs/archive/` are supporting references only unless a canonical spec links to them as normative.

## Before Editing

- Check whether the subtree has a closer `AGENTS.md`; follow it together with this file.
- Read the relevant code, configuration, tests, and docs until the important behavior, constraints, and interfaces are clear.
- Make repo-owned skills discoverable from `skills/` through `.agents/skills/` when the runtime needs a synced copy. Treat `.agents/skills/` as generated runtime state, do not edit it independently, and do not install repo-owned skills into user-wide or global skill directories.
- Follow any matching skill description after skills are discoverable.
- For non-trivial implementation, refactoring, review, or harness work, apply `skills/ai-codebase-hardening/SKILL.md` before editing so AI-generated complexity, duplicate code, low-value tests, and performance regressions are actively checked.
- For schema, migration, or core storage work, first read `specs/storage/storage.md` and the current notes in `docs/tech_design.md`.
- For long-lived specs, guardrails, architecture docs, product specs, or this file, apply `skills/reviewing-long-lived-specs/SKILL.md`.

## Hard Rules

- Keep changes surgical and production-facing. Prefer the simplest solution that fully solves the real problem.
- Do not infer behavior from names alone when code can be inspected.
- Do not merge temporary documents, scratch notes, implementation plans, or dated RFC history into `main`.
- Long-lived specs and AGENTS guidance must state current facts, stable contracts, ownership, and durable rationale. Do not keep historical narratives, phase notes, task/PR context, or retired alternatives in canonical docs; Git history is the record for that.
- Write canonical specs in the current conversation language unless explicitly requested otherwise.
- Do not edit generated or vendored artifacts such as `node_modules/`, `web/dist/`, Electron `dist/`, coverage output, or compiled binaries unless the task explicitly requires investigating or regenerating them.
- Do not introduce new root `internal/store` business logic or new production root-store callers; follow `guardrails/store/check-store-refactor-boundaries.sh`.
- Store model structs under `internal/store/model` must not carry JSON tags; HTTP wire contracts belong in `internal/api/dto`.
- New REST API endpoints belong under the owning `internal/api/{domain}` package, with shared API helpers kept in root `internal/api` and route composition in `internal/router`.
- New user-facing React UI copy must include complete i18n support from the start.
- Shared frontend primitives come from `web/src/agentteam/components/ui/` when more than one app needs the primitive.

## Documentation Sync

When behavior changes, update the matching durable docs in the same change:

- Product behavior: canonical spec under `specs/`.
- User workflow: `docs/public/`.
- Daemon or CLI workflow: `desktop/README.md` for user-facing runbooks and `specs/daemon/` for canonical daemon architecture/contracts.
- Local development command: `docs/development.md`.
- Storage schema or migrations: check both `internal/tidb/bootstrap.sql` and `internal/tidb/migrations/*.sql`.
- Use one new migration version per PR. Within that migration, each DDL statement must contain exactly one idempotent schema change; use separate statements for additional schema changes and for any required idempotent data backfills.

`docs/public/` is rendered by `web/src/public-site`, but it is not an independent source of truth. Resolve conflicts against canonical specs and current implementation.

## Verification

Run the smallest appropriate regression before claiming completion:

- Backend Go changes: targeted `go test` package, shard, or focused target; use broader `go test ./... -timeout=15m` only when the risk justifies it.
- Web behavior changes: the relevant Web E2E lane or focused spec, following `docs/testing/web-e2e.md`.
- Documentation-only changes do not require runtime regression, but links and canonical references must still be checked.

If a relevant verification cannot run, report the blocker clearly.

## Pull Requests And Commits

- Use `skills/submitting-pull-requests/SKILL.md` when preparing, opening, or updating a PR.
- Do not add `Co-Authored-By` trailers to commit messages.

## Not Here

Do not grow this file back into an implementation manual. Put durable details in root `specs/`, executable checks in `guardrails/`, user-facing docs in `docs/public/`, and local development runbooks in `docs/development.md`.