Fast Spec - Full Specification Pipeline

Role: Specification Pipeline Orchestrator

You orchestrate the complete feature specification workflow by launching each step as a subtask with clean context. Each subtask invokes its corresponding speckit command, ensuring no context pollution between phases.

Capabilities

Execute full spec pipeline in one command
Clean context isolation between steps (each runs as independent subtask)
Delegate each phase to specialized speckit commands
Progress tracking with phase indicators
Final consolidated summary with all artifacts
Fail-fast on critical errors
Consistent behavior with standalone speckit commands

Requirements

Existing speckit commands (/speckit.specify, /speckit.clarify, /speckit.plan, /speckit.tasks, /speckit.analyze)
.specify/ directory structure with templates and scripts
Git repository for branch management

Workflow Overview

/fast-spec <feature description>
     |
     v
[1/5] SUBTASK: /speckit.specify --> Creates branch + spec.md (clean context)
     |
     v
[2/5] SUBTASK: /speckit.clarify --> Resolves ambiguities (clean context)
     |
     v
[3/5] SUBTASK: /speckit.plan --> Generates design artifacts (clean context)
     |
     v
[4/5] SUBTASK: /speckit.tasks --> Generates tasks.md (clean context)
     |
     v
[5/5] SUBTASK: /speckit.analyze --> Validates consistency (clean context)
     |
     v
[SUMMARY] Consolidated report with all artifacts and issues

Context Isolation Strategy

CRITICAL: Each step MUST run as an independent subtask to ensure clean context.

Why Clean Context Matters

Prevents token bloat: Each phase generates significant content; accumulated context would exceed limits
Avoids hallucination: Previous phase artifacts in context can cause the agent to "remember" outdated states
Ensures consistency: Each command reads fresh state from disk, not stale in-memory representations
Matches standalone behavior: Running /speckit.plan standalone should behave identically to running it within /fast-spec

How to Execute Each Step

Use the Task tool to launch each step as a subtask:

Task(
  description="[Step N/5] speckit.{command}",
  prompt="/speckit.{command} {arguments if any}",
  subagent_type="general"
)

IMPORTANT:

Wait for each subtask to complete before launching the next
Parse the subtask result to check for success/failure
Only proceed to next step if current step succeeded
Collect key outputs (paths, metrics) from each subtask for final summary

Usage

Basic Usage

/fast-spec Add user authentication with OAuth2

With Context

/fast-spec Create a dashboard for analytics that shows user metrics and trends

Execution Steps

When /fast-spec <feature description> is invoked, you MUST execute these steps in order, each as an independent subtask:

Step 1: Specify [1/5]

Execution: Launch subtask with clean context

Task(
  description="[1/5] speckit.specify",
  prompt="/speckit.specify <feature description>",
  subagent_type="general"
)

What the subtask does:

Creates feature branch (numbered)
Generates initial spec.md from template
Runs specification quality validation
Handles clarification questions if needed (max 3)

Success criteria:

Branch created and checked out
spec.md created in specs/{number}-{short-name}/
All quality checklist items pass
No more than 3 [NEEDS CLARIFICATION] markers remain

Collect from result: Branch name, spec file path

On failure: Stop pipeline, report error, suggest fix

Step 2: Clarify [2/5]

Execution: Launch subtask with clean context

Task(
  description="[2/5] speckit.clarify",
  prompt="/speckit.clarify",
  subagent_type="general"
)

What the subtask does:

Loads current spec from active branch (fresh from disk)
Scans for ambiguities across taxonomy categories
Asks up to 5 targeted clarification questions (sequential)
Updates spec with answers in ## Clarifications section
Integrates clarifications into relevant spec sections

Success criteria:

All critical ambiguities resolved
Coverage summary shows acceptable status
Spec updated with clarifications

User interaction: May pause for answers (respects user "done" signal)

On failure: Report coverage gaps, suggest proceeding if only low-impact items remain

Step 3: Plan [3/5]

Execution: Launch subtask with clean context

Task(
  description="[3/5] speckit.plan",
  prompt="/speckit.plan",
  subagent_type="general"
)

What the subtask does:

Loads spec.md and constitution.md (fresh from disk)
Runs Constitution Check against quality gates
Phase 0: Generates research.md (resolves tech unknowns)
Phase 1: Generates data-model.md, contracts/, quickstart.md
Updates agent context (AGENTS.md)

Success criteria:

plan.md complete with Technical Context filled
Constitution Check passes or violations justified
All design artifacts generated
No unresolved NEEDS CLARIFICATION in technical sections

Collect from result: List of generated artifacts

On failure: Report gate violations or missing clarifications

Step 4: Tasks [4/5]

Execution: Launch subtask with clean context

Task(
  description="[4/5] speckit.tasks",
  prompt="/speckit.tasks",
  subagent_type="general"
)

What the subtask does:

Loads plan.md, spec.md, and optional artifacts (fresh from disk)
Maps user stories to tasks
Organizes tasks by phase (Setup → Foundational → User Stories → Polish)
Generates dependency graph
Creates parallel execution examples

Success criteria:

tasks.md generated with all user stories covered
Each task follows checklist format: - [ ] [TaskID] [P?] [Story?] Description
All requirements have ≥1 task
Dependencies clearly defined

Collect from result: Task count, phase count

On failure: Report missing coverage or format violations

Step 5: Analyze [5/5]

Execution: Launch subtask with clean context

Task(
  description="[5/5] speckit.analyze",
  prompt="/speckit.analyze",
  subagent_type="general"
)

What the subtask does:

Loads spec.md, plan.md, tasks.md (fresh from disk, read-only)
Detects duplications, ambiguities, underspecifications
Validates constitution alignment
Checks coverage (requirements → tasks mapping)
Identifies inconsistencies

Success criteria:

Analysis report generated
Coverage metrics calculated
Issues categorized by severity (CRITICAL/HIGH/MEDIUM/LOW)

Collect from result: Coverage %, issue counts by severity, critical issues list

Output: Structured Markdown report with findings table

On failure: N/A (read-only, always succeeds)

Step 6: Summary (Orchestrator Context)

Execution: This step runs in the orchestrator context (NOT a subtask)

Action: Generate consolidated pipeline report using collected data from subtasks

Content:

## Fast Spec Pipeline - COMPLETE

**Feature**: {branch name}
**Status**: ✅ All phases completed

### Generated Artifacts

- Branch: `{number}-{short-name}`
- Spec: `specs/{number}-{short-name}/spec.md`
- Plan: `specs/{number}-{short-name}/plan.md`
- Tasks: `specs/{number}-{short-name}/tasks.md`
- Research: `specs/{number}-{short-name}/research.md` (if exists)
- Data Model: `specs/{number}-{short-name}/data-model.md` (if exists)
- Contracts: `specs/{number}-{short-name}/contracts/` (if exists)

### Analysis Summary

- Total Requirements: {count}
- Total Tasks: {count}
- Coverage: {percentage}%
- Issues: {critical} CRITICAL, {high} HIGH, {medium} MEDIUM, {low} LOW

### Next Steps

{If CRITICAL issues}: ⚠️ Resolve CRITICAL issues before `/speckit.implement`
{If no CRITICAL}: ✅ Ready for implementation - run `/speckit.implement`

### Critical Issues (if any)

{List of CRITICAL findings from analyze}

Patterns

Clean Context Execution

CRITICAL: Each phase MUST run as an independent subtask:

Orchestrator (this context)
    │
    ├──► Task [1/5] speckit.specify ──► returns: branch, spec path
    │         (clean context)
    │
    ├──► Task [2/5] speckit.clarify ──► returns: clarification count
    │         (clean context)
    │
    ├──► Task [3/5] speckit.plan ──► returns: artifact list
    │         (clean context)
    │
    ├──► Task [4/5] speckit.tasks ──► returns: task count
    │         (clean context)
    │
    ├──► Task [5/5] speckit.analyze ──► returns: metrics, issues
    │         (clean context)
    │
    └──► Summary (orchestrator generates from collected results)

Why this works:

Each subtask starts fresh, reading artifacts from disk
No accumulated context between phases
Subtask results are minimal (paths, counts, issues)
Orchestrator only holds summary data, not full artifacts

Sequential Execution (REQUIRED)

Steps MUST run sequentially, not in parallel:

specify creates branch and spec → must complete before clarify
clarify updates spec → must complete before plan
plan generates design → must complete before tasks
tasks needs plan → must complete before analyze
analyze validates all → runs last

DO NOT launch multiple subtasks in parallel - each depends on the previous.

Full Pipeline Execution

Each phase delegates to its corresponding speckit command via subtask, ensuring:

Clean context isolation (no token bloat or stale state)
Consistent behavior with standalone commands
Reusable components
Maintainability (single source of truth)

Error Handling

Failures in one subtask stop the pipeline
Clear error messages reference the failed command
User can resume from specific step using standalone commands
Preserve all artifacts up to failure point
Context isolation ensures partial failures don't corrupt state

User Interaction

/speckit.specify subtask may pause for clarification questions (max 3)
/speckit.clarify subtask may pause for sequential questions (max 5)
User can signal early termination ("done", "skip clarify")
User interactions happen within subtask context, not orchestrator

Anti-Patterns

Running Without Subtasks

Why bad: Context accumulates across phases, causing token overflow and stale state

Instead: ALWAYS use Task tool to launch each step as independent subtask

Running Steps in Parallel

Why bad: Each step depends on artifacts from previous step

Instead: Run steps sequentially, waiting for each to complete

Collecting Full Artifacts in Orchestrator

Why bad: Defeats purpose of context isolation; orchestrator context bloats

Instead: Collect only summary data (paths, counts, issue lists) from subtask results

Running Steps Manually

Why bad: More tedious, no consolidated report

Instead: Use /fast-spec for full pipeline; use individual /speckit.* commands only for:

Debugging specific phase
Updating single artifact after implementation
Iterative refinement of one section

Skipping Clarify

Why bad: Downstream rework, ambiguous specs

Instead: Let pipeline run clarify unless explicitly exploratory spike

Ignoring Analyze Issues

Why bad: Inconsistent artifacts, implementation problems

Instead: Address CRITICAL issues before proceeding to /speckit.implement

Related Commands

/speckit.specify - Step 1: Create spec
/speckit.clarify - Step 2: Resolve ambiguities
/speckit.plan - Step 3: Generate technical design
/speckit.tasks - Step 4: Create task breakdown
/speckit.analyze - Step 5: Validate consistency
/speckit.implement - Next: Execute implementation

References

See individual speckit command files: .opencode/command/speckit.*.md
OpenCode Agents Documentation
OpenCode Commands Documentation