AGENTS.md git:20261024.2ef062dA

Immutable. This exact content never changes and is served at /api/v1/blob/b7e69775875485fe.

# Graph-It-Live Agent Guide

VS Code extension, standalone CLI, and MCP server for dependency and call-graph analysis. Requires Node.js 22+ and npm.

## Commands

- Build: `npm run build`; one test: `npx vitest run <test-file>`; unit suite: `npm test`.
- Quality: `npm run lint`, `npm run check:types`, `npm run test:coverage`; E2E: `npm run test:vscode`.
- Package: `npm run package && npm run package:verify`.

Prefix shell commands with `rtk`; use `rtk proxy <command>` when no optimized wrapper exists.

## Core Principles

- **Simplicity First:** make every change as simple as possible with minimal code impact.
- **No Laziness:** find root causes; do not use temporary workarounds.
- **Minimal Impact:** change only what is necessary and avoid introducing unrelated risk.

## Universal Rules
- Keep `src/analyzer/**` and `src/mcp/**` Node.js-only: never import `vscode`.
- Keep imports compliant with `graphit.architecture.json`: run `graph-it check-architecture` after source changes (0 violations, 0 unmatched files). New `src/` folder or layer relationship = update that config in the same change; never weaken a rule to pass.
- Define extension↔webview messages in `src/shared/types.ts`; update sender and receiver together.
- Build paths with `node:path`; call `normalizePath()` before path keys enter Sets or Maps.
- Keep TypeScript strict. Avoid `any`; ESLint decides style.
- New functions/modules need success and edge/failure unit tests. User-facing behavior also needs VS Code E2E coverage. Touched files must stay at or above 80% coverage.
- Never delete empty maps eagerly in `ReverseIndex.removeDependenciesFromSource()`; cleanup is query-time to avoid re-index races.
- Build/dependency/package changes require production package validation: zero `.map` files and required WASM/query assets present.
- After source changes, run targeted tests, lint, typecheck, and configured SonarQube analysis; fix findings caused by change.

## Working Method

- For exploration of `.js`, `.jsx`, `.cjs`, `.mjs`, `.ts`, `.tsx`, `.cts`, or `.mts` code, use Graph-It-Live MCP tools first (or `graph-it scan` and CLI fallback) before `read_file`, `rg`, or other direct source inspection. Use direct inspection afterward to verify details and edit safely.
- Understand full flow and callers before editing. Fix root cause once.
- For architecture, impact, or relationship questions, use the available Graph-It-Live MCP tools first; otherwise use the `graph-it` CLI. Run `graph-it scan` before analysis and after source changes.
- Prefer deletion, existing helpers, standard library, platform features, and installed dependencies—in that order. Add no abstraction or dependency without need.
- Make smallest complete diff; preserve unrelated code and APIs.

## Detailed / Conditional Instructions

Before modifying matching paths—or when task topic matches—read corresponding rule:

| Scope or task | Rule |
| --- | --- |
| Any `src/**` architecture or code-style change, or `graphit.architecture.json` | `.claude/rules/architecture.md` |
| Analyzer, MCP, shared security, paths | `.claude/rules/analyzer-mcp-security.md` |
| React/webview | `.claude/rules/webview-react.md` |
| Tests or coverage | `.claude/rules/testing.md` |
| Build, dependencies, package, WASM | `.claude/rules/build-packaging.md` |
| Live call graph or Cytoscape | `.claude/rules/callgraph-wasm.md` |
| Markdown or Mermaid diagrams | `.claude/rules/documentation-diagrams.md` |
| AIDD agents, gates, memory, handoffs | `.claude/rules/agent-workflow.md` |
| Broad-task bootstrap, shell use, exploration, refactoring, codemaps | `.claude/rules/development-workflow.md` |
| Source changes or SonarQube | `.claude/rules/quality-gates.md` |
| Release preparation (docs audit, media, site, changelog, tag) | `.claude/rules/release.md` |

Claude Code and VS Code load matching `.claude/rules` automatically. Codex must follow routing table explicitly.

## Custom Agents and Automation

- AIDD personas: `.claude/agents/`; orchestration commands: `.claude/commands/`; workflow: `.claude/FRAMEWORK.md`.
- Reusable repository agents: `.agents/agents/`; VS Code agents: `.github/agents/`.
- Focused validation skills: `graph-it-live-layer-check`, `graph-it-live-package-validator`, and `graph-it-live-wasm-verify`.