Create Workflow

Create Workflow

Formalize repeatable patterns into trackable kspec workflows. A meta-workflow for building new workflows with consistent structure.

When to Use

• Formalizing a repeated process into a trackable workflow
• Converting step-by-step documentation into executable steps
• Adding quality gates that are easy to skip without structure

Not for: Running existing workflows (use kspec workflow start @id), one-off processes, or tasks that don't repeat.

Identifying Good Candidates

Look for processes that are:

Good sources: project-local agent guidance, existing skills, task notes, session reflections.

Workflow Structure

Every workflow has:

id: kebab-case-name
description: What this workflow does
trigger: when-it-starts
mode: interactive # or loop
steps:
  - id: step-1
    type: action # action, check, or decision
    content: What to do in this step

Triggers

Step Types

Modes

• interactive — Pauses for user input at each step
• loop — Auto-resolves decisions, no user prompts (for automated agents)

Loop mode workflows typically have a based_on field referencing the interactive version.

Creating a Workflow

Step 1: Design the Steps

Before creating, outline your steps on paper:

1. What's the trigger?
2. What steps are needed?
3. Which are actions vs checks vs decisions?
4. What inputs does each step need?
5. What's the exit criteria?

Step 2: Create the Workflow

kspec meta add workflow \
  --id my-workflow \
  --trigger manual \
  --description "Description of what this workflow does" \
  --tag category \
  --steps '[
    {"id":"step-1","type":"action","content":"First action to take"},
    {"id":"step-2","type":"check","content":"Verify the condition"},
    {"id":"step-3","type":"decision","content":"Choose path A or B"}
  ]'

Step 3: Test the Workflow

Run through it end-to-end:

kspec workflow start @my-workflow
kspec workflow next --notes "Testing step 1"
kspec workflow next --input decision="path-a" --notes "Chose A because..."
# Continue through all steps
kspec workflow show  # Verify inputs and notes captured

Step 4: Consider a Matching Skill

A workflow may benefit from a matching skill when:

If creating a skill, add it as a project-local skill so the workflow's matching guidance lives in the project's shadow state. Project-local skill sources live under .kspec/skills/; register them with kspec meta commands and render them via kspec skill render so agents pick up the change.

Project-local skill authoring follows the same source/render rules as other shadow state: edit the project-local source, then render. The project's own maintenance context (for example, package-skill authoring, manifest edits, or commits to a specific branch) belongs in that project's local guidance, not in this shared workflow skill.

Step 5: Commit

Workflow definitions are auto-committed to the shadow branch by kspec when you run kspec meta add workflow or kspec meta set. If you created or edited project-local skill sources alongside the workflow, follow your project's commit guidance for those files. For projects that maintain package-shipped skill sources, follow the project-local maintenance instructions in that project's context.

Cross-Skill Consistency Check (When Updating Existing Skills)

If your workflow or wording change is cross-cutting, run this quick consistency pass before committing:

1. List related skills, templates, or project-local docs that describe the same concept.
2. Verify each related file is either updated in the same change or explicitly noted as intentionally unchanged.
3. Note which related files were reviewed when you submit the change for review.

This prevents partial updates where one skill changes but sibling skills keep outdated guidance.

Step Design Guidelines

Action Steps

Clear, specific instructions:

- id: run-tests
  type: action
  content: |
    Run the full test suite. Fix any failures before proceeding.
    Verify both unit and integration tests pass.

Check Steps

Binary yes/no verification:

- id: ci-passing
  type: check
  content: |
    Verify all CI checks are passing on the current HEAD.
    If not, wait for CI or fix failures.

Decision Steps

Clear options with guidance:

- id: choose-path
  type: decision
  content: |
    Choose execution path:
    - Import: 3+ specs, structured document, batch creation
    - Manual: 1-2 specs, incremental, quick additions

Tips

• Keep steps atomic — one action per step
• Include the "why" when it's not obvious
• Decision steps should list all options
• Check steps should describe what to do on failure
• Use content for detailed multi-line instructions

Loop Mode Variants

For automated agents, create a loop variant:

kspec meta add workflow \
  --id my-workflow-loop \
  --trigger manual \
  --mode loop \
  --based-on @my-workflow \
  --description "Automated variant of my-workflow" \
  --steps '[...]'

Loop variants typically:

• Auto-resolve decisions (pick the most common path)
• Skip user confirmation steps
• Add higher confidence thresholds
• Include automated exit conditions

Workflow Lifecycle

# Create
kspec meta add workflow --id ... --steps '[...]'

# Run
kspec workflow start @id
kspec workflow next --notes "..."
kspec workflow next --input key=value

# Manage
kspec workflow show        # Check progress
kspec workflow pause       # Pause for later
kspec workflow resume      # Resume paused run

# Update (edit the meta YAML)
kspec meta set workflow @id --steps '[...]'

Regenerate Agent Instructions

After creating a workflow, regenerate agent instructions so the workflow appears in the available workflows list:

kspec agents generate

Integration

• {skill:reflect} — Session reflections surface patterns worth formalizing
• {skill:observe} — Friction observations may reveal missing workflows
• kspec agents generate — Regenerate after creating workflows