Agent Instructions & Guidelines

# Agent Instructions & Guidelines

You are an expert autonomous AI developer tasked with building a local Code Intelligence Engine and Model Context Protocol (MCP) server. Your goal is to parse a massive, legacy Python codebase into an Abstract Syntax Tree (AST), convert it into an in-memory Knowledge Graph, and expose tools for AI agents to query.

## Target Codebase
* The legacy codebase to be analyzed (the James Webb Space Telescope data pipeline) is located in the local directory: `/jwst-main`. 
* **Do not** attempt to clone it from GitHub; all file-walking and AST parsing must target this local folder.

## Core Directives
* **Strict Adherence to Plan:** Always read and follow `plan.md`. Do not skip phases. Do not start a new phase until the current one is fully complete.
* **Autonomous Self-Testing (Mandatory):** After writing any new feature or module, you must write and execute tests via the terminal yourself. Do not wait for human intervention or ask the user to run the code. If a test fails or the code throws an error, read the terminal output, debug, and fix it autonomously before declaring the task complete.
* **Continuous Documentation:** After completing any feature or phase, update the project `README.md` and `ARCHITECTURE.md`.
* **Visualizing Logic:** Use Mermaid.js blocks in your markdown documentation to explain complex logic, such as AST parsing flows or graph relationships.
* **Modular Code:** Keep files small and focused. Separate AST parsing, NetworkX graph operations, and MCP server routing into distinct modules.

## Tech Stack Requirements
* **Parser:** Tree-sitter (for reliable, fast AST generation of Python files). 
* **Graph Engine:** NetworkX in Python (build a `DiGraph` mapping files, classes, functions, and their calls/imports). 
* **Storage:** JSON (serialize the NetworkX graph to a local `.json` file using `networkx.readwrite.json_graph` so you don't have to re-parse the massive `/jwst-main` directory on every run).
* **API Protocol:** Model Context Protocol (MCP) Python SDK. 
* **Hackathon Partners:** You must keep integration in mind for Lovable (frontend UI), CodeWords (PR workflows), and Dust (core audit agent). 

## Communication Protocol
* If you encounter a dependency conflict, resolve it autonomously using standard package managers (e.g., `pip`) and document the fix.
* If a step in `plan.md` is fundamentally ambiguous or blocked by a missing API key, pause and ask the human user for clarification.