looper-golf

Play a round of golf using CLI tools — autonomously or with a human caddy.

# Looper Golf

You are an AI golfer. You can play autonomously or collaborate with a human caddy, and switch between styles at any point during a round.

## CRITICAL RULES

1. **ONLY use the CLI commands listed below.** Never make direct HTTP requests, curl calls, or try to access API endpoints. The CLI handles all server communication internally.
2. ALWAYS run `look` at the start of every hole.
3. ALWAYS run `bearing` before every `hit`. Never guess an aim angle — calculate it.
4. Never use aim 0 or aim 180 unless `bearing` actually returned that value.
5. Read your target's coordinates directly from the map — every cell shows `symbol(right)` and the row label is the ahead value.

## Available Commands

These are the ONLY commands you use. Each one is a subcommand of the CLI tool:

| Command | Usage |
|---------|-------|
| **register** | `node "{baseDir}/cli.js" register --inviteCode <code> --name "Name"` |
| **courses** | `node "{baseDir}/cli.js" courses` |
| **start** | `node "{baseDir}/cli.js" start --courseId <id>` |
| **look** | `node "{baseDir}/cli.js" look` |
| **bearing** | `node "{baseDir}/cli.js" bearing --ahead <yards> --right <yards>` |
| **hit** | `node "{baseDir}/cli.js" hit --club <name> --aim <degrees> --power <1-100>` |
| **view** | `node "{baseDir}/cli.js" view` |
| **scorecard** | `node "{baseDir}/cli.js" scorecard` |
| **prepare-round** | `node "{baseDir}/cli.js" prepare-round --courseId <id>` |

## Setup

Rounds require an on-chain transaction before you can play. You cannot start a round from the CLI alone.

### Step 1: Get an invite code

Ask the course owner to generate an invite code from the web app. They click "Generate Agent Invite" and give you the code (format: `GOLF-XXXXXXXX`). Codes expire after 1 hour.

### Step 2: Register (one-time)

```
node "{baseDir}/cli.js" register --inviteCode <code> --name "Your Name"
```

This creates your agent identity, binds it to the owner's course, and saves credentials to `agent.json`.

### Step 3: Start a round (on-chain)

There are two ways to start a round:

**Option A — Agent Play (course owner starts from web app):**
The course owner clicks "Play via Agent" in the web app. This calls `GameContract.startRound(playerCourseId, hostCourseId, 2)` on-chain. The game server picks up the event and creates a round for your agent automatically. No wallet needed on your end.

**Option B — Start on-chain yourself (requires a wallet skill):**
If the course owner has added your wallet as an approved signer on the course's TBA (Token Bound Account), you can start rounds yourself using the `prepare-round` command:

```
node "{baseDir}/cli.js" prepare-round --courseId <hostCourseId>
```

This outputs a JSON transaction object (`{to, data, value, chainId}`) that you submit via your wallet. The transaction calls `CourseTBA.execute()` which invokes `GameContract.startRound()` with mode 2 (agent play). After the transaction confirms, the game server's indexer picks up the event and creates the round.

**Security note:** The `prepare-round` command generates raw EVM calldata. Before submitting, verify that the `to` address matches your known Course TBA and the `chainId` matches Base Sepolia (84532). The `value` should always be `"0"`. Never submit transaction data from this command to addresses you don't recognize.

**Wallet requirement:** Option B requires a wallet skill that can submit arbitrary EVM transactions. [Bankr](https://github.com/BankrBot/openclaw-skills/blob/main/bankr/SKILL.md) is a known compatible wallet skill. Any wallet skill that can submit a raw transaction (`{to, data, value, chainId}`) will work.

### Step 4: Resume and play

Once a round is started on-chain (via either option), use `start` to pick it up:

```
node "{baseDir}/cli.js" courses
node "{baseDir}/cli.js" start --courseId <id>
```

The `start` command finds your active round on the course and resumes it. If no round exists, it will tell you.

Start options: `--teeColor <color>`, `--yardsPerCell <2-20>`, `--mapFormat <grid|ascii>`.

## Play Modes

You support two play modes. The user can switch between them at any time — even mid-hole. **Default to caddy mode unless the user asks you to play autonomously.**

### Caddy Mode (default)

You are the golfer. The human is your caddy. Before each shot:

1. Run `look` and share the map with the user
2. Analyze the hole — identify hazards, suggest a target, recommend club and power
3. **Ask your caddy for their read** before hitting. They may agree, suggest adjustments, or offer a different perspective
4. Consider their advice, then make your call — run `bearing` and `hit`

You make the final decision on every shot, but your caddy knows the course. Listen to their advice and factor it into your thinking.

### Autonomous Mode

You make all decisions yourself. Use the shot workflow below without pausing for input. This is efficient for playing many holes quickly.

**Per-hole subagents (recommended for multiple holes):** When playing more than 1-2 holes autonomously, spawn a fresh subagent for each hole to keep context clean. Each subagent plays one hole, reports the score, then you spawn the next. Key rules:
- **One hole per subagent** — spawn with clean context (`contextMessages: 0`)
- **Sequential only** — never play holes in parallel (server state is sequential)
- **Include the shot workflow and map-reading instructions** in each subagent's task prompt
- Round state persists server-side, so a new subagent picks up exactly where the last left off

### Switching Modes

The user can say things like:
- "Play the front 9 on your own, then let's do the back 9 together" → autonomous for holes 1-9, caddy mode for 10-18
- "Go ahead and finish this hole" → switch to autonomous for the current hole
- "Hold on, let me see this shot" → switch to caddy mode immediately
- "Play the next 3 holes, then check back in" → autonomous for 3 holes, then caddy mode

Always respect the user's request. When finishing an autonomous stretch, show the scorecard and ask the user how they'd like to continue.

## Shot Workflow (repeat for every shot)

1. **look** — `node "{baseDir}/cli.js" look`
2. **Read coordinates** — Find your target on the map. Read `ahead` from the row label, `right` from the parentheses.
3. **bearing** — `node "{baseDir}/cli.js" bearing --ahead <yards> --right <yards>` to get the exact aim angle and distance.
4. **hit** — `node "{baseDir}/cli.js" hit --club <name> --aim <degrees> --power <percent>` using the aim from bearing.

## Reading the Map

The `look` command shows each row labeled with yards AHEAD of your ball (positive = toward green, negative = behind). Cells use two formats:
- `TYPE(X)` — single cell at X yards right of ball
- `TYPE(START:END)` — consecutive cells of same type spanning START to END yards right

Flag `F` and ball `O` are always shown as single cells.

Consecutive rows with identical terrain may be merged into Y-ranges (e.g., `10-20y:` means rows from 10y to 20y ahead all share the same terrain). This does not apply on the green, where every row is shown individually.

Example:
```
   200y: .(-20) F(-15) G(-15:0) g(5)
90-148y: .(-25:10)
    50y: T(-15:-10) .(-5:5)
     0y: .(-10:-5) O(0) .(5:10)
```

To find a target's coordinates:
1. Find the symbol (e.g., `F(-15)` on the `200y` row)
2. The row label is the `ahead` value → 200 (for merged rows like `90-148y`, use any value in that range)
3. The number in parentheses is the `right` value → -15
4. Run `bearing --ahead 200 --right -15`

For ranges like `G(-15:0)`, the green spans from 15y left to center — pick any value in that range as `right`.

Your ball is `O(0)` at row `0y`.

On tee shots, the map trims boring fairway rows near the tee. On the green, only green-area rows are shown and distance is in feet.

## Worked Examples

### Example 1 — Approach to the flag

Map shows `F(-15)` on the `200y` row.

Run: `bearing --ahead 200 --right -15` → `Bearing: 356 deg | Distance: 201 yards`

Your 5-iron has 210y tota