#1983·OpenSpec

feat: keep agents on spec by wiring in the project's own checks

Author: clay-goodCreated Sep 25, 2026Updated Sep 25, 2026
Labelsdesign-review

OpenSpec's value depends on the agent actually following the specs while it writes code. Today that's mostly left to the agent's judgment, and it often drifts. #901 is one example: agents skip reading the existing specs before proposing a change.

Agents already check their own work as they go: they run tests, linters and builds. OpenSpec doesn't use any of that. The apply instructions never tell the agent to run the project's checks, and config.yaml has no place to say what those checks are. So "done" means "tasks ticked," not "the code passes and matches the spec."

Ideas

Idea What it does
Project checks in config.yaml Declare the project's test, lint and build commands once, e.g. checks: { test: "make test", lint: "make lint" }
Apply runs them Apply tells the agent to run the declared checks after each task and fix failures before ticking it off
Read the specs first Apply and propose name the exact main specs the change touches and tell the agent to read them before writing anything (#901)
Trace scenarios to tests Every scenario the agent implements should have a test, reported by verify (builds on #1979)
Setup check in openspec doctor Warn when the project has no declared checks, no tests, or an agent instructions file too big to be useful

Out of scope

  • OpenSpec running the checks itself or blocking archive on them. This issue is about steering the agent, not replacing CI.
  • Judging whether the code is good. Only whether the agent did what the project and spec ask.

Open questions

  • Should checks be advisory guidance only (like operations.apply.guidance), or also something openspec verify reports on?
  • Can we detect likely commands (package.json scripts, Makefile targets) during init and offer to fill checks in?

Related: #901, #880, #1979, #1720