diff --git a/tasks/HANDOFF_PROMPT.md b/tasks/HANDOFF_PROMPT.md new file mode 100644 index 0000000..17eaa2c --- /dev/null +++ b/tasks/HANDOFF_PROMPT.md @@ -0,0 +1,137 @@ +# 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 ` + - 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 +``` + +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: +``` + +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.