gantry: Skill for Claude Code

Adding an API Route — Gantry Server

1. Where the file goes

New route module: server/src/web/routes/<name>.ts. Test: server/src/web/routes/<name>.test.ts (co-located).

Canonical example to copy: server/src/web/routes/directives.ts + directives.test.ts — simple CRUD over one service module, clean auth story, in-memory DB test. For an SSE example, copy server/src/web/routes/status.ts (GET /stream) or read server/src/web/routes/sse.test.ts / agent-stream.test.ts.

Stale doc warning: AGENTS.md (both root and server/) says "register in ROUTE_REGISTRATIONS in route-config.ts". That file does not exist. The real registration point is server/src/web/routes/api-routes.ts, which manually mounts every sub-router with router.use(...) inside createApiRoutes(). Two source comments (map.ts, credentials.ts) still say "route-config" too — ignore them, they're leftover from a prior refactor.

2. Two router shapes

Pick based on whether the route needs shared state / DB deps at construction time:

A. Plain router, default export — no constructor args, imports its own service functions directly (notes.ts, directives.ts, comms.ts, tool-calls.ts):

import { Router } from 'express';
import { validateAgentName } from '../config.js';
import { getFoo, createFoo } from '../../services/foo-db.js';

const router: Router = Router();

router.get('/:name', (req, res) => {
  const name = req.params.name;
  if (!validateAgentName(name)) {
    res.status(404).json({ error: 'Unknown agent' });
    return;
  }
  res.json(getFoo(name));
});

export default router;

B. Factory function — needs sharedState slices, sessions, config, etc. injected (status.ts, market.ts, game-state.ts, accounts.ts):

export function createFooRouter(statusCache: Map<string, AgentStatus>, config: GantryConfig): Router {
  const router: Router = Router();
  router.get('/', (_req, res) => res.json([...statusCache.values()]));
  return router;
}