Files
chess-endgame-trainer/AGENTS.md
T

3.3 KiB
Raw Blame History

Phoenix 1.8 web app — an endgame trainer. LiveView 1.2, Ecto/Postgres, chessground for board rendering. Modules are Chesstrainer and ChesstrainerWeb.

Graft — repo context graph

This repo is indexed in graft/: small linked markdown nodes that explain each system and carry exact file:line spans, kept in sync with the code through git.

For ANY task here — understanding how something works, finding where code lives, or scoping a change — get context from the graph before grepping or opening source files. Re-ask freely (it's cheap) and reuse literal identifiers you already have (symbol, error string, file name) as the query. New to this repo? Run graft map first — a token-budgeted orientation (dir clusters, hubs, hotspots), no LLM, no key.

  • Run graft ask "<your question>" --source → ranked nodes with the relevant code spans inlined (each hit's ≤8-line crux by default; --full for whole definitions when the crux isn't enough). Match the tool to the task shape: for understanding or editing, the top node IS the answer — cite its covers: file:line spans and edit straight from --source. For exhaustive tasks ("every occurrence / every caller of this pattern"), ranked results are top-N, not complete — run graft grep "<literal>" instead (exhaustive over indexed files, grouped by enclosing symbol), falling back to raw grep -rn only for unindexed files.
  • graft skeleton <file> → every definition's signature + span, ~10× cheaper than reading the file; use it to skim an API surface.
  • graft callers <symbol> gives precomputed, exact edges — who calls this. Add --direction out for what it calls, or --depth N to walk transitively for the full blast radius. For structural questions, skip ranking and use this directly.
  • Or browse: graft/INDEX.md lists every node; follow the links.
  • Monorepos and folders of multiple repos rank fairly across sub-projects — hits carry [scope/] labels naming which one they're from. Narrow with graft ask "<task>" --in <scope>/ once you know where you're working.

If a returned span is truncated ("+N more lines"), open the file at that exact range before finalizing. Only open source files when a node genuinely lacks a needed detail, and then at the exact file:line the node points to — never re-read whole files.

After big code changes, refresh the graph with graft build (deterministic, no API key, $0).

Coding standards

Read CODING_STANDARDS.md before writing code. Read the section for the layer you're touching: Elixir, Ecto, Phoenix, HEEx, LiveView, Forms, Assets, or Testing.

Done

Run mix precommit and fix what it flags.

Type-check risky changes with mix dialyzer (not part of mix precommit; the first run builds a PLT and is slow).

Agent skills

Issue tracker

Issues live in GitHub Issues for TheRealOwenRees/chess-endgame-trainer, driven by the gh CLI. See docs/agents/issue-tracker.md.

Triage labels

The five canonical triage roles, each label string equal to its name (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). See docs/agents/triage-labels.md.

Domain docs

Single-context: GLOSSARY.md and docs/adr/ at the repo root. See docs/agents/domain.md.