Code navigation

This repo has a CodeGraph index (symbols, calls, imports for the Python server and the TS/React UI), exposed as the codegraph MCP server (.mcp.json, .vscode/mcp.json).

• To find callers, callees, or the blast radius of a symbol, or to explore an unfamiliar area, use codegraph_explore before reading files or grepping.
• Several symbols share names (for example _clean_title exists in both server/services/tickets.py and server/services/docs.py); the results list each definition separately, so check the file before editing.
• If the MCP tool is not available, use the same index from the shell: .claude/scripts/codegraph.sh run callers <symbol> (also callees, impact, query, node, context).
• The index is local (.codegraph/, git-ignored) and is synced by .claude/scripts/codegraph.sh; the CLI version is pinned there.

Subagents and models

Do not spawn subagents by reflex. Each one costs tokens, often has to gather context you already have, and loses detail in the handoff. A subagent gives you parallelism, a clean context or a fresh pair of eyes, not a smarter answer.

• Do it yourself when the task is quick: a handful of tool calls, a lookup whose target you already know, one edit, or a check you can run inline.
• Delegate only when it pays: a wide search or a long test run whose output would otherwise fill your context, independent pieces that can run in parallel, or a review by an agent that has not seen how the code was written.
• Split by context, not by type of work. Good cuts: independent search paths, components with clean interfaces, checking a finished result. Do not chain agents by role (plan → implement → test → review), and do not split sequential steps of one change or tightly coupled code; do those yourself.
• At most 3 subagents at a time. If there are more pieces, run them in waves or do the small ones yourself. If the user asked for a specific number, spawn exactly that many.
• Brief each one fully: the goal, the files, what is already ruled out, and what done looks like. No two agents edit the same files, and none waits on another's result. Ask for a short summary back, not raw output.
• Check what comes back before relying on it, and do not redo a delegated task yourself. A verifier must run every test related to the change (see Tests below, not just one or two), check against concrete criteria, and report only what affects correctness, not style.

Pick the model and effort for each subagent from the task, not by default:

• Start cheap and escalate on evidence. Raise the effort first and the model second, and only when a cheaper run came back wrong or thin. When the result can be checked (tests, a verifier), run at low effort and re-run only the failures at high.
• Keep max for a hard problem worked through without the user (a security hunt); on ordinary work it overthinks.
• An escalation agent is a consultant: give it the code and the facts, ask for a recommendation, and do the implementation yourself (or with a cheaper agent) once the way forward is clear.

Tests

Run only the tests related to what you changed, never the whole suite (it is slow, and some tests fail in a cloud container for reasons that have nothing to do with the change). Related means:

• the test files of the modules you changed, and the suites that exercise them (for a change in server/services/docs*.py or the Docs MCP tools: tests/test_docs*.py; for the MCP tool list or instructions: tests/test_mcp_tool_quality.py; for the board's skills: tests/test_shared_skills_277.py; for the AI team (services/ai): tests/test_ai_teams.py, tests/test_ai_runs_v2.py, tests/test_ai_launch_v2.py, tests/test_runner.py and the tests/test_ai_*_v2.py of the module you changed);
• in ui/, npx vitest run <the folders you changed> plus npx tsc --noEmit -p ., eslint and prettier on the files you touched;
• in desktop/, npm test when you changed desktop/.

A test that starts a process (a real server, the AI runner) must give it its own KANBAN_CONFIG_DIR and KANBAN_DB_PATH: tests/conftest.py exports temporary ones, never remove that. Without them the process opens the database named in the developer's ~/.kanban-board/config.json and migrates it.

Find the related suites with CodeGraph (callers, impact) or a grep for the module's name in server/tests and the *.test.ts(x) files. Say in the PR which suites you ran. Run the whole suite only when the user asks for it.

Pull requests

Every pull request you create gets an assignee and labels. If the tool that creates it cannot set them (the GitHub MCP create_pull_request cannot), set them right after with issue_write (method: update, the PR number as issue_number):

• Assignee: iamcaominhtien.
• Labels: every label that fits, from the repo's existing labels first. If none of them fits, create a new one (short, lowercase, in the style of the existing ones) and use it.
  • bug: fixes broken behavior.
  • enhancement: a new feature, an improvement, or a chore or CI change.
  • documentation: design docs, guides, README or other docs.
  • dependencies: adds, removes or bumps a dependency (pyproject.toml/uv.lock, package.json/lockfiles).