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.
license: MIT
---

# 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

```bash
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

```yaml
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

```json
{
  "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).