docs: add comprehensive documentation plan (tasks_plan.md)

1 files changed, 261 insertions, 0 deletions

diff --git a/tasks_plan.md b/tasks_plan.md
new file mode 100644
index 0000000..caeaf27
--- /dev/null
+++ b/tasks_plan.md
@@ -0,0 +1,261 @@
+# 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 |