Epic: Integrate AI Agent Agent Guides Governance Framework into oxidizedgraph

[stevei101]

Overview

Integrate the AI Agent Agent Guides governance framework into oxidizedgraph's agent orchestration, enabling governance-aware agents that follow dynamic guidance rules with role-based routing.

Goals

• ✅ Enable governance-aware agent graphs with rule enforcement
• ✅ Implement role-based routing (architect, builder, auditor roles)
• ✅ Maintain real-time symlink synchronization for guidance updates
• ✅ Integrate Nix CI diagnostics into agent failure handling
• ✅ Provide automatic agent discovery within orchestration graphs
• ✅ Zero breaking changes to existing oxidizedgraph API

Epic Scope

This is a 4-week, 4-phase integration:

• Phase 1 (Week 1): Foundation - Core types, GovernanceNode, parser
• Phase 2 (Week 2): Integration - LLMNode/ToolNode awareness, symlinks, example
• Phase 3 (Week 3): Advanced - Diagnostics, discovery, CLI commands, tests
• Phase 4 (Week 4): Polish - Docs, optimization, release

Key Components

New Modules

• src/governance/ (7 sub-modules)
• src/nodes/governance.rs (GovernanceNode)
• examples/governance_workflow.rs
• Comprehensive test suite

Integration Points

• State: Add GuidanceContext to AgentState
• Nodes: Make LLM, Tool, Conditional nodes governance-aware
• Error Handling: Nix diagnostics integration
• CLI: New governance commands (validate, sync, status, list-agents, check-compliance)

Success Criteria

• Governance rules applied to agent execution
• Symlinks stay synchronized in graphs
• Role-based routing works (architect vs builder)
• Nix diagnostics integrated with error handling
• All existing oxidizedgraph examples still work
• Comprehensive documentation & examples
• 90%+ test coverage for governance module

Related Repositories

• stevedores-org/ai-agent-agent-guides
• lornu-ai/ai-agent-agent-guides (original)
• lornu-ai/lornu.ai (monorepo source)

References

Full integration plan: INTEGRATION_PLAN.md

---

Status: Planning Phase
Team: @stevedores-org/oxidizedgraph
Priority: High
Effort: 4 weeks