# saubakirov/trace-first-starter architecture

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

- Interactive diagram: https://gitdiagram.com/saubakirov/trace-first-starter
- Repository: https://github.com/saubakirov/trace-first-starter

## Overview

TFW is a human–AI workflow methodology and starter kit: a human chooses an Edition, copies it into a project, and follows its instructions to create durable task context, execute bounded work, and review results. The README documents Assisted handoffs and independent review, plus Full’s formal lifecycle and research, documentation, knowledge, release, update, configuration, and initialization workflows. The supplied tree is selective, so Edition and workflow nodes use documented paths; only the maintainer diagnostics’ implementation relationship is confirmed by sampled source.

Main entry points: [`editions/README.md`](https://github.com/saubakirov/trace-first-starter/blob/master/editions/README.md) (Edition choice), [`editions/02-assisted`](https://github.com/saubakirov/trace-first-starter/tree/master/editions/02-assisted) (Task traces), [`.tfw/workflows`](https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows) (Plan task), [`tools/tfw_doctor.py`](https://github.com/saubakirov/trace-first-starter/blob/master/tools/tfw_doctor.py) (Diagnostics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_adoption["Project Adoption"]
  node_edition_choice["Edition choice<br/>[README.md]"]
  node_assisted_edition["Assisted edition"]
  node_full_edition["Full framework<br/>[.tfw]"]
end

subgraph group_assisted["Assisted Workflow"]
  node_task_trace["Task traces"]
  node_handoff["Handoff"]
  node_independent_review["Independent review"]
end

subgraph group_full["Full Lifecycle"]
  node_plan["Plan task<br/>[workflows]"]
  node_execute["Execute handoff<br/>[workflows]"]
  node_review["Review work<br/>[workflows]"]
  node_research["Research workflow<br/>[workflows]"]
  node_docs["Documentation workflow<br/>[workflows]"]
  node_knowledge["Knowledge workflow<br/>[workflows]"]
  node_release["Release workflow<br/>[workflows]"]
  node_update["Update workflow<br/>[workflows]"]
  node_configure["Configuration workflow<br/>[workflows]"]
  node_initialize["Initialization workflow<br/>[workflows]"]
end

subgraph group_maintenance["Maintainer Support"]
  node_doctor["Diagnostics<br/>[tfw_doctor.py]"]
  node_state_readers["State readers<br/>[tfw_state.py]"]
end

node_human(("Human owner"))
node_agent(("AI agent"))

node_human -->|"chooses edition"| node_edition_choice
node_edition_choice -->|"selects"| node_assisted_edition
node_edition_choice -->|"selects"| node_full_edition
node_human -->|"authorizes work"| node_agent
node_agent -->|"records context"| node_task_trace
node_task_trace -.->|"supports handoff"| node_handoff
node_agent -->|"requests review"| node_independent_review
node_agent -->|"starts task"| node_plan
node_plan -->|"approves handoff"| node_execute
node_execute -->|"submits completion"| node_review
node_agent -->|"runs workflow"| node_research
node_agent -->|"runs workflow"| node_docs
node_agent -->|"runs workflow"| node_knowledge
node_agent -->|"runs workflow"| node_release
node_agent -->|"runs workflow"| node_update
node_agent -->|"runs workflow"| node_configure
node_agent -->|"runs workflow"| node_initialize
node_doctor -->|"reads task state"| node_state_readers

click node_edition_choice "https://github.com/saubakirov/trace-first-starter/blob/master/editions/README.md"
click node_assisted_edition "https://github.com/saubakirov/trace-first-starter/tree/master/editions/02-assisted"
click node_full_edition "https://github.com/saubakirov/trace-first-starter/tree/master/.tfw"
click node_task_trace "https://github.com/saubakirov/trace-first-starter/tree/master/editions/02-assisted"
click node_handoff "https://github.com/saubakirov/trace-first-starter/tree/master/editions/02-assisted"
click node_independent_review "https://github.com/saubakirov/trace-first-starter/tree/master/editions/02-assisted"
click node_plan "https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows"
click node_execute "https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows"
click node_review "https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows"
click node_research "https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows"
click node_docs "https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows"
click node_knowledge "https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows"
click node_release "https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows"
click node_update "https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows"
click node_configure "https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows"
click node_initialize "https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows"
click node_doctor "https://github.com/saubakirov/trace-first-starter/blob/master/tools/tfw_doctor.py"
click node_state_readers "https://github.com/saubakirov/trace-first-starter/blob/master/tools/tfw_state.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_edition_choice,node_assisted_edition,node_full_edition toneBlue
class node_task_trace,node_handoff,node_independent_review toneAmber
class node_plan,node_execute,node_review,node_research,node_docs,node_knowledge,node_release,node_update,node_configure,node_initialize toneMint
class node_doctor,node_state_readers toneRose
class node_human,node_agent toneIndigo
```

## Components

### Project Adoption

- [Edition choice](https://github.com/saubakirov/trace-first-starter/blob/master/editions/README.md): `editions/README.md`
- [Assisted edition](https://github.com/saubakirov/trace-first-starter/tree/master/editions/02-assisted): `editions/02-assisted`
- [Full framework](https://github.com/saubakirov/trace-first-starter/tree/master/.tfw): `.tfw`

### Assisted Workflow

- [Task traces](https://github.com/saubakirov/trace-first-starter/tree/master/editions/02-assisted): `editions/02-assisted`
- [Handoff](https://github.com/saubakirov/trace-first-starter/tree/master/editions/02-assisted): `editions/02-assisted`
- [Independent review](https://github.com/saubakirov/trace-first-starter/tree/master/editions/02-assisted): `editions/02-assisted`

### Full Lifecycle

- [Plan task](https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows): `.tfw/workflows`
- [Execute handoff](https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows): `.tfw/workflows`
- [Review work](https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows): `.tfw/workflows`
- [Research workflow](https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows): `.tfw/workflows`
- [Documentation workflow](https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows): `.tfw/workflows`
- [Knowledge workflow](https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows): `.tfw/workflows`
- [Release workflow](https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows): `.tfw/workflows`
- [Update workflow](https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows): `.tfw/workflows`
- [Configuration workflow](https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows): `.tfw/workflows`
- [Initialization workflow](https://github.com/saubakirov/trace-first-starter/tree/master/.tfw/workflows): `.tfw/workflows`

### Maintainer Support

- [Diagnostics](https://github.com/saubakirov/trace-first-starter/blob/master/tools/tfw_doctor.py): `tools/tfw_doctor.py`
- [State readers](https://github.com/saubakirov/trace-first-starter/blob/master/tools/tfw_state.py): `tools/tfw_state.py`

### Other components

- **Human owner**
- **AI agent**

## Connections

- Human owner → Edition choice: chooses edition (evidence: `README.md`)
- Edition choice → Assisted edition: selects (evidence: `README.md`)
- Edition choice → Full framework: selects (evidence: `README.md`)
- Human owner → AI agent: authorizes work (evidence: `README.md`)
- AI agent → Task traces: records context (evidence: `README.md`)
- Task traces → Handoff: supports handoff
- AI agent → Independent review: requests review (evidence: `README.md`)
- AI agent → Plan task: starts task (evidence: `README.md`)
- Plan task → Execute handoff: approves handoff (evidence: `README.md`)
- Execute handoff → Review work: submits completion (evidence: `README.md`)
- AI agent → Research workflow: runs workflow (evidence: `README.md`)
- AI agent → Documentation workflow: runs workflow (evidence: `README.md`)
- AI agent → Knowledge workflow: runs workflow (evidence: `README.md`)
- AI agent → Release workflow: runs workflow (evidence: `README.md`)
- AI agent → Update workflow: runs workflow (evidence: `README.md`)
- AI agent → Configuration workflow: runs workflow (evidence: `README.md`)
- AI agent → Initialization workflow: runs workflow (evidence: `README.md`)
- Diagnostics → State readers: reads task state (evidence: `tools/tfw_doctor.py`)
