# matbanik/agentic-framework architecture

> Architecture diagram of the GitHub repository matbanik/agentic-framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/matbanik/agentic-framework
- Repository: https://github.com/matbanik/agentic-framework

## Overview

This is a portable agentic-work governance framework: it guides adopters in configuring safety gates, then structures agent work through research, planning, independent review, implementation, validation, and human-gated completion. Its issue-to-MEU loop turns defects into tracked work; durable files, review limits, and structural gates support evidence and fail-closed behavior. The README documents broader workflow and model-routing capabilities; sampled source confirms selected triage, MEU, review-ledger, and validation behavior, not every connection shown.

Main entry points: [`core/.agent/workflows`](https://github.com/matbanik/agentic-framework/tree/main/core/.agent/workflows) (Delivery Workflows), [`core/AGENTS.md`](https://github.com/matbanik/agentic-framework/blob/main/core/AGENTS.md) (Operating Contract), [`ADOPTION-GUIDE.md`](https://github.com/matbanik/agentic-framework/blob/main/ADOPTION-GUIDE.md) (Adoption Guide), [`ADOPTION-QUESTIONS.md`](https://github.com/matbanik/agentic-framework/blob/main/ADOPTION-QUESTIONS.md) (Adoption Questions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_adoption["Adoption"]
  node_adoption_questions["Adoption Questions"]
  node_adoption_guide["Adoption Guide<br/>[ADOPTION-GUIDE.md]"]
  node_domain_mapping["Domain Mapping<br/>[DOMAIN-MAPPING.md]"]
  node_instantiate["Project Instantiation<br/>[instantiate.py]"]
end

subgraph group_delivery["Work Delivery"]
  node_delivery_workflows["Delivery Workflows<br/>[workflows]"]
  node_agent_roles["Agent Roles<br/>[roles]"]
  node_workflow_skills["Workflow Skills<br/>[skills]"]
  node_task_templates["Work Templates"]
end

subgraph group_learning["Learning Loop"]
  node_issue_cli["Issue Triage CLI<br/>[issue_triage.py]"]
  node_issue_store[("Issue Registry<br/>[known-issues.yaml]")]
  node_issue_to_meu["Issue-to-MEU Guidance<br/>[triage-meu-loop.md]"]
  node_meu_cli["MEU Status CLI<br/>[meu_status.py]"]
  node_meu_store[("MEU Registry<br/>[meu-status.yaml]")]
end

subgraph group_governance["Safety Controls"]
  node_operating_contract["Operating Contract<br/>[AGENTS.md]"]
  node_guardrails["Safety Guardrails<br/>[GUARDRAILS.md]"]
  node_review_ledger["Bounded Review Ledger<br/>[review_ledger.py]"]
  node_closeout_gate["Closeout Gate"]
  node_task_contract_gate["Task Contract Gate"]
end

subgraph group_configuration["Agent Configuration"]
  node_harness_profiles["Harness Profiles"]
  node_model_routing["Model Routing<br/>[model-routing.md]"]
  node_registry_tools["Model Registry Tools<br/>[resolve_model.py]"]
end

node_adopter(("Adopting User"))
node_agent(("Working Agent"))
node_human(("Human Reviewer"))
node_model_service(("External Model Provider"))

node_adopter -->|"answers first"| node_adoption_questions
node_adoption_questions -->|"configures adoption"| node_adoption_guide
node_adoption_guide -->|"translates practice"| node_domain_mapping
node_adoption_guide -->|"instructs setup"| node_instantiate
node_adopter -->|"runs setup"| node_instantiate
node_agent -->|"follows contract"| node_operating_contract
node_operating_contract -->|"enforces constraints"| node_guardrails
node_operating_contract -->|"directs work"| node_delivery_workflows
node_delivery_workflows -->|"assigns roles"| node_agent_roles
node_delivery_workflows -->|"uses practices"| node_workflow_skills
node_delivery_workflows -->|"produces artifacts"| node_task_templates
node_agent -->|"triages defects"| node_issue_cli
node_issue_cli -->|"reads and updates"| node_issue_store
node_issue_to_meu -->|"guides registration"| node_meu_cli
node_meu_cli -->|"reads and updates"| node_meu_store
node_delivery_workflows -->|"feeds learning loop"| node_issue_to_meu
node_agent -->|"records review rounds"| node_review_ledger
node_review_ledger -->|"requests continuation"| node_human
node_agent -->|"checks closeout"| node_closeout_gate
node_agent -->|"checks task contract"| node_task_contract_gate
node_operating_contract -->|"configures capabilities"| node_harness_profiles
node_operating_contract -->|"describes delegation"| node_model_routing
node_model_routing -->|"resolves models"| node_registry_tools
node_registry_tools -.->|"supports provider selection"| node_model_service
node_delivery_workflows -->|"gates irreversible work"| node_human

click node_adoption_questions "https://github.com/matbanik/agentic-framework/blob/main/ADOPTION-QUESTIONS.md"
click node_adoption_guide "https://github.com/matbanik/agentic-framework/blob/main/ADOPTION-GUIDE.md"
click node_domain_mapping "https://github.com/matbanik/agentic-framework/blob/main/DOMAIN-MAPPING.md"
click node_instantiate "https://github.com/matbanik/agentic-framework/blob/main/scripts/instantiate.py"
click node_operating_contract "https://github.com/matbanik/agentic-framework/blob/main/core/AGENTS.md"
click node_guardrails "https://github.com/matbanik/agentic-framework/blob/main/core/GUARDRAILS.md"
click node_delivery_workflows "https://github.com/matbanik/agentic-framework/tree/main/core/.agent/workflows"
click node_agent_roles "https://github.com/matbanik/agentic-framework/tree/main/core/.agent/roles"
click node_workflow_skills "https://github.com/matbanik/agentic-framework/tree/main/core/.agent/skills"
click node_task_templates "https://github.com/matbanik/agentic-framework/tree/main/core/templates"
click node_issue_cli "https://github.com/matbanik/agentic-framework/blob/main/core/tools/issue_triage.py"
click node_issue_store "https://github.com/matbanik/agentic-framework/blob/main/core/.agent/context/known-issues.yaml"
click node_issue_to_meu "https://github.com/matbanik/agentic-framework/blob/main/core/.agent/docs/triage-meu-loop.md"
click node_meu_cli "https://github.com/matbanik/agentic-framework/blob/main/core/tools/meu_status.py"
click node_meu_store "https://github.com/matbanik/agentic-framework/blob/main/core/.agent/context/meu-status.yaml"
click node_review_ledger "https://github.com/matbanik/agentic-framework/blob/main/core/tools/review_ledger.py"
click node_closeout_gate "https://github.com/matbanik/agentic-framework/blob/main/core/tools/validate_closeout_artifacts.py"
click node_task_contract_gate "https://github.com/matbanik/agentic-framework/blob/main/core/tools/lint_task_contract.py"
click node_harness_profiles "https://github.com/matbanik/agentic-framework/blob/main/core/.agent/docs/harness-profiles.md"
click node_model_routing "https://github.com/matbanik/agentic-framework/blob/main/core/.agent/docs/model-routing.md"
click node_registry_tools "https://github.com/matbanik/agentic-framework/blob/main/.agent/tools/resolve_model.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_adoption_questions,node_adoption_guide,node_domain_mapping,node_instantiate,node_adopter,node_human toneBlue
class node_delivery_workflows,node_agent_roles,node_workflow_skills,node_task_templates toneAmber
class node_issue_cli,node_issue_store,node_issue_to_meu,node_meu_cli,node_meu_store toneMint
class node_operating_contract,node_guardrails,node_review_ledger,node_closeout_gate,node_task_contract_gate toneRose
class node_harness_profiles,node_model_routing,node_registry_tools,node_agent,node_model_service toneIndigo
```

## Components

### Adoption

- [Adoption Questions](https://github.com/matbanik/agentic-framework/blob/main/ADOPTION-QUESTIONS.md): `ADOPTION-QUESTIONS.md`
- [Adoption Guide](https://github.com/matbanik/agentic-framework/blob/main/ADOPTION-GUIDE.md): `ADOPTION-GUIDE.md`
- [Domain Mapping](https://github.com/matbanik/agentic-framework/blob/main/DOMAIN-MAPPING.md): `DOMAIN-MAPPING.md`
- [Project Instantiation](https://github.com/matbanik/agentic-framework/blob/main/scripts/instantiate.py): `scripts/instantiate.py`

### Work Delivery

- [Delivery Workflows](https://github.com/matbanik/agentic-framework/tree/main/core/.agent/workflows): `core/.agent/workflows`
- [Agent Roles](https://github.com/matbanik/agentic-framework/tree/main/core/.agent/roles): `core/.agent/roles`
- [Workflow Skills](https://github.com/matbanik/agentic-framework/tree/main/core/.agent/skills): `core/.agent/skills`
- [Work Templates](https://github.com/matbanik/agentic-framework/tree/main/core/templates): `core/templates`

### Learning Loop

- [Issue Triage CLI](https://github.com/matbanik/agentic-framework/blob/main/core/tools/issue_triage.py): `core/tools/issue_triage.py`
- [Issue Registry](https://github.com/matbanik/agentic-framework/blob/main/core/.agent/context/known-issues.yaml): `core/.agent/context/known-issues.yaml`
- [Issue-to-MEU Guidance](https://github.com/matbanik/agentic-framework/blob/main/core/.agent/docs/triage-meu-loop.md): `core/.agent/docs/triage-meu-loop.md`
- [MEU Status CLI](https://github.com/matbanik/agentic-framework/blob/main/core/tools/meu_status.py): `core/tools/meu_status.py`
- [MEU Registry](https://github.com/matbanik/agentic-framework/blob/main/core/.agent/context/meu-status.yaml): `core/.agent/context/meu-status.yaml`

### Safety Controls

- [Operating Contract](https://github.com/matbanik/agentic-framework/blob/main/core/AGENTS.md): `core/AGENTS.md`
- [Safety Guardrails](https://github.com/matbanik/agentic-framework/blob/main/core/GUARDRAILS.md): `core/GUARDRAILS.md`
- [Bounded Review Ledger](https://github.com/matbanik/agentic-framework/blob/main/core/tools/review_ledger.py): `core/tools/review_ledger.py`
- [Closeout Gate](https://github.com/matbanik/agentic-framework/blob/main/core/tools/validate_closeout_artifacts.py): `core/tools/validate_closeout_artifacts.py`
- [Task Contract Gate](https://github.com/matbanik/agentic-framework/blob/main/core/tools/lint_task_contract.py): `core/tools/lint_task_contract.py`

### Agent Configuration

- [Harness Profiles](https://github.com/matbanik/agentic-framework/blob/main/core/.agent/docs/harness-profiles.md): `core/.agent/docs/harness-profiles.md`
- [Model Routing](https://github.com/matbanik/agentic-framework/blob/main/core/.agent/docs/model-routing.md): `core/.agent/docs/model-routing.md`
- [Model Registry Tools](https://github.com/matbanik/agentic-framework/blob/main/.agent/tools/resolve_model.py): `.agent/tools/resolve_model.py`

### Other components

- **Adopting User**
- **Working Agent**
- **Human Reviewer**
- **External Model Provider**

## Connections

- Adopting User → Adoption Questions: answers first
- Adoption Questions → Adoption Guide: configures adoption
- Adoption Guide → Domain Mapping: translates practice
- Adoption Guide → Project Instantiation: instructs setup
- Adopting User → Project Instantiation: runs setup
- Working Agent → Operating Contract: follows contract
- Operating Contract → Safety Guardrails: enforces constraints
- Operating Contract → Delivery Workflows: directs work
- Delivery Workflows → Agent Roles: assigns roles
- Delivery Workflows → Workflow Skills: uses practices
- Delivery Workflows → Work Templates: produces artifacts
- Working Agent → Issue Triage CLI: triages defects
- Issue Triage CLI → Issue Registry: reads and updates
- Issue-to-MEU Guidance → MEU Status CLI: guides registration
- MEU Status CLI → MEU Registry: reads and updates
- Delivery Workflows → Issue-to-MEU Guidance: feeds learning loop
- Working Agent → Bounded Review Ledger: records review rounds
- Bounded Review Ledger → Human Reviewer: requests continuation
- Working Agent → Closeout Gate: checks closeout
- Working Agent → Task Contract Gate: checks task contract
- Operating Contract → Harness Profiles: configures capabilities
- Operating Contract → Model Routing: describes delegation
- Model Routing → Model Registry Tools: resolves models
- Model Registry Tools → External Model Provider: supports provider selection
- Delivery Workflows → Human Reviewer: gates irreversible work