diff options
| -rw-r--r-- | tasks_plan.md | 261 |
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 | |