servalsheets: Instructions file for Claude Code

Claude Code Rules (ServalSheets)

Size cap: 300 lines. If this file exceeds 300 lines, move content to docs/. Architecture reference: docs/development/ARCHITECTURE.md

Live State & Session Context

Live project state (auto-generated): @.serval/state.md

Load on demand — do NOT auto-load these large files:

• Session notes (20KB): .serval/session-notes.md — read only the section matching current task
• Codebase context (80KB+): docs/development/CODEBASE_CONTEXT.md — load only handler/service section matching current module
• Feature roadmap (40KB+): docs/development/FEATURE_PLAN.md — load only the section for current feature
• Dispatch map (JSON): .serval/routing-map.json — query by tool.action key (e.g. sheets_data.read)

Project Overview

ServalSheets is a production-grade MCP server for Google Sheets with 25 tools and 410 actions. Runtime: Node.js + TypeScript (strict). See src/schemas/index.ts for authoritative counts.

Core Pipeline

MCP Request → src/server.ts:handleToolCall()
  → src/mcp/registration/tool-handlers.ts:createToolCallHandler()
    → normalizeToolArgs() → Zod validation → handler.executeAction()
      → src/services/google-api.ts (auto-retry + circuit breaker)
    → buildToolResponse() → CallToolResult

Full 4-layer trace with line numbers: docs/development/ARCHITECTURE.md

Non-negotiable Workflow

1. Verify before claiming — every fact needs file:line OR command → output
2. Trace execution paths — prove reachability from entrypoint (STDIO/HTTP/Remote)
3. No "fixes" without failing proof — reproduce with script or failing test first
4. Minimal change policy — ≤3 src/ files unless tests require more; no refactors while debugging
5. No silent fallbacks — never return {} without logging; use ErrorCode enum
6. Dead code claims need proof — run npm run validate:dead-code <file> <start> <end>
7. Schema-handler alignment — run npm run validate:alignment; deviations must be in src/schemas/handler-deviations.ts
8. Audit docs must validate — npm run validate:audit with .github/AUDIT_TEMPLATE.md format