github / github/spec-kit

[Feature]: Add a Verification Spec to Support Automated Agent Loops

Offen
#1,862 5 Kommentare 2 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
enhancement stale
Vorherrschende Sprache
Python
Sterne
137k
Forks
12.3k
Ø Merge
2 T. 7 Std.
Gemergte PRs (30 T.)
155

Beschreibung

### Problem Statement

## Background

In the current Spec-Kit workflow, the typical structure generated during `specify` and `plan` includes multiple specification files such as:

* Feature specification
* Architecture / technical plan
* Implementation tasks

This works well for **human-driven development**, where developers manually implement the code, run tests, and decide whether the implementation satisfies the requirements.

However, in **AI-driven development workflows**, especially those using autonomous coding agents, there is an important missing component: **a structured verification specification** that defines how the implementation should be validated.

## Problem

Without a machine-readable or structured verification specification, AI agents face several challenges:

1. **No clear completion criteria**
The agent cannot reliably determine when the task is finished.

2. **No standardized validation process**
Validation steps (tests, linting, build, etc.) are implicit rather than explicitly defined.

3. **Weak support for iterative agent loops**
Modern AI coding workflows rely on iterative execution loops (e.g., implement → verify → fix → verify) until success. Without a verification spec, this loop becomes unreliable.

This becomes particularly important for agent-based workflows such as autonomous coding systems, where the agent needs deterministic rules for validating progress.

## Proposal

Introduce an additional spec file, for example:

```
verification-spec.md
```

or

```
acceptance-spec.md
```

This file would explicitly define **how the implementation should be verified**.

Example structure:

```
/specs
feature-spec.md
plan.md
tasks.md
verification-spec.md
```

## Example Verification Spec

Example content for `verification-spec.md`:

```
# Verification Specification

## Build

The project must build successfully:

make build

## Unit Tests

All tests must pass:

go test ./...

## Lint

The code must pass lint checks:

golangci-lint run

## Integration Tests

Start the service:

docker compose up

Run API tests:

scripts/test_api.sh

Expected result:
- HTTP 200 responses
- JSON schema matches specification

## Performance (optional)

Benchmark must reach:

TPS >= 5000

Run:

scripts/benchmark.sh
```

## Benefits

Adding a verification spec would significantly improve Spec-Kit's compatibility with **AI-assisted and autonomous development workflows**, including:

* AI coding agents
* iterative execution loops
* automated implementation pipelines

It enables a clear workflow like:

```
spec → plan → tasks → implement → verify → fix → verify
```

This kind of loop is increasingly common in modern AI coding environments and helps agents reliably determine success conditions.

## Optional Future Direction

A more advanced version could support a **machine-executable verification format**, such as:

```
verify:
- cmd: make build
- cmd: go test ./...
- cmd: golangci-lint run
```

This would allow agents to directly execute the verification steps without manual interpretation.

## Summary

Adding a `verification-spec` would:

* provide explicit acceptance criteria
* improve automation compatibility
* support modern AI-driven development loops

This could make Spec-Kit significantly more powerful for agent-based development workflows.

Would love to hear thoughts from maintainers and the community.

### Proposed Solution

verification-spec.md

### Alternatives Considered

_No response_

### Component

Specify CLI (initialization, commands)

### AI Agent (if applicable)

None

### Use Cases

_No response_

### Acceptance Criteria

_No response_

### Additional Context

_No response_

Beitragsleitfaden

Beitragsleitfaden öffnen

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.