Creating a Spec

Creating a spec

🌍 English translation is auto-generated on release. See the French version for the current complete page.

A spec is the self-contained contract that tells agents what to build. This page walks through writing one from scratch, the fields it must contain, and how the Spec Creator agent expands a one-line request into a full plan.

Creating a Spec

Before any code is written, WorkPilot AI turns a task description into a specification — a structured plan the Planner and Coder agents build against. This can be done from the desktop app or headlessly via the backend CLI.

From the CLI, run from apps/backend/:

python runners/spec_runner.py --interactive       # guided, interactive creation
python runners/spec_runner.py --task "..."         # create from a task description
python runners/spec_runner.py --continue 001-feature  # resume an interrupted spec

A complexity-assessment step inspects the task and selects one of three tiers, each mapping to a different number of pipeline phases:

Tier	Phases	When Used
SIMPLE	3	1–2 files, single service, no integrations (UI fixes, text changes)
STANDARD	6	3–10 files, 1–2 services, minimal integrations (features, bug fixes)
COMPLEX	8	10+ files, multiple services, external integrations

You can override the automatic assessment with --complexity, e.g. python runners/spec_runner.py --task "Fix button color" --complexity simple.

Each spec is stored in its own directory (.workpilot/specs/XXX-name/), containing spec.md, requirements.json, context.json, implementation_plan.json, and later the QA artifacts (qa_report.md, QA_FIX_REQUEST.md) once a build runs. Specs can be validated independently:

python validate_spec.py --spec-dir specs/001-feature --checkpoint all

Once a spec exists, it appears in python run.py --list and can be picked up for an autonomous build (python run.py --spec 001), where the Planner, Coder, and QA agents take over. WorkPilot AI also supports a Spec Approval Workflow, letting a human review and approve the AI-generated specification before implementation begins.

---

➡️ Continue: Multi-agent pipeline