# tremtec/maestro architecture

> Architecture diagram of the GitHub repository tremtec/maestro, 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/tremtec/maestro
- Repository: https://github.com/tremtec/maestro

## Overview

Maestro is a Go CLI for initializing and maintaining an OpenCode-based squad setup, and for submitting workflow prompts to an OpenCode CLI or server. The documented workflow is Discovery → Synthesis → Build → Quality Gate, but the sampled `run` implementation delegates execution and does not expose those internal stages. The graph therefore shows the real CLI dispatch and scaffold/run behavior, while retaining the documented phase workflow as an unverified subsystem. `update`, `drop`, and self-upgrade are separate product capabilities; workflow state is documented as Markdown in `.maestro/`.

Main entry points: [`cmd/root.go`](https://github.com/tremtec/maestro/blob/main/cmd/root.go) (Command dispatch), [`cmd/run.go`](https://github.com/tremtec/maestro/blob/main/cmd/run.go) (Run command), [`internal/scaffold/scaffold.go`](https://github.com/tremtec/maestro/blob/main/internal/scaffold/scaffold.go) (Project scaffolder), [`main.go`](https://github.com/tremtec/maestro/blob/main/main.go) (Program entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry"]
  node_main["Program entry<br/>[main.go]"]
  node_commands["Command dispatch<br/>[root.go]"]
end

subgraph group_setup["Project setup"]
  node_initcmd["Init command<br/>[init.go]"]
  node_scaffold["Project scaffolder<br/>[scaffold.go]"]
  node_agenttemplates["Squad templates"]
  node_projectfiles["Project config and agents"]
end

subgraph group_execution["Workflow execution"]
  node_state[("Markdown state")]
  node_runcommand["Run command<br/>[run.go]"]
  node_phases["Four workflow phases"]
  node_runtimeinterface["Runtime abstraction<br/>[runtime.go]"]
  node_opencoderuntime["OpenCode runtime adapter<br/>[opencode.go]"]
end

subgraph group_maintenance["Maintenance"]
  node_updatecmd["Update command<br/>[update.go]"]
  node_dropcmd["Drop command<br/>[drop.go]"]
  node_upgradecmd["Upgrade command<br/>[upgrade.go]"]
end

node_user(("User"))
node_opencodecli{{"OpenCode CLI"}}
node_opencodeapi{{"OpenCode server"}}
node_githubreleases{{"GitHub releases"}}

node_user -->|"invokes"| node_main
node_main -->|"executes"| node_commands
node_commands -->|"dispatches"| node_initcmd
node_initcmd -->|"initializes"| node_scaffold
node_scaffold -->|"reads"| node_agenttemplates
node_scaffold -->|"writes"| node_projectfiles
node_user -->|"submits prompt"| node_runcommand
node_commands -->|"dispatches"| node_runcommand
node_runcommand -->|"invokes when available"| node_opencodecli
node_runcommand -->|"posts otherwise"| node_opencodeapi
node_opencodeapi -->|"returns output"| node_runcommand
node_runcommand -.->|"requests workflow"| node_phases
node_phases -.->|"records artifacts"| node_state
node_runtimeinterface -->|"registers implementation"| node_opencoderuntime
node_commands -->|"dispatches"| node_updatecmd
node_updatecmd -->|"resets agents"| node_scaffold
node_commands -->|"dispatches"| node_dropcmd
node_dropcmd -->|"removes setup"| node_scaffold
node_commands -->|"dispatches"| node_upgradecmd
node_upgradecmd -->|"checks and downloads"| node_githubreleases

click node_main "https://github.com/tremtec/maestro/blob/main/main.go"
click node_commands "https://github.com/tremtec/maestro/blob/main/cmd/root.go"
click node_initcmd "https://github.com/tremtec/maestro/blob/main/cmd/init.go"
click node_scaffold "https://github.com/tremtec/maestro/blob/main/internal/scaffold/scaffold.go"
click node_agenttemplates "https://github.com/tremtec/maestro/tree/main/internal/scaffold/templates"
click node_runcommand "https://github.com/tremtec/maestro/blob/main/cmd/run.go"
click node_runtimeinterface "https://github.com/tremtec/maestro/blob/main/internal/runtime/runtime.go"
click node_opencoderuntime "https://github.com/tremtec/maestro/blob/main/internal/runtime/opencode.go"
click node_updatecmd "https://github.com/tremtec/maestro/blob/main/cmd/update.go"
click node_dropcmd "https://github.com/tremtec/maestro/blob/main/cmd/drop.go"
click node_upgradecmd "https://github.com/tremtec/maestro/blob/main/cmd/upgrade.go"

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_main,node_commands,node_user toneBlue
class node_initcmd,node_scaffold,node_agenttemplates,node_projectfiles toneAmber
class node_state,node_runcommand,node_phases,node_runtimeinterface,node_opencoderuntime,node_opencodeapi toneMint
class node_updatecmd,node_dropcmd,node_upgradecmd toneRose
class node_opencodecli,node_githubreleases toneIndigo
```

## Components

### CLI entry

- [Program entry](https://github.com/tremtec/maestro/blob/main/main.go): `main.go`
- [Command dispatch](https://github.com/tremtec/maestro/blob/main/cmd/root.go): `cmd/root.go`

### Project setup

- [Init command](https://github.com/tremtec/maestro/blob/main/cmd/init.go): `cmd/init.go`
- [Project scaffolder](https://github.com/tremtec/maestro/blob/main/internal/scaffold/scaffold.go): `internal/scaffold/scaffold.go`
- [Squad templates](https://github.com/tremtec/maestro/tree/main/internal/scaffold/templates): `internal/scaffold/templates`
- **Project config and agents**

### Workflow execution

- **Markdown state**
- [Run command](https://github.com/tremtec/maestro/blob/main/cmd/run.go): `cmd/run.go`
- **Four workflow phases**
- [Runtime abstraction](https://github.com/tremtec/maestro/blob/main/internal/runtime/runtime.go): `internal/runtime/runtime.go`
- [OpenCode runtime adapter](https://github.com/tremtec/maestro/blob/main/internal/runtime/opencode.go): `internal/runtime/opencode.go`

### Maintenance

- [Update command](https://github.com/tremtec/maestro/blob/main/cmd/update.go): `cmd/update.go`
- [Drop command](https://github.com/tremtec/maestro/blob/main/cmd/drop.go): `cmd/drop.go`
- [Upgrade command](https://github.com/tremtec/maestro/blob/main/cmd/upgrade.go): `cmd/upgrade.go`

### Other components

- **User**
- **OpenCode CLI**
- **OpenCode server**
- **GitHub releases**

## Connections

- User → Program entry: invokes (evidence: `README.md`)
- Program entry → Command dispatch: executes (evidence: `main.go`)
- Command dispatch → Init command: dispatches (evidence: `cmd/init.go`)
- Init command → Project scaffolder: initializes (evidence: `cmd/init.go`)
- Project scaffolder → Squad templates: reads (evidence: `internal/scaffold/scaffold.go`)
- Project scaffolder → Project config and agents: writes (evidence: `internal/scaffold/scaffold.go`)
- User → Run command: submits prompt (evidence: `README.md`)
- Command dispatch → Run command: dispatches (evidence: `cmd/run.go`)
- Run command → OpenCode CLI: invokes when available (evidence: `cmd/run.go`)
- Run command → OpenCode server: posts otherwise (evidence: `cmd/run.go`)
- OpenCode server → Run command: returns output (evidence: `cmd/run.go`)
- Run command → Four workflow phases: requests workflow (evidence: `README.md`)
- Four workflow phases → Markdown state: records artifacts (evidence: `README.md`)
- Runtime abstraction → OpenCode runtime adapter: registers implementation (evidence: `internal/runtime/opencode.go`)
- Command dispatch → Update command: dispatches (evidence: `cmd/update.go`)
- Update command → Project scaffolder: resets agents (evidence: `cmd/update.go`)
- Command dispatch → Drop command: dispatches (evidence: `cmd/drop.go`)
- Drop command → Project scaffolder: removes setup (evidence: `cmd/drop.go`)
- Command dispatch → Upgrade command: dispatches (evidence: `cmd/upgrade.go`)
- Upgrade command → GitHub releases: checks and downloads (evidence: `cmd/upgrade.go`)
