NakshAstraMCP — Agent Instructions (v3.20.0)

This file is automatically provisioned in your workspace root by nakshastramcp start --workspace .. It instructs AI coding assistants to use NakshAstraMCP tools efficiently and safely.

MANDATORY: Always prioritize MCP tools over manual file-dumps or generic shell commands.

🛠️ MCP Capabilities (Ground Truth)

Tool	Priority	Usage Instruction
`deep_context`	🥇 Primary	Start here for all tasks. Locates files and adds their immediate graph neighbors (1-hop) for structural context. Strongly prefer over scattered `search_codebase` calls.
`search_codebase`	🥈 Discovery	Broad “grep-style” keyword search when you lack a specific entry point.
`find_symbol`	🥉 Surgical	Precise lookup for classes/functions by name. Use for “Go to Definition.”
`read_file`	📖 Verification	MANDATORY before any edit. Read the target block using `start_line`/`end_line` to avoid assumptions. Use `if_changed_since=<hash>` on re-reads to skip unchanged files (saves 100% tokens).
`find_references`	🔎 Audit	Trace call-sites (blast-radius) before changing custom functions. Avoid on standard library utilities to save tokens.
`generate_report`	🗺️ Map	Produce a macro-level architectural report of the workspace.
`server_status`	🩺 Diagnostic	Use only if indexing or memory issues are suspected.

📂 Workspace Artifacts

NakshAstraMCP generates architectural insights in:

nakshastra-out/
├── NAKSHASTRA_REPORT.md   ← Architectural walkthrough: PageRank hubs, Louvain clusters, blast-radius warnings
└── graph.json             ← Raw symbol relationship graph (JSON), renderable in external diagram tools

Always check NAKSHASTRA_REPORT.md first for macro architectural context before starting complex tasks.

🔄 Standardized Workflow

Follow this pattern for every non-trivial task:

1. generate_report   (Optional) → Read NAKSHASTRA_REPORT.md for macro context
         │
2. deep_context      → Discover relevant files + 1-hop architectural neighbors
         │
3. find_symbol       → Locate the exact definition (line range) for the target logic
         │
4. read_file         → Read the target code block (with enclosing context) BEFORE editing
         │
5. find_references   → Audit call sites of custom functions BEFORE making changes

🛡️ Guardrails

[!IMPORTANT] Violating these rules causes inefficiency, bugs, and wasted tokens.

Rule	Detail
❌ No Snippet Assumptions	Snippets are for discovery only. Never assume a full definition from a snippet — always use `read_file` with line ranges.
❌ No Full File Dumps	Never read an entire file into context if a specific line range meets the requirement.
❌ No Terminal MCP Execution	Never attempt to run MCP tools as shell commands (e.g., `nakshastramcp_generate_report`). Call them strictly via the MCP tool protocol.
✅ Verification First	Never edit code you haven’t read in its local context via `read_file`.
✅ Blast-Radius Audit	Always run `find_references` on custom functions before modifying their signatures.
✅ Tool Efficiency	Prefer `deep_context` for multi-file discovery over scattered `search_codebase` calls.
✅ Truncate Log Reads	When analyzing logs, focus on relevant failure stack traces or tail lines only — never read entire log streams.
✅ Security Protocols	All paths are jailed. If a tool fails with a security error, verify the path is inside a registered workspace.

🏠 Home · 📖 User Guide · 🎯 MCP-First Skill Profile