specification-workflow-spec

module

v0.2.0 Latest Latest Go to latest Published: Aug 3, 2026 License: MIT

README ¶

Specification Workflow Spec

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

Package	Description
`pkg/spectype`	Spec type registry and category definitions
`pkg/workflow`	Workflow configuration (spec requirements, synthesis, execution, evaluation)
`pkg/workflows`	Embedded default workflows with loaders (embedded, file, chain, resolving)
`pkg/template`	Spec template structure definitions
`pkg/synthesis`	Synthesis rule DAG for spec generation
`pkg/gate`	Phase gates and approval checkpoints
`pkg/layout`	Filesystem layout conventions for spec projects
`pkg/diagram`	D2 and Mermaid diagram generation from workflows
`schema`	Generated JSON Schema files

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

Spec Types

The registry defines canonical spec types across methodologies:

Source Specs (Human-Authored)

ID	Name	Category	Origins
`mrd`	Market Requirements Document	source	enterprise, aws-product, big-tech-product
`prd`	Product Requirements Document	source	startup, enterprise, big-tech
`uxd`	User Experience Design	source	design-thinking, big-tech
`opportunity-spec`	Opportunity Specification	source	aws-feature, big-tech-feature
`hypothesis`	Hypothesis Document	source	lean-startup, 0-1
`shapeup-pitch`	Shape Up Pitch	source	shapeup
`ost`	Opportunity Solution Tree	source	continuous-discovery

GTM Specs (Synthesized)

ID	Name	Category	Origins
`press`	Press Release	gtm	aws-product, big-tech
`faq`	Frequently Asked Questions	gtm	aws-product, big-tech
`narrative-6p`	Six-Pager Narrative	gtm	aws-product, big-tech-product
`narrative-1p`	One-Pager Executive Summary	gtm	enterprise, big-tech
`bmc`	Business Model Canvas	gtm	enterprise, lean-startup

Technical Specs (Synthesized)

ID	Name	Category	Origins
`trd`	Technical Requirements Document	technical	enterprise, google, big-tech
`tpd`	Test Plan Document	technical	enterprise, big-tech
`ird`	Infrastructure Requirements Document	technical	enterprise, big-tech-product

Execution Specs

ID	Name	Category	Origins
`plan`	Implementation Plan	execution	pbhq-lite
`roadmap`	Roadmap	execution	pbhq-lite
`spec`	Reconciled Specification	output	enterprise

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-product, 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-feature extends enterprise)
w, err := workflows.DefaultLoader().Load("aws-feature")
if err != nil {
    // handle error
}

w.Workflow.Name              // "aws-feature"
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(),
))

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

Project	Purpose
visionspec	CLI for spec workflow execution
structured-evaluation	LLM-as-Judge evaluation reports
multi-agent-spec	Multi-agent system definitions

License

MIT

Directories ¶

Path	Synopsis
pkg
diagram Package diagram generates workflow visualizations from profiles.	Package diagram generates workflow visualizations from profiles.
gate Package gate defines phase gates and approval checkpoints.	Package gate defines phase gates and approval checkpoints.
layout Package layout defines filesystem conventions for specification projects.	Package layout defines filesystem conventions for specification projects.
spectype Package spectype defines the registry of specification document types.	Package spectype defines the registry of specification document types.
synthesis Package synthesis defines rules for generating specs from other specs.	Package synthesis defines rules for generating specs from other specs.
template Package template defines the structure of spec templates.	Package template defines the structure of spec templates.
workflow Package workflow defines specification workflow configurations.	Package workflow defines specification workflow configurations.
workflows Package workflows provides embedded default workflows with templates and rubrics.	Package workflows provides embedded default workflows with templates and rubrics.
schema Package schema provides embedded JSON Schema files generated from Go types.	Package schema provides embedded JSON Schema files generated from Go types.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL