Skip to content

Customizing Pipelines

RaiSE pipelines are data, not code. When you start a pipeline, the AI loads a YAML pipeline definition and orchestrates each phase using skills and MCP tools. You customize pipelines by editing those YAML files — no programming required.

How Pipelines Run

You never run pipelines directly. Instead, ask Rai inside Claude Code:

What you say Pipeline Definition What It Does
"Start the story pipeline for RAISE-123" story.yaml Full story lifecycle: start, design, plan, implement, review, close
"Start the bugfix pipeline for RAISE-456" bugfix.yaml 10-phase bugfix pipeline with review gates
"Start the epic pipeline for RAISE-789" epic.yaml Epic lifecycle with delegation gates

Behind the scenes, Rai uses MCP tools (pipeline_start, pipeline_advance, pipeline_status) to load the YAML definition, execute each phase, and enforce gates. The AI manages the orchestration — you review and approve at gate checkpoints.

Note: The legacy slash commands /rai-story-run, /rai-bugfix-run, and /rai-epic-run were removed in 3.0. See Migrating from 2.x.

Loading Hierarchy

The pipeline loader checks three locations in order:

Priority Location Use case
1 (highest) ~/.rai/pipelines/ Personal overrides
2 .raise/pipelines/ Project-specific pipelines
3 (lowest) Built-in (pipelines_base/) Shipped defaults

A pipeline at a higher priority replaces one with the same name at a lower priority. This means you can override story.yaml for your project without modifying the built-in.

Customization Points

Editing Pipeline Definitions

To customize the story pipeline for your project, create your own override:

mkdir -p .raise/pipelines

Then create .raise/pipelines/story.yaml. Your version takes precedence over the built-in. The next time you start the story pipeline, the AI loads your custom definition instead.

Adding or Removing Phases

Each pipeline is a sequence of phases. Add, remove, or reorder them:

name: story
description: "Minimal 4-phase story pipeline"
issue_types:
  - story

phases:
  - id: start
    type: llm
    skill: rai-story-start

  - id: design
    type: llm
    skill: rai-story-design
    gate:
      type: hitl
      level: REVIEW

  - id: implement
    type: llm
    skill: rai-story-implement
    gate:
      type: hitl
      level: REVIEW

  - id: close
    type: llm
    skill: rai-story-close

This stripped-down pipeline skips the plan and review phases — useful for small projects where the overhead is not justified.

Customizing Which Skills Run

Each llm phase references a skill by name. Swap in your own skill to change what the AI does at that phase:

- id: design
  type: llm
  skill: my-custom-design    # Your skill in .claude/skills/
  context:
    graph:
      - types: [pattern]
        limit: 5

Adding and Removing Gates

Gates control when the pipeline pauses for review or runs automated checks.

HITL gates pause for human review:

gate:
  type: hitl
  level: REVIEW        # REVIEW, NOTIFY, or AUTO
  mandatory: true      # Cannot be overridden by delegation level

Deterministic gates run automated checks — pass/fail based on exit code:

gate:
  type: deterministic
  command: "uv run pytest --tb=no -q"

Remove a gate to let the AI proceed without stopping. Add gates to phases where you want a checkpoint.

Conditional Phases with when

Skip phases based on metadata:

- id: architecture-review
  type: llm
  skill: rai-architecture-review
  when: "story_type == 'code'"    # Skipped for docs/analysis stories

Variables available in when expressions come from defaults and the story type metadata.

Phase Types

llm --- AI-Driven Phases

Loads a skill and delegates to Claude:

- id: design
  type: llm
  skill: rai-story-design
  context:
    graph:
      - types: [pattern]
        limit: 5

deterministic --- Shell Command Phases

Runs commands sequentially. Fails on first non-zero exit:

- id: lint
  type: deterministic
  commands:
    - "uv run ruff check src/"
    - "uv run pyright src/"

Artifact Validation

Require specific files to exist after a phase completes:

validates:
  - pattern: "**/*-design.md"
    description: "Story design document"
  - pattern: "**/*-plan.md"
    description: "Story plan document"

The engine blocks progression if any required artifact is missing.

Context Injection

Inject knowledge graph context into LLM phases:

context:
  graph:
    - types: [pattern]
      limit: 5
    - types: [module, decision]
      limit: 3

Available types: pattern, module, decision, principle, guardrail, epic, story.

Review Modes

For review phases, enable adversarial review templates:

- id: quality-review
  type: llm
  skill: rai-quality-review
  review_mode: adversarial
  review_template: adversarial-qr

Creating a New Pipeline

Create .raise/pipelines/deploy.yaml for a custom pipeline:

name: deploy
description: "3-phase deployment pipeline"
issue_types:
  - task

phases:
  - id: validate
    type: deterministic
    commands:
      - "rai release check"
      - "rai gate check --all"

  - id: build
    type: deterministic
    commands:
      - "uv build --out-dir dist"
      - "twine check dist/*"
    gate:
      type: hitl
      level: REVIEW

  - id: publish
    type: deterministic
    commands:
      - "twine upload dist/*"

Once defined, a corresponding slash command or MCP tool call can reference it by name.

Advanced: Direct MCP Access

For debugging or scripting, pipeline MCP tools can be called directly via the rai-workspace server:

Tool Description
pipeline_list List available pipelines and their phases
pipeline_start Start a pipeline run
pipeline_status Check status of a running pipeline

Most developers will not need to call MCP tools directly — the AI handles orchestration automatically.

Next Steps