bisco/hoopscout-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
develop
hoopscout-v2/AGENTS.md

5.5 KiB
Raw Permalink Blame History

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.