poimen-workflows/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:

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:

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.