The WORKFLOW.md format

WORKFLOW.md is a multi-actor contract: a structured document that specifies, for each step in a workflow, who is eligible to perform it (actor), what inputs it requires, what outputs it produces, and what happens next. It is designed for teams where human and AI agents work together — the typed outputs of one step become the required inputs of the next.

Any worker reading a workflow file — human or agent — can immediately identify which steps they are eligible to perform, what artifacts must exist before they start, and what they must produce before the next step can begin.

A workspace is split into two tiers to avoid bloating any single LLM context:

The manifest contains a load instruction that tells the LLM exactly what to do — read the manifest, then load only the relevant workflow file for the current task.

The root WORKFLOW.md is a Markdown file with YAML frontmatter and a structured YAML code block:

---
name: Acme Engineering
version: 1.0.0
team: Acme Platform Team
exported: 2026-05-08T10:00:00Z
---

# Workflow Manifest: Acme Engineering

## Load Instructions

This file is the workspace index. When starting a session, read this manifest first.
Load only the workflow files relevant to your current task.
Match your task to the workflow descriptions and tags below.

```yaml
workspace:
  name: Acme Engineering
  version: 1.0.0
  workflows:
    - id: discovery
      name: Discovery & Requirements
      file: workflows/discovery.md
      description: User research, design, and PRD drafting
      tags: [discovery, ux, requirements]
      tokens: 1420
    - id: development
      name: Development
      file: workflows/development.md
      description: AI-assisted feature development and testing
      tags: [dev, claude-code, cursor, testing]
      depends_on: [discovery]
      tokens: 2180
    - id: delivery
      name: Delivery
      file: workflows/delivery.md
      description: Deployment, CI/CD, and monitoring
      tags: [deployment, ci-cd, vercel]
      depends_on: [development]
      tokens: 980
```

## Workflow Index

- **[Discovery & Requirements](workflows/discovery.md)** — User research, design, and PRD drafting *(≈1,420 tokens)*
- **[Development](workflows/development.md)** — AI-assisted feature development and testing *(≈2,180 tokens)*
- **[Delivery](workflows/delivery.md)** — Deployment, CI/CD, and monitoring *(≈980 tokens)*

Each workflow file follows the same pattern: YAML frontmatter, a prose introduction, a conventions section, and a single ## Steps YAML block containing all steps for that workflow:

---
name: Discovery & Requirements
version: 1.0.0
team: Acme Platform Team
description: User research, design, and PRD drafting.
tags: [discovery, ux, requirements]
exported: 2026-05-08T10:00:00Z
---

# Workflow: Discovery & Requirements

This workflow covers user research through PRD sign-off.
See `WORKFLOW.md` in the project root for the full workspace manifest.

## Conventions

- `actor: human` — must be performed by a person
- `actor: agent` — can be fully delegated to an AI agent
- `actor: either` — human or agent, at the team's discretion
- `enforcement: required` — this step must be completed before proceeding
- `enforcement: recommended` — skip only with documented justification
- `enforcement: optional` — use at team discretion
- `alternatives` — acceptable substitutes when the primary tool is unavailable

---

## Steps

```yaml
workflow:
  id: discovery-requirements
  name: Discovery & Requirements
  steps:
    - id: research-synthesis
      name: User Research Synthesis
      description: Synthesize interviews and analytics into insights.
      inputs:
        - "Interview recordings"
        - "Analytics exports"
      outputs:
        - "Insight brief"
        - "User journey map"
      ai:
        - name: Claude Sonnet
          model: claude-sonnet-4-6
          skills: [summarize, extract-themes]
          harness: claude-code
      tools:
        - name: Notion
          type: saas
          required: true
          alternatives: [Confluence, Miro]
        - name: Dovetail
          type: saas
          required: false
      actor: either
      enforcement: required
    - id: prd-drafting
      name: PRD Drafting
      description: Draft product requirements with Claude assistance.
      inputs:
        - "Insight brief"
        - "User journey map"
      outputs:
        - "PRD"
        - "Acceptance criteria"
      ai:
        - name: Claude Sonnet
          model: claude-sonnet-4-6
          skills: [write, structure, critique]
          harness: claude-code
      tools:
        - name: Linear
          type: saas
          required: true
          alternatives: [Jira, "GitHub Issues"]
      actor: agent
      enforcement: required
```

Token counts are estimated as ceil(serializedChars / 3.8). The constant 3.8 chars/token is the empirical midpoint for mixed YAML + English content, based on published benchmarks against the cl100k tokenizer (the same family used by Claude). Accuracy is ±8% on typical workflow files.

Budget guidelines: keep individual workflow files under 2,000 tokens for comfortable inclusion in a working session. The manifest itself targets ≤ 300 tokens.

Add this to your project's CLAUDE.md or system prompt:

## Workflow context

A `WORKFLOW.md` file exists at the project root. It is the manifest for this team's
product workflow. When starting any work session:

1. Read `WORKFLOW.md` to understand what workflow files exist.
2. Identify which workflow(s) are relevant to the current task based on descriptions and tags.
3. Read only those workflow files from the `workflows/` directory.
4. Only perform steps where `actor` is `agent` or `either`. Steps marked `actor: human`
   require a person and must not be executed autonomously.
5. Before starting a step, verify its inputs exist. A step's outputs become the required
   inputs for downstream steps — do not skip producing them.
6. Follow enforcement levels: complete `required` steps, use judgment on `recommended`,
   skip `optional` unless specifically helpful.
7. Prefer the listed tools and agents unless there is a documented reason to deviate.

The Flowz skill lets you build a WORKFLOW.md conversationally inside Claude Code — no visual editor needed.

# Install into your project
npx flowz-skill

# This adds:
# .agents/skills/flowz/
#   SKILL.md      skill definition
#   README.md     usage guide
#   examples/     sample workflow files

# Invoke in a Claude Code session:
/flowz

The skill guides you through defining your workflows, steps, agents, and tools via a structured conversation, then writes the resulting WORKFLOW.md (and workflows/ files) directly to your project.

The skill is part of the Flowz repository. See skill/README.md for source and contribution details.