Saltar a contenido

Pipeline Quickstart

This guide walks you through running a story pipeline end-to-end. By the end, you'll understand how pipelines sequence skills, pause at HITL gates for your approval, and recover across sessions.

Prerequisites

  • RaiSE initialized (rai init)
  • A Jira issue to work on (e.g., RAISE-1234)
  • Claude Code with the rai-workspace MCP server connected

Run a Story Pipeline

Inside Claude Code, ask Rai to start the pipeline:

Start the story pipeline for RAISE-1234

Rai calls the pipeline_start MCP tool, which loads the story.yaml pipeline definition, resolves your delegation level, and begins executing phases:

Pipeline: story (8 phases)
Issue:    RAISE-1234
Delegation: review

  [1/8] start.......................... PASSED  (12.3s)
  [2/8] design......................... PASSED  (45.1s)
        gate: PAUSED — awaiting review

At each phase, Rai reads the corresponding SKILL.md and follows its steps automatically. You stay in Claude Code the entire time — there is nothing to run in a terminal.

Reviewing at HITL Gates

When the pipeline reaches a gate, it pauses and presents the phase output for your review. You respond directly in the conversation:

  • Approve — the skill calls pipeline_advance to move to the next phase
  • Revise — the skill re-executes the phase with your feedback
  • Reject — the skill calls pipeline_cancel to stop the pipeline

Gates are the key control point. Start with review delegation level so you see every gate until you trust the process.

What Happens at Each Phase

Phase Skill What it does Gate
start /rai-story-start Creates branch, scope commit —
design /rai-story-design Gemba walk, lean spec, examples HITL
plan /rai-story-plan Decomposes into atomic tasks —
implement /rai-story-implement TDD execution of tasks HITL
architecture-review /rai-architecture-review Proportionality + lean audit HITL
quality-review /rai-quality-review Semantic bugs + pattern check HITL
review /rai-story-review Retrospective + pattern extraction —
close /rai-story-close Merge, cleanup, tracking —

Phases with when conditions (like architecture-review: story_type == 'code') are automatically skipped when the condition is false.

MCP Tools Under the Hood

The slash command orchestrates these MCP tools on your behalf:

Tool Purpose
pipeline_start Start a pipeline run for a given issue
pipeline_advance Move to the next phase after a gate approval
pipeline_status Check the current state of a pipeline run
pipeline_pause Pause a running pipeline manually
pipeline_restore Restore a pipeline after session restart or context compaction
pipeline_cancel Stop a pipeline run
pipeline_list List available pipeline definitions
pipeline_runs List active and recent pipeline runs

You do not need to call these tools directly — the skill handles it. But they are available if you want finer-grained control during a session.

Session Recovery

Pipelines survive context compaction and session restarts. State is persisted in .rai-state/.

If you start a new Claude Code session and need to resume:

Resume my pipeline for RAISE-1234

Rai calls pipeline_restore to find the existing run and picks up where it left off. You can also check state explicitly:

What's the status of my pipeline for RAISE-1234?

Available Pipelines

The framework ships with several built-in pipelines:

  • story — full story lifecycle (8 phases)
  • epic — epic lifecycle with milestone tracking
  • bugfix — 7-phase bug fix with 3 HITL gates
  • hotfix — expedited fix for production issues

Pipelines are loaded from a 3-tier hierarchy:

  1. Built-in — shipped with rai-agent
  2. Project — defined in your project's .raise/pipelines/
  3. User — defined in ~/.rai/pipelines/

Project and user pipelines override built-in ones with the same name.

Tips

  • Start with REVIEW delegation — see every gate until you trust the process
  • Use story_type: docs — skips architecture and quality review phases (they only run for code)
  • Pipelines don't replace skills — you can always invoke /rai-story-design directly if you prefer manual control
  • Artifacts are traced — every phase validates its output exists before the gate runs

Advanced: Direct MCP Access

The MCP tools listed above are available for direct use when you need finer-grained control. Ask Rai to call them explicitly, or invoke them from any MCP-capable client.

Note: There is no rai pipeline CLI command in 3.0. Pipeline orchestration runs exclusively through the MCP server (rai-workspace). See rai pipeline CLI reference for planned CLI support.

Next Steps