# AGENTS.md ## Scope of this repository Phase 0 is complete. The repository now has: - a completed workflow and portability foundation from phase 0 - accepted phase-1 technical decisions recorded through ADRs - enough documented guidance to support implementation work that follows the accepted baseline The goal of the current phase is to continue: - how development with Codex and custom agents works - how repository workflow works - how technical decisions are documented and applied - how implementation work follows accepted repository decisions This repository is no longer limited to workflow/bootstrap work. Runtime, database, structure, workflow, and configuration baselines have already been accepted through ADRs and must guide future implementation tasks. Agents must optimize for: - repeatability - portability - low ambiguity - clean branch discipline - durable project instructions stored in the repository --- ## Ground rules - Do not work directly on `main` - Do not work directly on `develop` - Use task branches created from `develop` - Merge completed task branches back into `develop` - Do not rewrite history - Do not silently stash work and continue elsewhere - Do not broaden task scope unnecessarily - Stop after the requested task is complete --- ## Default Git workflow Unless explicitly overridden by the user, use this branch model: - `main` = stable production branch - `develop` = integration branch - `feature/*` = normal development work - `release/*` = release stabilization - `hotfix/*` = urgent production fixes For normal implementation tasks: 1. checkout `develop` 2. create a `feature/*` branch from `develop` 3. complete the task on that branch 4. commit the work 5. merge the feature branch back into `develop` 6. stop If a large multi-step initiative needs an umbrella integration branch, the user must explicitly approve it and the branch must be documented in `docs/WORKFLOW.md`. --- ## Required behavior for Codex tasks For any coding task, agents should respond in this order: 1. confirm branch strategy 2. state which branch will be used 3. list the files to change 4. explain the design briefly 5. make the requested changes 6. update tests/docs when relevant 7. provide the commit message used 8. confirm the merge target 9. stop If a remote fetch/pull fails, continue using local branch state and say so explicitly. --- ## Repository-first portability rules Assume development may happen from different machines. Anything durable must live in the repository, not only in local Codex config. Put stable project behavior in: - `AGENTS.md` - `.codex/config.toml` - `.codex/agents/*.toml` - `.agents/skills/*` - `docs/*.md` Do not rely on undocumented local conventions. --- ## What belongs in local machine config vs repository ### Must be repository-owned - task workflow - branch strategy - coding process - agent roles - repo-specific instructions - reusable task-closing workflows - machine setup instructions - test execution instructions ### Must stay local - authentication - personal shell aliases - personal editor preferences - secrets - API keys - machine-specific paths unless documented as examples only --- ## Agent role boundaries ### implementer Use for: - targeted implementation work - small safe refactors - wiring code/tests/docs for a defined task Must avoid: - broad redesign without approval - speculative cleanup outside the task ### reviewer Use for: - correctness review - regression risk review - test gap review - release-readiness review Must avoid: - making code changes directly unless explicitly asked ### docs_researcher Use for: - documentation verification - framework/API behavior checking - repo docs consistency checks Must avoid: - changing runtime behavior unless explicitly asked --- ## Skills philosophy Use skills for repeatable repository workflows, not for one-off prompts. Preferred early skill examples: - task closeout - branch hygiene - release checklist - docs consistency check Keep skills narrow and explicit. --- ## Testing discipline When a task changes behavior, update or add tests where relevant. If test tooling is not available in the runtime image, document the correct dev/test path instead of pretending tests ran. Never claim tests passed unless they were actually executed. --- ## ADR Discipline Implementation work must follow accepted ADRs. Current accepted decisions live under `docs/adr/` and include the baseline runtime, structure, developer workflow, and configuration strategy. If a task depends on a new major technical choice, document or update the decision explicitly rather than relying on undocumented assumptions. --- ## Documentation discipline Whenever behavior changes, update docs if relevant. At minimum, keep aligned: - `README.md` - `docs/WORKFLOW.md` - `docs/MACHINE_SETUP.md` - `docs/TASK_TEMPLATE.md` Do not let docs drift from actual workflow. --- ## Out of scope in phase 0 Phase 0 no longer blocks technical decision-making. Phase-1 baseline decisions have already been accepted. Still do not treat product decisions as implicit. If a task drifts into new product scope or a major technical choice that is not yet documented, stop and ask for a separate explicit decision or ADR update. --- ## Preferred task style Make the smallest safe change that solves the requested process problem. Avoid: - unnecessary abstraction - premature architecture - speculative optimization - introducing tools that are not yet justified This phase is about building a clean development method first. That method now extends to implementation work that follows the accepted ADR baseline.