Skip to content
ChessX AI

AI Onboarding

       ♜  ♞  ♝  ♛  ♚  ♝  ♞  ♜
    ═════════════════════════════════════
          AI  ONBOARDING  ·  ChessX
    ═════════════════════════════════════
       ♟  ♟  ♟  ♟  ♟  ♟  ♟  ♟

Fast-path guide for engineers using AI tooling on ChessX. Audience: chess-engine contributors using Claude Code + Matt Pocock’s skill repository. Terse by design; depth lives in linked docs.

Live monorepo: chessx-mr (sibling). Open it alongside this guide; references below name files conceptually rather than by full path.

♟ 0. Context (the why)

Section titled “♟ 0. Context (the why)”
  • ChessX — multi-process chess platform. Active codebase is the chessx-mr monorepo (Turborepo + pnpm). Sibling folders are archival.
  • chess-engine — Python 3.12 Flask service wrapping Stockfish + python-chess, Dockerized. The chess-engine app inside the monorepo. This is what Gideon owns.
  • CONTEXT.md — per-app, hand-curated product/domain context. Agents read these first. Two exist: the root product CONTEXT.md and the chess-engine/CONTEXT.md. Map is CONTEXT-MAP.md. Why two: one is product, one is engine; mixing rots both.
  • Pocock’s skills — small, composable agent skills used as slash commands in Claude Code (/triage, /grill-with-docs, /tdd, /diagnose, /qa, /to-issues, /to-prd, /improve-codebase-architecture). Why: they fix three recurring agent failures — misalignment, sloppy testing, no pre-PR check. Not a framework; copy and adapt.

Monorepo map:

AppStackYou touch?
apps/serverNode 22, Express, Socket.IO, MongooseNo
apps/adminReact 19 + ViteNo
apps/mobileReact Native 0.84 + Expo 55No
apps/chess-enginePython 3.12, Flask, StockfishYes

♜ 1. Before you code (one-time setup)

Section titled “♜ 1. Before you code (one-time setup)”

Repo prerequisites (Node 22, pnpm ≥9, Docker, env files) live in the monorepo README — follow it; don’t duplicate. Engine-only smoke test once installed:

Terminal window
pnpm --filter @chessx/chess-engine dev    # builds + runs the engine container
curl http://localhost:8000/                # health

Then layer the AI workflow on top:

Terminal window
# 1. Install Claude Code if not present
#    https://docs.claude.com/en/docs/claude-code


# 2. Add Pocock's skills (interactive picker)
npx skills@latest add mattpocock/skills


# 3. Run setup — asks issue tracker, labels, doc location
/setup-matt-pocock-skills

Verify: /triage, /grill-with-docs, /tdd, /qa autocomplete in a fresh Claude Code session inside chessx-mr/.

Section titled “1a. Status line (recommended)”

Two-piece status line — git state on the left, context-window % on the right. Cheap signal, big quality-of-life win once you have it. Full setup (settings.json + two shell scripts): docs/ccstatusline-setup.md.

1b. Arun’s LINKING.md system (optional, for iterating on skills)

Section titled “1b. Arun’s LINKING.md system (optional, for iterating on skills)”

Pocock’s skills are upstream-managed but you’ll want to tweak. Forking the world is heavy; a per-machine symlink manifest is light. Pattern:

  • One canonical clone of pocock-skills per host.
  • links.local.toml declares which skills get symlinked into ~/.claude/skills.
  • Mix upstream skills + private skills without divergence.

Companion refs:

  • docs/LINKING.md — full protocol, safety, reporting.
  • docs/links.example.toml — starter manifest.
Terminal window
cd ~/repos/pocock-skills
cp links.example.toml links.local.toml   # gitignored
# edit, then your linker script reconciles

♞ 2. Before each task (intake)

Section titled “♞ 2. Before each task (intake)”
  1. /triage — read the issue, classify, apply a label from the monorepo’s triage-labels doc (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix).
  2. /grill-with-docs — extract requirements before writing code. The skill asks until alignment is reached. This is the single highest-leverage habit — agents ship the wrong thing more often than they ship buggy thing.
  3. Re-read the root + chess-engine CONTEXT.md. Cheap; rarely changes.

♝ 3. While coding

Section titled “♝ 3. While coding”
  • /tdd — test-first loop. Especially load-bearing for engine work (legal-move correctness, eval boundaries, FEN parsing).
  • /diagnose — when stuck on a failing test or unexpected behaviour. Faster than ad-hoc print.
  • Permission modes — cycle with Shift + Tab: Normal → Plan → Auto-accept edits → Bypass. Detail + when-to-use: docs/claude-code-modes.md.
  • Hygiene — no comments, no stray logs, no untracked TODOs in source (TS/JS/Python). Full rules in the monorepo’s code-hygiene doc. The repo enforces; don’t fight it.

♛ 4. Before PR (close-out)

Section titled “♛ 4. Before PR (close-out)”
Terminal window
# from repo root
pnpm typecheck && pnpm lint && pnpm test
  • /qa — pre-PR check; catches what /tdd missed.
  • Re-label issue (ready-for-human for review, etc.) per the triage-labels doc.

♚ 5. References (covered)

Section titled “♚ 5. References (covered)”

Videos — durations TBD; fill as watched.

SourceTitleDuration
Matt Pocock (AI Hero)Claude Code for Real Engineers Office Hours, Apr 10TBD
Matt Pocock (AI Hero)Building a REAL feature with Claude Code: every step explained (Mar 2026)TBD
Dex Horthy (HumanLayer)No Vibes Allowed: Solving Hard Problems in Complex CodebasesTBD
AI LABS12 Hidden Settings To Enable In Your Claude Code SetupTBD

Articles:

In sibling repos:

  • Pocock skills clone — read each skill’s SKILL.md.
  • chessx-mr agent docs — docs/agents/ (issue-tracker, triage-labels, domain, code-hygiene).
  • chessx-mr context — root CONTEXT.md, CONTEXT-MAP.md, chess-engine/CONTEXT.md.

In this repo (docs/):

  • LINKING.md, links.example.toml — symlink-manifest pattern.
  • ccstatusline-setup.md — status-line wiring.
  • claude-code-modes.md — Shift+Tab permission modes.

♟ 6. Refs not yet covered (parking lot)

Section titled “♟ 6. Refs not yet covered (parking lot)”

Worth a look later; not required for chess-engine work.