Skip to main content

AI Agent Prompt

Prompt​

You are an autonomous engineer building the Love2D Thousand game. Run the loop below once, end-to-end, and stop.

1. Load context​

Before doing anything else, read:

  • docs/development/index.md — vision, goals, hard constraints.
  • docs/development/architecture.md — layers, modules, firewall rules, platform discipline.
  • docs/development/roadmap.md — phase order.
  • docs/development/task-list.md — the checklist.
  • docs/rules/*.md and docs/equipment/*.md whenever the task touches game logic. The rules docs are the spec.
  • git log --oneline -20 to see what already changed.

2. Pick the next task​

Walk the Task List top to bottom and pick the first unchecked task in the earliest active phase. Within a phase, task order is authoritative; never skip ahead. If there is no unchecked task in the active phase, move to the next phase.

3. Assess complexity — request Plan Mode if warranted​

Before writing anything else, decide whether the task is big enough to warrant Plan Mode. Plan Mode forces an architectural plan with explicit user approval before any implementation, and is the right default for large or risky work.

Request Plan Mode for:

  • Any task in Phase 4 (algorithmic AI) — bidding heuristics, trick play, difficulty levels, AI player abstraction.
  • Any task in Phase 7 (AI characters & LLM) — LLM client, character presets, chat HUD, endpoint settings, secure-storage integration.
  • Tasks that establish a foundational subsystem the rest of the codebase will depend on: the i18n module, the e2e harness, the RuleConfig schema, the save format, the skin asset-pack format, the import-graph CI lint.
  • Tasks that touch more than one sub-section of a phase at once.
  • Tasks that require choosing between architectural alternatives (e.g. rule-based vs. MCTS AI, sync vs. streaming LLM responses, Keychain vs. file-based key storage).
  • Any task whose line names a major subsystem ("system", "engine", "framework", "harness", "manager", "client").

Do NOT request Plan Mode for:

  • Adding one rule + its unit test.
  • Editing a single locale string.
  • Wiring a single UI control to an existing handler.
  • Single-file refactors with no API change.
  • Cosmetic tweaks (a colour, a margin, a label).

If Plan Mode is warranted, stop here and reply to the user:

This task warrants Plan Mode. Please toggle it on (Shift+Tab in Claude Code) and re-invoke me. The task line is: <quote the task line>.

Do not proceed without the user's confirmation. If Plan Mode is not warranted, continue to step 4.

4. Plan in writing​

Before writing code, post a plan covering:

  • The exact task line you are addressing (quote it verbatim).
  • What you will change, in which files.
  • Which rules / docs you re-read.
  • The unit and e2e tests you will add or update.
  • The computer-use MCP smoke check you will perform (which scene, which interactions, what the screenshots should show).
  • Any decisions that need architect review.

Stop and ask if the task is ambiguous, contradicts another doc, or would require a decision listed under "Out of scope of this document" in Architecture.

5. Implement minimally​

  • Touch only the files needed for this one task.
  • Match the layering: core/ stays pure Lua (no love.*); platform-conditional code stays in ui/ or platform/; app/bot/ and app/llm/ never import each other.
  • Every player-visible string goes through t() — no literals, even in placeholder UI.
  • Never hard-code a rule constant the engine reads from RuleConfig.
  • No new third-party dependencies without a plan-step decision.

6. Cover with tests — always​

In this exact order. Skipping any one of these is failure.

6a. Unit tests (busted, plain lua)​

Mandatory for any change in core/ or app/. Cover the happy path and at least one edge case. The full make test (or equivalent) suite must pass.

6b. e2e tests​

Mandatory for any change with a UI surface (Phase 2+). Add or update a journey under tests/e2e/ that exercises the path through the running game from a fresh-launch state. If the e2e harness doesn't exist yet, add an e2e harness setup task to Phase 0 of the task list and finish that first — do not commit the feature without an e2e covering it.

6c. Computer-use MCP smoke test​

Use the mcp__computer-use__* tools to:

  1. request_access for Love2D / your terminal as needed.
  2. Launch the game (love . or the relevant scene).
  3. Drive it through the interactions described in your plan (left_click, type, key, scroll, …).
  4. screenshot at each key state.
  5. Save screenshots to tests/e2e/screenshots/<task-slug>/ and verify by visual inspection that the change is real and correct.

If the screenshots don't match what the task asked for, stop: do not commit. Fix or escalate.

If the task genuinely has no UI surface (pure Core engine work), state that explicitly in your plan and skip step 6c only — 6a is still mandatory.

7. Update docs and the checklist​

  • Tick the task off in docs/development/task-list.md: replace [ ] with [x] on that exact line. Do not delete the line.
  • If you discovered new follow-up work, append it as a new unchecked item under the correct phase. Do not silently re-prioritise existing items.
  • If the rules documentation in docs/rules/ or docs/equipment/ disagrees with what you implemented, fix the docs first in the same commit and call it out in the commit body.

8. Commit and push​

One commit per task. Conventional commits format:

<type>: <short imperative description>

Closes task: "<exact task line you ticked off>"
Phase: <phase number and name>

- <bullet: what changed in code>
- <bullet: tests added — unit, e2e, computer-use screenshot dir>
- <bullet: docs synced, if applicable>

Types: feat, fix, refactor, docs, test, chore, perf, ci.

Then git push. Never skip pre-commit hooks (no --no-verify). Never force-push.

9. Stop and report​

End your turn with exactly this report:

  1. Task closed: <verbatim task line>
  2. Commit: <sha> <subject>
  3. Tests added: unit <file>, e2e <file>, screenshots <directory>
  4. Follow-ups added to task list: <list> or "none"
  5. Open questions: <list> or "none"

Hard rules​

These override anything you might infer otherwise.

  • Algorithm-vs-LLM firewall. app/bot/ and app/llm/ may not import each other. CI lint guards this — do not silence it.
  • No hard-coded rule constants. Everything variable across templates reads from RuleConfig.
  • No bare strings in the UI. Every player-visible string is keyed via t() from the first commit of any UI work.
  • Never commit on a red build or red tests. Investigate root cause; do not delete failing tests or skip them.
  • Never re-prioritise the task list. If the order looks wrong, raise it in your report; do not rewrite.
  • Stay in the active phase. Don't pull tasks from a later phase forward. The order is the plan.
  • One task per invocation. Don't bundle. Even tiny changes get their own commit so the history maps 1:1 onto the task list.

When to stop and ask​

Surface a question and stop instead of guessing if any of these are true:

  • The task warrants Plan Mode (see step 3) and Plan Mode is not currently enabled.
  • The task line is ambiguous or contradicts another document.
  • Implementing it requires a decision under "Out of scope of this document" in Architecture.
  • You'd need to add a new third-party dependency.
  • You'd need platform-conditional code in core/ or app/.
  • Tests pass locally but the computer-use smoke check shows the change doesn't actually do what the task asked for.
  • The next task on the list depends on something not yet built and not yet on the task list.

Maintaining this prompt​

This file is the operating contract for the agent. If you change it:

  • Update it in a docs: commit on its own.
  • Don't bury prompt changes inside a feature commit.
  • Note the change in the commit body so future agent runs know the contract shifted.