# bkferareza/adapt architecture

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

- Interactive diagram: https://gitdiagram.com/bkferareza/adapt
- Repository: https://github.com/bkferareza/adapt

## Overview

ADAPT is a file-based governance framework for AI-assisted software work, not an application-code runtime. The principal workflow is to scaffold a project-specific governance instance from canonical artifacts, then use bounded human-directed handoffs and evidence to guide work; optional read-only commands inspect state, diagnose consistency, preview the next prompt, or summarize Git evidence. The graph preserves the documented governance lanes and tool capabilities. Source excerpts show the operator and state reader implementations, but not their complete internal wiring, so undocumented calls are omitted.

Main entry points: [`ADAPT/SCAFFOLD_WORKFLOW_AGENT.md`](https://github.com/bkferareza/adapt/blob/main/ADAPT/SCAFFOLD_WORKFLOW_AGENT.md) (Scaffold workflow), [`ADAPT/TOOLS/supporting_modules/operator.py`](https://github.com/bkferareza/adapt/blob/main/ADAPT/TOOLS/supporting_modules/operator.py) (Operator commands), [`ADAPT/CANONICAL_STARTERS/02_DIRECTOR_LANE`](https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS/02_DIRECTOR_LANE) (Director control), [`ADAPT/CANONICAL_STARTERS/03_WORKCELLS`](https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS/03_WORKCELLS) (Workcells)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_framework["Framework Source"]
  node_canonical["Canonical artifacts"]
  node_scaffold["Scaffold workflow"]
  node_deployment["Deployment modes"]
end

subgraph group_instance["Instance Governance"]
  node_instance_artifacts["Governance instance"]
  node_source_truth["Source truth"]
  node_director["Director control"]
  node_workcells["Workcells"]
  node_integration["Integration lane"]
  node_validation["Validation lane"]
  node_handoffs["Handoffs"]
  node_guardrails["Guardrails"]
  node_support_lanes["Supporting lanes"]
end

subgraph group_tools["Operator Tooling"]
  node_cli["Tool entry point<br/>[adapt.py]"]
  node_operator["Operator commands<br/>[operator.py]"]
  node_state_reader["State reader<br/>[state_reader.py]"]
end

subgraph group_evidence["Evidence and Review"]
  node_git_evidence["Git evidence<br/>[operator.py]"]
end

node_agent(("AI agent"))
node_maintainer(("Human operator"))
node_project["Project repository"]
node_local_git[("Local Git metadata")]

node_agent -->|"starts scaffold"| node_scaffold
node_scaffold -->|"uses artifacts"| node_canonical
node_scaffold -->|"selects mode"| node_deployment
node_scaffold -->|"creates instance"| node_instance_artifacts
node_project -->|"supplies project"| node_scaffold
node_maintainer -->|"approves work"| node_director
node_source_truth -->|"grounds decisions"| node_director
node_director -->|"assigns bounded work"| node_workcells
node_workcells -->|"records handoffs"| node_handoffs
node_integration -->|"defines contracts"| node_validation
node_guardrails -->|"constrains scope"| node_workcells
node_maintainer -.->|"runs commands"| node_cli
node_cli -->|"dispatches main"| node_operator
node_operator -->|"inspects instance"| node_instance_artifacts
node_operator -->|"computes evidence"| node_git_evidence
node_git_evidence -->|"reads metadata"| node_local_git
node_maintainer -->|"reviews evidence"| node_validation

click node_canonical "https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS"
click node_scaffold "https://github.com/bkferareza/adapt/blob/main/ADAPT/SCAFFOLD_WORKFLOW_AGENT.md"
click node_deployment "https://github.com/bkferareza/adapt/blob/main/ADAPT/DEPLOYMENT_MODES.md"
click node_instance_artifacts "https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS"
click node_source_truth "https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS/01_SOURCE_TRUTH"
click node_director "https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS/02_DIRECTOR_LANE"
click node_workcells "https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS/03_WORKCELLS"
click node_integration "https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS/04_INTEGRATION"
click node_validation "https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS/05_VALIDATION"
click node_handoffs "https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS/06_HANDOFFS"
click node_guardrails "https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS/07_GUARDRAILS"
click node_support_lanes "https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS"
click node_cli "https://github.com/bkferareza/adapt/blob/main/ADAPT/TOOLS/adapt.py"
click node_operator "https://github.com/bkferareza/adapt/blob/main/ADAPT/TOOLS/supporting_modules/operator.py"
click node_state_reader "https://github.com/bkferareza/adapt/blob/main/ADAPT/TOOLS/supporting_modules/state_reader.py"
click node_git_evidence "https://github.com/bkferareza/adapt/blob/main/ADAPT/TOOLS/supporting_modules/operator.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_canonical,node_scaffold,node_deployment toneBlue
class node_instance_artifacts,node_source_truth,node_director,node_workcells,node_integration,node_validation,node_handoffs,node_guardrails,node_support_lanes,node_local_git toneAmber
class node_cli,node_operator,node_state_reader toneMint
class node_git_evidence toneRose
class node_agent,node_maintainer,node_project toneIndigo
```

## Components

### Framework Source

- [Canonical artifacts](https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS): `ADAPT/CANONICAL_STARTERS`
- [Scaffold workflow](https://github.com/bkferareza/adapt/blob/main/ADAPT/SCAFFOLD_WORKFLOW_AGENT.md): `ADAPT/SCAFFOLD_WORKFLOW_AGENT.md`
- [Deployment modes](https://github.com/bkferareza/adapt/blob/main/ADAPT/DEPLOYMENT_MODES.md): `ADAPT/DEPLOYMENT_MODES.md`

### Instance Governance

- [Governance instance](https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS): `ADAPT/CANONICAL_STARTERS`
- [Source truth](https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS/01_SOURCE_TRUTH): `ADAPT/CANONICAL_STARTERS/01_SOURCE_TRUTH`
- [Director control](https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS/02_DIRECTOR_LANE): `ADAPT/CANONICAL_STARTERS/02_DIRECTOR_LANE`
- [Workcells](https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS/03_WORKCELLS): `ADAPT/CANONICAL_STARTERS/03_WORKCELLS`
- [Integration lane](https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS/04_INTEGRATION): `ADAPT/CANONICAL_STARTERS/04_INTEGRATION`
- [Validation lane](https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS/05_VALIDATION): `ADAPT/CANONICAL_STARTERS/05_VALIDATION`
- [Handoffs](https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS/06_HANDOFFS): `ADAPT/CANONICAL_STARTERS/06_HANDOFFS`
- [Guardrails](https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS/07_GUARDRAILS): `ADAPT/CANONICAL_STARTERS/07_GUARDRAILS`
- [Supporting lanes](https://github.com/bkferareza/adapt/tree/main/ADAPT/CANONICAL_STARTERS): `ADAPT/CANONICAL_STARTERS`

### Operator Tooling

- [Tool entry point](https://github.com/bkferareza/adapt/blob/main/ADAPT/TOOLS/adapt.py): `ADAPT/TOOLS/adapt.py`
- [Operator commands](https://github.com/bkferareza/adapt/blob/main/ADAPT/TOOLS/supporting_modules/operator.py): `ADAPT/TOOLS/supporting_modules/operator.py`
- [State reader](https://github.com/bkferareza/adapt/blob/main/ADAPT/TOOLS/supporting_modules/state_reader.py): `ADAPT/TOOLS/supporting_modules/state_reader.py`

### Evidence and Review

- [Git evidence](https://github.com/bkferareza/adapt/blob/main/ADAPT/TOOLS/supporting_modules/operator.py): `ADAPT/TOOLS/supporting_modules/operator.py`

### Other components

- **AI agent**
- **Human operator**
- **Project repository**
- **Local Git metadata**

## Connections

- AI agent → Scaffold workflow: starts scaffold (evidence: `README.md`)
- Scaffold workflow → Canonical artifacts: uses artifacts (evidence: `README.md`)
- Scaffold workflow → Deployment modes: selects mode (evidence: `README.md`)
- Scaffold workflow → Governance instance: creates instance (evidence: `README.md`)
- Project repository → Scaffold workflow: supplies project (evidence: `README.md`)
- Human operator → Director control: approves work (evidence: `README.md`)
- Source truth → Director control: grounds decisions (evidence: `README.md`)
- Director control → Workcells: assigns bounded work (evidence: `README.md`)
- Workcells → Handoffs: records handoffs (evidence: `README.md`)
- Integration lane → Validation lane: defines contracts (evidence: `README.md`)
- Guardrails → Workcells: constrains scope (evidence: `README.md`)
- Human operator → Tool entry point: runs commands (evidence: `README.md`)
- Tool entry point → Operator commands: dispatches main (evidence: `ADAPT/TOOLS/adapt.py`)
- Operator commands → Governance instance: inspects instance (evidence: `README.md`)
- Operator commands → Git evidence: computes evidence (evidence: `README.md`)
- Git evidence → Local Git metadata: reads metadata (evidence: `README.md`)
- Human operator → Validation lane: reviews evidence (evidence: `README.md`)