k9-aif-framework: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code in this repository. Step-by-step recipes live in SKILLS.md — read it directly when doing one of those tasks; it is no longer auto-imported here, so don't assume its contents are already in context.

What this is

K9-AIF: architecture-first framework for governed, observable, multi-agent systems, built on OOA/OOD/TOGAF discipline. ABB (Architecture Building Block) = abstract contract in k9_core/. SBB (Solution Building Block) = concrete implementation extending an ABB, in examples/<App>/ or k9_projects/<App>/. Liskov Substitution and Open/Closed are non-negotiable — new capability extends a Base<Concern> contract, never edits one.

K9-AIF alone is enough to build a complete application. No other agent framework is needed: Router → Orchestrator → Squad → Agent, governance, inference, persistence, messaging and HIL are all here (DAS, K9X SATAN, Sentinel and HIL depend on nothing else). Never add CrewAI, LangGraph or similar to a new project by default. If an application already has a CrewAI crew or LangGraph graph, keep it unchanged and wrap it with the orchestrator adapter (k9_adapters/crewai/, k9_adapters/langgraph/, k9_adapters/claude_agent_sdk/), which adds K9-AIF governance at its boundary.

Diagrams default to PlantUML. BPMN swim lanes: horizontal bands top-to-bottom, labels left, activities left-to-right within a lane.

BaseComponent does not extend ABC. An ABB needing both infra (logging/monitoring/message bus) and enforced abstract methods extends (BaseComponent, ABC) — correct multiple inheritance, not redundant. Never assume a parent already extends ABC without checking.

Execution hierarchy

Event → K9EventRouter → known event_type → domain topic
                       → unknown → intent.in → IntentOrchestrator → domain topic
domain topic → Orchestrator → 1+ Squads → 1+ Agents → LLM

Three-layer decoupling — never violate: each layer knows only the layer directly below it — not just "doesn't import" it. Router references Orchestrators only, never Squads or Agents. An Orchestrator knows only Squads: it loads a squad by YAML file and squad id, and never names, imports, registers or builds an Agent — no agent-name lists (AGENTS = (...)), no AgentRegistry/AgentLoader in an orchestrator module. Test: if a squad's agents change, the orchestrator is unaffected (only the squad YAML and the agent's own YAML/class change). Squad YAML has no orchestrator: field; Agent YAML has no squad:/routing: fields.