# maro525/harness architecture

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

- Interactive diagram: https://gitdiagram.com/maro525/harness
- Repository: https://github.com/maro525/harness

## Overview

Harness defines an AI-coding workflow centered on /orchestrate: classify a task by tier, then run startproject, team-implement, team-review, and deploy. Agent Skills and Claude/OpenCode/Pi entry points expose that workflow; scripts support phase dispatch, consultation, fallback, and Herdr delegation. A separate read-only taskboard scans TASK_FILE records and presents phase progress, waiting questions, and optional live harness activity. Edges reflect README statements and shown imports/calls; unsampled workflow internals are represented only where documented.

Main entry points: [`agents/skills/orchestrate/SKILL.md`](https://github.com/maro525/harness/blob/main/agents/skills/orchestrate/SKILL.md) (Orchestrate), [`kanban/taskboard/scanner.py`](https://github.com/maro525/harness/blob/main/kanban/taskboard/scanner.py) (Task Scanner), [`kanban/taskboard/server.py`](https://github.com/maro525/harness/blob/main/kanban/taskboard/server.py) (Board HTTP Server), [`claude/scripts/phase-run.sh`](https://github.com/maro525/harness/blob/main/claude/scripts/phase-run.sh) (Phase Dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Task Workflow"]
  node_orchestrate["Orchestrate<br/>[SKILL.md]"]
  node_startproject["Startproject<br/>[SKILL.md]"]
  node_implement["Implementation<br/>[SKILL.md]"]
  node_review["Review<br/>[SKILL.md]"]
  node_deploy["Deploy<br/>[SKILL.md]"]
  node_phase_dispatch["Phase Dispatch<br/>[phase-run.sh]"]
  node_task_records["Task Records<br/>[task-file.sh]"]
end

subgraph group_agent_ops["Agent Operations"]
  node_consult["AI Consultation<br/>[consult.sh]"]
  node_fallback["Model Fallback<br/>[ai-fallback.sh]"]
  node_herdr_agent["Herdr Agent<br/>[herdr-agent.sh]"]
  node_boss_skill["Boss Skill<br/>[SKILL.md]"]
end

subgraph group_board["Taskboard"]
  node_task_files["TASK_FILE Markdown"]
  node_scanner["Task Scanner<br/>[scanner.py]"]
  node_parser["Task Parser<br/>[parser.py]"]
  node_asklog["Question Log Parser<br/>[asklog.py]"]
  node_phases["Phase Classifier<br/>[phases.py]"]
  node_board_model["Board Model<br/>[model.py]"]
  node_harness_records["Harness Record Reader<br/>[harness.py]"]
  node_herdr_poll["Herdr Poller<br/>[herdr.py]"]
  node_activity["Activity Joiner<br/>[activity.py]"]
  node_http_server["Board HTTP Server<br/>[server.py]"]
  node_board_ui["Board UI<br/>[app.js]"]
  node_activity_ui["Activity Views<br/>[activity.js]"]
end

node_developer(("Engineer"))
node_herdr_service["Herdr CLI"]

node_developer -->|"starts workflow"| node_orchestrate
node_orchestrate -->|"runs first"| node_startproject
node_orchestrate -->|"runs next"| node_implement
node_orchestrate -->|"runs next"| node_review
node_orchestrate -->|"runs last"| node_deploy
node_orchestrate -->|"resolves records"| node_task_records
node_phase_dispatch -.->|"executes phase"| node_startproject
node_phase_dispatch -.->|"executes phase"| node_implement
node_phase_dispatch -.->|"executes phase"| node_review
node_phase_dispatch -.->|"executes phase"| node_deploy
node_developer -.->|"requests consultation"| node_consult
node_consult -.->|"uses fallback"| node_fallback
node_boss_skill -->|"delegates work"| node_herdr_agent
node_task_files -->|"scans files"| node_scanner
node_scanner -->|"parses tasks"| node_parser
node_scanner -->|"parses questions"| node_asklog
node_scanner -->|"classifies tasks"| node_phases
node_scanner -->|"builds snapshot"| node_board_model
node_http_server -->|"requests scans"| node_scanner
node_http_server -->|"serves assets"| node_board_ui
node_board_ui -->|"fetches board"| node_http_server
node_harness_records -->|"provides records"| node_activity
node_herdr_poll -->|"provides live sessions"| node_activity
node_activity -->|"provides activity"| node_http_server
node_activity_ui -.->|"fetches activity"| node_http_server
node_herdr_poll -.->|"polls agents"| node_herdr_service

click node_orchestrate "https://github.com/maro525/harness/blob/main/agents/skills/orchestrate/SKILL.md"
click node_startproject "https://github.com/maro525/harness/blob/main/agents/skills/startproject/SKILL.md"
click node_implement "https://github.com/maro525/harness/blob/main/agents/skills/team-implement/SKILL.md"
click node_review "https://github.com/maro525/harness/blob/main/agents/skills/team-review/SKILL.md"
click node_deploy "https://github.com/maro525/harness/blob/main/agents/skills/deploy/SKILL.md"
click node_phase_dispatch "https://github.com/maro525/harness/blob/main/claude/scripts/phase-run.sh"
click node_task_records "https://github.com/maro525/harness/blob/main/claude/scripts/task-file.sh"
click node_consult "https://github.com/maro525/harness/blob/main/claude/scripts/consult.sh"
click node_fallback "https://github.com/maro525/harness/blob/main/claude/scripts/ai-fallback.sh"
click node_herdr_agent "https://github.com/maro525/harness/blob/main/claude/scripts/herdr-agent.sh"
click node_boss_skill "https://github.com/maro525/harness/blob/main/agents/skills/herdr-boss/SKILL.md"
click node_scanner "https://github.com/maro525/harness/blob/main/kanban/taskboard/scanner.py"
click node_parser "https://github.com/maro525/harness/blob/main/kanban/taskboard/parser.py"
click node_asklog "https://github.com/maro525/harness/blob/main/kanban/taskboard/asklog.py"
click node_phases "https://github.com/maro525/harness/blob/main/kanban/taskboard/phases.py"
click node_board_model "https://github.com/maro525/harness/blob/main/kanban/taskboard/model.py"
click node_harness_records "https://github.com/maro525/harness/blob/main/kanban/taskboard/harness.py"
click node_herdr_poll "https://github.com/maro525/harness/blob/main/kanban/taskboard/herdr.py"
click node_activity "https://github.com/maro525/harness/blob/main/kanban/taskboard/activity.py"
click node_http_server "https://github.com/maro525/harness/blob/main/kanban/taskboard/server.py"
click node_board_ui "https://github.com/maro525/harness/blob/main/kanban/taskboard/static/app.js"
click node_activity_ui "https://github.com/maro525/harness/blob/main/kanban/taskboard/static/activity.js"

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_orchestrate,node_startproject,node_implement,node_review,node_deploy,node_phase_dispatch,node_task_records toneBlue
class node_consult,node_fallback,node_herdr_agent,node_boss_skill toneAmber
class node_task_files,node_scanner,node_parser,node_asklog,node_phases,node_board_model,node_harness_records,node_herdr_poll,node_activity,node_http_server,node_board_ui,node_activity_ui toneMint
class node_developer,node_herdr_service toneIndigo
```

## Components

### Task Workflow

- [Orchestrate](https://github.com/maro525/harness/blob/main/agents/skills/orchestrate/SKILL.md): `agents/skills/orchestrate/SKILL.md`
- [Startproject](https://github.com/maro525/harness/blob/main/agents/skills/startproject/SKILL.md): `agents/skills/startproject/SKILL.md`
- [Implementation](https://github.com/maro525/harness/blob/main/agents/skills/team-implement/SKILL.md): `agents/skills/team-implement/SKILL.md`
- [Review](https://github.com/maro525/harness/blob/main/agents/skills/team-review/SKILL.md): `agents/skills/team-review/SKILL.md`
- [Deploy](https://github.com/maro525/harness/blob/main/agents/skills/deploy/SKILL.md): `agents/skills/deploy/SKILL.md`
- [Phase Dispatch](https://github.com/maro525/harness/blob/main/claude/scripts/phase-run.sh): `claude/scripts/phase-run.sh`
- [Task Records](https://github.com/maro525/harness/blob/main/claude/scripts/task-file.sh): `claude/scripts/task-file.sh`

### Agent Operations

- [AI Consultation](https://github.com/maro525/harness/blob/main/claude/scripts/consult.sh): `claude/scripts/consult.sh`
- [Model Fallback](https://github.com/maro525/harness/blob/main/claude/scripts/ai-fallback.sh): `claude/scripts/ai-fallback.sh`
- [Herdr Agent](https://github.com/maro525/harness/blob/main/claude/scripts/herdr-agent.sh): `claude/scripts/herdr-agent.sh`
- [Boss Skill](https://github.com/maro525/harness/blob/main/agents/skills/herdr-boss/SKILL.md): `agents/skills/herdr-boss/SKILL.md`

### Taskboard

- **TASK_FILE Markdown**
- [Task Scanner](https://github.com/maro525/harness/blob/main/kanban/taskboard/scanner.py): `kanban/taskboard/scanner.py`
- [Task Parser](https://github.com/maro525/harness/blob/main/kanban/taskboard/parser.py): `kanban/taskboard/parser.py`
- [Question Log Parser](https://github.com/maro525/harness/blob/main/kanban/taskboard/asklog.py): `kanban/taskboard/asklog.py`
- [Phase Classifier](https://github.com/maro525/harness/blob/main/kanban/taskboard/phases.py): `kanban/taskboard/phases.py`
- [Board Model](https://github.com/maro525/harness/blob/main/kanban/taskboard/model.py): `kanban/taskboard/model.py`
- [Harness Record Reader](https://github.com/maro525/harness/blob/main/kanban/taskboard/harness.py): `kanban/taskboard/harness.py`
- [Herdr Poller](https://github.com/maro525/harness/blob/main/kanban/taskboard/herdr.py): `kanban/taskboard/herdr.py`
- [Activity Joiner](https://github.com/maro525/harness/blob/main/kanban/taskboard/activity.py): `kanban/taskboard/activity.py`
- [Board HTTP Server](https://github.com/maro525/harness/blob/main/kanban/taskboard/server.py): `kanban/taskboard/server.py`
- [Board UI](https://github.com/maro525/harness/blob/main/kanban/taskboard/static/app.js): `kanban/taskboard/static/app.js`
- [Activity Views](https://github.com/maro525/harness/blob/main/kanban/taskboard/static/activity.js): `kanban/taskboard/static/activity.js`

### Other components

- **Engineer**
- **Herdr CLI**

## Connections

- Engineer → Orchestrate: starts workflow (evidence: `README.md`)
- Orchestrate → Startproject: runs first (evidence: `README.md`)
- Orchestrate → Implementation: runs next (evidence: `README.md`)
- Orchestrate → Review: runs next (evidence: `README.md`)
- Orchestrate → Deploy: runs last (evidence: `README.md`)
- Orchestrate → Task Records: resolves records (evidence: `README.md`)
- Phase Dispatch → Startproject: executes phase
- Phase Dispatch → Implementation: executes phase
- Phase Dispatch → Review: executes phase
- Phase Dispatch → Deploy: executes phase
- Engineer → AI Consultation: requests consultation
- AI Consultation → Model Fallback: uses fallback
- Boss Skill → Herdr Agent: delegates work (evidence: `README.md`)
- TASK_FILE Markdown → Task Scanner: scans files (evidence: `kanban/taskboard/scanner.py`)
- Task Scanner → Task Parser: parses tasks (evidence: `kanban/taskboard/scanner.py`)
- Task Scanner → Question Log Parser: parses questions (evidence: `kanban/taskboard/scanner.py`)
- Task Scanner → Phase Classifier: classifies tasks (evidence: `kanban/taskboard/scanner.py`)
- Task Scanner → Board Model: builds snapshot (evidence: `kanban/taskboard/scanner.py`)
- Board HTTP Server → Task Scanner: requests scans (evidence: `kanban/taskboard/server.py`)
- Board HTTP Server → Board UI: serves assets (evidence: `kanban/taskboard/server.py`)
- Board UI → Board HTTP Server: fetches board (evidence: `kanban/taskboard/static/app.js`)
- Harness Record Reader → Activity Joiner: provides records (evidence: `kanban/taskboard/activity.py`)
- Herdr Poller → Activity Joiner: provides live sessions (evidence: `kanban/taskboard/activity.py`)
- Activity Joiner → Board HTTP Server: provides activity (evidence: `kanban/taskboard/server.py`)
- Activity Views → Board HTTP Server: fetches activity
- Herdr Poller → Herdr CLI: polls agents
