211 lines
4.7 KiB
Markdown
211 lines
4.7 KiB
Markdown
# 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. |