pipeline

name	pipeline
description	YAML-based sequential workflow engine — define, list, run, resume, add, and delete pipelines from natural language or YAML files. Supports skill invocation, free-form prompts, conditional steps, foreach iteration, state tracking, and halt-and-resume error recovery.

Pipeline

A YAML-based sequential workflow engine for AI coding agents. Define multi-step pipelines as YAML files and execute them with automatic state tracking, error recovery, and natural language pipeline creation.

Installation

npx skills add baekenough/baekenough-skills --skill pipeline

Compatibility: Works with Claude Code, Cursor, Windsurf, and any AI coding agent that supports the skills.sh standard.

Commands

Command	Description
/pipeline	List all available pipelines in the workflows directory
/pipeline <name>	Run a pipeline by name
/pipeline resume	Resume a previously halted pipeline from its failure point
/pipeline add <natural language>	Generate a new pipeline from a natural language description
/pipeline delete <name>	Delete an existing pipeline file
/pipeline <name> --dir <path>	Run a pipeline from a custom directory (default: workflows/)

---

YAML Schema

Full Example

name: deploy
description: "Build, test, and deploy to staging"
error: halt-and-report
mode: confirm

steps:
  - name: lint
    skill: dev-review
    description: Run lint checks

  - name: test
    prompt: "Run the full test suite and report results"
    description: Execute all tests

  - name: build
    prompt: "Build the project for production"
    description: Production build
    condition: "tests passed"

  - name: deploy
    skill: vercel-deploy
    description: Deploy to staging
    input: build-output

  - name: notify
    prompt: "Summarize deployment results"
    foreach: deploy-results

Pipeline-Level Fields

Field	Required	Default	Description
name	Yes	—	Pipeline identifier (kebab-case)
description	Yes	—	One-line summary of what the pipeline does
error	No	halt-and-report	Error mode: halt-and-report or continue
mode	No	confirm	Execution mode: confirm (ask before each step) or auto (run all without asking)
steps	Yes	—	Ordered list of step definitions

Step-Level Fields

Field	Required	Description
name	Yes	Step identifier (unique within pipeline, kebab-case)
skill	One of skill or prompt	Invoke a named skill via the Skill tool
prompt	One of skill or prompt	Free-form text the agent interprets and executes directly
description	Yes	Human-readable summary of the step
condition	No	Natural language guard — agent evaluates from prior context
input	No	Reference a previous step's output by step name
foreach	No	Iterate over a collection from a previous step's output

Each step MUST have exactly one of skill: or prompt:. Having both or neither is a validation error.

---

List Mode (/pipeline)

When the user invokes /pipeline with no arguments:

1. Scan the pipeline directory for *.yaml and *.yml files
   • Default directory: workflows/ relative to project root
   • Override with --dir <path>
2. For each file found, extract name and description from YAML frontmatter
3. Display a table:

Available Pipelines (workflows/)

| Pipeline | Description | Steps |
|----------|-------------|-------|
| deploy   | Build, test, and deploy to staging | 5 |
| release  | Full release workflow with changelog | 8 |

4. If no pipeline files are found, display:

No pipelines found in workflows/. Create one with: /pipeline add <description>

---

Run Mode (/pipeline <name>)

When the user invokes /pipeline <name>:

Phase 1: Validate and Load

1. Locate <name>.yaml or <name>.yml in the pipeline directory
2. If not found, report error and suggest /pipeline to list available pipelines
3. Parse YAML and validate against schema:
   • All required fields present
   • Each step has exactly one of skill: or prompt:
   • Step names are unique
   • Referenced skill names are valid kebab-case identifiers
4. If validation fails, report all errors with line references

Phase 2: Announce

Display pipeline overview before execution:

[Pipeline] deploy — Build, test, and deploy to staging
├── Mode: confirm
├── Error: halt-and-report
└── Steps: 5

  1. lint — Run lint checks (skill: dev-review)
  2. test — Execute all tests (prompt)
  3. build — Production build (prompt, condition)
  4. deploy — Deploy to staging (skill: vercel-deploy, input)
  5. notify — Summarize deployment results (prompt, foreach)

Starting pipeline...

Phase 3: Execute Steps Sequentially

For each step in order:

1. Announce step: [Step 1/5] lint — Run lint checks
2. Check condition (if present): Evaluate the natural language condition against the current context. If the condition is NOT met, skip the step and report: [Skipped] lint — Condition not met: "tests passed"
3. Resolve input (if present): Retrieve the output from the referenced step name
4. Resolve foreach (if present): Identify the collection from the referenced step output and iterate
5. Confirm (if mode is confirm): Ask the user Proceed with step "lint"? [Yes/Skip/Abort]
   • Yes: Execute the step
   • Skip: Skip this step, continue to next
   • Abort: Halt the entire pipeline
6. Execute: See Step Execution Protocol below
7. Record state: Write step result to state file
8. Report: [Done] lint — Completed successfully or [Failed] lint — {error}

Phase 4: Report

After all steps complete (or pipeline halts):

[Pipeline Complete] deploy
├── ✓ lint — Completed
├── ✓ test — Completed
├── ✓ build — Completed
├── ✓ deploy — Completed
└── ✓ notify — Completed

Duration: ~3m 24s
Result: All 5 steps completed successfully

Or on failure:

[Pipeline Halted] deploy
├── ✓ lint — Completed
├── ✓ test — Completed
├── ✗ build — Failed: build script returned non-zero exit
├── ○ deploy — Not reached
└── ○ notify — Not reached

Result: 2/5 completed, 1 failed, 2 not reached
Resume with: /pipeline resume

---

Step Execution Protocol

skill: Steps

Invoke the named skill using the Skill tool:

Skill(skill: "<skill-name>")

• Pass the step description as context for the skill
• If input: is specified, include the referenced step output as additional context
• If foreach: is specified, invoke the skill once per item in the collection
• Capture the skill's output as the step result

prompt: Steps

The agent interprets the prompt text and executes it directly using available tools (Bash, Read, Write, Edit, Grep, Glob, etc.):

• The prompt is a natural language instruction — the agent decides HOW to execute it
• If input: is specified, the referenced step output is provided as context
• If foreach: is specified, the agent processes each item in the collection
• The agent's actions and their results become the step output

condition: Evaluation

The condition is a natural language statement. The agent evaluates it based on the current execution context:

• Review outputs of all previously completed steps
• Determine if the condition is satisfied (true) or not (false)
• Example: condition: "tests passed" — the agent checks if the test step completed without failures
• Example: condition: "no lint errors found" — the agent checks the lint step output for errors

If the condition evaluates to false, the step is SKIPPED (not failed).

input: Resolution

The input: field references a previous step by name:

• Locate the step with the matching name in the completed steps
• Retrieve its output (the result stored during execution)
• Provide this output as context to the current step
• If the referenced step was skipped or failed, report a warning and proceed without input

foreach: Iteration

The foreach: field references a previous step whose output is a collection:

• Locate the referenced step's output
• The agent identifies the iterable collection within the output (list of files, test results, deployment targets, etc.)
• Execute the current step once per item in the collection
• Aggregate all iteration results as the step output

---

State Tracking

State File

Location: /tmp/.claude-pipeline-{name}-{PPID}.json

• {name}: Pipeline name from YAML
• {PPID}: Parent process ID (ensures session isolation)

State File Format

{
  "pipeline": "deploy",
  "file": "workflows/deploy.yaml",
  "started_at": "2026-04-02T10:30:00Z",
  "updated_at": "2026-04-02T10:33:24Z",
  "status": "halted",
  "current_step": 2,
  "steps": [
    {
      "name": "lint",
      "status": "completed",
      "output_summary": "No lint errors found"
    },
    {
      "name": "test",
      "status": "completed",
      "output_summary": "42 tests passed, 0 failed"
    },
    {
      "name": "build",
      "status": "failed",
      "error": "build script returned non-zero exit"
    },
    {
      "name": "deploy",
      "status": "pending"
    },
    {
      "name": "notify",
      "status": "pending"
    }
  ]
}

State Management Rules

• Create state file when pipeline execution begins
• Update after each step completes, fails, or is skipped
• Delete state file when pipeline completes successfully
• Preserve state file when pipeline halts on error (enables resume)
• Use Read tool to load state, Write tool to save state
• State file is JSON — write it via the Write tool, read via Read tool

---

Error Handling

halt-and-report Mode (Default)

When a step fails:

1. Record the failure in the state file
2. Mark remaining steps as pending
3. Display the halted pipeline report
4. Inform the user: Resume with: /pipeline resume
5. Stop execution immediately

continue Mode

When a step fails:

1. Record the failure in the state file
2. Log the error: [Failed] build — {error}. Continuing...
3. Proceed to the next step
4. At the end, report all failures in the summary

---

Resume Mode (/pipeline resume)

When the user invokes /pipeline resume:

1. Scan /tmp/ for state files matching .claude-pipeline-*-{PPID}.json
2. If no state files found: No halted pipelines found.
3. If one state file found: display resume info and proceed
4. If multiple found: list them and ask user to choose

Resume Display

[Pipeline Resume] deploy
├── File: workflows/deploy.yaml
├── Halted at: Step 3/5 (build)
├── Error: build script returned non-zero exit
├── Completed: lint ✓, test ✓
└── Remaining: build, deploy, notify

Options:
  [Retry] Re-execute the failed step (build)
  [Skip]  Skip the failed step, continue from deploy
  [Abort] Cancel the pipeline and clean up state

Resume Behavior

• Retry: Re-execute the failed step from scratch. If it succeeds, continue with remaining steps.
• Skip: Mark the failed step as skipped, continue with the next step.
• Abort: Delete the state file and report cancellation.

After resuming, execution follows the same Phase 3 and Phase 4 flow as a normal run, starting from the failed/next step.

---

Add Mode (/pipeline add <natural language>)

When the user invokes /pipeline add <description>:

Phase 1: Parse Intent

The agent interprets the natural language description to understand:

• What the pipeline should accomplish
• What steps are needed
• Which steps should use skills vs. free-form prompts
• What conditions or dependencies exist between steps

Phase 2: Generate YAML

Generate a valid pipeline YAML file based on the parsed intent:

1. Choose an appropriate name (kebab-case, derived from description)
2. Write a concise description
3. Set sensible defaults for error and mode
4. Generate steps with appropriate skill: or prompt: assignments
5. Add condition:, input:, and foreach: where the intent implies them

Phase 3: Preview

Display the generated YAML to the user:

[Pipeline Add] Generated pipeline from: "<user description>"

--- Preview ---
name: deploy-and-notify
description: "Build the project, deploy to staging, and notify the team"
error: halt-and-report
mode: confirm

steps:
  - name: build
    prompt: "Build the project for production"
    description: Production build

  - name: deploy
    skill: vercel-deploy
    description: Deploy to staging
    input: build

  - name: notify
    prompt: "Send a summary of the deployment to the team channel"
    description: Notify team of deployment
--- End Preview ---

Save to workflows/deploy-and-notify.yaml? [Yes/Edit/Cancel]

Phase 4: Confirm and Save

• Yes: Write the YAML file to the pipeline directory
• Edit: Ask the user what to change, regenerate, and preview again
• Cancel: Discard the generated pipeline

---

Delete Mode (/pipeline delete <name>)

When the user invokes /pipeline delete <name>:

1. Locate <name>.yaml or <name>.yml in the pipeline directory
2. If not found: Pipeline "<name>" not found. Use /pipeline to list available pipelines.
3. Display confirmation:

[Pipeline Delete] deploy
├── File: workflows/deploy.yaml
├── Description: Build, test, and deploy to staging
└── Steps: 5

Delete this pipeline? [Yes/Cancel]

4. Yes: Delete the file using Bash rm command. Also clean up any matching state files in /tmp/.
5. Cancel: Abort deletion.

---

Output Format

Status Messages During Execution

[Pipeline] {name} — {description}
[Step N/M] {step-name} — {description}
[Done] {step-name} — {result summary}
[Failed] {step-name} — {error}
[Skipped] {step-name} — {reason}
[Pipeline Complete] {name} — {summary}
[Pipeline Halted] {name} — {summary}

Confirm Prompts

In confirm mode, before each step:

[Step 2/5] test — Execute all tests
Proceed? [Yes/Skip/Abort]

---

Validation Rules

Before executing a pipeline, validate:

1. Required pipeline fields: name, description, steps must be present
2. Steps non-empty: At least one step must be defined
3. Step type: Each step must have exactly one of skill: or prompt: (not both, not neither)
4. Step names unique: No duplicate step names within a pipeline
5. Step names valid: Step names must be kebab-case (lowercase alphanumeric and hyphens)
6. Skill name format: skill: values must be valid kebab-case identifiers
7. Error mode valid: error: must be halt-and-report or continue (if specified)
8. Execution mode valid: mode: must be confirm or auto (if specified)
9. Input references valid: input: values must reference step names defined earlier in the pipeline
10. Foreach references valid: foreach: values must reference step names defined earlier in the pipeline

Report all validation errors at once (do not stop at the first error).