specification-workflow-spec

Specification Workflow Spec (Archived)

This repository is archived. Its content — the workflow catalog, loaders, templates, rubrics, and the tools it grew (pipelines, loops, integrations, prism-sync) — has been merged into ProductBuildersHQ/visionspec, which has been renamed to specification-workflow-spec, taking over this repository's former name and Go import path. Full git history was preserved in the merge. Depend on the new repository going forward; this one is retained privately as a historical record. See docs/releases/v0.3.0.md for the final release before archival.

A formal specification for defining product specification workflows.

Overview

specification-workflow-spec provides standardized types for defining:

• Spec Types - Registry of specification document types (PRD, MRD, Press Release, FAQ, 6-Pager, etc.)
• Workflows - Methodology configurations bundling spec requirements, synthesis rules, and evaluation criteria
• Templates - Document structure definitions with required/optional sections and embedded content
• Rubrics - LLM-as-Judge evaluation criteria using structured-evaluation's rubric.RubricSet
• Synthesis Rules - Dependency graphs for generating specs from other specs
• Phase Gates - Approval checkpoints and workflow control

Architecture

┌───────────────────────────────────────────────────────────────────────────┐
│                       Workflow (Methodology Configuration)                │
├───────────────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │  SpecConfig  │  │  Synthesis   │  │  Templates   │  │   Rubrics    │   │
│  │  (required/  │  │  (DAG of     │  │  (document   │  │  (evaluation │   │
│  │   optional)  │  │   sources)   │  │   structure) │  │   criteria)  │   │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘   │
└───────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                                Execution                                  │
├───────────────────────────────────────────────────────────────────────────┤
│  Phase 1: Discovery  →  Gate  →  Phase 2: Vision  →  Gate  →  Phase 3...  │
│  (MRD)                          (Press, FAQ)                  (PRD, UXD)  │
└───────────────────────────────────────────────────────────────────────────┘

Installation

go get github.com/ProductBuildersHQ/specification-workflow-spec

Packages

Rubric definitions use structured-evaluation's canonical rubric.RubricSet type.

Spec Types

The registry defines canonical spec types across methodologies:

Source Specs (Human-Authored)

GTM Specs (Synthesized)

Technical Specs (Synthesized)

Execution Specs

See pkg/spectype/spectype.go for the full registry.

Workflows

Workflows bundle spec requirements, synthesis rules, templates, and rubrics for specific methodologies. Default workflows (aws-one-way-door, big-tech-feature, lean-startup, etc.) are embedded and load with no filesystem access:

import "github.com/ProductBuildersHQ/specification-workflow-spec/pkg/workflows"

// Load with inheritance resolution (aws-two-way-door extends enterprise)
w, err := workflows.DefaultLoader().Load("aws-two-way-door")
if err != nil {
    // handle error
}

w.Workflow.Name              // "aws-two-way-door"
w.Workflow.RequiredSpecs()   // required spec type IDs
w.Templates["press"].Content // raw markdown template
w.Rubrics["press"].Categories // structured-evaluation rubric categories

Loaders compose for customization:

// Organization overrides from a directory, falling back to embedded defaults
loader := workflows.NewResolvingLoader(workflows.NewChainLoader(
    workflows.NewFileLoader("./custom-workflows"),
    workflows.DefaultLoader(),
))

Inheritance and Provenance

Workflows inherit via extends: (e.g. both AWS door profiles extend enterprise), with child entries overriding parent entries per key. Beyond implicit inheritance, a spec can declare exactly where its template or rubric comes from:

spec_config:
  mrd:
    required: false
    template: {from: enterprise}   # resolved from the enterprise workflow
    rubric: enterprise             # bare-string shorthand for the same
  press:
    template: local                # this workflow's own templates/ dir

Declared provenance is loader-enforced: a source that does not actually provide the file is a load-time error, and a source whose resolution path leads back to the declaring workflow (e.g. naming a descendant) fails as a circular reference instead of recursing. Point sources at ancestors or unrelated workflows; descendant-owned content must be copied, not referenced.

Two library-wide guarantees are enforced by tests:

• Every declared spec resolves. Each spec in a workflow's spec_config — required or optional — must resolve to both a template and a rubric. "Optional" means optional to use in a workflow run, not optional for the library to support.
• Every synthesis source is declared. A synthesis rule may only consume specs the workflow declares in its spec_config.

Layered Rubrics

Rubrics separate three kinds of judgment via a per-category class, so an LLM-as-Judge evaluation can distinguish cultural fit from contract quality:

Categories also carry blocking (a failing blocking category fails the document regardless of weighted score) and an evaluation mode (deterministic, semantic, or human). The hardened workflow families (enterprise, aws-one-way-door, aws-two-way-door) ship fully layered PRD/TRD/TPD/IRD/UXD rubric sets, guarded by regression tests.

Domain Content Sync

Roadmap-domain spec content (MRD, OpportunitySpec, V2MOM, BMC, …) is owned upstream by prism-roadmap and synced into the embedded library by tools/prism-sync (a nested Go module). Synced files carry provenance headers; prism-sync -check detects drift.

Definition vs. Execution

Workflows describe the definition side of spec-driven development — the methodologies that produce what to build (PRD, six-pager, TRD). External tools such as GitHub Spec-Kit and AWS AI-DLC own the execution side — consuming those specs to produce code. These are the "Definition" and "Execution" halves surfaced in the VisionStudio viewer.

• Integrations (pkg/integration, pkg/integrations) are declarative descriptors of external tools: how to detect a project on disk, its artifacts and lifecycle, how to compute status from those artifacts, and where its inputs and outputs connect. They hold no scanning or execution logic — consumers implement detection against the contract.
• Pipelines (pkg/pipeline, pkg/pipelines) link a definition workflow to an execution integration, declaring how the workflow's output specs feed the tool (e.g., aws-one-way-door → ai-dlc).

Default execution integrations: spec-kit, ai-dlc, openspec, kiro.

import (
    "github.com/ProductBuildersHQ/specification-workflow-spec/pkg/integrations"
    "github.com/ProductBuildersHQ/specification-workflow-spec/pkg/pipelines"
)

// An execution tool descriptor: detection, artifacts, lifecycle, status.
in, _ := integrations.Get("spec-kit")
in.Detection.RootMarkers        // [".specify/", ...] — how to recognize a project
in.Status.Method                // "task-checkboxes" — how a viewer reads progress
in.Artifacts[0].SpecType        // maps a tool file to a spec type ID where applicable

// A definition→execution handoff: aws-one-way-door's specs feed AI-DLC.
p, _ := pipelines.Get("aws-one-way-door-to-ai-dlc")
p.Definition.Workflow           // "aws-one-way-door"
p.Execution.Integration         // "ai-dlc"
p.Handoffs                      // per-spec-type mappings across the seam

Diagram Generation

Generate D2 or Mermaid diagrams from workflows:

import "github.com/ProductBuildersHQ/specification-workflow-spec/pkg/diagram"

// Generate D2 diagram
opts := diagram.DefaultOptions()
opts.Title = "AWS Product Flow"
d2, _ := diagram.Generate(w.Workflow, diagram.FormatD2, opts)

// Generate Mermaid diagram
mermaid, _ := diagram.Generate(w.Workflow, diagram.FormatMermaid, opts)

Output formats:

• D2 - D2 language for SVG generation via d2 CLI
• Mermaid - Mermaid for embedding in Markdown

Schema Generation

JSON Schema files are generated from Go types:

go generate ./schema/...

This produces:

• schema/spectype.schema.json
• schema/workflow.schema.json
• schema/template.schema.json
• schema/synthesis.schema.json
• schema/gate.schema.json
• schema/layout.schema.json

Ecosystem

This repository is the contract layer of the ProductBuildersHQ spec stack (visionstudio → visionspec → specification-workflow-spec): it defines workflow types, schemas, and the embedded default workflow library, and holds no execution logic. The layers above act on it.

License

MIT