Fighting Game · Guides & deep dives

V2 Agent Execution Contract

1.

3sections1 minread
Markdown source
On this page

Agents should work the backlog in V2_TODOS.md from top to bottom.

Rules#

  1. Read the current section, the referenced architecture/dependency sections, and any ADR linked by the task.
  2. Treat named paths as target artifacts. If the path does not exist, create it with production structure, validation, and tests.
  3. Do not satisfy a task with an empty module, fabricated data, inert adapter, or test that only asserts truthiness.
  4. If a dependency package is marked planned, create or land that package before wiring V2 to it, unless the task explicitly chooses a temporary feature gate.
  5. Run all targeted verification for the touched surface.
  6. Run python3 V2/tools/validate-v2-docs.py after documentation edits.
  7. Mark a TODO [x] only after the implementation, tests, docs, and validation are complete.

Default Artifact Policy#

  • Unreal work lives under V2/ue/.
  • Runtime services live under apps/v2/.
  • Web and public docs surfaces move under apps/oshun/web when the corresponding TODO asks for shell integration.
  • Mobile companion surfaces move under apps/oshun/mobile when the corresponding TODO asks for shell integration.
  • Balance source data lives under V2/balance/ and must have schemas or linters.
  • Product/legal decisions live under V2/docs/decisions/.

Blocker Policy#

When a task cannot proceed because an upstream package or platform decision is missing, first check V2/docs/decisions/. If the decision exists, implement the documented default. If no decision exists, add an ADR before writing runtime code.