# AGENTS.md

## Scope of this repository

This repository is in **phase 0**.

The goal of this phase is to define:
- how development with Codex and custom agents works
- how repository workflow works
- how tasks are executed and closed
- how the project remains portable across machines

This phase is **not** for deciding the product architecture or implementing application features.

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.

---

## 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

Do not decide yet:
- final application architecture
- final domain model
- runtime services beyond workflow tooling
- database technology
- ingestion strategy
- feature list

If a task drifts into product design, stop and ask for a separate explicit decision.

---

## 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.