Ground live agent answers in project context (AGENTS.md/CLAUDE.md)

[alexkroman]

The live agent now reads the launch directory's AGENTS.md or CLAUDE.md into its system prompt, grounding spoken answers in the project it's run from — following the same convention coding agents use.

Changes

• New module aai_cli/agent_cascade/project_context.py: Loads project instruction files with deduplication (identical content included once) and truncation (capped at 16KB so oversized files don't crowd the conversation). Reads AGENTS.md first (higher precedence), then CLAUDE.md, defaulting to the current working directory.

• Updated aai_cli/agent_cascade/prompt.py: build_system_prompt() now accepts an optional project_context parameter and appends it as project background when present, introduced with a heading so the model treats it as grounding rather than another instruction to recite.

• Updated aai_cli/agent_cascade/brain.py: Threads project_context from the cascade config into the system prompt when building the agent graph.

• Updated aai_cli/agent_cascade/config.py: Added project_context field to CascadeConfig to carry the loaded instruction file through the cascade pipeline.

• Updated aai_cli/commands/agent_cascade/_exec.py: run_agent_cascade() calls load_project_context() and passes it to the config before building the cascade engine.

• Updated REFERENCE.md: Documented the new behavior, noting that it's independent of --files and not reflected in --show-code output.

• Comprehensive test coverage:

  • tests/test_agent_cascade_project_context.py (new): Tests the loader's file reading, deduplication, truncation, and edge cases.
  • tests/test_agent_cascade_prompt.py: Tests system prompt integration with and without project context.
  • tests/test_agent_cascade_brain.py: Tests that project context flows into the built graph's system prompt.

Implementation details

• Identical file content (e.g., CLAUDE.md symlinked to AGENTS.md) is deduplicated on content, not filename, so it works across platforms without depending on symlink support.
• Whitespace-only files are treated as absent (return None, not an empty heading).
• The truncation marker [project context truncated] signals to the model when it's seeing only the head of an oversized file.
• The feature is always active when instruction files are present; it's not gated by --files or any other flag.

https://claude.ai/code/session_01QegBRMt1QU2LRvbEMyCdiT