# dammar01/agent-workflow architecture

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

- Interactive diagram: https://gitdiagram.com/dammar01/agent-workflow
- Repository: https://github.com/dammar01/agent-workflow

## Overview

agent-workflow is a Python control plane around a primary coding agent. The primary agent submits a task to the runtime, which routes and governs it, manages session/job state, builds a bounded prompt, and dispatches to a secondary provider. The runtime checks and shapes the returned evidence, persists artifacts, and returns a digest and evidence reference for the primary agent to assess. It also supports local workspace operations, browser-based verification, and promotion of verified knowledge. The README documents these capabilities; some internal wiring is inferred only where the sampled source supports it.

Main entry points: [`main.py`](https://github.com/dammar01/agent-workflow/blob/main/main.py) (Command entry), [`core/provider/executor.py`](https://github.com/dammar01/agent-workflow/blob/main/core/provider/executor.py) (Delegation executor), [`core/evidence/e2e/runner.py`](https://github.com/dammar01/agent-workflow/blob/main/core/evidence/e2e/runner.py) (Browser verification), [`adapters/providers`](https://github.com/dammar01/agent-workflow/tree/main/adapters/providers) (Provider adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Runtime orchestration"]
  node_cli["Command entry<br/>[main.py]"]
  node_router["Command routing<br/>[router.py]"]
  node_jobs["Job lifecycle<br/>[job_manager.py]"]
  node_sessions["Session manager<br/>[session_manager.py]"]
end

subgraph group_delegation["Provider delegation"]
  node_executor["Delegation executor<br/>[executor.py]"]
  node_prompt["Prompt builder<br/>[prompt_builder.py]"]
  node_registry["Adapter registry<br/>[registry.py]"]
  node_adapters["Provider adapters"]
end

subgraph group_evidence["Evidence processing"]
  node_contract["Evidence contracts<br/>[contract.py]"]
  node_shaping["Result shaping<br/>[result_shaping.py]"]
  node_evidence_store[("Evidence artifacts<br/>[evidence_store.py]")]
  node_browser["Browser verification<br/>[runner.py]"]
  node_browser_player["Browser player<br/>[browser.py]"]
end

subgraph group_workspace["Workspace and policy"]
  node_workspace["Workspace runtime<br/>[workspace_paths.py]"]
  node_governance["Provider governance<br/>[governance.py]"]
  node_audit["Audit and diagnostics"]
end

subgraph group_knowledge["Knowledge lifecycle"]
  node_knowledge["Knowledge retrieval<br/>[retrieve.py]"]
  node_knowledge_store[("Knowledge store<br/>[store.py]")]
  node_knowledge_verify["Knowledge verification<br/>[verify.py]"]
  node_knowledge_reconcile["Claim reconciliation<br/>[reconcile.py]"]
end

node_primary(("Primary agent"))
node_secondary(("Secondary agent"))

node_primary -->|"submits command"| node_cli
node_cli -->|"manages jobs"| node_jobs
node_cli -->|"loads session"| node_sessions
node_cli -->|"executes task"| node_executor
node_executor -->|"routes command"| node_router
node_router -->|"checks provider"| node_governance
node_executor -->|"builds prompt"| node_prompt
node_executor -->|"resolves adapter"| node_registry
node_registry -->|"selects provider"| node_adapters
node_adapters -->|"sends task"| node_secondary
node_secondary -->|"returns response"| node_adapters
node_executor -->|"validates result"| node_contract
node_executor -->|"shapes result"| node_shaping
node_executor -->|"reads and writes"| node_evidence_store
node_shaping -->|"returns digest"| node_primary
node_cli -->|"dispatches verification"| node_browser
node_browser -->|"runs scenario"| node_browser_player
node_browser -->|"checks evidence"| node_contract
node_executor -->|"retrieves context"| node_knowledge
node_knowledge -->|"reads documents"| node_knowledge_store
node_cli -->|"loads promoted document"| node_knowledge_store
node_cli -->|"verifies promotion"| node_knowledge_verify
node_cli -->|"reconciles claims"| node_knowledge_reconcile
node_cli -->|"manages workspace"| node_workspace
node_cli -->|"reports diagnostics"| node_audit

click node_cli "https://github.com/dammar01/agent-workflow/blob/main/main.py"
click node_router "https://github.com/dammar01/agent-workflow/blob/main/core/prompt/router.py"
click node_jobs "https://github.com/dammar01/agent-workflow/blob/main/core/jobs/job_manager.py"
click node_sessions "https://github.com/dammar01/agent-workflow/blob/main/core/workspace/session_manager.py"
click node_executor "https://github.com/dammar01/agent-workflow/blob/main/core/provider/executor.py"
click node_prompt "https://github.com/dammar01/agent-workflow/blob/main/core/prompt/prompt_builder.py"
click node_registry "https://github.com/dammar01/agent-workflow/blob/main/adapters/contract/registry.py"
click node_adapters "https://github.com/dammar01/agent-workflow/tree/main/adapters/providers"
click node_contract "https://github.com/dammar01/agent-workflow/blob/main/core/evidence/contract.py"
click node_shaping "https://github.com/dammar01/agent-workflow/blob/main/core/evidence/result_shaping.py"
click node_evidence_store "https://github.com/dammar01/agent-workflow/blob/main/core/evidence/evidence_store.py"
click node_browser "https://github.com/dammar01/agent-workflow/blob/main/core/evidence/e2e/runner.py"
click node_browser_player "https://github.com/dammar01/agent-workflow/blob/main/core/evidence/e2e/browser.py"
click node_workspace "https://github.com/dammar01/agent-workflow/blob/main/core/workspace/workspace_paths.py"
click node_governance "https://github.com/dammar01/agent-workflow/blob/main/core/policy/governance.py"
click node_audit "https://github.com/dammar01/agent-workflow/tree/main/core/audit"
click node_knowledge "https://github.com/dammar01/agent-workflow/blob/main/core/knowledge/retrieve.py"
click node_knowledge_store "https://github.com/dammar01/agent-workflow/blob/main/core/knowledge/store.py"
click node_knowledge_verify "https://github.com/dammar01/agent-workflow/blob/main/core/knowledge/verify.py"
click node_knowledge_reconcile "https://github.com/dammar01/agent-workflow/blob/main/core/knowledge/reconcile.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_cli,node_router,node_jobs,node_sessions toneBlue
class node_executor,node_prompt,node_registry,node_adapters toneAmber
class node_contract,node_shaping,node_evidence_store,node_browser,node_browser_player toneMint
class node_workspace,node_governance,node_audit toneRose
class node_knowledge,node_knowledge_store,node_knowledge_verify,node_knowledge_reconcile,node_primary,node_secondary toneIndigo
```

## Components

### Runtime orchestration

- [Command entry](https://github.com/dammar01/agent-workflow/blob/main/main.py): `main.py`
- [Command routing](https://github.com/dammar01/agent-workflow/blob/main/core/prompt/router.py): `core/prompt/router.py`
- [Job lifecycle](https://github.com/dammar01/agent-workflow/blob/main/core/jobs/job_manager.py): `core/jobs/job_manager.py`
- [Session manager](https://github.com/dammar01/agent-workflow/blob/main/core/workspace/session_manager.py): `core/workspace/session_manager.py`

### Provider delegation

- [Delegation executor](https://github.com/dammar01/agent-workflow/blob/main/core/provider/executor.py): `core/provider/executor.py`
- [Prompt builder](https://github.com/dammar01/agent-workflow/blob/main/core/prompt/prompt_builder.py): `core/prompt/prompt_builder.py`
- [Adapter registry](https://github.com/dammar01/agent-workflow/blob/main/adapters/contract/registry.py): `adapters/contract/registry.py`
- [Provider adapters](https://github.com/dammar01/agent-workflow/tree/main/adapters/providers): `adapters/providers`

### Evidence processing

- [Evidence contracts](https://github.com/dammar01/agent-workflow/blob/main/core/evidence/contract.py): `core/evidence/contract.py`
- [Result shaping](https://github.com/dammar01/agent-workflow/blob/main/core/evidence/result_shaping.py): `core/evidence/result_shaping.py`
- [Evidence artifacts](https://github.com/dammar01/agent-workflow/blob/main/core/evidence/evidence_store.py): `core/evidence/evidence_store.py`
- [Browser verification](https://github.com/dammar01/agent-workflow/blob/main/core/evidence/e2e/runner.py): `core/evidence/e2e/runner.py`
- [Browser player](https://github.com/dammar01/agent-workflow/blob/main/core/evidence/e2e/browser.py): `core/evidence/e2e/browser.py`

### Workspace and policy

- [Workspace runtime](https://github.com/dammar01/agent-workflow/blob/main/core/workspace/workspace_paths.py): `core/workspace/workspace_paths.py`
- [Provider governance](https://github.com/dammar01/agent-workflow/blob/main/core/policy/governance.py): `core/policy/governance.py`
- [Audit and diagnostics](https://github.com/dammar01/agent-workflow/tree/main/core/audit): `core/audit`

### Knowledge lifecycle

- [Knowledge retrieval](https://github.com/dammar01/agent-workflow/blob/main/core/knowledge/retrieve.py): `core/knowledge/retrieve.py`
- [Knowledge store](https://github.com/dammar01/agent-workflow/blob/main/core/knowledge/store.py): `core/knowledge/store.py`
- [Knowledge verification](https://github.com/dammar01/agent-workflow/blob/main/core/knowledge/verify.py): `core/knowledge/verify.py`
- [Claim reconciliation](https://github.com/dammar01/agent-workflow/blob/main/core/knowledge/reconcile.py): `core/knowledge/reconcile.py`

### Other components

- **Primary agent**
- **Secondary agent**

## Connections

- Primary agent → Command entry: submits command
- Command entry → Job lifecycle: manages jobs
- Command entry → Session manager: loads session
- Command entry → Delegation executor: executes task
- Delegation executor → Command routing: routes command
- Command routing → Provider governance: checks provider
- Delegation executor → Prompt builder: builds prompt
- Delegation executor → Adapter registry: resolves adapter
- Adapter registry → Provider adapters: selects provider
- Provider adapters → Secondary agent: sends task
- Secondary agent → Provider adapters: returns response
- Delegation executor → Evidence contracts: validates result
- Delegation executor → Result shaping: shapes result
- Delegation executor → Evidence artifacts: reads and writes
- Result shaping → Primary agent: returns digest
- Command entry → Browser verification: dispatches verification
- Browser verification → Browser player: runs scenario
- Browser verification → Evidence contracts: checks evidence
- Delegation executor → Knowledge retrieval: retrieves context
- Knowledge retrieval → Knowledge store: reads documents
- Command entry → Knowledge store: loads promoted document
- Command entry → Knowledge verification: verifies promotion
- Command entry → Claim reconciliation: reconciles claims
- Command entry → Workspace runtime: manages workspace
- Command entry → Audit and diagnostics: reports diagnostics