Quickstart: spec-engine

Run a spec plan end-to-end with quality gates in a single Python call.

from pipeline import PipelineOrchestrator

result = PipelineOrchestrator("my-plan.md").run_all()
print(result.summary())

Expected output:

3/3 tasks completed — all quality gates passed.

Step 1: Read your plan file

Use read_spec to parse a plan file and inspect the tasks before executing anything:

from pipeline import read_spec

tasks = read_spec("my-plan.md")
for task in tasks:
    print(task)

This confirms the plan file is valid and shows you the DecomposedTask objects that the orchestrator will execute.

Step 2: Run the pipeline

Pass the same plan path to PipelineOrchestrator and call run_all:

from pipeline import PipelineOrchestrator

orchestrator = PipelineOrchestrator("my-plan.md")
result = orchestrator.run_all()

To skip quality gates during a quick smoke-test, pass skip_gates=True to the constructor.

Step 3: Check the result

Inspect PipelineResult to confirm success and review per-task outcomes:

print(result.success())   # True if all tasks executed and passed gates
print(result.summary())   # Human-readable summary of the run

for task_result in result.tasks:
    print(task_result.task_name, task_result.severity())

A passing run prints True from result.success(). If a task failed, task_result.quality_gate_passed is False and task_result.error contains the failure reason.

Step 4: Resume an interrupted run

If a run was interrupted, use find_resumable_plans to find plans with saved state, then pass the path back to PipelineOrchestrator:

from spec import find_resumable_plans, load_state, get_pending_tasks

resumable = find_resumable_plans()          # searches .claude/plans by default
state = load_state(resumable[0].plan_path)
tasks = read_spec(resumable[0].plan_path)
pending = get_pending_tasks(tasks, state)
print(f"{len(pending)} tasks remaining")

Next: To run with per-task approval prompts, call execute_with_approval from spec.runner — it accepts the same skip_gates, skip_tests, and skip_simplify flags as PipelineOrchestrator.

Unresolved references

Auto-generated by attune-author fact-check. Review and either fix the source code, fix this doc, or add an override.