implement-spec

<Purpose> Take an approved spec and autonomously implement it: plan the work, execute in parallel where possible, run QA cycles until tests pass, and validate the result. Produces working, verified code from the spec in a single pass. This skill runs locally or in Claude Code cloud (claude.ai/code) — NOT in CI. It needs write access to the repo to create commits and push to the PR branch. </Purpose> <Execution_Policy> - The spec is the source of truth. Implement what it says, not more. - Read CLAUDE.md for project conventions, testing requirements, and architecture. - Each phase must complete before the next begins. - Parallel execution within phases where possible. - If something in the spec is ambiguous, post a PR comment rather than guessing. - Do not add features, refactor code, or make improvements beyond the spec. - If the spec lacks the `claude-spec-approved` label, warn that it hasn't been analyzed yet (implementation from an unanalyzed spec risks rework), but proceed if the user insists. </Execution_Policy> <Steps> ## Phase 1: Plan 1. **Read the spec**: Find the `specs/*.md` file in this PR (exclude `TEMPLATE.md`). If a path is provided in `{{ARGUMENTS}}`, use that. 2. **Read CLAUDE.md**: Understand architecture, conventions, testing requirements. 3. **Read `jolt-eval/README.md`**: Understand the eval framework — the spec's Intent → Invariants and Evaluation → Performance sections may reference it. 4. **Explore relevant code**: Use `explore` agents to understand the modules, types, and patterns the implementation will touch. 5. **Extract evals**: Scan the spec's Intent → Invariants and Evaluation → Performance sections for `jolt-eval` references and list: - New invariants to add → each becomes a `/new-invariant <name>` subtask. - New objectives to add → each becomes a `/new-objective <name>` subtask. - Existing invariants/objectives that need to be changed. 6. **Create implementation plan**: Based on the spec's Intent and Execution sections, determine: - Files to create, modify, or remove - Order of changes (dependencies first) - How existing patterns and abstractions should be extended - Which tasks can run in parallel vs. sequential 7. **Post the plan** as a PR comment for visibility: ``` **Implementation plan for: {spec title}** **Changes:** 1. {file/module} — {what changes and why} 2. ... **Order:** {dependency chain} **Parallel tasks:** {which can run simultaneously} **Estimated scope:** {number of files, rough line count} ``` ## Phase 2: Execute 1. **Add jolt-eval scaffolding first**: For each new invariant/objective extracted in Phase 1, invoke the corresponding skill so the mechanical checks are in place before the implementation lands: - `/new-invariant <name>` for each new invariant - `/new-objective <name>` for each new objective Commit these additions as their own logical units. 2. **Implement** all changes from the plan. - Run independent tasks in parallel using agents where beneficial. - Follow project code style and conventions from CLAUDE.md. - Performance is critical — avoid regressions in hot paths. 3. **Commit** with clear, well-scoped messages as logical units complete. ## Phase 3: QA Cycle until all checks pass (up to 5 cycles): 1. **Format**: `cargo fmt -q` 2. **Lint** (both modes): - `cargo clippy --all --features host --message-format=short -q --all-targets -- -D warnings` - `cargo clippy --all --features host,zk --message-format=short -q --all-targets -- -D warnings` 3. **Test**: Run evaluation criteria from the spec, plus: - `cargo nextest run -p jolt-prover-legacy muldiv --cargo-quiet --features host` - `cargo nextest run -p jolt-prover-legacy muldiv --cargo-quiet --features host,zk` - `cargo nextest run -p jolt-eval --cargo-quiet` — runs every invariant's seed-corpus + random-inputs tests; any named in the spec must pass. 4. **Fix** any failures and repeat. If the same error persists 3 times, stop and post a PR comment describing the fundamental issue. ## Phase 4: Validate Run parallel validation: 1. **Correctness**: All spec evaluation criteria pass. 2. **Mechanical checks (jolt-eval)**: For each objective named in the spec's Evaluation → Performance section, run `cargo run -p jolt-eval --bin measure-objectives -- --objective <name>` and confirm it moved in the declared direction (or stayed within the declared tolerance). All invariants named or introduced in the spec's Intent → Invariants section must pass — the Phase 3 `cargo nextest run -p jolt-eval` covers seed corpus + random inputs. 3. **Code review**: Self-review for consistency with existing patterns, missing edge cases, unnecessary changes beyond the spec. 4. **Security**: Check for OWASP top 10 patterns if the changes touch input handling or external data. Fix any issues found and re-validate. ## Phase 5: Finalize 1. **Update spec status**: Change `Status` from `proposed`/`approved` to `implemented` in the spec file. 2. **Push** all commits to the PR branch. 3. **Post summary** as a PR comment: ``` **Implementation complete for: {spec title}** **Changes made:** - {file} — {summary} - ... **Evaluation results:** - {criterion 1}: PASS - {criterion 2}: PASS - ... **Tests:** All passing (host + zk modes) **Lint:** Clean ``` </Steps> Task: Implement the spec in this PR. {{ARGUMENTS}}