# simonli357/t3-workflows architecture

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

- Interactive diagram: https://gitdiagram.com/simonli357/t3-workflows
- Repository: https://github.com/simonli357/t3-workflows

## Overview

T3 Workflows is a global CLI and agent skill for creating and managing T3 sessions, coordinating workers across linked environments, and maintaining a custom T3 build. The main user flow resolves a project and profile, then plans or runs a spawn/fork against a T3 server; related commands find sessions, assess capacity, move workers, and manage peers. Separate branches review upstream changes and release the custom build. Deployment helpers validate and reconcile activation evidence. The README documents several capabilities whose implementation was not sampled, so their internal links are omitted rather than inferred.

Main entry points: [`bin/t3w.mjs`](https://github.com/simonli357/t3-workflows/blob/main/bin/t3w.mjs) (T3 workflows CLI), [`skills/t3-fork-session/scripts/fork-session.mjs`](https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/fork-session.mjs) (Spawn and fork), [`release/release.py`](https://github.com/simonli357/t3-workflows/blob/main/release/release.py) (Build and activate), [`deploy/cli.mjs`](https://github.com/simonli357/t3-workflows/blob/main/deploy/cli.mjs) (Deployment commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_session["Session workflows"]
  node_t3cli["T3 workflows CLI<br/>[t3w.mjs]"]
  node_projectconfig["Project resolution<br/>[config.mjs]"]
  node_sessioncreate["Spawn and fork<br/>[fork-session.mjs]"]
  node_sessionsearch["Session history<br/>[find-session.mjs]"]
end

subgraph group_coordination["Worker coordination"]
  node_capacity["Capacity checks<br/>[check-capacity.mjs]"]
  node_capacitydata["Host capacity data<br/>[capacity-load.mjs]"]
  node_peers["Peer links<br/>[peers.mjs]"]
  node_protocol["Environment protocol<br/>[protocol.mjs]"]
  node_sessionmove["Session moves<br/>[move-session.mjs]"]
  node_profile["Worker profiles<br/>[worker-profile.mjs]"]
  node_refresh["Refresh fork bases<br/>[refresh-bases.mjs]"]
  node_stats["Worker statistics<br/>[report-stats.mjs]"]
  node_settle["Worker settlement<br/>[settle-worker.mjs]"]
end

subgraph group_maintenance["Build maintenance"]
  node_release["Build and activate<br/>[release.py]"]
  node_migration["Migration rehearsal"]
  node_trial["Release trial<br/>[trial.py]"]
end

subgraph group_deployment["Deployment safety"]
  node_deploycli["Deployment commands<br/>[cli.mjs]"]
  node_deploynative["Native deployment verifier<br/>[native.mjs]"]
  node_deploycore["Deployment validation<br/>[core.mjs]"]
  node_recovery["Failure recovery<br/>[recovery.mjs]"]
  node_prepared["Prepared-state review"]
end

subgraph group_upstream["Upstream review"]
  node_upstream["Upstream change review<br/>[check-upstream.mjs]"]
end

node_user(("CLI user"))
node_t3server["T3 server"]
node_gitremote["Upstream Git remote"]

node_user -->|"runs commands"| node_t3cli
node_t3cli -->|"dispatches sessions"| node_sessioncreate
node_t3cli -->|"resolves projects"| node_projectconfig
node_sessioncreate -->|"resolves project"| node_projectconfig
node_sessioncreate -->|"plans and creates"| node_t3server
node_t3cli -.->|"dispatches find"| node_sessionsearch
node_t3cli -.->|"dispatches capacity"| node_capacity
node_capacity -->|"reads capacity"| node_capacitydata
node_t3cli -.->|"dispatches peer commands"| node_peers
node_sessioncreate -->|"uses protocol"| node_protocol
node_sessioncreate -->|"uses remote environments"| node_peers
node_t3cli -.->|"dispatches moves"| node_sessionmove
node_t3cli -.->|"dispatches profiles"| node_profile
node_t3cli -.->|"dispatches refresh"| node_refresh
node_t3cli -.->|"dispatches reports"| node_stats
node_t3cli -.->|"dispatches settlement"| node_settle
node_user -->|"requests release"| node_release
node_release -->|"rehearses migrations"| node_migration
node_release -->|"runs release trial"| node_trial
node_user -.->|"runs deployment"| node_deploycli
node_deploycli -->|"invokes verifier"| node_deploynative
node_deploycli -->|"uses validation"| node_deploycore
node_deploynative -->|"validates deployment"| node_deploycore
node_deploynative -->|"checks recovery"| node_recovery
node_recovery -->|"uses validation"| node_deploycore
node_recovery -->|"inspects prepared state"| node_prepared
node_user -->|"requests review"| node_upstream
node_upstream -->|"fetches changes"| node_gitremote

click node_t3cli "https://github.com/simonli357/t3-workflows/blob/main/bin/t3w.mjs"
click node_projectconfig "https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/config.mjs"
click node_sessioncreate "https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/fork-session.mjs"
click node_sessionsearch "https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/find-session.mjs"
click node_capacity "https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/check-capacity.mjs"
click node_capacitydata "https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/capacity-load.mjs"
click node_peers "https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/peers.mjs"
click node_protocol "https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/protocol.mjs"
click node_sessionmove "https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/move-session.mjs"
click node_profile "https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/worker-profile.mjs"
click node_refresh "https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/refresh-bases.mjs"
click node_stats "https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/report-stats.mjs"
click node_settle "https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/settle-worker.mjs"
click node_release "https://github.com/simonli357/t3-workflows/blob/main/release/release.py"
click node_trial "https://github.com/simonli357/t3-workflows/blob/main/release/trial.py"
click node_deploycli "https://github.com/simonli357/t3-workflows/blob/main/deploy/cli.mjs"
click node_deploynative "https://github.com/simonli357/t3-workflows/blob/main/deploy/native.mjs"
click node_deploycore "https://github.com/simonli357/t3-workflows/blob/main/deploy/core.mjs"
click node_recovery "https://github.com/simonli357/t3-workflows/blob/main/deploy/recovery.mjs"
click node_prepared "https://github.com/simonli357/t3-workflows/blob/main/deploy/prepared-review.mjs"
click node_upstream "https://github.com/simonli357/t3-workflows/blob/main/bin/check-upstream.mjs"

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_t3cli,node_projectconfig,node_sessioncreate,node_sessionsearch,node_user toneBlue
class node_capacity,node_capacitydata,node_peers,node_protocol,node_sessionmove,node_profile,node_refresh,node_stats,node_settle toneAmber
class node_release,node_migration,node_trial,node_t3server toneMint
class node_deploycli,node_deploynative,node_deploycore,node_recovery,node_prepared toneRose
class node_upstream,node_gitremote toneIndigo
```

## Components

### Session workflows

- [T3 workflows CLI](https://github.com/simonli357/t3-workflows/blob/main/bin/t3w.mjs): `bin/t3w.mjs`
- [Project resolution](https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/config.mjs): `skills/t3-fork-session/scripts/config.mjs`
- [Spawn and fork](https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/fork-session.mjs): `skills/t3-fork-session/scripts/fork-session.mjs`
- [Session history](https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/find-session.mjs): `skills/t3-fork-session/scripts/find-session.mjs`

### Worker coordination

- [Capacity checks](https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/check-capacity.mjs): `skills/t3-fork-session/scripts/check-capacity.mjs`
- [Host capacity data](https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/capacity-load.mjs): `skills/t3-fork-session/scripts/capacity-load.mjs`
- [Peer links](https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/peers.mjs): `skills/t3-fork-session/scripts/peers.mjs`
- [Environment protocol](https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/protocol.mjs): `skills/t3-fork-session/scripts/protocol.mjs`
- [Session moves](https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/move-session.mjs): `skills/t3-fork-session/scripts/move-session.mjs`
- [Worker profiles](https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/worker-profile.mjs): `skills/t3-fork-session/scripts/worker-profile.mjs`
- [Refresh fork bases](https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/refresh-bases.mjs): `skills/t3-fork-session/scripts/refresh-bases.mjs`
- [Worker statistics](https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/report-stats.mjs): `skills/t3-fork-session/scripts/report-stats.mjs`
- [Worker settlement](https://github.com/simonli357/t3-workflows/blob/main/skills/t3-fork-session/scripts/settle-worker.mjs): `skills/t3-fork-session/scripts/settle-worker.mjs`

### Build maintenance

- [Build and activate](https://github.com/simonli357/t3-workflows/blob/main/release/release.py): `release/release.py`
- **Migration rehearsal**
- [Release trial](https://github.com/simonli357/t3-workflows/blob/main/release/trial.py): `release/trial.py`

### Deployment safety

- [Deployment commands](https://github.com/simonli357/t3-workflows/blob/main/deploy/cli.mjs): `deploy/cli.mjs`
- [Native deployment verifier](https://github.com/simonli357/t3-workflows/blob/main/deploy/native.mjs): `deploy/native.mjs`
- [Deployment validation](https://github.com/simonli357/t3-workflows/blob/main/deploy/core.mjs): `deploy/core.mjs`
- [Failure recovery](https://github.com/simonli357/t3-workflows/blob/main/deploy/recovery.mjs): `deploy/recovery.mjs`
- [Prepared-state review](https://github.com/simonli357/t3-workflows/blob/main/deploy/prepared-review.mjs): `deploy/prepared-review.mjs`

### Upstream review

- [Upstream change review](https://github.com/simonli357/t3-workflows/blob/main/bin/check-upstream.mjs): `bin/check-upstream.mjs`

### Other components

- **CLI user**
- **T3 server**
- **Upstream Git remote**

## Connections

- CLI user → T3 workflows CLI: runs commands
- T3 workflows CLI → Spawn and fork: dispatches sessions (evidence: `bin/t3w.mjs`)
- T3 workflows CLI → Project resolution: resolves projects (evidence: `bin/t3w.mjs`)
- Spawn and fork → Project resolution: resolves project (evidence: `skills/t3-fork-session/scripts/fork-session.mjs`)
- Spawn and fork → T3 server: plans and creates
- T3 workflows CLI → Session history: dispatches find
- T3 workflows CLI → Capacity checks: dispatches capacity
- Capacity checks → Host capacity data: reads capacity (evidence: `skills/t3-fork-session/scripts/check-capacity.mjs`)
- T3 workflows CLI → Peer links: dispatches peer commands
- Spawn and fork → Environment protocol: uses protocol (evidence: `skills/t3-fork-session/scripts/fork-session.mjs`)
- Spawn and fork → Peer links: uses remote environments (evidence: `skills/t3-fork-session/scripts/fork-session.mjs`)
- T3 workflows CLI → Session moves: dispatches moves
- T3 workflows CLI → Worker profiles: dispatches profiles
- T3 workflows CLI → Refresh fork bases: dispatches refresh
- T3 workflows CLI → Worker statistics: dispatches reports
- T3 workflows CLI → Worker settlement: dispatches settlement
- CLI user → Build and activate: requests release
- Build and activate → Migration rehearsal: rehearses migrations
- Build and activate → Release trial: runs release trial (evidence: `release/trial.py`)
- CLI user → Deployment commands: runs deployment
- Deployment commands → Native deployment verifier: invokes verifier (evidence: `deploy/cli.mjs`)
- Deployment commands → Deployment validation: uses validation (evidence: `deploy/cli.mjs`)
- Native deployment verifier → Deployment validation: validates deployment (evidence: `deploy/native.mjs`)
- Native deployment verifier → Failure recovery: checks recovery (evidence: `deploy/native.mjs`)
- Failure recovery → Deployment validation: uses validation (evidence: `deploy/recovery.mjs`)
- Failure recovery → Prepared-state review: inspects prepared state (evidence: `deploy/recovery.mjs`)
- CLI user → Upstream change review: requests review
- Upstream change review → Upstream Git remote: fetches changes
