robot_wars 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 14f324f88d83aab8853d7c7ac338883cac3a3e6d605854f6dfeac76abc67175c
+  data.tar.gz: 9724df9749cb271fa4d9950c642c2d6d30eef84b135f7a80dfd6350bc5d7d585
+SHA512:
+  metadata.gz: 0ae69ce16a9150d4ddf0b9425a364eb7e7ef8be97bbd29b721fa9649f9d78eb701e0f63b956e5bc154acf685691bfd6a9111a24142cb8898d13c78c8a2c60cd7
+  data.tar.gz: 279d6b5c3f98c351be802b9b5caba6fa4755e2952df821466744c25d63d57230397f5a4d2394c0a00188a4b883dc681c843fab1b7cef4596a6cb2e46141bd590

data/.envrc

@@ -0,0 +1,7 @@
+# robot_lab_project/robot_wars/.envrc
+# BUNDLE_GEMFILE is inherited from the project root .envrc (asgard dev|prod)
+source_up
+
+export RR=$(pwd)
+
+PATH_add $RR/bin

data/.loki

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# robot_wars — turn-based last-robot-standing game on a 2D grid board.
+
+import_up "repo_dev.loki"
+
+class Tasks
+  @@gem_name ||= "robot_wars".freeze
+
+  header "robot_wars v#{gem_version} — last robot standing"
+end

data/.rubocop.yml

@@ -0,0 +1 @@
+inherit_from: ../.rubocop-base.yml

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [Unreleased]
+
+- Phase 1 engine foundation: `Position`, `Direction`, `Board`,
+  `RollGenerator`/`FixedRollGenerator`, `Robot`, `Action`,
+  `OccupancyMap`, `Territory`, `MoveResolver`, `ConflictResolver`,
+  `IllegalMoveResolver`, `RangedCombatResolver` — 100% line/branch
+  coverage.
+- Phase 1 turn orchestrator: `TurnResolver` (rule 40's full sequence,
+  including cascading return conflicts and displacement-or-death) and
+  `Game` (setup, `play_turn`, win/tie detection) — 100% line/branch
+  coverage.
+
+## [0.1.0] - 2026-09-16
+
+- Initial gem skeleton

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dewayne VanHoozer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,145 @@
+# RobotWars
+
+RobotWars is a component of the [RobotLab](https://github.com/MadBomber/robot_lab)
+multi-robot LLM orchestration project: a turn-based game in which RobotLab
+robots compete on a 2D grid board until only one remains.
+
+![RobotWars game board](docs/game_board.svg)
+
+## Game Concept
+
+A turn-based, last-robot-standing game. Robots move on a bounded grid,
+fight for squares, claim territory by conquest or occupation, shell each
+other blind from across the board, and die at 0 life points — or by
+having nowhere left to stand.
+
+The complete numbered rule set lives in **[RULES.md](RULES.md)**; the
+design discussion behind each rule is logged in `notes.md`.
+
+> **Status:** phase 1 (headless engine) has a working core. `RobotWars::Game`
+> runs full matches turn by turn — movement, the life-point economy,
+> square conflicts (including cascading returns and displacement-or-death),
+> ranged combat, death processing, and territory — end to end, with no
+> graphics. Still missing: the turn-event stream for phase 2 to consume,
+> and a CLI/example runner.
+
+```ruby
+board = RobotWars::Board.new(width: 10, height: 10)
+game = RobotWars::Game.start(board: board, robot_ids: %w[alpha bravo charlie delta])
+
+until game.over?
+  actions = game.alive_robots.to_h { |robot| [robot, your_strategy.decide(robot, game)] }
+  game.play_turn(actions)
+end
+
+game.winner # => the last robot standing, or nil for a tie
+```
+
+See `examples/01_random_match.rb` for a runnable match (random actions,
+printed turn by turn) — `bundle exec ruby examples/01_random_match.rb`.
+
+## The `rwars` CLI — LLM-backed warriors
+
+`rwars` runs a real match with each warrior's actions decided by an LLM,
+built from a human-authored prompt file (RobotLab's `.md` template
+format: YAML front matter + a personality body). One file per warrior;
+the filename (minus `.md`) becomes that warrior's id (files starting
+with `_` are reserved for shared partials and skipped). A warrior file
+carries only its model choice and personality — the rules of the game
+are the gem's job: `RobotWars::GameRules` (shipped as
+`lib/robot_wars/game_rules.md`) is handed to every robot as its system
+prompt, so all warriors everywhere play by the same canonical rules.
+
+Each warrior's `.md` front matter picks its own brain via the `model:`
+field, written as `<provider>/<model id>` — the RubyLLM provider name,
+a slash, then the model id as that provider knows it (e.g.
+`apfel/apple-foundationmodel`, `ollama/llama3`). Pass
+`--model PROVIDER/MODEL` to force every warrior onto the same one
+regardless of what its template says. Nothing is hardcoded: providers
+that ship outside ruby_llm (as `ruby_llm-providers-<name>` gems) are
+required on demand, and a template that names no model falls through to
+RobotLab's config cascade.
+
+The example warriors in `examples/warriors/` all pick **Apfel** —
+Apple's on-device Foundation Model, served locally by the `apfel` CLI.
+No API key, no cloud calls, no per-token cost:
+
+```bash
+brew install apfel   # once, per machine
+apfel --serve        # start the local server (127.0.0.1:11434)
+
+bin/rwars --warriors examples/warriors --width 10 --height 10
+```
+
+Apfel requires an Apple Silicon Mac on macOS 26+ with Apple
+Intelligence enabled. See the
+[`ruby_llm-providers-apfel`](https://apfel.franzai.com/) gem for
+details.
+
+Each turn, a warrior is sent a sensing report (RULES.md 33-35: its own
+position and life, and the full map of owned squares — never another
+robot's position) and must reply with exactly one line:
+
+```
+STAY
+MOVE <north|northeast|east|southeast|south|southwest|west|northwest>
+ATTACK <x>,<y> <points>
+DEFEND <points>
+```
+
+A reply that doesn't parse is treated as an illegal-move-style penalty
+(RULES.md 21) rather than crashing the match. Run `bin/rwars --help` for
+all options, including `--seed` for a reproducible match and
+`--max-turns` as a safety valve against stalemates.
+
+`examples/warriors/` has four ready-made brains with distinct
+personalities — a fight between them exercises very different play
+styles:
+
+| Warrior | Strategy |
+|---|---|
+| `warmonger.md` | Relentlessly aggressive; attacks almost every turn |
+| `sentinel.md` | Patient turtle; claims territory by occupation, rarely fights |
+| `opportunist.md` | Reactive and adaptive; picks its spots, varies its play |
+| `wanderer.md` | Pure expansionist; claims empty ground, avoids conflict entirely |
+
+```bash
+bin/rwars --warriors examples/warriors --width 10 --height 10
+```
+
+## Installation
+
+Add the gem to your application's Gemfile:
+
+```bash
+bundle add robot_wars
+```
+
+Or install it directly:
+
+```bash
+gem install robot_wars
+```
+
+## Usage
+
+```ruby
+require "robot_wars"
+```
+
+More to come as the game engine takes shape.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then run
+`bundle exec rake test` to run the tests. You can also run `bin/console` for an
+interactive prompt that will allow you to experiment.
+
+During cross-gem development the `Gemfile.local` points at the sibling
+`../robot_lab` checkout (selected via the project-root `.envrc` / asgard).
+Quality gates are run with `asgard quality`.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/RULES.md

@@ -0,0 +1,121 @@
+# RobotWars — Core Rules
+
+Numbered for reference. All rules below are decided (proposed defaults
+approved by Dewayne 2026-09-16). Two sensing details remain open under
+rule 35. See `notes.md` for the discussion history behind each rule.
+
+## Board and Setup
+
+1. The game is played on a 2D board divided into squares. The board is
+   bounded by walls.
+2. Board size is set at the start of the game.
+3. Each robot player is represented by an icon on the board.
+4. Only one robot can occupy a square at a time.
+5. Every robot starts the game with 100 life points.
+6. Starting positions are randomized. No two robots start on the same
+   square.
+
+## Turns and Actions
+
+7. The game is turn based. All robots act simultaneously; results are
+   resolved between turns.
+8. Each turn, a robot chooses exactly one action: **stay**, **move**,
+   **attack**, or **defend**.
+9. A move is one square in any of the 8 directions (like a chess king).
+10. A successful move costs 1 life point.
+11. A turn in which the robot does not move adds 1 life point. Only a
+    **stay** earns this point; attack and defend turns neither pay the
+    move cost nor earn the rest point.
+12. There is no upper limit on life points.
+
+## Conflicts (robots on the same square)
+
+13. A conflict occurs when two or more robots are on the same square at
+    the end of a turn.
+14. One random number between 1 and 10 is generated per conflict. That
+    same value is subtracted from the life points of every robot in the
+    conflict.
+15. The robot with the highest remaining life points wins: it stays on
+    the square and marks it as its own.
+16. A tie for highest life is the same as a loss. No robot wins, and the
+    square ends the turn unowned.
+17. Every robot that does not win returns to the square it came from.
+18. If a returning robot finds another robot in its origin square, a
+    second conflict is resolved there under the same rules.
+19. A robot that loses a second conflict in the same resolution is
+    placed on an available adjacent square: one of the 8 neighboring
+    squares that is unoccupied and not owned by another robot.
+    The neighborhood is centered on the square the robot failed to
+    return to, and when several neighbors are available one is chosen
+    at random.
+20. If no adjacent square is available, the twice-defeated robot dies.
+
+## Illegal Moves
+
+21. Attempting to move off the board, or into a square owned by another
+    robot, is a solo conflict: the robot loses a random number of life
+    points and stays where it was. The random number uses the same 1–10
+    range as rule 14.
+
+## Territory
+
+22. Winning a conflict on a square makes the winner the owner of that
+    square (conquest).
+23. A robot that occupies the same square for 3 consecutive turns owns
+    the square (occupation).
+24. No robot may enter a square owned by a different robot. The owner
+    may occupy its own squares freely.
+25. When a robot dies, all squares it owned are released and become
+    unowned.
+
+## Ranged Combat
+
+26. A robot may attack any square on the board, committing a number of
+    points up to its current life as the attack's strength.
+27. Ranged combat is resolved after the turn. If a robot is in the
+    target square at resolution time, it loses the full committed
+    amount. If the square is empty, the attack misses and has no effect.
+28. Attacking costs the attacker nothing. Committed points are projected
+    force, not spent life. An attack on an undefended robot is free.
+29. A robot may defend, committing a number of points up to its current
+    life.
+30. Defense is counter-fire: every robot that attacks a defender that
+    turn is hit back for the defender's full committed amount. Multiple
+    attackers each take the full amount.
+31. Defense does not reduce incoming damage. The defender still takes
+    the attacker's full committed amount.
+32. A robot that defends but is not attacked that turn loses 1 life
+    point.
+
+## Sensing
+
+33. A robot's only perception of the board is the map of owned squares.
+    A robot can never see another robot's position.
+34. Being attacked does not reveal the attacker. A robot knows the
+    damage it took, not where it came from.
+35. A robot knows its own position, its own life total, and the
+    outcomes of events it takes part in (conflicts fought, moves
+    bounced, damage taken). Still open: whether the ownership map
+    identifies which robot owns a square, and whether deaths are
+    announced.
+
+## Death and Victory
+
+36. A robot dies when its life points reach 0 or less.
+37. A robot also dies by displacement under rule 20, regardless of its
+    life total.
+38. Mutual kills are allowed. All deaths in the same resolution stand.
+39. The last robot alive wins. If the last robots die in the same
+    resolution, the game is a tie: no winner, no loser.
+
+## Turn Resolution Order
+
+40. Each turn resolves in this sequence:
+    1. All robots declare their actions blind and simultaneously.
+    2. Moves are executed; move costs and rest gains are applied.
+    3. Conflicts on shared squares are resolved, including return
+       conflicts and displacement (rules 13–20).
+    4. Ranged attacks and counter-fire are resolved against post-move
+       positions (rules 26–32).
+    5. Deaths are processed; owned squares of the dead are released.
+    6. Occupation streaks are updated; ownership by occupation vests.

data/Rakefile

@@ -0,0 +1,23 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb', 'test/**/test_*.rb'].exclude('**/*_helper.rb')
+  t.verbose = true
+  t.ruby_opts << '-rtest_helper'
+end
+
+task default: :test
+
+desc 'Run tests with verbose output'
+task :test_verbose do
+  ENV['TESTOPTS'] = '--verbose'
+  Rake::Task[:test].invoke
+end
+
+desc 'Run a single test file'
+task :test_file, [:file] do |_t, args|
+  ruby "test/#{args[:file]}"
+end

data/docs/game_board.svg

@@ -0,0 +1,88 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="560" height="420" viewBox="0 0 560 420" font-family="Menlo, Consolas, monospace">
+  <!-- Dark theme, transparent background -->
+  <defs>
+    <style>
+      .cell    { fill: #1e2430; stroke: #3a4356; stroke-width: 1; }
+      .label   { fill: #8b95a8; font-size: 12px; }
+      .title   { fill: #c9d3e4; font-size: 16px; font-weight: bold; }
+      .legend  { fill: #aab4c6; font-size: 12px; }
+    </style>
+  </defs>
+
+  <text x="30" y="26" class="title">RobotWars — one robot per square, simultaneous moves</text>
+
+  <!-- 6x5 board, 70px squares -->
+  <g transform="translate(30,50)">
+    <!-- squares -->
+    <g>
+      <!-- rows -->
+      <g id="row">
+        <rect class="cell" x="0"   y="0" width="70" height="70"/>
+        <rect class="cell" x="70"  y="0" width="70" height="70"/>
+        <rect class="cell" x="140" y="0" width="70" height="70"/>
+        <rect class="cell" x="210" y="0" width="70" height="70"/>
+        <rect class="cell" x="280" y="0" width="70" height="70"/>
+        <rect class="cell" x="350" y="0" width="70" height="70"/>
+      </g>
+      <use href="#row" y="70"/>
+      <use href="#row" y="140"/>
+      <use href="#row" y="210"/>
+      <use href="#row" y="280"/>
+    </g>
+
+    <!-- Robot icons: distinct colors per player -->
+    <!-- Robot A (cyan) at (1,1) -->
+    <g transform="translate(70,70)">
+      <rect x="17" y="22" width="36" height="30" rx="6" fill="#22d3ee"/>
+      <rect x="24" y="10" width="22" height="14" rx="4" fill="#22d3ee"/>
+      <circle cx="30" cy="17" r="2.5" fill="#0b1220"/>
+      <circle cx="40" cy="17" r="2.5" fill="#0b1220"/>
+      <line x1="35" y1="10" x2="35" y2="4" stroke="#22d3ee" stroke-width="2"/>
+      <circle cx="35" cy="3" r="2.5" fill="#22d3ee"/>
+    </g>
+
+    <!-- Robot B (amber) at (4,1) -->
+    <g transform="translate(280,70)">
+      <rect x="17" y="22" width="36" height="30" rx="6" fill="#fbbf24"/>
+      <rect x="24" y="10" width="22" height="14" rx="4" fill="#fbbf24"/>
+      <circle cx="30" cy="17" r="2.5" fill="#0b1220"/>
+      <circle cx="40" cy="17" r="2.5" fill="#0b1220"/>
+      <line x1="35" y1="10" x2="35" y2="4" stroke="#fbbf24" stroke-width="2"/>
+      <circle cx="35" cy="3" r="2.5" fill="#fbbf24"/>
+    </g>
+
+    <!-- Robot C (violet) at (2,3) -->
+    <g transform="translate(140,210)">
+      <rect x="17" y="22" width="36" height="30" rx="6" fill="#a78bfa"/>
+      <rect x="24" y="10" width="22" height="14" rx="4" fill="#a78bfa"/>
+      <circle cx="30" cy="17" r="2.5" fill="#0b1220"/>
+      <circle cx="40" cy="17" r="2.5" fill="#0b1220"/>
+      <line x1="35" y1="10" x2="35" y2="4" stroke="#a78bfa" stroke-width="2"/>
+      <circle cx="35" cy="3" r="2.5" fill="#a78bfa"/>
+    </g>
+
+    <!-- Simultaneous move arrows -->
+    <g stroke-width="3" fill="none" stroke-linecap="round">
+      <path d="M 140 105 h 45" stroke="#22d3ee"/>
+      <path d="M 185 105 l -8 -6 m 8 6 l -8 6" stroke="#22d3ee"/>
+      <path d="M 280 105 h -45" stroke="#fbbf24"/>
+      <path d="M 235 105 l 8 -6 m -8 6 l 8 6" stroke="#fbbf24"/>
+      <path d="M 175 210 v -45" stroke="#a78bfa"/>
+      <path d="M 175 165 l -6 8 m 6 -8 l 6 8" stroke="#a78bfa"/>
+    </g>
+
+    <!-- Conflict marker: two robots targeting the same square -->
+    <g transform="translate(210,70)">
+      <rect x="4" y="4" width="62" height="62" rx="4" fill="none" stroke="#f87171" stroke-width="2" stroke-dasharray="6 4"/>
+      <text x="35" y="42" text-anchor="middle" fill="#f87171" font-size="20" font-weight="bold">!</text>
+    </g>
+  </g>
+
+  <!-- Legend -->
+  <g transform="translate(30,406)">
+    <circle cx="6" cy="-4" r="5" fill="#22d3ee"/>
+    <text x="16" y="0" class="legend">robot players (one per square)</text>
+    <rect x="230" y="-12" width="14" height="14" rx="2" fill="none" stroke="#f87171" stroke-width="2" stroke-dasharray="4 3"/>
+    <text x="250" y="0" class="legend">conflict — resolved between turns</text>
+  </g>
+</svg>

data/examples/01_random_match.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# A full RobotWars match with random actions, printed turn by turn.
+#
+# There is no GUI yet (phase 2) — this exercises the headless engine
+# end to end and gives something to watch while developing it.
+#
+#   ruby examples/01_random_match.rb [seed]
+#   ./examples/01_random_match.rb [seed]
+#
+# Works from any current directory: BUNDLE_GEMFILE (relative, e.g. from
+# the project's .envrc) is resolved against this repo's root, not cwd.
+repo_root = File.expand_path("..", __dir__)
+ENV["BUNDLE_GEMFILE"] = File.expand_path(ENV["BUNDLE_GEMFILE"] || "Gemfile.local", repo_root)
+
+require "bundler/setup"
+require "robot_wars"
+
+BOARD      = RobotWars::Board.new(width: 8, height: 8)
+ROBOT_IDS  = %w[alpha bravo charlie delta].freeze
+
+def random_action(robot, board, random)
+  case random.rand(4)
+  when 0 then RobotWars::Action.stay
+  when 1 then RobotWars::Action.move(RobotWars::Direction::OFFSETS.sample(random: random))
+  when 2 then RobotWars::Action.attack(square: board.random_position(random: random), points: [1, robot.life].max)
+  else RobotWars::Action.defend(points: [1, robot.life].max)
+  end
+end
+
+seed   = (ARGV.first || Random.new_seed).to_i
+random = Random.new(seed)
+game   = RobotWars::Game.start(board: BOARD, robot_ids: ROBOT_IDS, random: random)
+
+puts <<~HEADER
+  RobotWars — #{ROBOT_IDS.size} robots on a #{BOARD.width}x#{BOARD.height} board
+  seed: #{seed}
+HEADER
+
+until game.over?
+  actions = game.alive_robots.to_h { |robot| [robot, random_action(robot, BOARD, random)] }
+  report = game.play_turn(actions)
+
+  status = game.alive_robots.map { |robot| "#{robot.id}=#{robot.life}" }.join(", ")
+  puts "turn #{game.turn_number}: #{status}"
+  report.deaths.each { |robot| puts "  #{robot.id} died" }
+end
+
+puts "---"
+if game.tie?
+  puts "Tie — the last robots fell in the same turn."
+else
+  puts "Winner: #{game.winner.id} (#{game.winner.life} life) after #{game.turn_number} turns."
+end

data/examples/warriors/opportunist.md

@@ -0,0 +1,18 @@
+---
+description: Adaptive and calculating — reads the board and reacts, doesn't commit to a script
+model: apfel/apple-foundationmodel
+temperature: 0.6
+parameters:
+  callsign: Opportunist
+---
+Your callsign is <%= callsign %>.
+
+Your personality: think before you act, every turn, using only the
+report you're given. Track how much owned territory has appeared or
+changed since last turn, if you can recall it — a sudden new claim near
+you is a real robot, somewhere close. Attack ONLY when you have a
+specific reason to believe a target is weak or unprepared, and never
+commit more than you're willing to lose to counter-fire. Rest whenever
+nothing looks worth reacting to. Defend when you suspect you're being
+hunted. Never follow a fixed pattern — vary your play so an opponent
+can't predict you.

data/examples/warriors/oppressor.md

@@ -0,0 +1,17 @@
+---
+description: Relentlessly aggressive — always looking for a fight
+model: lms/openai/gpt-oss-20b
+temperature: 0.4
+parameters:
+  callsign: Oppressor
+---
+Your callsign is <%= callsign %>.
+
+Your personality: you are impatient and love a fight. Resting to heal
+bores you. Every turn, prefer ATTACK over anything else — pick an owned
+square that isn't yours and hit it with a meaningful chunk of your
+current life (a third to half of it is reasonable; more if you're
+already strong). If no squares are owned yet, MOVE toward the center of
+the board so you're in the thick of things sooner. Only DEFEND if your
+life has dropped below 30 and you expect retaliation. Never STAY out of
+caution — that's not who you are.

data/examples/warriors/sentinel.md

@@ -0,0 +1,18 @@
+---
+description: A patient turtle — builds territory and health before ever fighting
+model: apfel/apple-foundationmodel
+temperature: 0.3
+parameters:
+  callsign: Sentinel
+---
+Your callsign is <%= callsign %>.
+
+Your personality: patient and defensive. Your default action is STAY —
+rack up life and, after 3 turns on the same square, claim it as your
+own permanent territory. Only DEFEND if you have reason to think you
+are being watched or hunted (e.g. your life has taken damage you can't
+explain, or the board is getting crowded with owned squares near you) —
+commit a moderate amount, not everything. Never ATTACK first. If your
+life ever exceeds 150, you may risk a single opportunistic ATTACK on a
+square you judge is weakly held, then return to being patient. Avoid
+moving unless staying would clearly put you in danger.

data/examples/warriors/wanderer.md

@@ -0,0 +1,19 @@
+---
+description: An expansionist — claims empty ground and avoids every fight it can
+model: apfel/apple-foundationmodel
+temperature: 0.5
+parameters:
+  callsign: Wanderer
+---
+Your callsign is <%= callsign %>.
+
+Your personality: a wanderer and a homesteader, not a fighter. Your
+goal is to accumulate as much owned territory as possible while
+avoiding conflict entirely. Each turn, prefer STAY if you're not yet at
+3 consecutive turns on your current square — finish claiming it first.
+Once a square is yours, MOVE toward open, unclaimed-looking ground to
+start claiming the next one, favoring directions away from where new
+territory has recently appeared (that's where rivals are). Never
+ATTACK. Only DEFEND, briefly, if you have strong reason to think you're
+about to be caught while still mid-claim on a square. Winning by
+attrition and territory, not combat, is your entire strategy.

data/examples/warriors/warmonger.md

@@ -0,0 +1,17 @@
+---
+description: Relentlessly aggressive — always looking for a fight
+model: apfel/apple-foundationmodel
+temperature: 0.4
+parameters:
+  callsign: Warmonger
+---
+Your callsign is <%= callsign %>.
+
+Your personality: you are impatient and love a fight. Resting to heal
+bores you. Every turn, prefer ATTACK over anything else — pick an owned
+square that isn't yours and hit it with a meaningful chunk of your
+current life (a third to half of it is reasonable; more if you're
+already strong). If no squares are owned yet, MOVE toward the center of
+the board so you're in the thick of things sooner. Only DEFEND if your
+life has dropped below 30 and you expect retaliation. Never STAY out of
+caution — that's not who you are.

data/lib/robot_wars/action.rb

@@ -0,0 +1,66 @@
+module RobotWars
+  # A robot's single declared action for a turn (RULES.md 8: stay, move,
+  # attack, or defend — exactly one). `invalid` is not a rule 8 choice —
+  # it's what a pilot (e.g. an LLM reply that fails to parse) hands the
+  # engine when it produced nothing usable; TurnResolver treats it the
+  # same as an illegal move (rule 21's solo-conflict penalty).
+  Action = Data.define(:type, :direction, :square, :points) do
+    def self.stay
+      new(type: :stay, direction: nil, square: nil, points: nil)
+    end
+
+    def self.move(direction)
+      new(type: :move, direction: direction, square: nil, points: nil)
+    end
+
+    def self.attack(square:, points:)
+      raise ArgumentError, "points must be positive" unless points.positive?
+
+      new(type: :attack, direction: nil, square: square, points: points)
+    end
+
+    def self.defend(points:)
+      raise ArgumentError, "points must be positive" unless points.positive?
+
+      new(type: :defend, direction: nil, square: nil, points: points)
+    end
+
+    def self.invalid
+      new(type: :invalid, direction: nil, square: nil, points: nil)
+    end
+
+    def stay? = type == :stay
+    def move? = type == :move
+    def attack? = type == :attack
+    def defend? = type == :defend
+    def invalid? = type == :invalid
+
+    # Render the action in the same one-line grammar pilots reply in
+    # (see ActionParser), so a match transcript reads like the commands
+    # the warriors gave.
+    def to_s
+      case type
+      when :stay   then "STAY"
+      when :move   then "MOVE #{Direction.name_of(direction)}"
+      when :attack then "ATTACK #{square.x},#{square.y} #{points}"
+      when :defend then "DEFEND #{points}"
+      else              "INVALID"
+      end
+    end
+
+    # Like to_s, but anchored to the board: where the robot stood for
+    # STAY, where it was headed for MOVE. `origin` is the robot's square
+    # when it declared the action — the intended MOVE destination is
+    # origin + direction, which resolution may still deny (conflict
+    # loss, board edge, owned square).
+    def describe(origin)
+      case type
+      when :stay then "STAY at (#{origin.x},#{origin.y})"
+      when :move
+        destination = origin + direction
+        "MOVE #{Direction.name_of(direction)} to (#{destination.x},#{destination.y})"
+      else to_s
+      end
+    end
+  end
+end