Add pipeline workflow to community catalog by domattioli · Pull Request #3338 · github/spec-kit

domattioli · 2026-07-05T01:42:42Z

What

Registers the Guided SDD Pipeline workflow in workflows/catalog.community.json.

The workflow itself is now hosted externally, per maintainer guidance (comment):

Repository: https://github.com/domattioli/spec-kit-workflow-pipeline
Release: v1.0.0
Raw URL: https://raw.githubusercontent.com/domattioli/spec-kit-workflow-pipeline/v1.0.0/workflow.yml

What the workflow does

Chains specify → clarify (single interactive gate) → plan → tasks → analyze → implement → converge into one guided run. Optional constitution and checklist phases. Post-implement convergence loop replaces the earlier analyze/implement fix-loop, per review discussion.

Changes in this PR

Removed the in-tree workflows/pipeline/ files (moved to the external repo above)
Added the pipeline entry to workflows/catalog.community.json

Testing

workflow.yml validates via specify workflow info
Raw URL at the v1.0.0 tag verified fetchable
Catalog JSON validates

Chains the Spec Kit phases into one guided, single-invocation pipeline with a deterministic phase resolver and one interactive clarify gate.

mnriem · 2026-07-06T15:56:36Z

Thanks for this — the analyze/fix retry loop and the single-clarify-gate UX are genuinely nice, and the code is clean and well-tested.

Before going further, I'd like to steer this toward our workflows system, because that's precisely the mechanism Spec Kit ships for chaining /speckit.* phases into one guided, resumable invocation. The pipeline's charter — "collapse the manual command sequence into one command with a human checkpoint, orchestrating the stock commands rather than reimplementing them" — is verbatim what specify workflow run already does. The built-in speckit workflow (workflows/speckit/workflow.yml) already chains specify → plan → tasks → implement with review gates, and the engine natively provides everything the extension hand-rolls:

Clarify gate → type: gate
Analyze/fix loop (≤3 cycles) → type: while with max_iterations
--skip / --add phases → boolean inputs guarding type: if steps
Deterministic phase ordering + validation → the declarative steps: list (validated up front by specify workflow run)
preview dry-run → specify workflow info ./workflow.yml
Resume / state persistence / catalog distribution → for free

Concretely, here's your pipeline expressed as a single workflow.yml — no Python resolver, wrappers, or test suite needed, since the engine owns ordering and validation:

# workflow.yml
schema_version: "1.0"
workflow:
  id: "pipeline"
  name: "Guided SDD Pipeline"
  version: "1.0.0"
  author: "domattioli"
  description: >
    Chains specify → clarify → plan → tasks → analyze → implement into one
    guided run with a single clarify gate and an analyze/fix loop.

requires:
  speckit_version: ">=0.8.5"
  integrations:
    any: ["claude", "copilot", "gemini", "opencode"]

inputs:
  spec:
    type: string
    required: true
    prompt: "Describe what you want to build"
  integration:
    type: string
    default: "auto"
  with_constitution:   # replaces --add constitution
    type: boolean
    default: false
  with_checklist:      # replaces --add checklist
    type: boolean
    default: false
  skip_clarify:        # replaces --skip clarify
    type: boolean
    default: false
  max_fix_cycles:
    type: number
    default: 3

steps:
  - id: constitution
    type: if
    condition: "{{ inputs.with_constitution }}"
    then:
      - id: constitution-run
        command: speckit.constitution
        integration: "{{ inputs.integration }}"
        input: { args: "{{ inputs.spec }}" }

  - id: specify
    command: speckit.specify
    integration: "{{ inputs.integration }}"
    input: { args: "{{ inputs.spec }}" }

  - id: clarify
    type: if
    condition: "{{ inputs.skip_clarify == false }}"
    then:
      - id: clarify-run
        command: speckit.clarify
        integration: "{{ inputs.integration }}"
        input: { args: "{{ inputs.spec }}" }
      - id: clarify-gate
        type: gate
        message: "Review clarifications before planning."
        options: [approve, reject]
        on_reject: abort

  - id: plan
    command: speckit.plan
    integration: "{{ inputs.integration }}"
    input: { args: "{{ inputs.spec }}" }

  - id: checklist
    type: if
    condition: "{{ inputs.with_checklist }}"
    then:
      - id: checklist-run
        command: speckit.checklist
        integration: "{{ inputs.integration }}"
        input: { args: "{{ inputs.spec }}" }

  - id: tasks
    command: speckit.tasks
    integration: "{{ inputs.integration }}"
    input: { args: "{{ inputs.spec }}" }

  - id: analyze-first
    command: speckit.analyze
    integration: "{{ inputs.integration }}"
    continue_on_error: true
    input: { args: "{{ inputs.spec }}" }

  - id: fix-loop
    type: while
    condition: "{{ steps.analyze-first.output.exit_code != 0 }}"
    max_iterations: 3   # see note below on templating this
    steps:
      - id: apply-fixes
        command: speckit.implement
        integration: "{{ inputs.integration }}"
        input: { args: "Resolve the analyze findings for {{ inputs.spec }}" }
      - id: analyze-again
        command: speckit.analyze
        integration: "{{ inputs.integration }}"
        continue_on_error: true
        input: { args: "{{ inputs.spec }}" }

  - id: implement
    command: speckit.implement
    integration: "{{ inputs.integration }}"
    input: { args: "{{ inputs.spec }}" }

Two things to verify if you go this route:

max_iterations from an input — I hardcoded 3 above because I'm not certain the engine coerces a templated {{ inputs.max_fix_cycles }} at that field. If it accepts an expression, wire the input back in; if not, hardcoding is fine.
Analyze signaling — the loop assumes speckit.analyze returns non-zero when findings remain. If it always exits 0, branch on parsed output instead (an if/gate on steps.analyze-first.output).

If you'd like to publish this, the path is the community workflow catalog — see workflows/PUBLISHING.md. That gets it discoverable via specify workflow search/add while keeping it maintained in your own repo.

domattioli · 2026-07-08T20:30:59Z

Thanks for the feedback, mnriem. We've implemented the workflow approach you suggested instead of the extension.

Summary of changes

Created workflows/pipeline/workflow.yml that expresses the full pipeline using Spec Kit's workflows engine:

Chains specify → clarify → plan → tasks → analyze → implement
Optional phases: constitution, checklist
Analyze/fix loop with configurable max cycles (default 3)
Clarify gate (can be skipped)
Full documentation in README.md and CHANGELOG.md

Advantages

Uses engine-native if/while/gate constructs (no Python resolver needed)
Declarative YAML configuration
Built-in resume and state persistence via the engine
Discoverable via specify workflow search
Simpler to maintain

Validation

We validated the workflows/pipeline/workflow.yml locally against specify workflow run. It correctly handles the clarify gate (pausing for approval), phase sequencing, and resumability via specify workflow resume.

One fix along the way: max_iterations in the while step needs a literal integer — it doesn't accept a templated {{ inputs.max_fix_cycles }} expression, so we hardcoded it to 3 for now (matching your original suggestion).

Example invocation:

specify workflow run workflows/pipeline/workflow.yml --input 'spec=add user authentication with JWT tokens'

This runs the full pipeline and pauses at the clarify gate for approval before continuing to plan/tasks/analyze/implement.

mnriem · 2026-07-09T18:06:58Z

You are aware we have a converge command now too? Should that one be in play?

Drop the extensions/pipeline Python resolver, command wrappers, and test suite in favor of a single workflows/pipeline/workflow.yml, per review feedback that the workflows engine already owns phase orchestration, ordering, validation, and resume. Rework the loop around the new speckit.converge command: analyze runs as a single pre-implement consistency pass (its findings are artifact-level, not code-level), and a bounded post-implement convergence loop (implement -> converge, up to 3 cycles) closes any code/spec gaps. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

domattioli · 2026-07-10T01:07:32Z

You're right: converge fits better than my original pairing. Two changes:

Dropped the analyze/implement fix-loop. analyze checks artifact consistency, not code, so "fix via implement" was a verbiage bug that the orchestrator bot and I didn't catch.
Added a post-implement convergence loop per converge's own contract ("must run after implement"): implement → converge → (tasks appended?) → implement → converge…, capped at 3 cycles. A converged run leaves tasks.md untouched, so the loop stays safe even when the engine can't branch on converge's outcome. If steps.X.output can carry the converged/tasks_appended signal, I'll wire the condition to it.

Also removed the old extensions/pipeline/ tree (Python resolver + wrappers + tests) since the workflow supersedes it — the PR is now purely the workflows/pipeline/workflow.yml approach. Updated the workflow, README, and CHANGELOG.

Copilot

Pull request overview

This PR introduces a new “pipeline” workflow under workflows/ that aims to run the full Spec-Driven Development command sequence (with optional phases) as a single guided workflow, and adds accompanying documentation/changelog for publishing and use.

Changes:

Added a new pipeline workflow YAML that chains Spec Kit phases and attempts a post-implement convergence loop.
Added workflow documentation (README.md) and a workflow-local changelog (CHANGELOG.md).

Show a summary per file

File	Description
workflows/pipeline/workflow.yml	Defines the new pipeline workflow steps, inputs, requirements, and convergence loop logic.
workflows/pipeline/README.md	Documents workflow purpose, inputs, and usage examples.
workflows/pipeline/CHANGELOG.md	Tracks workflow version history and initial feature set.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 3/3 changed files
Comments generated: 9
Review effort level: Low

+  - id: converge-loop
+    type: while
+    condition: "{{ steps.converge-first.output.exit_code != 0 }}"
+    max_iterations: 3
+    steps:
+      - id: implement-remaining
+        command: speckit.implement
+        integration: "{{ inputs.integration }}"
+        input: { args: "Complete the appended convergence tasks for {{ inputs.spec }}" }
+      - id: converge-again
+        command: speckit.converge
+        integration: "{{ inputs.integration }}"
+        continue_on_error: true
+        input: { args: "{{ inputs.spec }}" }


+  id: "pipeline"
+  name: "Guided SDD Pipeline"
+  version: "1.0.0"
+  author: "domattioli"


+
+## Overview
+
+This workflow orchestrates the full SDD (Software Design Document) pipeline:


+### 3. Clarify (Optional Gate)
+Provides clarifications on the spec, then pauses for human review/approval before proceeding to planning.
+
+Can be skipped entirely with `--skip-clarify`.


+### Added
+- Initial release of the Guided SDD Pipeline workflow
+- Support for optional constitution phase (`with_constitution`)
+- Support for optional checklist phase (`with_checklist`)  


+
+### Run with defaults
+```bash
+specify workflow run pipeline "build a todo app"


+specify workflow run pipeline \
+  "build a todo app" \
+  --with-constitution \
+  --with-checklist


+specify workflow run pipeline \
+  "build a todo app" \
+  --integration claude


+specify workflow run pipeline \
+  "build a todo app" \
+  --skip-clarify


mnriem · 2026-07-10T19:03:39Z

Similarly to our extension and presets we can host this in our community catalog. Please create it in your own GitHub repository so we can do so. See https://github.com/github/spec-kit/blob/main/workflows/PUBLISHING.md

…nity catalog

domattioli · 2026-07-10T19:24:18Z

Done — the workflow now lives in its own repository:

Repo: https://github.com/domattioli/spec-kit-workflow-pipeline (workflow.yml, README, CHANGELOG, MIT license)
Release: v1.0.0, raw URL verified fetchable at the tag

This PR is reworked to only add the pipeline entry to workflows/catalog.community.json, per PUBLISHING.md. Let me know if you'd like any changes to the catalog entry.

Copilot

Review details

Files reviewed: 1/1 changed files
Comments generated: 3
Review effort level: Medium

+      "description": "Chains specify, clarify, plan, tasks, analyze, implement, and converge into one guided run with a single clarify gate and a post-implement convergence loop",
+      "author": "domattioli",
+      "version": "1.0.0",
+      "url": "https://raw.githubusercontent.com/domattioli/spec-kit-workflow-pipeline/v1.0.0/workflow.yml",


+      "repository": "https://github.com/domattioli/spec-kit-workflow-pipeline",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.5"


+      "author": "domattioli",
+      "version": "1.0.0",
+      "url": "https://raw.githubusercontent.com/domattioli/spec-kit-workflow-pipeline/v1.0.0/workflow.yml",
+      "repository": "https://github.com/domattioli/spec-kit-workflow-pipeline",


mnriem · 2026-07-13T15:23:15Z

Please address Copilot feedback

Add pipeline extension

afaefe5

Chains the Spec Kit phases into one guided, single-invocation pipeline with a deterministic phase resolver and one interactive clarify gate.

domattioli changed the title ~~Add pipeline extension~~ [feat] Add pipeline extension Jul 5, 2026

mnriem requested a review from Copilot July 10, 2026 13:22

Copilot started reviewing on behalf of mnriem July 10, 2026 13:23 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

refactor(pipeline): move workflow to external repo, register in commu…

7b0365d

…nity catalog

domattioli changed the title ~~[feat] Add pipeline extension~~ Add pipeline workflow to community catalog Jul 10, 2026

mnriem requested a review from Copilot July 13, 2026 12:44

Copilot started reviewing on behalf of mnriem July 13, 2026 12:45 View session

Copilot AI reviewed Jul 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add pipeline workflow to community catalog#3338

Add pipeline workflow to community catalog#3338
domattioli wants to merge 3 commits into
github:mainfrom
domattioli:add-pipeline-extension

domattioli commented Jul 5, 2026 •

edited

Loading

Uh oh!

mnriem commented Jul 6, 2026

Uh oh!

domattioli commented Jul 8, 2026 •

edited

Loading

Uh oh!

mnriem commented Jul 9, 2026

Uh oh!

domattioli commented Jul 10, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

mnriem commented Jul 10, 2026

Uh oh!

domattioli commented Jul 10, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

mnriem commented Jul 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		## Overview

		This workflow orchestrates the full SDD (Software Design Document) pipeline:

Uh oh!

Conversation

domattioli commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

What the workflow does

Changes in this PR

Testing

Uh oh!

mnriem commented Jul 6, 2026

Uh oh!

domattioli commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of changes

Advantages

Validation

Uh oh!

mnriem commented Jul 9, 2026

Uh oh!

domattioli commented Jul 10, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

mnriem commented Jul 10, 2026

Uh oh!

domattioli commented Jul 10, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

mnriem commented Jul 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

domattioli commented Jul 5, 2026 •

edited

Loading

domattioli commented Jul 8, 2026 •

edited

Loading