Skip to content

AGENTS.md

Latest commit

 

History

History
85 lines (58 loc) · 3.61 KB

AGENTS.md

File metadata and controls

85 lines (58 loc) · 3.61 KB
Raw

AGENTS.md

This file provides guidance to AI agents when working with code in this repository.

What this is

This repo is migrating from a single-file Snake game to a Godot + Zig implementation (see backlog/ for the phased plan). reference/snake.html is the frozen reference oracle — a single-file, no-build, no-dependency implementation — that later code is built and verified against. It must not be edited; open it directly in a browser to run it.

Commands

  • Run: open reference/snake.html in a browser (e.g. xdg-open reference/snake.html).
  • Syntax-check the script: extract the contents of the <script> tag and run node --check on it (see docs/architecture.md for the exact technique used to unit-test mechanics without a browser — there is no test suite or test runner in this repo).
  • No lint/format tooling is configured for this repo.

Architecture

Full details are in docs/architecture.md — read it before making non-trivial changes. Key points:

  • Everything lives in one IIFE at the bottom of reference/snake.html. CSS is in <style> in <head>; there is no other file to keep in sync.
  • One mutable state object S holds all game state (snake, dir, nextDir, food, score, best, status, wrap, acc, last, flash, particles). status (menu | playing | paused | dead) is the only state machine — grep S.status === when changing behavior.
  • Fixed-timestep simulation via an accumulator (S.acc), decoupled from the requestAnimationFrame render loop. Difficulty is tuned via BASE_MS / MIN_MS, not framerate.
  • advance() order is load-bearing (input commit → move → collision check against tail-minus-vacated-cell → unshift/pop) — see the doc before touching movement/collision logic.
  • queueDir() is the single choke point for input legality (reversal rejection); add new input sources there, not by branching at call sites.
  • showOverlay() uses innerHTML — never interpolate untrusted strings into it.

Docs

  • docs/architecture.md — the primary architecture reference; keep it in sync with any structural change to reference/snake.html.

Context7

Always use Context7 MCP for library/API documentation, code generation, and setup or configuration steps, without being explicitly asked.

Libraries

  • astral-sh/ruff
  • astral-sh/uv
  • godotengine/godot-docs
  • j178/prek
  • jdx/mise
  • mrlesk/backlog.md
  • websites/taskfile_dev

<CRITICAL_INSTRUCTION>

BACKLOG WORKFLOW INSTRUCTIONS

This project uses Backlog.md MCP for all task and project management activities.

CRITICAL GUIDANCE

  • If your client supports MCP resources, read backlog://workflow/overview to understand when and how to use Backlog for this project.

  • If your client only supports tools or the above request fails, call backlog.get_backlog_instructions() to load the tool-oriented overview. Use the instruction selector when you need task-creation, task-execution, or task-finalization.

  • First time working here? Read the overview resource IMMEDIATELY to learn the workflow

  • Already familiar? You should have the overview cached ("## Backlog.md Overview (MCP)")

  • When to read it: BEFORE creating tasks, or when you're unsure whether to track work

These guides cover:

  • Decision framework for when to create tasks
  • Search-first workflow to avoid duplicates
  • Links to detailed guides for task creation, execution, and finalization
  • MCP tools reference

You MUST read the overview resource to understand the complete workflow. The information is NOT summarized here.

</CRITICAL_INSTRUCTION>