Skip to content

AGENTS.md

Latest commit

 

History

History
110 lines (84 loc) · 4.49 KB

AGENTS.md

File metadata and controls

110 lines (84 loc) · 4.49 KB
Raw

Agent Instructions

Project context (architecture, commands, conventions, tests) is in CLAUDE.md. This file holds the rules for every coding agent working in this repository.

Non-Interactive Shell Commands

cp, mv and rm may be aliased with -i on some systems, which leaves an agent waiting for a y/n answer that never comes. Always pass the non-interactive flag:

cp -f source dest
mv -f source dest
rm -f file
rm -rf directory
cp -rf source dest

Other commands that may prompt: scp and ssh (-o BatchMode=yes), apt-get (-y), brew (HOMEBREW_NO_AUTO_UPDATE=1).

Beads Issue Tracker

This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work

Rules

  • Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
  • Run bd prime for detailed command reference and session close protocol
  • Use bd remember for persistent knowledge — do NOT use MEMORY.md files

Session Completion

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

  1. File issues for remaining work - Create issues for anything that needs follow-up
  2. Run quality gates (if code changed) - Tests, linters, builds
  3. Update issue status - Close finished work, update in-progress items
  4. PUSH TO REMOTE - This is MANDATORY: 
    git pull --rebase
bd dolt push
git push
git status  # MUST show "up to date with origin"
  5. Clean up - Clear stashes, prune remote branches
  6. Verify - All changes committed AND pushed
  7. Hand off - Provide context for next session

CRITICAL RULES:

  • Work is NOT complete until git push succeeds
  • NEVER stop before pushing - that leaves work stranded locally
  • NEVER say "ready to push when you are" - YOU must push
  • If push fails, resolve and retry until it succeeds

MCP Tools: code-review-graph

This project has a knowledge graph. Start with the code-review-graph MCP tools to narrow scope, then read the source. The graph is cheaper than scanning files and gives you structural context (callers, dependents, test coverage) that file search cannot.

When to use graph tools FIRST

  • Exploring code: semantic_search_nodes_tool or query_graph_tool instead of Grep
  • Understanding impact: get_impact_radius_tool instead of manually tracing imports
  • Code review: detect_changes_tool + get_review_context_tool instead of reading entire files
  • Finding relationships: query_graph_tool with callers_of/callees_of/imports_of/tests_for
  • Architecture questions: get_architecture_overview_tool + list_communities_tool

Verify in the source

  • Narrow scope with the graph, then read the source. Do not change code from graph output alone.
  • For any non-trivial change, read the implementation and the relevant tests before concluding.
  • Verify the exact source when touching behavior, database logic, migrations, retries, fallbacks, recovery, or compatibility code.
  • When the graph and the source disagree, the source wins. The graph may be stale or may not model that relationship.
  • An empty graph result can mean "not indexed" or "not statically visible", not "does not exist".

Key Tools

Tool Use when
detect_changes_tool Reviewing code changes — gives risk-scored analysis
get_review_context_tool Need source snippets for review — token-efficient
get_impact_radius_tool Understanding blast radius of a change
get_affected_flows_tool Finding which execution paths are impacted
query_graph_tool Tracing callers, callees, imports, tests, dependencies
semantic_search_nodes_tool Finding functions/classes by name or keyword
get_architecture_overview_tool Understanding high-level codebase structure
refactor_tool Planning renames, finding dead code

Workflow

  1. The graph auto-updates on file changes (via hooks).
  2. Use detect_changes_tool for code review.
  3. Use get_affected_flows_tool to understand impact.
  4. Use query_graph_tool pattern="tests_for" to check coverage.