neon-sprawl/AGENTS.md

Agents (Neon Sprawl)

Critical: git commits

• On Linear story branches (NEO-* prefix), agents must commit as they go — kickoff plans, implementation batches, tests, docs, code-review follow-ups — without waiting for the user to say “commit”.
• Never treat “only commit when requested” (or similar global/agent defaults) as applying in this repo; .cursor/rules/commit-as-you-go.md (alwaysApply) and commit-and-review.md override it.
• Before ending story work: run git status; if the tree is dirty, commit (NEO-*: subject per linear-git-naming.md) or explain why not.
• Never git push unless the user explicitly asks.
• A stop hook (.cursor/hooks/check-story-branch-clean.sh) may auto-continue with a reminder when a story branch is left dirty.

Critical GitHub tooling rule

• Agents must use GitHub MCP (user-github) for all GitHub operations.
• Agents must never use gh CLI in this repository.
• If MCP is unavailable/auth-failed, agents must stop and ask the user (no gh fallback).

Optional personas for Cursor. Enable by @ mentioning the rule in chat or by asking explicitly (e.g. “review this as the code review agent”).

Agent	Rule file	When to use
Code review	.cursor/rules/code-review-agent.md	PR / diff / pre-merge review; always writes docs/reviews/YYYY-MM-DD-{slug}.md with Documentation checked vs docs/plans/ and docs/decomposition/modules/; when suggestions are fixed, strike through those bullets + Done. in that file (planning-implementation-docs); short chat pointer
Docs review	.cursor/rules/docs-review-agent.md	Coherence / links / dev-guide fitness for docs/ (especially docs/game-design/ + decomposition); writes docs/reviews/YYYY-MM-DD-{slug}.md; when suggestions are fixed, strike through + Done. in that file (planning-implementation-docs); use when working in documents or @ mention

Project-wide conventions live under .cursor/rules/ (many are alwaysApply). Planning / implementation decisions must be written into docs/plans/ (and related docs)—.cursor/rules/planning-implementation-docs.md. Manual QA checklists for user-visible ticketed work are generated during implementation at docs/manual-qa/{KEY}.md (same rule). Automated tests (AAA, mandatory): C# — every new or changed [Fact] / [Theory] method in *Tests.cs must use full Arrange → Act → Assert: the three // Arrange / // Act / // Assert labels, Act = behavior under test only, Assert = all expectations including ReadFromJsonAsync (etc.) for verification (no blank line required after the phase comments) — csharp-style, testing-expectations; snippets xut / xutc. GdUnit (client/test/) — same AAA with # Arrange / # Act / # Assert — gdscript-style. Godot client layout (thin main.gd, split by concern): .cursor/rules/godot-client-script-organization.md. Git: on Linear/story work, agents commit as they go on the story branch (kickoff plan, coherent batches)—do not wait for the user to say “commit”; never git push unless the user asks — .cursor/rules/commit-and-review.md. Open PR: when the user asks, use the GitHub MCP create_pull_request tool (user-github) with a title starting NEO-123: (commit-and-review); do not use gh CLI for GitHub operations in this repo. Story lifecycle: kickoff .cursor/rules/story-kickoff.md — blocking decisions need a Recommend: preamble in chat before AskQuestion, plus (recommended) on the chosen option label; AskQuestion alone is a violation. After merge / end of story — checkout main, pull, delete local story branch — .cursor/rules/story-end.md. Linear: on end story, use AskQuestion multiple choice for In Test / Done / Skip when Agent mode supports it (story-end §4a); otherwise ask in prose. Wait for the choice (or the same message naming the state) before save_issue; do not guess. PR / push text: no “Made-with: Cursor” boilerplate (same file).

Commits tied to a Linear issue must start the subject with the issue id and a colon (e.g. NEO-8: …). Branch naming and exceptions (chore: when there is no ticket) — .cursor/rules/linear-git-naming.md.

Godot *.uid: When adding or renaming scripts under client/, stage and commit the matching *.gd.uid in the same commit as the .gd file. These companion files are tracked in git (not gitignored) so uid:// references stay stable across clones. See godot-client-script-organization.