# lerugray/generalstaff architecture

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

- Interactive diagram: https://gitdiagram.com/lerugray/generalstaff
- Repository: https://github.com/lerugray/generalstaff

## Overview

GeneralStaff is a local dispatcher and verification gate for AI coding work. The main workflow queues bounded project tasks, runs an engineer, verifies the resulting change, obtains an independent scope-match review, and records an auditable outcome; failed checks are rolled back. A separate verify-only workflow checks externally created changes in an isolated worktree. The repository also documents autonomous dispatch, persistent aides, phase management, and a local dashboard. Some relationships below are based on README descriptions because the relevant implementation excerpts were not shown.

Main entry points: [`src/cycle.ts`](https://github.com/lerugray/generalstaff/blob/master/src/cycle.ts) (Cycle dispatcher), [`src/cli.ts`](https://github.com/lerugray/generalstaff/blob/master/src/cli.ts) (CLI), [`src/verify_only/run.ts`](https://github.com/lerugray/generalstaff/blob/master/src/verify_only/run.ts) (Isolated verify run), [`src/engineer.ts`](https://github.com/lerugray/generalstaff/blob/master/src/engineer.ts) (Engineer runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dispatch["Work dispatch"]
  node_cli["CLI<br/>[cli.ts]"]
  node_projects["Project config<br/>[projects.ts]"]
  node_tasks["Task queue<br/>[tasks.ts]"]
  node_cycle["Cycle dispatcher<br/>[cycle.ts]"]
  node_engineer["Engineer runner<br/>[engineer.ts]"]
  node_providers["Engineer providers<br/>[aider.ts]"]
end

subgraph group_gate["Verification gate"]
  node_verification["Change verification<br/>[verification.ts]"]
  node_reviewer["Scope reviewer<br/>[reviewer.ts]"]
  node_verify_cli["Verify-only CLI<br/>[cli.ts]"]
  node_verify_run["Isolated verify run<br/>[run.ts]"]
  node_verify_git["Verify Git operations<br/>[git.ts]"]
  node_verify_runner["Command runner<br/>[runner.ts]"]
  node_digest["Change digest<br/>[digest.ts]"]
end

subgraph group_records["State and audit"]
  node_state[("Project state<br/>[state.ts]")]
  node_audit[("Cycle audit log<br/>[audit.ts]")]
end

subgraph group_optional["Optional capabilities"]
  node_autonomous["Autonomous sessions"]
  node_aides["Persistent aides<br/>[aides.ts]"]
end

subgraph group_dashboard["Local dashboard"]
  node_server["Dashboard server<br/>[server.ts]"]
  node_fleet["Fleet overview<br/>[fleet_overview.ts]"]
  node_phase["Phase management<br/>[phase.ts]"]
  node_layout["Page layout<br/>[layout.ts]"]
end

node_user(("Project owner"))

node_user -->|"queues work"| node_cli
node_cli -->|"adds tasks"| node_tasks
node_cli -->|"starts cycle"| node_cycle
node_cycle -.->|"runs engineer"| node_engineer
node_engineer -->|"selects provider"| node_providers
node_cycle -->|"checks changes"| node_verification
node_cycle -->|"requests review"| node_reviewer
node_cycle -.->|"records state"| node_state
node_engineer -->|"appends events"| node_audit
node_cli -->|"starts verify-only"| node_verify_cli
node_verify_cli -->|"runs check"| node_verify_run
node_verify_run -->|"manages worktree"| node_verify_git
node_verify_run -->|"runs verification"| node_verify_runner
node_verify_run -->|"requests review"| node_reviewer
node_verify_cli -->|"checks digest"| node_digest
node_cycle -.->|"records cycle"| node_audit
node_user -->|"enables mode"| node_autonomous
node_autonomous -->|"routes work"| node_cycle
node_user -->|"registers aides"| node_aides
node_user -->|"opens dashboard"| node_server
node_server -->|"renders overview"| node_fleet
node_server -->|"routes requests"| node_phase
node_phase -->|"wraps page"| node_layout

click node_cli "https://github.com/lerugray/generalstaff/blob/master/src/cli.ts"
click node_projects "https://github.com/lerugray/generalstaff/blob/master/src/projects.ts"
click node_tasks "https://github.com/lerugray/generalstaff/blob/master/src/tasks.ts"
click node_cycle "https://github.com/lerugray/generalstaff/blob/master/src/cycle.ts"
click node_engineer "https://github.com/lerugray/generalstaff/blob/master/src/engineer.ts"
click node_providers "https://github.com/lerugray/generalstaff/blob/master/src/engineer_providers/aider.ts"
click node_verification "https://github.com/lerugray/generalstaff/blob/master/src/verification.ts"
click node_reviewer "https://github.com/lerugray/generalstaff/blob/master/src/reviewer.ts"
click node_verify_cli "https://github.com/lerugray/generalstaff/blob/master/src/verify_only/cli.ts"
click node_verify_run "https://github.com/lerugray/generalstaff/blob/master/src/verify_only/run.ts"
click node_verify_git "https://github.com/lerugray/generalstaff/blob/master/src/verify_only/git.ts"
click node_verify_runner "https://github.com/lerugray/generalstaff/blob/master/src/verify_only/runner.ts"
click node_digest "https://github.com/lerugray/generalstaff/blob/master/src/verify_only/digest.ts"
click node_state "https://github.com/lerugray/generalstaff/blob/master/src/state.ts"
click node_audit "https://github.com/lerugray/generalstaff/blob/master/src/audit.ts"
click node_autonomous "https://github.com/lerugray/generalstaff/blob/master/src/autonomous_session.ts"
click node_aides "https://github.com/lerugray/generalstaff/blob/master/src/aides.ts"
click node_server "https://github.com/lerugray/generalstaff/blob/master/src/server.ts"
click node_fleet "https://github.com/lerugray/generalstaff/blob/master/src/views/fleet_overview.ts"
click node_phase "https://github.com/lerugray/generalstaff/blob/master/src/server/routes/phase.ts"
click node_layout "https://github.com/lerugray/generalstaff/blob/master/src/server/templates/layout.ts"

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_cli,node_projects,node_tasks,node_cycle,node_engineer,node_providers toneBlue
class node_verification,node_reviewer,node_verify_cli,node_verify_run,node_verify_git,node_verify_runner,node_digest toneAmber
class node_state,node_audit toneMint
class node_autonomous,node_aides toneRose
class node_server,node_fleet,node_phase,node_layout,node_user toneIndigo
```

## Components

### Work dispatch

- [CLI](https://github.com/lerugray/generalstaff/blob/master/src/cli.ts): `src/cli.ts`
- [Project config](https://github.com/lerugray/generalstaff/blob/master/src/projects.ts): `src/projects.ts`
- [Task queue](https://github.com/lerugray/generalstaff/blob/master/src/tasks.ts): `src/tasks.ts`
- [Cycle dispatcher](https://github.com/lerugray/generalstaff/blob/master/src/cycle.ts): `src/cycle.ts`
- [Engineer runner](https://github.com/lerugray/generalstaff/blob/master/src/engineer.ts): `src/engineer.ts`
- [Engineer providers](https://github.com/lerugray/generalstaff/blob/master/src/engineer_providers/aider.ts): `src/engineer_providers/aider.ts`

### Verification gate

- [Change verification](https://github.com/lerugray/generalstaff/blob/master/src/verification.ts): `src/verification.ts`
- [Scope reviewer](https://github.com/lerugray/generalstaff/blob/master/src/reviewer.ts): `src/reviewer.ts`
- [Verify-only CLI](https://github.com/lerugray/generalstaff/blob/master/src/verify_only/cli.ts): `src/verify_only/cli.ts`
- [Isolated verify run](https://github.com/lerugray/generalstaff/blob/master/src/verify_only/run.ts): `src/verify_only/run.ts`
- [Verify Git operations](https://github.com/lerugray/generalstaff/blob/master/src/verify_only/git.ts): `src/verify_only/git.ts`
- [Command runner](https://github.com/lerugray/generalstaff/blob/master/src/verify_only/runner.ts): `src/verify_only/runner.ts`
- [Change digest](https://github.com/lerugray/generalstaff/blob/master/src/verify_only/digest.ts): `src/verify_only/digest.ts`

### State and audit

- [Project state](https://github.com/lerugray/generalstaff/blob/master/src/state.ts): `src/state.ts`
- [Cycle audit log](https://github.com/lerugray/generalstaff/blob/master/src/audit.ts): `src/audit.ts`

### Optional capabilities

- [Autonomous sessions](https://github.com/lerugray/generalstaff/blob/master/src/autonomous_session.ts): `src/autonomous_session.ts`
- [Persistent aides](https://github.com/lerugray/generalstaff/blob/master/src/aides.ts): `src/aides.ts`

### Local dashboard

- [Dashboard server](https://github.com/lerugray/generalstaff/blob/master/src/server.ts): `src/server.ts`
- [Fleet overview](https://github.com/lerugray/generalstaff/blob/master/src/views/fleet_overview.ts): `src/views/fleet_overview.ts`
- [Phase management](https://github.com/lerugray/generalstaff/blob/master/src/server/routes/phase.ts): `src/server/routes/phase.ts`
- [Page layout](https://github.com/lerugray/generalstaff/blob/master/src/server/templates/layout.ts): `src/server/templates/layout.ts`

### Other components

- **Project owner**

## Connections

- Project owner → CLI: queues work (evidence: `README.md`)
- CLI → Task queue: adds tasks (evidence: `README.md`)
- CLI → Cycle dispatcher: starts cycle (evidence: `README.md`)
- Cycle dispatcher → Engineer runner: runs engineer
- Engineer runner → Engineer providers: selects provider (evidence: `src/engineer.ts`)
- Cycle dispatcher → Change verification: checks changes (evidence: `README.md`)
- Cycle dispatcher → Scope reviewer: requests review (evidence: `README.md`)
- Cycle dispatcher → Project state: records state
- Engineer runner → Cycle audit log: appends events (evidence: `src/engineer.ts`)
- CLI → Verify-only CLI: starts verify-only (evidence: `README.md`)
- Verify-only CLI → Isolated verify run: runs check (evidence: `src/verify_only/cli.ts`)
- Isolated verify run → Verify Git operations: manages worktree (evidence: `src/verify_only/run.ts`)
- Isolated verify run → Command runner: runs verification (evidence: `src/verify_only/run.ts`)
- Isolated verify run → Scope reviewer: requests review (evidence: `src/verify_only/run.ts`)
- Verify-only CLI → Change digest: checks digest (evidence: `src/verify_only/cli.ts`)
- Cycle dispatcher → Cycle audit log: records cycle
- Project owner → Autonomous sessions: enables mode (evidence: `README.md`)
- Autonomous sessions → Cycle dispatcher: routes work (evidence: `README.md`)
- Project owner → Persistent aides: registers aides (evidence: `README.md`)
- Project owner → Dashboard server: opens dashboard (evidence: `README.md`)
- Dashboard server → Fleet overview: renders overview (evidence: `src/server.ts`)
- Dashboard server → Phase management: routes requests (evidence: `src/server.ts`)
- Phase management → Page layout: wraps page (evidence: `src/server/routes/phase.ts`)
