# Work Workflow

The work workflow reads `plan.md` and produces `work.md` — implementing the actual code changes and validating them with tests.

## Inputs

- `session_folder` (required) — should typically contain `plan.md`.
- `work_builder_provider` — which LLM provider the artifact builder uses. Accepts `"claude"`, `"gemini"`, `"codex"`, or `"random"` (picks one at random). Defaults to `"claude"`.
- `max_test_iterations` — how many build-test cycles before giving up. Defaults to 5. Set to 0 to skip testing entirely (build only, no tester runs).
- `instructions` — optional free-text guidance injected into the artifact builder's prompt. Passed to the initial build only, not to resume calls during the test-fix loop.

## Orchestration

The orchestrator (`create_work.py`) runs a **build-test loop**:

1. The artifact builder implements all changes from the plan and writes `work.md` (what changed, revision history).
2. The tester runs tests to validate the implementation.
3. If tests fail and iterations remain, the tester's feedback goes back to the artifact builder for fixes.
4. This repeats up to `max_test_iterations` times.

On success, the orchestrator writes a passing Build Status block at the top of `work.md`. On final failure (all iterations exhausted), it writes a failing status and raises an error.

The Build Status block tracks: whether the build succeeded, whether tests succeeded, how many iterations were used, and the last test feedback.

## Agents

**Artifact Builder** (`shared/builder.py`, stage `work`, model L) — implements code according to the plan. Maintains `work.md` with a "What Changed" section (complete current state, not just deltas), a "Key Findings" section (curated insights, unexpected discoveries, open issues), and a "Build Log" (raw chronological account of what was built, revised, tested, and failed). Supports resume via session ID for the test-fix loop.

**Tester** (`agents/work_tester.py`, model L, full file access) — runs tests and verifies the implementation works. Reports specific failures with file paths and error messages. Ignores the Build Status block in `work.md` — uses actual test outcomes for pass/fail.
