hoopscout-v2/AGENTS.md

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.