feat: add code-tree knowledge graph for AI-assisted development and PR reviews

[jsonmp-k8]

Summary

• Restructure monolithic CLAUDE.md (214 lines) into AGENTS.md entry
  point + 6 topic-specific guides under docs/agents/, 5 PR review
  guides under .github/review-guides/, and Copilot reviewer
  instructions
• Add zero-dependency code-tree knowledge graph tooling
  (tools/code-tree/) for symbol lookup, dependency analysis, impact
  analysis, call graph traversal, and test impact mapping
• All original CLAUDE.md content preserved — policies, commands, and
  quick references stay in AGENTS.md; detailed content (architecture,
  error handling, test patterns) moved to sub-guides

Why this matters

For contributors: The monolithic CLAUDE.md forced every agent/developer to load 214 lines of context regardless of what they were working on. Now a contributor adding a CRD field loads only the Go guide (~184 lines), while someone debugging CI loads only the testing guide (~178 lines). Task routing in AGENTS.md tells you exactly which guide to read.

For PR reviewers: Copilot and human reviewers previously had no structured review process. The new .github/copilot-instructions.md defines a batch-based file review strategy with explicit ordering (CRD types → controllers → ADK → UI → Helm → tests), context pruning between batches, and code-tree impact queries to catch untested blast radius. The 5 review guides under .github/review-guides/ provide targeted checklists for architecture, impact, language-specific patterns, security, and test quality — loaded only when relevant.

For blast-radius analysis: Before this PR, understanding "what breaks if I change agent_types.go?" required manually tracing imports across Go, Python, and TypeScript. The code-tree tools automate this:

# Shows 3 affected files and 11 affected symbols in <1 second
python3 tools/code-tree/query_graph.py --impact go/api/v1alpha2/agent_types.go --depth 2

# Shows which tests need re-running after a change
python3 tools/code-tree/query_graph.py --test-impact go/core/internal/controller/agent_controller.go

For onboarding: New contributors get a clear entry point (AGENTS.md) with a task routing table that maps common tasks to the right guide and section. The code-tree --search and --symbol commands help navigate unfamiliar code without reading every file.

Zero runtime cost: The code-tree tools are optional developer tooling with no dependencies. They don't affect CI, builds, or production code. Generated artifacts (docs/code-tree/) are git-ignored and rebuilt per session.

What's new

Code-tree tools (tools/code-tree/)

File	Lines	Purpose
code_tree.py	2,259	Knowledge graph builder — parses Go, Python, TS, Java, Rust via AST/tree-sitter/regex. Outputs graph.json, tags.json, modules.json, summary.md
query_graph.py	1,043	Query CLI — symbol lookup, deps/rdeps, callers/callees/call-chains, hierarchy, BFS impact analysis, test impact
test_query_graph.py	321	31 unit tests — impact BFS depth, edge-type filtering, determinism, all query types

Agent guides (docs/agents/)

Guide	Lines	Covers
architecture.md	153	End-to-end flow, subsystem boundaries, dependency rules, CRDs, protocols
go-guide.md	184	Controllers, API, ADK, CLI, coding standards, CRD field workflow
python-guide.md	152	ADK executor flow, UV workspace, type alignment, LLM providers
ui-guide.md	137	Next.js 16 routing, Shadcn/ui, hub components, patterns
testing-ci.md	178	Test suites, CI matrix, coverage requirements, failure patterns
code-tree.md	179	Query examples, entry points, hub files, module deps

PR review guides (.github/review-guides/)

Guide	Lines	Covers
architecture-context.md	86	Subsystem boundaries, dependency rules, backward compat
impact-analysis.md	62	Hub files, CRD change checklist, cross-boundary changes
language-checklists.md	64	Go, Python, TypeScript, YAML review checklists
security-review.md	55	SecurityContext, RBAC, credentials, network security
test-quality.md	74	Coverage requirements, test organization, CI quality

Entry points

• AGENTS.md (193 lines): Main agent guide — skill reference, language table, policies, commands, file index, task routing, validation checklist, both code-tree options
• .github/copilot-instructions.md (81 lines): Batch-based PR review strategy with code-tree integration
• CLAUDE.md: Slimmed to ./AGENTS.md redirect

Verification

• Code-tree builder tested on kagent repo: 4,123 nodes, 12,435 edges across 557 files (Go 268, TypeScript 147, Python 128, Bash 7, JavaScript 7)
• All 31 unit tests pass (Python 3.12)
• 21 documentation claims audited against codebase — all file paths, entry points, CI matrix values, and tool versions confirmed accurate
• Generated docs/code-tree/ artifacts git-ignored (rebuilt per session)

Test plan

• python3.12 tools/code-tree/code_tree.py --repo-root . --incremental -q builds graph successfully
• python3.12 tools/code-tree/query_graph.py --stats reports correct node/edge counts
• python3.12 tools/code-tree/query_graph.py --symbol Reconcile finds all 5 controllers
• python3.12 tools/code-tree/query_graph.py --impact go/api/v1alpha2/agent_types.go --depth 2 shows correct blast radius
• python3.12 -m pytest tools/code-tree/test_query_graph.py -v — 31/31 pass
• All markdown links in AGENTS.md and docs/agents/ resolve to existing files
• Verify code-tree queries work in CI Python environment (3.10+)

[Copilot]

Pull request overview

This PR introduces an in-repo, zero-dependency “code-tree” knowledge graph toolchain to support AI-assisted development and PR reviews, and restructures the prior monolithic agent guidance into a navigable set of focused guides and review checklists.

Changes:

• Added tools/code-tree/ graph builder + query CLI for symbol/dependency/call/impact/test-impact analysis, plus unit tests.
• Replaced CLAUDE.md with an AGENTS.md entry point and added topic-specific agent docs under docs/agents/.
• Added GitHub PR review guides under .github/review-guides/ and Copilot reviewer instructions, plus gitignore updates for generated artifacts.

Reviewed changes

Copilot reviewed 17 out of 18 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tools/code-tree/code_tree.py	Builds the repo knowledge graph artifacts (nodes/edges/tags/modules/summary).
tools/code-tree/query_graph.py	CLI + query layer for looking up symbols, deps, call graph, and impact/test-impact.
tools/code-tree/test_query_graph.py	Unit tests covering graph query behaviors and determinism.
docs/agents/architecture.md	New architecture-focused agent guide (system boundaries, dependency rules).
docs/agents/go-guide.md	New Go-focused agent guide (controllers/CLI/testing patterns).
docs/agents/python-guide.md	New Python-focused agent guide (ADK/runtime/testing/type alignment).
docs/agents/ui-guide.md	New UI-focused agent guide (Next.js structure, testing, key components).
docs/agents/testing-ci.md	Consolidated testing/CI guidance and local reproduction steps.
docs/agents/code-tree.md	Usage guide for code-tree artifacts and query workflows.
AGENTS.md	New top-level entry point indexing the sub-guides and commands/policies.
CLAUDE.md	Redirects to AGENTS.md (replacing the previous monolithic content).
.github/copilot-instructions.md	Defines Copilot PR review strategy including code-tree usage.
.github/review-guides/architecture-context.md	Review checklist for multi-subsystem / CRD / controller changes.
.github/review-guides/impact-analysis.md	Review checklist emphasizing blast radius and hub-file scrutiny.
.github/review-guides/language-checklists.md	Language-specific review checklists (Go/Python/TS/YAML).
.github/review-guides/security-review.md	Security-oriented PR review checklist.
.github/review-guides/test-quality.md	Test quality/coverage expectations for PR reviews.
.gitignore	Ignores local knowledge-graph artifacts and other generated files.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.