# AGENTS.md — Working Agreements and Conventions

Scope: Applies to the entire repository unless overridden by a deeper AGENTS.md.

Note: The canonical system rules used by the agent are mirrored in `prompts/global/system.md` (human) and `prompts/global/system.llm.md` (LLM). Keep AGENTS.md and the system prompt aligned. A seed AGENTS template for generated projects lives at `meta/AGENTS.seed.md` (and `.llm.md`).

## Collaboration Artifacts
- Root: `collab/`
- Subdirectories: `collab/questions/`, `collab/proposals/`, `collab/plan/`
- Naming per round: `NN-<subject>.md` inside each subdirectory (e.g., `00-bootstrap.md`, `01-codexhelper.md`).
- LLM-optimized copies: add `.llm.md` sibling files (e.g., `01-codexhelper.llm.md`) that are concise and machine-friendly.
- Versioning: start a new numbered file for major rounds rather than expanding one doc indefinitely.
- Principle: Keep chat minimal; prefer file-based collaboration via these documents.

### Sequencing Rules
- Begin with a questions file in `collab/questions/` and iterate there until the agent is satisfied or the user instructs to proceed.
- Do not create a proposal or plan until the questions have been edited by the user and explicitly approved.
- After approval, create a concise proposal in `collab/proposals/` and a concrete plan in `collab/plan/`, then implement.
- One-way progression: once a step (questions → proposal → plan) is approved, do not return to a prior step. Perform any subsequent clarifications/edits within the current step’s file for that round (e.g., continue editing `collab/proposals/NN-*.md` after proposal approval) and only create the next step’s file when moving forward.
- Artifact edits live in-place: Users/humans will edit the non-LLM `.md` files; the agent reads `.llm.md` and writes both `.md` and `.llm.md` siblings for every collaboration artifact.

### One-Time Exceptions
- Only bypass the Questions→Proposal→Plan cycle when explicitly directed by the user; log such exceptions in `docs/devlog/`.

## Logs and Documentation
- Dev logs: `docs/devlog/DEVLOG_LLM.md` and `docs/devlog/DEVLOG_HUMAN.md` updated each meaningful change.
- Project docs: `docs/` for feature docs (`<feature>.md`) and architectural decisions (`adr-<feature>.md`).
- README: Keep `README.md` current with quickstart and usage.

## Code and Tests
- Add unit tests in `tests/` alongside features as they are introduced.
- Keep changes minimal and focused. Avoid unrelated refactors.

## Git Workflow
- Branch: work on `main` for now.
- Commits: concise, present-tense; Conventional Commits style preferred (e.g., `feat:`, `fix:`, `chore:`).
- Releases/Tags: `YYYY-MM-DD-HHMM` when warranted; use `tea` if configured.

## Wrapper Project Guidelines
- Aim: Bash wrapper around `codex-cli` with modes (global prompt, mode prompt, project prompt, codex settings, MCP).
- Approach: crawl → walk → run. Start with documented defaults and override via flags/env/config.
- Wizards: Intake markdown forms for creating modes and projects.

## Agent Notes
- Ask clarifying questions in `collab/<...>-questions.md`.
- Propose in `collab/<...>-proposal.md`, plan in `collab/<...>-plan.md`, then implement.
- Respect repository structure and this AGENTS.md across all changes.

## Token/Context Hygiene
- Chat minimalism: keep messages short; prefer pointers to files over inline dumps.
- Use `.llm.md` files for concise, machine-friendly summaries; avoid duplicating full human docs.
- Read `.llm.md` for intake; do not rely on `.md` for reading. Write both `.md` and `.llm.md` when updating artifacts.
- No large pastes in chat: never paste large code or markdown; write to files and reference paths/sections.
- Incremental artifacts: start a new `NN-<subject>.md` per round to avoid long single files.
- Status style: one-line updates before tool calls; rely on devlog for detail.
- Avoid re-reading large files in chat; reference exact file paths and sections instead.

## Chat Output Policy
- Default message: `Updated <filepath>. Read/edit and let me know.`
- Keep chat to five lines or fewer.
- Do not paste diffs or file contents in chat; write to files instead.
- Aggregate multiple updates in a short bulleted list of filepaths.
- Push detailed reasoning/status to `docs/devlog/` and reference it when needed.
- Only announce changes to collaboration files: `collab/questions/`, `collab/proposals/`, and `collab/plan/`.
- For all other changes (docs, code, configs), skip chat announcements and log in DevLog.