feat: AGKC reverse engineering for agent codebases (v0.5.0)

[RichardHightower]

Summary

Adds AGKC (Agent Graph Knowledge Capture) — reverse engineering for multi-agent systems — as a first-class part of the okf-agent-graph plugin (v0.5.0).

Forward path today: define AGER graphs (ager-init / ager-author / ager-validate / ager-compile).

New reverse path (same pattern as system-architecture-capture and data-engineering-knowledge-capture):

1. Scan brownfield agent code
2. Capture draft AGER OKF knowledge with provenance
3. Promote via ager-author + validate

What gets extracted

Signal	Maps toward AGER
Frameworks (LangGraph, LangChain, CrewAI, LlamaIndex, OpenAI/Claude APIs, Claude Agent SDK, Deep Agents, AutoGen, Semantic Kernel, MCP, …)	Framework notes / adapters
System prompts & prompts	AgentNode.instructions / Prompt
Tools + JSON Schema / Zod / Pydantic	Tool, InputSchema, OutputSchema
MCP servers & JSON-RPC	Tool + schemas + SecretRef
Graphs / edges / nodes	AgentGraph + ControlEdge
Loops (max turns, recursion, deadlines)	LoopPolicy + LoopControl
Orchestration (supervisor, handoffs, fan-out, human gates)	Orchestrator / Handoff / FanOut / HumanGate
Hyperscalers (Bedrock AgentCore, Azure AI Agents, Vertex Agent Engine)	Run + CheckpointPolicy
Hardened sandboxes (Firecracker, gVisor, Kata, E2B, hardened pods)	ContextIsolationPolicy

Plugin surface

• Scripts: scripts/ager_scan.py, scripts/ager_capture.py, scripts/ager_reverse_engineer.py (stdlib only)
• Skills / commands: ager-scan, ager-reverse-engineer (/… and $…)
• Agent: agent-graph-re-orchestrator
• Docs: docs/REVERSE_ENGINEERING.md (+ README / user guide / AGER_SPEC updates)
• Tests: tests/fixtures/agent-repo/*, tests/test_ager_scan.py

Usage

python3 scripts/ager_scan.py --root /path/to/project --json -o scan.json
python3 scripts/ager_reverse_engineer.py --root /path/to/project --out discovered-ager --json

Or /ager-scan → /ager-reverse-engineer in Claude/Grok; $ager-scan / $ager-reverse-engineer in Codex.

Test plan

• python3 -m unittest tests/test_ager_scan.py tests/test_plugin.py tests/test_ager.py -v (18 tests, 1 skip without okf-plugin)
• Fixture detects langgraph, langchain, crewai, anthropic-sdk, claude-agent-sdk, mcp
• Reverse engineer writes draft bundle with index, discoveries, frameworks, capture-report
• Review draft concept types (currently Reference placeholders) vs promoting stricter AGER types on capture
• Optional follow-up: wire AGKC explorer UI (separate) or deeper AST-based extractors