Workflows

Workflows automate multi-step Spec-Driven Development processes — chaining commands, prompts, shell steps, and human checkpoints into repeatable sequences. They support conditional logic, loops, fan-out/fan-in, and can be paused and resumed from the exact point of interruption.

Run a Workflow

kiss workflow run <source>
Option Description
-i / --input Pass input values as key=value (repeatable)

Runs a workflow from a catalog ID, URL, or local file path. Inputs declared by the workflow can be provided via --input or will be prompted interactively.

Example:

kiss workflow run kiss -i spec="Build Bookshelf, a single-user reading tracker with categories and reviews" -i scope=full

Note: All workflow commands require a project already initialized with kiss init.

Resume a Workflow

kiss workflow resume <run_id>

Resumes a paused or failed workflow run from the exact step where it stopped. Useful after responding to a gate step or fixing an issue that caused a failure.

Workflow Status

kiss workflow status [<run_id>]

Shows the status of a specific run, or lists all runs if no ID is given. Run states: created, running, completed, paused, failed, aborted.

List Installed Workflows

kiss workflow list

Lists workflows installed in the current project.

Install a Workflow

kiss workflow add <source>

Installs a workflow from the catalog, a URL (HTTPS required), or a local file path.

Remove a Workflow

kiss workflow remove <workflow_id>

Removes an installed workflow from the project.

Search Available Workflows

kiss workflow search [query]
Option Description
--tag Filter by tag

Searches all active catalogs for workflows matching the query.

Workflow Info

kiss workflow info <workflow_id>

Shows detailed information about a workflow, including its steps, inputs, and requirements.

Catalog Management

Workflow catalogs control where search and add look for workflows. Catalogs are checked in priority order.

List Catalogs

kiss workflow catalog list

Shows all active catalog sources.

Add a Catalog

kiss workflow catalog add <url>
Option Description
--name <name> Optional name for the catalog

Adds a custom catalog URL to the project's .kiss/workflow-catalogs.yml.

Remove a Catalog

kiss workflow catalog remove <index>

Removes a catalog by its index in the catalog list.

Catalog Resolution Order

Catalogs are resolved in this order (first match wins):

  1. Environment variable — KISS_WORKFLOW_CATALOG_URL overrides all catalogs
  2. Project config — .kiss/workflow-catalogs.yml
  3. User config — ~/.kiss/workflow-catalogs.yml
  4. Built-in defaults — official catalog + community catalog

Workflow Definition

Workflows are defined in YAML files. Here is the built-in Full SDD Cycle workflow that ships with kiss:

schema_version: "1.0"
workflow:
  id: "kiss"
  name: "Full SDD Cycle"
  version: "1.0.0"
  author: "GitHub"
  description: "Runs specify → plan → tasks → implement with review gates"

requires:
  kiss_version: ">=0.3.0"
  integrations:
    any: ["copilot", "claude", "gemini"]

inputs:
  spec:
    type: string
    required: true
    prompt: "Describe what you want to build"
  integration:
    type: string
    default: "copilot"
    prompt: "Integration to use (e.g. claude, copilot, gemini)"
  scope:
    type: string
    default: "full"
    enum: ["full", "backend-only", "frontend-only"]

steps:
  - id: specify
    command: kiss.specify
    integration: "{{ inputs.integration }}"
    input:
      args: "{{ inputs.spec }}"

  - id: review-spec
    type: gate
    message: "Review the generated spec before planning."
    options: [approve, reject]
    on_reject: abort

  - id: plan
    command: kiss.plan
    integration: "{{ inputs.integration }}"
    input:
      args: "{{ inputs.spec }}"

  - id: review-plan
    type: gate
    message: "Review the plan before generating tasks."
    options: [approve, reject]
    on_reject: abort

  - id: tasks
    command: kiss.taskify
    integration: "{{ inputs.integration }}"
    input:
      args: "{{ inputs.spec }}"

  - id: implement
    command: kiss.implement
    integration: "{{ inputs.integration }}"
    input:
      args: "{{ inputs.spec }}"

This produces the following execution flow:

flowchart TB
    A["specify<br/>(command)"] --> B{"review-spec<br/>(gate)"}
    B -- approve --> C["plan<br/>(command)"]
    B -- reject --> X1["⏹ Abort"]
    C --> D{"review-plan<br/>(gate)"}
    D -- approve --> E["tasks<br/>(command)"]
    D -- reject --> X2["⏹ Abort"]
    E --> F["implement<br/>(command)"]

    style A fill:#49a,color:#fff
    style B fill:#a94,color:#fff
    style C fill:#49a,color:#fff
    style D fill:#a94,color:#fff
    style E fill:#49a,color:#fff
    style F fill:#49a,color:#fff
    style X1 fill:#999,color:#fff
    style X2 fill:#999,color:#fff

Run it with:

kiss workflow run kiss -i spec="Build a kanban board with drag-and-drop task management"

Step Types

Type Purpose
command Invoke a kiss command (e.g., kiss.plan)
prompt Send an arbitrary prompt to the AI coding agent
shell Execute a shell command and capture output
gate Pause for human approval before continuing
if Conditional branching (then/else)
switch Multi-branch dispatch on an expression
while Loop while a condition is true
do-while Execute at least once, then loop on condition
fan-out Dispatch a step for each item in a list
fan-in Aggregate results from a fan-out step

Expressions

Steps can reference inputs and previous step outputs using {{ expression }} syntax:

Namespace Description
inputs.spec Workflow input values
steps.kiss.output.file Output from a previous step
item Current item in a fan-out iteration

Available filters: default, join, contains, map.

Example:

condition: "{{ steps.test.output.exit_code == 0 }}"
args: "{{ inputs.spec }}"
message: "{{ status | default('pending') }}"

Input Types

Type Coercion
string Pass-through
number "42" → 42, "3.14" → 3.14
boolean "true" / "1" / "yes" → True

State and Resume

Each workflow run persists its state at .kiss/workflows/runs/<run_id>/:

  • state.json — current run state and step progress
  • inputs.json — resolved input values
  • log.jsonl — step-by-step execution log

This enables kiss workflow resume to continue from the exact step where a run was paused (e.g., at a gate) or failed.

FAQ

What happens when a workflow hits a gate step?

The workflow pauses and waits for human input. Run kiss workflow resume <run_id> after reviewing to continue.

Can I run the same workflow multiple times?

Yes. Each run gets a unique ID and its own state directory. Use kiss workflow status to see all runs.

Who maintains workflows?

Most workflows are independently created and maintained by their respective authors. The kiss maintainers do not review, audit, endorse, or support workflow code. Review a workflow's source before installing and use at your own discretion.

Edit this page