# nullurl/marvin-adaptive-delivery architecture

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

- Interactive diagram: https://gitdiagram.com/nullurl/marvin-adaptive-delivery
- Repository: https://github.com/nullurl/marvin-adaptive-delivery

## Overview

Marvin Adaptive Delivery is an agent-facing delivery workflow and local execution control plane, not a project-management service. The principal path starts with a user goal: the Skill selects risk-appropriate governance, organizes work and evidence, and can use the A2A server to track delegated attempts and recovery before verification and acceptance. Separate capabilities initialize project governance, route model profiles, validate visual evidence, and preserve context and reusable experience. The A2A server owns execution state but leaves worker execution to its caller. Relationships for unsampled subsystems rely on README statements; source excerpts do not establish additional runtime call chains.

Main entry points: [`scripts/a2a_server.py`](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/scripts/a2a_server.py) (A2A control plane), [`SKILL.md`](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/SKILL.md) (Risk-tiered flow), [`references/long-task-governance.md`](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/references/long-task-governance.md) (Agent coordination), [`scripts/init_project.py`](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/scripts/init_project.py) (Project initializer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delivery["Delivery workflow"]
  node_delivery_skill["Delivery Skill<br/>[SKILL.md]"]
  node_risk_flow["Risk-tiered flow<br/>[SKILL.md]"]
  node_multi_agent["Agent coordination"]
  node_context["Context governance"]
  node_experience["Experience methods"]
end

subgraph group_control["Execution control"]
  node_a2a["A2A control plane<br/>[a2a_server.py]"]
  node_sqlite[("Execution database<br/>[a2a_server.py]")]
  node_worker(("Worker agents"))
  node_verifier(("Verifier"))
  node_recovery(("Recovery worker"))
  node_model_router["Model profile router<br/>[model_routing.py]"]
end

subgraph group_governance["Project governance"]
  node_init["Project initializer<br/>[init_project.py]"]
  node_templates["Project templates"]
  node_governance_lint["Governance checks<br/>[lint_governance.py]"]
end

subgraph group_evidence["Evidence and validation"]
  node_verification["Verification receipts"]
  node_visual_guard["Visual evidence guard"]
  node_visual_policy["Visual reference governance"]
  node_harness["Harness and release"]
end

node_user(("User"))

node_user -->|"requests delivery"| node_delivery_skill
node_delivery_skill -->|"selects flow"| node_risk_flow
node_risk_flow -->|"coordinates work"| node_multi_agent
node_risk_flow -->|"governs context"| node_context
node_risk_flow -->|"captures methods"| node_experience
node_user -->|"initializes project"| node_init
node_init -->|"copies templates"| node_templates
node_user -->|"checks governance"| node_governance_lint
node_multi_agent -->|"creates tasks"| node_a2a
node_a2a -->|"persists state"| node_sqlite
node_a2a -->|"dispatches attempts"| node_worker
node_worker -->|"sends events"| node_a2a
node_a2a -->|"provides candidates"| node_verifier
node_recovery -->|"resumes checkpoints"| node_a2a
node_a2a -->|"resolves profiles"| node_model_router
node_user -->|"runs verification"| node_verification
node_verification -->|"records receipts"| node_harness
node_user -->|"checks receipt"| node_visual_guard
node_visual_policy -->|"defines evidence"| node_visual_guard

click node_delivery_skill "https://github.com/nullurl/marvin-adaptive-delivery/blob/main/SKILL.md"
click node_risk_flow "https://github.com/nullurl/marvin-adaptive-delivery/blob/main/SKILL.md"
click node_multi_agent "https://github.com/nullurl/marvin-adaptive-delivery/blob/main/references/long-task-governance.md"
click node_context "https://github.com/nullurl/marvin-adaptive-delivery/blob/main/references/context-governance.md"
click node_experience "https://github.com/nullurl/marvin-adaptive-delivery/blob/main/references/experience-catalog.md"
click node_init "https://github.com/nullurl/marvin-adaptive-delivery/blob/main/scripts/init_project.py"
click node_templates "https://github.com/nullurl/marvin-adaptive-delivery/tree/main/assets/templates"
click node_governance_lint "https://github.com/nullurl/marvin-adaptive-delivery/blob/main/scripts/lint_governance.py"
click node_a2a "https://github.com/nullurl/marvin-adaptive-delivery/blob/main/scripts/a2a_server.py"
click node_sqlite "https://github.com/nullurl/marvin-adaptive-delivery/blob/main/scripts/a2a_server.py"
click node_model_router "https://github.com/nullurl/marvin-adaptive-delivery/blob/main/scripts/model_routing.py"
click node_verification "https://github.com/nullurl/marvin-adaptive-delivery/blob/main/scripts/verification_guard.py"
click node_visual_guard "https://github.com/nullurl/marvin-adaptive-delivery/blob/main/scripts/visual_evidence_guard.py"
click node_visual_policy "https://github.com/nullurl/marvin-adaptive-delivery/blob/main/references/visual-reference-governance.md"
click node_harness "https://github.com/nullurl/marvin-adaptive-delivery/blob/main/references/harness-and-release.md"

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_delivery_skill,node_risk_flow,node_multi_agent,node_context,node_experience,node_user toneBlue
class node_a2a,node_sqlite,node_worker,node_verifier,node_recovery,node_model_router toneAmber
class node_init,node_templates,node_governance_lint toneMint
class node_verification,node_visual_guard,node_visual_policy,node_harness toneRose
```

## Components

### Delivery workflow

- [Delivery Skill](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/SKILL.md): `SKILL.md`
- [Risk-tiered flow](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/SKILL.md): `SKILL.md`
- [Agent coordination](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/references/long-task-governance.md): `references/long-task-governance.md`
- [Context governance](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/references/context-governance.md): `references/context-governance.md`
- [Experience methods](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/references/experience-catalog.md): `references/experience-catalog.md`

### Execution control

- [A2A control plane](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/scripts/a2a_server.py): `scripts/a2a_server.py`
- [Execution database](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/scripts/a2a_server.py): `scripts/a2a_server.py`
- **Worker agents**
- **Verifier**
- **Recovery worker**
- [Model profile router](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/scripts/model_routing.py): `scripts/model_routing.py`

### Project governance

- [Project initializer](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/scripts/init_project.py): `scripts/init_project.py`
- [Project templates](https://github.com/nullurl/marvin-adaptive-delivery/tree/main/assets/templates): `assets/templates`
- [Governance checks](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/scripts/lint_governance.py): `scripts/lint_governance.py`

### Evidence and validation

- [Verification receipts](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/scripts/verification_guard.py): `scripts/verification_guard.py`
- [Visual evidence guard](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/scripts/visual_evidence_guard.py): `scripts/visual_evidence_guard.py`
- [Visual reference governance](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/references/visual-reference-governance.md): `references/visual-reference-governance.md`
- [Harness and release](https://github.com/nullurl/marvin-adaptive-delivery/blob/main/references/harness-and-release.md): `references/harness-and-release.md`

### Other components

- **User**

## Connections

- User → Delivery Skill: requests delivery (evidence: `README.md`)
- Delivery Skill → Risk-tiered flow: selects flow (evidence: `README.md`)
- Risk-tiered flow → Agent coordination: coordinates work (evidence: `README.md`)
- Risk-tiered flow → Context governance: governs context (evidence: `README.md`)
- Risk-tiered flow → Experience methods: captures methods (evidence: `README.md`)
- User → Project initializer: initializes project (evidence: `README.md`)
- Project initializer → Project templates: copies templates (evidence: `README.md`)
- User → Governance checks: checks governance (evidence: `README.md`)
- Agent coordination → A2A control plane: creates tasks (evidence: `README.md`)
- A2A control plane → Execution database: persists state (evidence: `README.md`)
- A2A control plane → Worker agents: dispatches attempts (evidence: `README.md`)
- Worker agents → A2A control plane: sends events (evidence: `README.md`)
- A2A control plane → Verifier: provides candidates (evidence: `README.md`)
- Recovery worker → A2A control plane: resumes checkpoints (evidence: `README.md`)
- A2A control plane → Model profile router: resolves profiles (evidence: `scripts/a2a_server.py`)
- User → Verification receipts: runs verification (evidence: `README.md`)
- Verification receipts → Harness and release: records receipts (evidence: `README.md`)
- User → Visual evidence guard: checks receipt (evidence: `README.md`)
- Visual reference governance → Visual evidence guard: defines evidence (evidence: `README.md`)
