gantry: Skill for Claude Code

Adding a Routine — Gantry Server

1. What a routine is

A routine is a scripted state machine that runs a full multi-step game sequence (travel → dock → sell, or check-fleet → jump → verify-arrival) without LLM inference per step — the whole sequence executes server-side and returns one result. They cut cost by avoiding an LLM round-trip per game action.

18 routines exist today (server/src/routines/routine-runner.ts, BUILTIN_ROUTINES): sell_cycle, mining_loop, refuel_repair, patrol_and_attack, mission_run, mission_check, navigate_and_mine, craft_and_sell, explore_system, salvage_loop, full_trade_run, supply_run, navigate_home, explore_and_mine, manage_storage, upgrade_ship, fleet_refuel, fleet_jump.

Stale doc warning: the execute_routine unknown-routine error message in server/src/proxy/gantry-v2.ts (~line 830) hard-codes a 13-name list that is missing manage_storage, navigate_home, explore_and_mine, fleet_refuel, fleet_jump. Don't treat that error string as the source of truth — always call getAvailableRoutines() (or read BUILTIN_ROUTINES) for the real list. If you touch that error message while adding a routine, fix the list too.

Canonical examples to copy:

• Simple, single-destination: server/src/routines/sell-cycle.ts + sell-cycle.test.ts (14 tests) — travel/dock, market analysis, retry-on- not_docked, early-abort-on-no-demand.
• Fleet-coordination style (no travel/dock): server/src/routines/fleet-jump.ts — checks spacemolt_fleet(action="status"), hands off if members are scattered, jumps, re-verifies via a second fleet-status call.

2. Module shape

New file: server/src/routines/<name>.ts. Test: server/src/routines/<name>.test.ts (co-located, bun:test). Every routine implements RoutineDefinition<TParams> from server/src/routines/types.ts:

export interface RoutineDefinition<TParams = Record<string, unknown>> {
  name: string;                    // e.g. "sell_cycle" — must match ROUTINE_REGISTRY key
  description: string;             // shown to agents
  parseParams(raw: unknown): TParams;   // validate + parse, throw Error on bad input
  run(ctx: RoutineContext, params: TParams): Promise<RoutineResult>;
}