# All-Day Build Contract: coderace v0.2.0

Status: In Progress
Date: 2026-02-23
Owner: Codex/sub-agent execution pass
Scope type: Deliverable-gated (no hour promises)

## 1. Objective

Ship coderace v0.2.0 with five new features that make comparison results shareable, statistically meaningful, and broader in agent coverage. The "Claude Code vs Codex" comparison trend is peaking this week. OpenCode (60k-star open-source alternative) just got a major benchmark review. Adding OpenCode as the 5th agent + HTML reports makes coderace the go-to tool for this moment.

This contract is considered complete only when every deliverable and validation gate below is satisfied.

## 2. Non-Negotiable Build Rules

1. No time-based completion claims.
2. Completion is allowed only when all checklist items are checked.
3. Full test suite must pass at the end (existing 39 tests + new tests).
4. New features must ship with docs and report addendum updates in the same pass.
5. CLI outputs must be deterministic and schema-backed where specified.
6. Never modify files outside the project directory.
7. Commit after each completed deliverable (not at the end).
8. If stuck on same issue for 3 attempts, stop and write a blocker report.
9. Do NOT refactor, restyle, or "improve" code outside the deliverables.
10. Read existing tests and docs before writing new code.

## 3. Feature Deliverables

### D1. OpenCode Adapter (5th CLI agent)

Add OpenCode CLI as a supported agent. OpenCode is a terminal-first open-source coding assistant with 60k+ GitHub stars. It's invoked as `opencode` with similar patterns to other CLI agents.

Required files:
- `coderace/adapters/opencode.py`
- `tests/test_opencode_adapter.py`

- [ ] Implement OpenCode adapter following existing adapter pattern (see claude.py, codex.py, aider.py, gemini.py)
- [ ] OpenCode invocation: `opencode` CLI with task prompt via stdin or --prompt flag (research actual CLI interface)
- [ ] If OpenCode CLI is not installed, adapter should detect and report clearly
- [ ] Register adapter in adapter registry
- [ ] Add `opencode` to task YAML agents list support
- [ ] Tests: unit tests for adapter (mock CLI invocation), integration with run pipeline
- [ ] Update README: add OpenCode to supported agents list and example YAML

### D2. Custom Scoring Weights

Allow users to override default scoring weights in the task YAML. Currently hardcoded (40/20/15/15/10). Users should be able to tune.

Required files:
- Modify `coderace/scoring.py` (or wherever scoring lives)
- `tests/test_custom_scoring.py`

- [ ] Add optional `scoring` section to task YAML schema:
  ```yaml
  scoring:
    tests: 50
    exit: 20
    lint: 10
    time: 10
    lines: 10
  ```
- [ ] Weights are normalized (sum to 100) automatically
- [ ] If `scoring` section omitted, use current defaults
- [ ] Validate: all weights >= 0, no unknown keys
- [ ] Tests: custom weights, partial override, invalid weights, normalization

### D3. HTML Report Output

Generate a self-contained HTML report from race results. This makes results shareable on blogs, tweets, and team Slack.

Required files:
- `coderace/report.py`
- `tests/test_report.py`

- [ ] `coderace results task.yaml --html report.html` generates a single-file HTML report
- [ ] Report includes: task name, date, agent scores table, scoring weights used, timing breakdown
- [ ] Styled with inline CSS (no external dependencies, single file)
- [ ] Table is sortable by clicking column headers (vanilla JS, inline)
- [ ] Include a "Generated by coderace" footer with version
- [ ] Tests: HTML generation, content validation, file output

### D4. Statistical Mode (multiple runs)

Run the same task N times and report mean/stddev for each metric. Real benchmarking needs statistical significance.

Required files:
- Modify `coderace/runner.py` (or equivalent)
- `coderace/stats.py`
- `tests/test_stats.py`

- [ ] `coderace run task.yaml --runs 5` runs each agent 5 times
- [ ] Results show mean ± stddev for score, time, and lines changed
- [ ] Rich table adapts to show statistical columns
- [ ] JSON output includes per-run data + aggregates
- [ ] HTML report (D3) also supports statistical view
- [ ] Tests: multi-run aggregation, edge cases (1 run = no stddev), JSON schema

### D5. Example Benchmark Tasks

Ship example tasks that work out of the box on any Python project. Users shouldn't have to write YAML from scratch to try coderace.

Required files:
- `examples/add-type-hints.yaml`
- `examples/fix-edge-case.yaml`
- `examples/write-tests.yaml`
- Update README with examples section

- [ ] 3 example task YAMLs that target common patterns (type hints, edge cases, test coverage)
- [ ] Each example has a description explaining what it tests
- [ ] Examples reference a small bundled test fixture (or clearly document how to point at user's repo)
- [ ] README section: "Try it now" with copy-paste commands
- [ ] Tests: validate example YAML files parse correctly

## 4. Test Requirements

- [ ] Unit tests for each deliverable (specified above)
- [ ] All 39 existing tests must still pass
- [ ] Integration test: run full pipeline with mock agents including OpenCode
- [ ] Edge cases: empty results, single agent, all agents fail, custom weights sum to 0

## 5. Reports

- Write progress to `progress-log.md` after each deliverable
- Include: what was built, what tests pass, what's next, any blockers
- Final summary when all deliverables done or stopped

## 6. Stop Conditions

- All deliverables checked and all tests passing -> DONE
- 3 consecutive failed attempts on same issue -> STOP, write blocker report
- Scope creep detected (new requirements discovered) -> STOP, report what's new
- All tests passing but deliverables remain -> continue to next deliverable

## 7. Version Bump

- [ ] Bump version to 0.2.0 in pyproject.toml
- [ ] Update CHANGELOG or add one if missing
