• Home
• Spec System
• Quickstart

Quickstart Walkthrough

This guide walks you through the complete Spec System lifecycle — from creating your first spec to shipping verified code. By the end, you'll have used all three commands and understand how they fit together.

Example Scenario

Throughout this guide we'll follow a realistic example: adding a Redis caching layer to an API. The commands you'll run are:

# Step 1 — Create the spec
/z-spec-create Add a Redis caching layer to our API endpoints

# Step 2 — Judge the spec
/z-spec-judge specs/20260406-redis-caching/spec-redis-caching-20260406.md

# Step 3 — Execute the spec
/z-spec-execute specs/20260406-redis-caching/

# Step 4 — Review and ship (manual)

Prerequisites

Before you start, make sure you have:

• Cursor IDE installed and running
• The zoto-spec-system plugin installed in your workspace (see the Overview for installation instructions)
• A project open in Cursor that you want to add a feature to

Step 0: Initialise the config file Required

Run the init command once per repository to scaffold .zoto/spec-system/config.yml. Every key is commented out alongside the default value the plugin would otherwise apply — uncomment any line(s) to override.

/z-spec-init

Step 1: Create a Spec

Open the Cursor chat and type the /z-spec-create command followed by a description of what you want to build:

/z-spec-create Add a Redis caching layer to our API endpoints

What happens

The Spec System spawns a generator agent that follows an 8-step workflow:

1. Gathers requirements — asks you clarifying questions about scope, constraints, and goals
2. Explores your codebase — scans files and patterns to understand existing architecture
3. Proposes key decisions — presents architectural choices for your approval
4. Builds the dependency graph — determines which subtasks depend on which
5. Assigns agents — picks the right subagent type for each subtask
6. Creates the spec files — writes the index and subtask files to disk
7. Reviews with you — presents the full spec for your approval
8. Runs an automatic judge — assesses quality before finalizing

What you'll see in Cursor

What gets created

After you approve, the system creates a spec directory with an index file and individual subtask files:

specs/20260406-redis-caching/
├── spec-redis-caching-20260406.md            # Coordination index
├── subtask-01-redis-caching-setup-20260406.md
├── subtask-02-redis-caching-client-20260406.md
├── subtask-03-redis-caching-middleware-20260406.md
├── subtask-04-redis-caching-invalidation-20260406.md
└── subtask-05-redis-caching-tests-20260406.md

The spec index contains the subtask manifest — the source of truth for the entire lifecycle:

# Spec: Redis Caching Layer

**Feature**: redis-caching
**Created**: 2026-04-06
**Status**: Ready for Review

## Overview

Add a Redis caching layer to API endpoints to reduce database load
and improve response times for frequently accessed resources.

## Subtask Manifest

| ID | File | Subagent | Dependencies | Phase |
|----|------|----------|-------------|-------|
| 01 | subtask-01-redis-caching-setup-20260406.md | generalPurpose | — | 1 |
| 02 | subtask-02-redis-caching-client-20260406.md | generalPurpose | 01 | 2 |
| 03 | subtask-03-redis-caching-middleware-20260406.md | generalPurpose | 02 | 3 |
| 04 | subtask-04-redis-caching-invalidation-20260406.md | generalPurpose | 02 | 3 |
| 05 | subtask-05-redis-caching-tests-20260406.md | generalPurpose | 03, 04 | 4 |

## Definition of Done

- [ ] Redis client configured and connecting
- [ ] Cache middleware intercepts API responses
- [ ] Invalidation strategy implemented
- [ ] Integration tests passing
- [ ] No linter errors introduced

Step 2: Judge the Spec

The judge runs automatically after spec creation, but you can also run it manually at any time. Pass the path to your spec index:

/z-spec-judge specs/20260406-redis-caching/spec-redis-caching-20260406.md

What happens

A fresh, independent judge agent assesses your spec across six dimensions. It has no knowledge of the creation process, ensuring an unbiased evaluation.

1. Loads the spec index and all subtask files
2. Explores the codebase to verify assumptions
3. Scores each of six quality dimensions (1–5)
4. Validates the subtask manifest and dependency graph
5. Checks each subtask for quality and completeness
6. Writes an assessment report to the spec directory
7. Offers to apply fixes — presents actionable findings and asks whether to apply them directly to the spec files

What you'll see

Understanding the verdict

The overall score is a weighted average of all six dimensions:

Dimension	Weight	What It Measures
Completeness	25%	All requirements covered, no gaps in deliverables
Feasibility	20%	Subtasks are achievable, scope is realistic
Structure	20%	Dependencies are correct, phases are logical
Specificity	15%	Clear objectives, concrete deliverables
Risk Awareness	10%	Edge cases considered, blockers identified
Convention Compliance	10%	Matches your repository's patterns and tooling

The verdict determines what happens next:

Verdict	Score	Action
Approve	4.0+	Spec is ready for /z-spec-execute
Conditional	3.0–3.9	Address the listed findings before executing
Reject	< 3.0	Significant issues — rework with /z-spec-create

Step 3: Execute the Spec

Once your spec is approved, run the execute command to have the system implement it:

/z-spec-execute specs/20260406-redis-caching/

What happens

The executor agent coordinates the entire implementation through a structured pipeline:

1. Validates the manifest — confirms all files exist and dependencies are consistent
2. Confirms with you — presents an execution summary and waits for your approval
3. Executes phase by phase — spawns subagents for each subtask, respecting dependency order
4. Verifies adversarially — after each subtask, a fresh judge agent independently confirms deliverables
5. Runs final checks — full test suite, linter, and quality audit
6. Writes the execution report — a persistent record of what was done

What you'll see

Phase execution model

Subtasks run in phases. Within a phase, independent subtasks run in parallel (up to 4 at a time by default). The next phase doesn't start until all subtasks in the current phase are complete and verified.

For our Redis caching example:

Phase	Subtasks	What happens
1	01 (Setup)	Redis dependencies and configuration added
2	02 (Client)	Redis client module created
3	03 (Middleware), 04 (Invalidation)	Run in parallel — both depend on the client
4	05 (Tests)	Integration tests covering all components

Adversarial verification

After each subtask completes, a fresh judge agent (not the one that did the work) independently verifies every deliverable. The judge:

• Confirms files exist and have expected content
• Checks that code builds and passes linting
• Validates that tests exist and are syntactically correct
• Sets the authoritative checklist state — unticking anything it can't confirm

Each subtask receives a verdict: Verified, Partial, or Failed. If a subtask fails verification, execution pauses and you're asked how to proceed.

Step 4: Verify & Ship

After execution completes, the system writes an execution report and presents it for your review:

specs/20260406-redis-caching/
├── spec-redis-caching-20260406.md
├── subtask-01-redis-caching-setup-20260406.md
├── ...
└── execution-report-redis-caching-20260406.md   # <-- New

Reading the execution report

The report contains a complete record of the execution:

# Execution Report: Redis Caching Layer

**Spec**: spec-redis-caching-20260406.md
**Started**: 2026-04-06 14:23:01 UTC
**Completed**: 2026-04-06 14:35:42 UTC
**Duration**: 12m 41s
**Status**: Completed

## Subtask Results

| ID | Subtask | Subagent | Verification | Files Modified |
|----|---------|----------|-------------|----------------|
| 01 | Setup | generalPurpose | Verified | 3 |
| 02 | Client | generalPurpose | Verified | 2 |
| 03 | Middleware | generalPurpose | Verified | 4 |
| 04 | Invalidation | generalPurpose | Verified | 2 |
| 05 | Tests | generalPurpose | Verified | 3 |

## Verification Results

### Test Suite
- Status: PASS
- Tests run: 24

### Linter
- Status: CLEAN

Reviewing the changes

Before approving, review the work:

1. Read the execution report — check that all subtasks are Verified and tests pass
2. Review modified files — the report lists every file that was created or changed
3. Run the application — verify the feature works as expected in your local environment
4. Check edge cases — test the scenarios from the spec's risk analysis

Once you're satisfied, approve the spec in the chat. The system marks it as Completed and the lifecycle is done.

What's Next

Now that you've completed the full lifecycle, explore these resources: