# Claudomator Documentation Plan

Generated: 2026-03-10
Repository: `/workspace/claudomator`

---

## System Overview

Claudomator is a Go-based task orchestration server that manages AI agent (Claude/Gemini) subprocesses via a REST+WebSocket API and a Cobra CLI. Tasks are defined in YAML, persisted in SQLite, and executed by a bounded goroutine pool.

**Pipeline:** CLI/API → `executor.Pool` → `ClaudeRunner`/`GeminiRunner` → subprocess → SQLite + log files

**Package dependency order (leaf → integrator):**
```
config, task, version, notify (no internal deps)
    ↓
storage (depends on task)
    ↓
executor (depends on storage, task)
reporter (depends on storage)
    ↓
api, cli (depend on all of the above)
    ↓
web (embedded assets, no Go imports)
```

---

## Subtask Definitions (Priority Order)

---

### P0 — ST-1: System Architecture Overview

**Purpose:** Single authoritative document describing the full system — pipeline, components, data flows, state machine, and how all packages fit together.

**Dependencies:** Requires familiarity with all packages (use the summary in tasks_plan.md).

**Output file:** `docs/architecture.md`

**Content Sections:**
1. System purpose and design goals
2. High-level architecture diagram (Mermaid flowchart)
3. Component table (package → role → key types)
4. Package dependency graph (Mermaid)
5. Task execution pipeline (step-by-step with code references)
6. Task state machine diagram (Mermaid stateDiagram-v2)
7. WebSocket broadcast flow
8. Subtask/parent-task dependency resolution
9. External dependencies summary
10. Links to ADRs and package docs

**Diagrams:**
- Mermaid flowchart: end-to-end task execution pipeline
- Mermaid graph: internal package dependencies
- Mermaid stateDiagram-v2: task state machine (all states + transitions)

**Audience:** Developers and architects
**Priority:** P0
**Effort:** Medium

**Key files to read:**
- `internal/task/task.go`, `internal/task/state.go` (or wherever ValidTransition is)
- `internal/executor/executor.go`
- `internal/api/server.go`
- `internal/storage/storage.go`
- `docs/adr/*.md`
- `CLAUDE.md`

---

### P0 — ST-2: Core Domain Documentation (task + storage)

**Purpose:** Document the foundational domain types — Task model, state machine, YAML parsing, validation, and the SQLite persistence layer.

**Output files:**
- `docs/packages/task.md`
- `docs/packages/storage.md`

**Content Sections (task.md):**
1. Overview: what a Task is
2. Task struct fields and AgentConfig fields with types and defaults
3. YAML task file format (with annotated example)
4. Batch file format
5. State constants (all 10 states) with descriptions
6. State machine: valid transitions table + Mermaid diagram
7. Validation rules
8. Key functions: ParseFile, ValidTransition, etc.

**Content Sections (storage.md):**
1. Overview: SQLite persistence layer
2. Schema: tasks and executions tables (columns, types, JSON blob fields)
3. Auto-migration behavior
4. DB methods: task CRUD, state updates, execution records
5. TaskFilter query options
6. File layout: where log files are stored

**Audience:** Developers
**Priority:** P0
**Effort:** Medium

**Key files to read:**
- `internal/task/*.go` (all files)
- `internal/storage/*.go` (all files)

---

### P1 — ST-3: Executor Package Documentation

**Purpose:** Document the execution engine — the bounded goroutine pool, Claude and Gemini agent runners, dynamic classifier, question handling, and rate limiting.

**Output file:** `docs/packages/executor.md`

**Content Sections:**
1. Overview: role of the executor in the pipeline
2. Pool: concurrency model, goroutine lifecycle, dependency polling
3. Runner interface and how runners are selected
4. ClaudeRunner: subprocess invocation, stream-json parsing, cost tracking, project sandboxing
5. GeminiRunner: how it differs from Claude
6. Classifier: dynamic agent/model assignment logic
7. QuestionRegistry: user question flow (write question file → exit → resume)
8. Rate limiter: per-agent-type token bucket behavior
9. BlockedError and how the pool handles it
10. Result struct and error classification

**Diagrams:**
- Mermaid sequence diagram: Pool.Submit → runner.Run → result handling
- Mermaid flowchart: question-handling flow (agent writes question → pool pauses → user answers → task resumes)

**Audience:** Developers
**Priority:** P1
**Effort:** Large

**Key files to read:**
- `internal/executor/*.go` (all files: executor.go, claude.go, gemini.go, classifier.go, question.go, ratelimit.go, stream.go)

---

### P1 — ST-4: API Package Documentation

**Purpose:** Document all REST endpoints and WebSocket behavior, including request/response formats, authentication, and the WebSocket broadcast hub.

**Output file:** `docs/packages/api.md`

**Content Sections:**
1. Overview: HTTP server structure
2. Authentication (API token)
3. REST Endpoints — for each endpoint:
   - Method + path
   - Request body / query params
   - Response format (with example JSON)
   - Error codes
4. Endpoints covered:
   - `POST /api/tasks` (create)
   - `GET /api/tasks` (list with filters)
   - `GET /api/tasks/{id}` (get)
   - `POST /api/tasks/{id}/run`
   - `POST /api/tasks/{id}/cancel`
   - `DELETE /api/tasks/{id}`
   - `GET /api/tasks/{id}/executions`
   - `GET /api/tasks/{id}/logs`
   - `GET /api/tasks/{id}/question` / `POST /api/tasks/{id}/answer`
   - `POST /api/tasks/{id}/elaborate`
   - `POST /api/validate`
   - Script endpoints (ScriptRegistry)
5. WebSocket: `GET /ws` — connection protocol, event format, broadcast behavior
6. Hub: connection lifecycle, fan-out implementation

**Audience:** Developers and API consumers
**Priority:** P1
**Effort:** Large

**Key files to read:**
- `internal/api/*.go` (all files: server.go, hub.go, tasks.go, executions.go, logs.go, elaborate.go, validate.go, scripts.go)

---

### P1 — ST-5: CLI Package Documentation

**Purpose:** Document all CLI commands with usage examples, flags, and integration with the underlying packages.

**Output file:** `docs/packages/cli.md`

**Content Sections:**
1. Overview: CLI entry point and Cobra setup
2. Global flags (config, data-dir, etc.)
3. Commands — for each:
   - `init`: initialize data directory
   - `serve`: start API server (flags: port, concurrency)
   - `run`: execute a task YAML file directly
   - `create`: create a task via CLI
   - `list`: list tasks with filters
   - `status`: show task status
   - `logs`: stream/view execution logs
   - `start`: queue a task for execution
   - `report`: output execution report
4. Config file format (TOML) with annotated example
5. Data directory layout

**Audience:** End users and operators
**Priority:** P1
**Effort:** Medium

**Key files to read:**
- `internal/cli/*.go` (all files)
- `internal/config/*.go`
- `cmd/claudomator/main.go`

---

### P2 — ST-6: Frontend & Operations Documentation

**Purpose:** Document the web UI architecture and operational scripts/runbook.

**Output files:**
- `docs/packages/web.md`
- `docs/operations.md`

**Content Sections (web.md):**
1. Overview: PWA embedded in Go binary
2. File structure (index.html, app.js, style.css, embed.go)
3. app.js architecture: key modules, WebSocket client, task list rendering, filtering/sorting
4. Test setup (Vitest/Mocha .mjs files)
5. How to develop/rebuild the frontend

**Content Sections (operations.md):**
1. Deployment (the `scripts/deploy` script)
2. Database location and SQLite schema
3. Log file layout
4. Common operational tasks:
   - Resetting failed tasks (`scripts/reset-failed-tasks`)
   - Resetting stale running tasks (`scripts/reset-running-tasks`)
   - Debugging failed executions (`scripts/debug-execution`)
   - Finding and starting next task (`scripts/next-task`, `scripts/start-next-task`)
5. Configuration reference (all Config fields)
6. Monitoring and observability

**Audience:** Operators and frontend contributors
**Priority:** P2
**Effort:** Medium

**Key files to read:**
- `web/*.html`, `web/*.js`, `web/*.css`, `web/embed.go`
- `scripts/` (all scripts)
- `internal/config/config.go`

---

## Output File Index

| File | Subtask | Status |
|------|---------|--------|
| `docs/architecture.md` | ST-1 | TODO |
| `docs/packages/task.md` | ST-2 | TODO |
| `docs/packages/storage.md` | ST-2 | TODO |
| `docs/packages/executor.md` | ST-3 | TODO |
| `docs/packages/api.md` | ST-4 | TODO |
| `docs/packages/cli.md` | ST-5 | TODO |
| `docs/packages/web.md` | ST-6 | TODO |
| `docs/operations.md` | ST-6 | TODO |