tasks/HANDOFF_PROMPT.md

# Handoff Prompt: Implement T0 Milestone

Use this prompt with Claude Haiku 4.5 to begin implementation of T0 tasks.

---

## Context

You're implementing a Temporal-based multi-agent software orchestrator in Go. The system drives development work on arbitrary target repos using three LLM-backed roles:
- **Planner** (reasoning model): reconciles state, dispatches tasks
- **Judge** (reasoning model): reviews correctness, runs integration tests
- **Implementer** (cheaper model): does actual work, learns from failures

All code lives in `/Users/rockliang/workplace/Poimen/workflows/`.

## What's Done

- ✅ Full design doc: `/Users/rockliang/.claude/plans/considered-u-are-a-curried-reef.md`
- ✅ Project scaffold: `PLAN.md`, `tasks/INDEX.md`, `tasks/board.md`
- ✅ Roadmap: T0 (core, 9 tasks) → T1 (hardening) → T2 (scale) → T3 (features)
- ✅ Task breakdown: `tasks/T0.1.md` through `tasks/T0.9.md` (each with verification criteria)

## Your Job: Implement T0.1 → T0.9

Start with T0.1 (repo scaffold). Each task:
1. Read its markdown file in `tasks/T0.x.md`
2. Implement the code sketches provided
3. Write unit tests per verification section
4. Run the verification command
5. When it passes, mark `[ ]` → `[x]` in `tasks/board.md`
6. Move to next task

## Key Constraints

1. **No hardcoded values:** All timeouts, retry counts, model IDs come from `OrchestratorConfig.Tuning` or `PromptSpec.Model` (read at runtime).
2. **Activities are independent:** One concern per `action/*.go` file (git, skills, planner, judge, implementer, etc). Testable in isolation.
3. **Testing is verification:** Unit tests via `go.temporal.io/sdk/testsuite` (mocked activities). E2E test (T0.9) against real `temporal.riotpiao.com`.
4. **Go style:** Per `golang-skills` conventions — no naked `_ =`, proper error handling, idiomatic names.
5. **Concurrency safety:** Shared FS with git worktrees + advisory lock. Test concurrent access.

## Implementation Path

```
1. T0.1: Scaffold directories, go.mod, empty stubs
   → verify: go build ./... succeeds

2. T0.2: Shared types (ModelSpec, PromptSpec, OrchestratorConfig, etc.)
   → verify: Unit test asserts all defaults

3. T0.3: Git & locking (CloneRepoActivity, worktrees, squash-merge)
   → verify: Test against local scratch repo

4. T0.4: Pi & error classification (PrepareSkillsActivity, classifyPiErr)
   → verify: Unit tests for 4xx/5xx/504 buckets

5. T0.5: LLM agents & prompts (Planner/Judge/Implementer, llm/client.go)
   → verify: Unit test renders PromptSpec with system prompt

6. T0.6: TaskUnit workflow (retry loops, timeout escalation, lessons)
   → verify: Testsuite: pass-first-try, fail-then-pass, timeout-escalation

7. T0.7: Orchestrator workflow (config, signals, fan-out/fan-in, continue-as-new, 504 learning)
   → verify: Testsuite: fan-out/fan-in, squash-merge, signal mutations

8. T0.8: Worker & starter CLIs (cmd/worker, cmd/starter, internal/config)
   → verify: go build succeeds, go run ./cmd/worker connects to temporal.riotpiao.com

9. T0.9: End-to-end (real cluster + disposable forgejo repo, all 7 checks)
   → verify: Full cycle with live signals, 5xx retry/exhaust, 504 learning, continue-as-new bounded
```

## Tools Available

- `pi` command: Clone/fetch skills from homelab API
  - Usage: `pi clone-or-fetch <skill-url>`
  - Errors: 4xx (non-retryable), 5xx (retryable), 504 (stream timeout — learn and double timeout)

- Temporal Web UI: `http://temporal.riotpiao.com:8080` (monitor workflows)
- Forgejo instance: For disposable scratch repos during testing

## Testing Locally

Each task has a "Verification" section with a test command. Run it after implementing:

```bash
cd /Users/rockliang/workplace/Poimen/workflows
go test -v ./tests -run Test<TaskName>
```

For T0.9 (e2e), you'll need:
- Real Temporal cluster connection
- Anthropic API key (`ANTHROPIC_API_KEY` env)
- Forgejo repo access or local git repo

## Commit Message Style

```
T0.x: Brief description

Detailed explanation of what was implemented.

Verification: <how you verified it works>
```

Example:
```
T0.2: Implement shared types with defaults

Added ModelSpec, PromptSpec, OrchestratorConfig, ActivityTuning, PiRetryPolicy.
All defaults documented: 5m ScheduleToCloseTimeout, 2s InitialInterval, 2.0 BackoffCoefficient, etc.

Verification: go test ./tests -run TestTypesDefaults passes
```

## When Stuck

1. Re-read the task markdown in `tasks/T0.x.md` — implementation sketches are concrete
2. Check `PLAN.md` §Design sections for detailed logic (§Timeout Extension, §Pi Command Retry Policy, etc.)
3. Look at the test case in the task markdown — it shows expected behavior
4. If a task depends on prior work, make sure the prior task is complete first

## After T0 Completes

When all T0.1–T0.9 pass:
```bash
cd /Users/rockliang/workplace/Poimen/workflows
git checkout main
git merge --squash task/T0.1 task/T0.2 ... task/T0.9
git commit -m "T0: Multi-agent orchestrator initial implementation"
git push origin main
```

Then start T1 (or hand off to another assistant).

---

**Ready?** Start with `tasks/T0.1.md` and work through in order.