# locriani/chief-of-stuff architecture

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

- Interactive diagram: https://gitdiagram.com/locriani/chief-of-stuff
- Repository: https://github.com/locriani/chief-of-stuff

## Overview

chief-of-stuff is a daily, agent-driven workspace coordinator. The user launches a supported CLI, which follows workspace coordinator rules to inspect tasks and worker status, reconcile the tracker and board, and dispatch ready work; interactive sessions require approval. Related capabilities include decisions with context pages, issue/review workflows, and board pages for workers. The graph reflects documented behavior and sampled command dispatch; source excerpts do not expose all coordinator-to-script wiring, so uncertain links are omitted.

Main entry points: [`chief_of_stuff.py`](https://github.com/locriani/chief-of-stuff/blob/main/chief_of_stuff.py) (Command router), [`start_coordinator.py`](https://github.com/locriani/chief-of-stuff/blob/main/start_coordinator.py) (Coordinator launcher), [`scripts/decision_page.py`](https://github.com/locriani/chief-of-stuff/blob/main/scripts/decision_page.py) (Decision pages), [`scripts/dispatch_prompt.py`](https://github.com/locriani/chief-of-stuff/blob/main/scripts/dispatch_prompt.py) (Worker dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_coordination["Coordination"]
  node_cli["Command router<br/>[chief_of_stuff.py]"]
  node_launcher["Coordinator launcher"]
  node_inbox["Inbox<br/>[inbox.py]"]
  node_settings["Settings<br/>[settings.py]"]
end

subgraph group_work["Task execution"]
  node_worker_dispatch["Worker dispatch<br/>[dispatch_prompt.py]"]
  node_spawn["Session launcher<br/>[spawn_session.py]"]
  node_worktree["Worktree manager<br/>[make_worktree.py]"]
  node_processes["Process status<br/>[process_status.py]"]
end

subgraph group_tracking["Tracking and review"]
  node_audit["Task audit<br/>[audit_tasks.py]"]
  node_tracker["Tracker writes<br/>[tracker_write.py]"]
  node_backlog["Backlog and issues<br/>[backlog.py]"]
  node_reviews["Review threads<br/>[review_threads.py]"]
end

subgraph group_board["Board and decisions"]
  node_board["Board renderer<br/>[render_board.py]"]
  node_pages["Page server<br/>[pages.py]"]
  node_workers_page["Workers page<br/>[workers_page.py]"]
  node_decision["Decision pages<br/>[decision_page.py]"]
end

subgraph group_setup["Workspace setup"]
end

node_user(("User"))
node_runtime(("Agent CLI"))
node_workspace["Workspace state"]
node_calendar["Calendar service"]
node_forge["Issue forge"]

node_user -->|"starts session"| node_runtime
node_user -->|"runs command"| node_cli
node_cli -->|"dispatches command"| node_inbox
node_cli -->|"dispatches command"| node_backlog
node_cli -->|"dispatches command"| node_board
node_cli -->|"dispatches command"| node_decision
node_launcher -->|"launches"| node_runtime
node_launcher -->|"runs check"| node_inbox
node_launcher -->|"runs check"| node_audit
node_launcher -->|"runs check"| node_processes
node_runtime -->|"reads configuration"| node_workspace
node_runtime -->|"checks messages"| node_inbox
node_runtime -->|"checks tasks"| node_audit
node_runtime -->|"reconciles state"| node_tracker
node_runtime -->|"updates board"| node_board
node_runtime -->|"dispatches work"| node_worker_dispatch
node_runtime -->|"requests decision page"| node_decision
node_worker_dispatch -->|"prepares worktree"| node_worktree
node_worker_dispatch -->|"starts session"| node_spawn
node_runtime -.->|"reads events"| node_calendar
node_backlog -.->|"reads and writes issues"| node_forge
node_reviews -.->|"reads and replies"| node_forge
node_board -->|"serves pages"| node_pages
node_pages -->|"renders workers"| node_workers_page
node_workers_page -->|"reads worker status"| node_processes
node_decision -->|"writes page"| node_workspace
node_user -->|"reviews decision"| node_decision

click node_cli "https://github.com/locriani/chief-of-stuff/blob/main/chief_of_stuff.py"
click node_launcher "https://github.com/locriani/chief-of-stuff/blob/main/start_coordinator.py"
click node_inbox "https://github.com/locriani/chief-of-stuff/blob/main/scripts/inbox.py"
click node_settings "https://github.com/locriani/chief-of-stuff/blob/main/scripts/settings.py"
click node_audit "https://github.com/locriani/chief-of-stuff/blob/main/scripts/audit_tasks.py"
click node_tracker "https://github.com/locriani/chief-of-stuff/blob/main/scripts/tracker_write.py"
click node_backlog "https://github.com/locriani/chief-of-stuff/blob/main/scripts/backlog.py"
click node_reviews "https://github.com/locriani/chief-of-stuff/blob/main/scripts/review_threads.py"
click node_worker_dispatch "https://github.com/locriani/chief-of-stuff/blob/main/scripts/dispatch_prompt.py"
click node_spawn "https://github.com/locriani/chief-of-stuff/blob/main/scripts/spawn_session.py"
click node_worktree "https://github.com/locriani/chief-of-stuff/blob/main/scripts/make_worktree.py"
click node_processes "https://github.com/locriani/chief-of-stuff/blob/main/scripts/process_status.py"
click node_board "https://github.com/locriani/chief-of-stuff/blob/main/scripts/render_board.py"
click node_pages "https://github.com/locriani/chief-of-stuff/blob/main/scripts/pages.py"
click node_workers_page "https://github.com/locriani/chief-of-stuff/blob/main/scripts/workers_page.py"
click node_decision "https://github.com/locriani/chief-of-stuff/blob/main/scripts/decision_page.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_cli,node_launcher,node_inbox,node_settings,node_user toneBlue
class node_worker_dispatch,node_spawn,node_worktree,node_processes toneAmber
class node_audit,node_tracker,node_backlog,node_reviews toneMint
class node_board,node_pages,node_workers_page,node_decision toneRose
class node_runtime,node_workspace,node_calendar,node_forge toneIndigo
```

## Components

### Coordination

- [Command router](https://github.com/locriani/chief-of-stuff/blob/main/chief_of_stuff.py): `chief_of_stuff.py`
- [Coordinator launcher](https://github.com/locriani/chief-of-stuff/blob/main/start_coordinator.py): `start_coordinator.py`
- [Inbox](https://github.com/locriani/chief-of-stuff/blob/main/scripts/inbox.py): `scripts/inbox.py`
- [Settings](https://github.com/locriani/chief-of-stuff/blob/main/scripts/settings.py): `scripts/settings.py`

### Task execution

- [Worker dispatch](https://github.com/locriani/chief-of-stuff/blob/main/scripts/dispatch_prompt.py): `scripts/dispatch_prompt.py`
- [Session launcher](https://github.com/locriani/chief-of-stuff/blob/main/scripts/spawn_session.py): `scripts/spawn_session.py`
- [Worktree manager](https://github.com/locriani/chief-of-stuff/blob/main/scripts/make_worktree.py): `scripts/make_worktree.py`
- [Process status](https://github.com/locriani/chief-of-stuff/blob/main/scripts/process_status.py): `scripts/process_status.py`

### Tracking and review

- [Task audit](https://github.com/locriani/chief-of-stuff/blob/main/scripts/audit_tasks.py): `scripts/audit_tasks.py`
- [Tracker writes](https://github.com/locriani/chief-of-stuff/blob/main/scripts/tracker_write.py): `scripts/tracker_write.py`
- [Backlog and issues](https://github.com/locriani/chief-of-stuff/blob/main/scripts/backlog.py): `scripts/backlog.py`
- [Review threads](https://github.com/locriani/chief-of-stuff/blob/main/scripts/review_threads.py): `scripts/review_threads.py`

### Board and decisions

- [Board renderer](https://github.com/locriani/chief-of-stuff/blob/main/scripts/render_board.py): `scripts/render_board.py`
- [Page server](https://github.com/locriani/chief-of-stuff/blob/main/scripts/pages.py): `scripts/pages.py`
- [Workers page](https://github.com/locriani/chief-of-stuff/blob/main/scripts/workers_page.py): `scripts/workers_page.py`
- [Decision pages](https://github.com/locriani/chief-of-stuff/blob/main/scripts/decision_page.py): `scripts/decision_page.py`

### Other components

- **User**
- **Agent CLI**
- **Workspace state**
- **Calendar service**
- **Issue forge**

## Connections

- User → Agent CLI: starts session
- User → Command router: runs command
- Command router → Inbox: dispatches command
- Command router → Backlog and issues: dispatches command
- Command router → Board renderer: dispatches command
- Command router → Decision pages: dispatches command
- Coordinator launcher → Agent CLI: launches
- Coordinator launcher → Inbox: runs check
- Coordinator launcher → Task audit: runs check
- Coordinator launcher → Process status: runs check
- Agent CLI → Workspace state: reads configuration
- Agent CLI → Inbox: checks messages
- Agent CLI → Task audit: checks tasks
- Agent CLI → Tracker writes: reconciles state
- Agent CLI → Board renderer: updates board
- Agent CLI → Worker dispatch: dispatches work
- Agent CLI → Decision pages: requests decision page
- Worker dispatch → Worktree manager: prepares worktree
- Worker dispatch → Session launcher: starts session
- Agent CLI → Calendar service: reads events
- Backlog and issues → Issue forge: reads and writes issues
- Review threads → Issue forge: reads and replies
- Board renderer → Page server: serves pages
- Page server → Workers page: renders workers
- Workers page → Process status: reads worker status
- Decision pages → Workspace state: writes page
- User → Decision pages: reviews decision