66 lines
4.4 KiB
Markdown
66 lines
4.4 KiB
Markdown
# 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.
|