chore: add Codex and agent workflow foundation

AGENTS.md

@@ -0,0 +1,211 @@
+# 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.