ai-maestro-code-graph-query

AI Maestro Code Graph Query

CRITICAL: AUTOMATIC BEHAVIOR - READ THIS FIRST

THIS IS NOT OPTIONAL. THIS IS YOUR DEFAULT BEHAVIOR.

Every time you use the Read tool on a code file, you MUST IMMEDIATELY query the graph to understand:

• What is this component/function?
• What depends on it? (callers, serializers, child classes)
• What does it depend on? (callees, parent classes, associations)

DO NOT:

• Wait for the user to ask you to query the graph
• Skip the graph query because "it seems simple"
• Assume you understand the impact without checking
• Make changes before understanding dependencies

ALWAYS:

• Query the graph IMMEDIATELY after reading any code file
• Query BEFORE making any modifications
• Query when you find files via search (grep/glob)
• Include graph findings in your analysis to the user

The Rule: Read File → Query Graph → Then Proceed

1. You read a file with Read tool
2. IMMEDIATELY run graph queries (describe, find-callers, find-serializers, etc.)
3. NOW you understand the full context
4. NOW you can analyze, modify, or discuss the code

Example - Reading a Model:

# After reading app/models/user.rb, IMMEDIATELY run:
graph-describe.sh User
graph-find-serializers.sh User
graph-find-associations.sh User

Example - Reading a Function:

# After reading a file with process_payment function, IMMEDIATELY run:
graph-find-callers.sh process_payment
graph-find-callees.sh process_payment

Available Commands

All commands auto-detect your agent ID from the tmux session. Just run them:

Query Commands

Indexing Commands

Delta Indexing (New)

When files change in your codebase, use delta indexing to quickly update the graph:

# Delta index - only process changed files
graph-index-delta.sh

# Delta index a specific project
graph-index-delta.sh /path/to/project

First Run Behavior:

• First time: Does a full index + initializes file tracking metadata
• Subsequent runs: Only indexes new/modified/deleted files

Output shows:

• New files added
• Modified files re-indexed
• Deleted files removed
• Unchanged files skipped

Performance:

• Full index: 30-120 seconds (1000+ files)
• Delta index: 1-5 seconds (5-10 changed files)

What to Query Based on What You Read

Why This Matters

Without querying the graph, you will:

• Miss serializers that need updating when you change a model
• Break callers when you change a function signature
• Miss child classes that inherit your changes
• Overlook associations that depend on this model

The graph query takes 1 second. A broken deployment takes hours to fix.

Component Types

Use with graph-find-by-type.sh:

• model - Database models
• serializer - JSON serializers
• controller - API controllers
• service - Service objects
• job - Background jobs
• concern - Shared modules
• component - React/Vue components
• hook - React hooks

Error Handling

Script not found:

• Check PATH: which graph-describe.sh
• Verify scripts installed: ls -la ~/.local/bin/graph-*.sh
• Scripts are installed to ~/.local/bin/ which should be in your PATH
• If not found, run: ./install-graph-tools.sh

API connection fails:

• Ensure AI Maestro is running: curl http://localhost:23000/api/agents
• Ensure your agent is registered (scripts auto-detect from tmux session)
• Check exact component names (case-sensitive)

Graph is unavailable:

• Inform the user: "Graph unavailable, proceeding with manual analysis - increased risk of missing dependencies."

Installation

If commands are not found:

./install-graph-tools.sh

This installs scripts to ~/.local/bin/.