# [F-14] Workflow Builder
Status: Specced for v2.26.0 (2026-06-10)
Milestone: v2.26.0
Issue: #133
Agent: Claude

> **Staleness banner (2026-06-10):** this brief's numbers and mechanics are historical ("29-skill library", "9 existing workflows", `generate-workflow-pages.py`, mkdocs.yml nav; the catalog is 65 with 12 workflows, and Pattern S generates site pages via `scripts/gen-site.mjs`). The authoritative design, including the decided name `utility-pm-workflow-builder` and the chain-promotion entry point, lives in `docs/internal/release-plans/v2.26.0/spec_workflow-builder-and-chaining.md`.

## Scope

Create a `utility-workflow-builder` skill that guides users through creating a new workflow file - the workflow equivalent of `utility-pm-skill-builder`. The builder produces a complete `_workflows/*.md` file with all required sections (metadata, steps, flow diagram, quality checklist, see also), a matching `commands/workflow-*.md` slash command, and regenerated docs pages.

## Problem

Creating a new workflow currently requires:
1. Knowing the file conventions (metadata table format, section structure, link conventions)
2. Manually selecting and sequencing skills from the 29-skill library
3. Writing handoff guidance between each step
4. Creating 3 files (_workflows/, commands/, docs/workflows/) + updating cross-cutting refs
5. Knowing which existing workflows might overlap

This is the same authoring friction that `pm-skill-builder` solved for individual skills.

## How It Would Work

### Input
User describes the workflow they want:
- "I need a workflow for quarterly business reviews"
- "Create a workflow that chains competitive-analysis, experiment-results, and pivot-decision"
- "I want something like Feature Kickoff but focused on API integrations"

### Process (mirrors pm-skill-builder's 4-step flow)

1. **Understand the Idea** - Accept problem-first or skill-first descriptions. Clarify: what PM process does this support? Who runs it? What's the end-to-end flow?

2. **Overlap Analysis** - Check against 9 existing workflows for coverage overlap. Could the user's need be met by an existing workflow + customization? Kill gate: if overlap is >70%, recommend customizing an existing workflow instead.

3. **Skill Selection & Sequencing** - Interactive step: present candidate skills from the library, help user select and order them, define handoff points and context flow between steps.

4. **Generate Files** - Produce:
   - `_workflows/{name}.md` with all sections (Metadata, When to Use, Steps with handoffs, Context Flow Diagram as mermaid, Tips, Quality Checklist, See Also)
   - `commands/workflow-{name}.md` slash command
   - Run `generate-workflow-pages.py` to produce `docs/workflows/{name}.md`
   - Suggest cross-cutting updates needed (AGENTS.md, mkdocs.yml nav, README)

### Output
A Workflow Implementation Packet (analogous to pm-skill-builder's Skill Implementation Packet):
- Draft workflow file ready for review
- Draft command file
- Checklist of cross-cutting updates

## Key Design Decisions (to resolve)

| Decision | Options | Recommendation |
|----------|---------|---------------|
| Skill or command? | New skill (`utility-workflow-builder`) vs. standalone command | Skill - follows pm-skill-builder pattern, allows TEMPLATE + EXAMPLE |
| Kill gate threshold | 50% / 70% / 80% overlap with existing workflow | 70% - same as pm-skill-builder |
| Auto-generate vs. review | Generate files directly vs. produce draft for human review | Draft for review (staging area) - workflows are higher-stakes than skills |
| Mermaid generation | Auto-generate mermaid from skill sequence? | Yes - linear graphs are trivially derivable |
| Cross-cutting automation | Auto-update AGENTS.md, mkdocs.yml, etc.? | No - checklist only. Too many files to safely auto-edit. |

## Dependencies

- Requires stable workflow file conventions (established in v2.9.0)
- Should ship after D-05 (workflows guide) so the builder can reference it

## Artifacts Produced

- `skills/utility-workflow-builder/SKILL.md`
- `skills/utility-workflow-builder/references/TEMPLATE.md`
- `skills/utility-workflow-builder/references/EXAMPLE.md`
- `commands/workflow-builder.md`
- Updated AGENTS.md, README, docs

## Estimated Complexity

Medium-High - similar scope to F-05 (pm-skill-builder). The overlap analysis and skill sequencing logic are non-trivial.

## PRs

TBD
