poimen-workflows/tasks/INDEX.md

# Poimen Workflows — Development Guidelines

This project orchestrates multi-agent software development tasks using Temporal + Go. The repo is organized as:
- `statemachine/` — Temporal workflow definitions (deterministic state machines)
- `action/` — Temporal activity definitions (units of work / LLM calls)
- `cmd/` — CLI entry points (worker registration, workflow starter)
- `prompts/` — LLM prompt templates (Go-embedded, live-updatable)
- `internal/` — Shared config/locking utilities
- `tests/` — Unit tests via `go.temporal.io/sdk/testsuite`

## Code Standards

### Go Style

Follow `golang-skills` conventions from `~/.claude/skills/golang-skills/`:
- Error handling mandatory; no naked `_ =` discards.
- Idiomatic naming: `ctx` for context, `err` for error returns.
- Interfaces kept narrow; one struct per concern.
- No over-generalization for hypothetical use.
- Documentation via comments only where the WHY is non-obvious.

### Testing

- Every `statemachine/*` change ships with a `testsuite`-based test in `tests/`.
- Unit tests use `go.temporal.io/sdk/testsuite.WorkflowTestEnvironment` with mocked activities.
- Activities are tested in isolation before integrating into workflows.
- No literal timeout/retry values in `action/*` code — all come from `OrchestratorConfig.Tuning` at runtime.

### Activity Design

Activities stay side-effect-isolated (one concern per file) so they remain independently reusable across projects.
- `action/git.go` — all git operations
- `action/skills.go` — skill prep / pi command
- `action/planner.go` — Planner LLM call
- `action/judge.go` — Judge LLM call
- `action/implementer.go` — Implementer LLM + tool-call loop
- `action/lessons.go` — Lessons store read/write

No composite activities like `PrepareAndImplement`; that's a workflow's job, not an activity's.

### Config as Data

**No hardcoded numbers.** Every timeout, retry count, backoff coefficient, stream timeout — all come from `OrchestratorConfig.Tuning` (or role-specific `PromptSpec.Model`), read at execution time. This lets:
- `update-tuning` signal to dynamically adjust timeouts without redeployment
- Planner activity to recommend per-task overrides
- Pi 504 handler to learn and persist `StreamTimeout` across `ContinueAsNew` cycles

**No LLM model hardcoded.** Every model ID comes from `ModelSpec.ModelID`, passed as data.

### Concurrency & Locking

Target repo sits on shared filesystem. Git concurrency is safe by construction:
- Task units use isolated worktrees (`git worktree add -b task/T0.x ...`)
- Commits within a worktree don't need a lock; git serializes object writes
- Only `CloneRepoActivity`, `GitPushActivity`, `GitSquashMergeActivity` need the `orchestrator.lock`, since they mutate the main working tree / refs

Monitor for deadlocks: if two workflows try to push simultaneously, the lock will serialize them. Test with concurrent tasks enabled.

## Task Board Format

Each task row in the board specifies:
- **ID**: `T0.1`, `T0.2`, etc.
- **Description**: One-line scope
- **Status**: `[ ]` (todo), `[x]` (done)
- **Branch**: `task/T0.x` (created when task starts, merged to main on submilestone complete)
- **Verification**: Specific criterion that marks it done (e.g. "Unit test passes", "E2E run completes")

A task is NOT marked done until its verification step passes. This mirrors the Judge role's own job: no hallucinated completion.

## Submilestones & Merges

When all tasks in `T0` (`T0.1` through `T0.9`) pass their verification:
1. Orchestrator calls `GitSquashMergeActivity` to merge all `task/T0.*` branches into `main` as a single squashed commit
2. All `task/T0.*` branches and worktrees are cleaned up
3. Main branch is the canonical history; the 9 subtask commits are compacted into one

This demonstrates the very mechanism the system orchestrates: a working software dev pipeline with multiple agents collaborating on a shared codebase, guarded by state checks (Judge), and landing changes via deterministic git workflow.

## Historical Lessons

Lessons live at `tasks/.orchestrator/lessons/<TaskID>.jsonl` — per-task file of failed attempts. When a Judge calls a task failure, the `UpdateLessonsActivity` appends `{Attempt, Critique, FailedApproachSummary, Timestamp}`. On retry, `ReadLessonsActivity` injects the last N entries into the Implementer's prompt as "known errors — do not repeat this time".

Lessons flush to git only as part of the Planner's board commit, not on every retry — keeps history clean.

## Skills & Preparation

Required skill sources are listed in `OrchestratorConfig.Skills` as a list of references (e.g. `["~/.claude/skills/golang-skills", "custom-skill-repo"]`). `PrepareSkillsActivity` runs once per config change, cloning/fetching them onto the shared FS via the `pi` command. All retry/backoff/timeout is delegated to Temporal's retry machinery, with special handling for 504 (stream timeout learning).

## Environment & Secrets

All external system access is via environment variables, loaded at worker startup:
- `TEMPORAL_NAMESPACE`, `TEMPORAL_TLS_CERT`, `TEMPORAL_TLS_KEY` — Temporal cluster connection
- `ANTHROPIC_API_KEY` — LLM API key
- Any target-repo-specific credentials (e.g. git SSH key) are assumed already available on the shared FS (e.g. via Kubernetes secret mount)

Use homelab's `vsource .env` pattern to load from a `.env` file during local development.

## Observability

- Temporal Web UI (`temporal.riotpiao.com:8080` or similar) shows workflow execution, signal delivery, activity retries
- Workflow `current-config` query returns live `OrchestratorConfig` (useful for debugging which tuning values are in effect)
- Activity heartbeats (`activity.RecordHeartbeat`) are sent after each tool-call iteration, visible in Temporal's activity details
- Lessons file grows as retries happen; inspect it on failure to understand what the Implementer is learning

## Deployment & Homelab Integration

This repo is application-layer code against the homelab's Temporal cluster. The orchestrator runs as a Kubernetes pod with:
- Persistent volume (PVC) for the shared FS where target repos are cloned
- Network access to Temporal + Anthropic APIs
- Git SSH key mounted for cloning target repos

The Kubernetes manifests + Helm charts live in the homelab repo under `k8s/` and follow homelab's GitOps workflow (commit → ArgoCD sync). This repo's CI/CD (GitHub Actions or Forgejo Actions) builds and pushes the Docker image; the homelab repo triggers a new pod deploy on image push.

## Questions & Debugging

If a task is marked done but you suspect it's wrong:
1. Re-run its verification step manually
2. Check the unit test against the latest code
3. For e2e tasks, review Temporal Web UI logs + board file + lessons file on the target repo
4. Update the board and task description if the criterion was misunderstood

If code doesn't compile or tests fail:
1. Check Go version and Temporal SDK version match
2. Run `go mod tidy` and `go mod vendor` if dependencies drift
3. Look for hardcoded values or model IDs that should be config instead