# Implement Spec

> Autonomous one-shot implementation from an approved spec (local/cloud only)

- Skill: `a16z/implement-spec` (Agent Skill)
- Install (CLI): `npx skillmds@latest add a16z/implement-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/a16z/implement-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: a16z (https://skillmd.com/u/a16z)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/a16z/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}}