Dune/AGENTS.md

Working on Dune

Unofficial Dune board game: React 19, TypeScript, Vinext/Vite, Cloudflare Workers and D1. Use npm and the checked-in lockfile; Node >=22.13 is required for the in-memory SQLite tests. tsx is a pinned development dependency.

Start small

• Read README.md and this guide first. See docs/DEVELOPMENT.md for the architecture map and focused verification commands.
• Read docs/CURRENT_STATUS.md for current gates and docs/RULE_DECISIONS.md for existing rulings before reopening research.
• Run git status --short before editing; preserve other work.
• Search the relevant feature in game/, components/, tests/, and docs/. Use rg -n and bounded reads for game/engine.ts and components/game-table.tsx; both are large orchestration files.
• docs/IMPLEMENTATION_STATUS.md is a historical evidence log, newest first. Read its opening checkpoint and the relevant feature document rather than loading the entire log. Verify historical claims against current code/tests.
• Do not read github.md for routine development: it is ignored private local credential material. Do not put secrets in logs or tracked files.

Prototype the remaining scope first

• The user prioritizes working first versions of all remaining functions across Basic, Advanced and every expansion, followed by integration, refinement and polish. Reuse existing capabilities; batch related functions by dependency.
• Track missing, prototyped, integrated, verified and polished work in the existing checklist. Prototypes need usable controls, a legal AI path and saved continuation; placeholders and disconnected helpers are not completed features.
• Keep focused checks for crashes, deadlocks, legality, custody, privacy and save integrity. Defer exhaustive combinations and visual polish until broader functional coverage, unless current failures require them.
• Defer full AI implementation, strategic refinement and difficulty calibration until all non-AI game features are complete. Until then, maintain only minimal legal participation and fix critical playability/correctness issues. Afterward, target approximately 75% higher-tier wins for each adjacent pair: Medium/Easy, Hard/Medium and Brutal/Hard. See docs/AI_DEVELOPMENT_PLAN.md for evaluation.
• Preserve required checkpoint checks, selective subagents and independent review for complex rules/privacy/persistence. Commit and push verified checkpoints under standing authorization. No user-imposed usage cutoff or routine account-usage check remains.
• Keep material rulings explicit and prototype independent work while pending. The user-authorized Advanced preview permits unfinished base-faction starts with a visible warning; see docs/ADVANCED_PREVIEW.md. Prototype evidence does not certify complete modes or open expansion/publication gates.

Implement and verify

• Keep rule calculations/validation in focused game/ modules; integrate them through the engine, player view, bots and UI as the feature requires.
• Preserve rejected-action immutability, physical card/force custody, private information boundaries, and JSON save/restore behavior. Reuse shared rule quotes instead of independently duplicating legality in bots or components.
• Add meaningful regressions to tests/**/*.test.ts; discovery is automatic. HTTP tests must start with // @dune-suite integration. Tests importing node:sqlite are classified as in-memory recovery tests automatically.
• During iteration: npm test -- <filename-fragment>; multiple fragments form a union. Use --list to inspect selection and --name <regex> to narrow cases. A filename typo fails rather than silently passing an empty suite.
• Before handing off code changes: npm run check (types, lint, offline tests). Run npm run build for app/build/dependency changes. Run npm run test:integration against a development server for HTTP, auth or persistence changes. Documentation-only edits need link/command review.
• Extend testing when failures or changed behavior justify it. Do not run AI calibration or browser acceptance for unrelated maintenance changes.
• If a sandbox blocks test subprocess pipes with EPERM, rerun the exact check with approved subprocess permissions. Do not disable isolation or skip tests to obtain a green result; the runner self-test checks real failure propagation.
• Report actual check results and limitations. Passing focused tests does not certify a complete faction, expansion or rules mode; preserve release gates.

Preserve development state

• The user-authorized 2026-09-13 reset cleared old local games once; see docs/VERIFICATION_WORKFLOW.md. Preserve all games created afterward.
• Keep .wrangler/state and all saved games. Never reset a database to fix a test, migration, connection or gameplay problem. Migrations are additive.
• Reuse a running dev server. Restart only when a code/configuration change or observed server condition warrants it; there is no hourly restart schedule. Warn before interrupting human play, defer to a safe point, and verify restoration after a necessary restart. No recurring maintenance automation is installed; do not recreate it without a request.
• .openai/hosting.json identifies the existing Sites project. Preserve it. Follow the applicable Sites skills for site work; publication has existing completion and verification gates documented in README.md.
• Keep generated builds, caches and editor backups out of version control. Avoid mass formatting, unrelated dependency updates and broad engine rewrites.

Efficient checkpoints

• Use docs/VERIFICATION_WORKFLOW.md for compact source-bound check reports and private saved-game/seat checks. Keep artifacts outside the checkout.
• Use subagents selectively for bounded independent tasks and complex reviews; they remain explicitly authorized. Share concise briefs and file ownership.
• Review, verify, commit and push completed checkpoints automatically under “Push all from now on.” Confirm push success; never force-push or expose secrets.