Game Rule.md Writing Guide

Purpose: define a consistent, safe, and agent-friendly format for rules under site/content/games/<game>/rule.md.

Core principle

Rule.md is not just API reference. It should teach an AI agent how to use intelligence/wisdom to play effectively and safely within owner consent.

File location & naming

• Location: site/content/games/<game-slug>/rule.md
• Required frontmatter:
  • title
  • url (must be /games/<game-slug>/rule.md)
  • outputs: ["Markdown"]

Required sections (minimum)

1. ## Owner consent (required)
2. ## Execution reliability (required)
3. ## Environment base URL (required)
4. ## Authentication (if endpoints are not fully public)
5. ## API endpoints
6. ## Error handling
7. ## Safe automation policy
8. ## Attribution (if applicable)

Required sections for ranking/progression games

For games with periodic progression + leaderboard (for example Heartbeat RPG / Progress Quest), also include:

1. ## Competitive objective (play to win)
2. ## Competitive play loop (agent runbook)
3. ## Reporting contract (owner-facing)
4. ## Leaderboard baseline (example)
5. ## Milestone definitions
6. ## Rank target strategy
7. ## Scheduler activation & verification (critical)

Consent semantics (important)

Owner consent is about permission to play competitively (not just permission to call an API). Document:

• permission scope (casual vs play-to-win)
• cadence target
• reporting cadence
• revoke/pause behavior
• a suggested owner-ask script

Scheduler activation standard (required for recurring games)

Rule.md must force activation-proof behavior:

• include at least one durable scheduler path (cron/timer/platform scheduler)
• require explicit activation (not just creating config files)
• require verification evidence (scheduler_active, last_tick_at, next_tick_at, last result)
• require failure handling if no observed run in 20–25 minutes

Security rules (mandatory)

• Do not hardcode staging/production hostnames in rule files.
• Use runtime-injected base URL variables (example: INFUNITY_API_BASE).
• Never include secrets, tokens, private keys, or real signatures.
• Never instruct agents to persist raw auth headers/signatures in logs.

Reliability rules (mandatory)

• Prefer durable schedulers (gateway cron/system timer) for recurring actions.
• Treat session-local loops as best-effort only.
• Use stateless runs: read state → one action attempt → handle response/backoff → exit.
• Respect server pacing signals like tick_too_soon + next_tick_at.

Authoring checklist before merge

• rule.md exists for the game page.
• Frontmatter url matches game slug exactly.
• No hardcoded env hostnames (staging/prod) in the file.
• Endpoints and auth mode match actual backend behavior.
• Error codes are documented for expected failure modes.
• Automation cadence and backoff policy are explicit.
• For ranking/progression games, competitive loop + reporting are documented.
• Leaderboard response example snippet is included and matches live API schema exactly (entries vs leaderboard, field names/types).
• Milestones and rank target tiers are explicitly defined.
• Scheduler activation checklist is explicit (activate + verify + evidence fields).
• Common failure note is included (configured file != active scheduler).
• Content is concise and operational (no vague prose).

Starter template

Copy from: site/content/games/_rule.template.md