The Full Pipeline

telesis run is the complete orchestration command. It takes a work item and drives it through the entire lifecycle — planning, execution, validation, committing, pushing, PR creation, and issue closure — with human gates where they matter.

Basic Usage

1

telesis run <work-item-id>

This starts the pipeline. Telesis will:

1. Create a plan from the work item
2. Show you the plan and ask for approval (interactive prompt)
3. Execute tasks sequentially with validation
4. Stage all changes and create a single commit
5. Push the branch to the remote
6. Create a PR (if configured)
7. Close the source GitHub issue (if configured)

Pipeline Stages

The pipeline moves through a defined sequence of stages:

1

planning → awaiting_approval → executing → quality_check → committing → pushing → creating_pr → closing_issue → completed

Each stage transition emits a pipeline:stage_changed event through the daemon event backbone, so you can monitor progress in real time with telesis daemon tui.

Planning

Telesis calls the planner agent to decompose the work item into a task graph. This is identical to telesis plan create — the plan includes tasks with dependencies, acceptance criteria, and a topological ordering.

Approval Gate

By default, Telesis shows you the generated plan and waits for confirmation before executing. This is the most important human gate in the pipeline — it’s your chance to review what the agent is about to do.

Skip the approval prompt:

1

telesis run <id> --auto-approve

Or configure it globally:

1
2

pipeline:
  autoApprove: true

Execution

Tasks are dispatched sequentially, respecting dependencies. After each task, the validation agent checks the output against acceptance criteria. Failed validations trigger retries (up to the configured limit). Exhausted retries escalate the task.

Skip validation:

1

telesis run <id> --no-validate

Review Gate (Optional)

If pipeline.reviewBeforePush is enabled in your config, Telesis runs a code review after execution and before committing. If findings exceed the configured severity threshold, the pipeline pauses.

1
2
3

pipeline:
  reviewBeforePush: true
  reviewBlockThreshold: high   # Block on high or critical findings

Skip review for a single run:

1

telesis run <id> --no-review

Quality Gates (Optional)

If pipeline.qualityGates is configured, Telesis runs automated checks after execution and before committing. Each gate is a named slot with a configurable shell command:

1
2
3
4
5
6
7

pipeline:
  qualityGates:
    format: "pnpm run format"
    lint: "pnpm run lint"
    test: "pnpm test"
    build: "pnpm run build"
    drift: true                  # Runs telesis drift (boolean, not a command)

Gates run in order: format, lint, test, build, drift. If any gate fails, the pipeline stops. Set a gate to null to skip it.

Skip all quality gates for a single run:

1

telesis run <id> --no-quality-check

Commit Squashing

During execution, agents may create multiple intermediate commits. The pipeline squashes all agent commits into a single pipeline commit, keeping the git history clean. The final commit contains all changes from the plan as one atomic unit.

Commit

All changes from the plan are committed together — one commit per plan. The commit message is generated from the plan and work item, including task summaries and the work item ID for traceability.

LLM-Generated Commit Messages

When git.llmCommitMessages is enabled, the commit message is generated by an LLM from the diff and plan context rather than assembled from templates. This produces more natural, descriptive messages.

1
2

git:
  llmCommitMessages: true

Push

The branch is pushed to the remote. You can skip this:

1

telesis run <id> --no-push

PR Creation

If git.createPR is enabled, Telesis creates a GitHub pull request. This requires GITHUB_TOKEN to be set.

When git.llmPRBody is enabled, the PR description is generated by an LLM from the plan and diff context, producing a structured summary with sections and test plans.

1
2

git:
  llmPRBody: true

Issue Closure

If pipeline.closeIssue is enabled and the work item originated from a GitHub issue, Telesis closes the source issue with a comment linking to the PR.

Options

Branching Behavior

By default, Telesis creates a new branch for each pipeline run, prefixed with the configured branch prefix:

1

telesis/work-item-slug

Override the branch name:

1

telesis run <id> --branch feature/custom-name

Or commit directly to the current branch (useful for small fixes):

1
2

git:
  commitToMain: true

Resumability

The pipeline persists its state to .telesis/pipeline-state/ after each stage transition. If the pipeline is interrupted — by a crash, a Ctrl-C, or a failed quality gate — you can pick up where you left off:

1

telesis run <work-item-id> --resume

This skips already-completed stages and resumes from the last successful checkpoint. Without --resume, Telesis detects the partial state and prompts you to choose: resume or restart.

To discard partial state and start the pipeline from scratch:

1

telesis run <work-item-id> --restart

Configuration

The full set of pipeline-relevant configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

git:
  branchPrefix: "telesis/"       # Branch name prefix
  commitToMain: false            # Skip branching, commit to current
  pushAfterCommit: true          # Auto-push after commit
  createPR: false                # Create PR after push
  llmCommitMessages: false       # LLM-generated commit messages
  llmPRBody: false               # LLM-generated PR descriptions

pipeline:
  autoApprove: false             # Skip plan confirmation
  closeIssue: false              # Close source GitHub issue
  reviewBeforePush: false        # Run review before push
  reviewBlockThreshold: high     # Severity to block push
  qualityGates:                  # Automated checks before commit
    format: "pnpm run format"
    lint: "pnpm run lint"
    test: "pnpm test"
    build: "pnpm run build"
    drift: true

validation:
  maxRetries: 3                  # Retry attempts before escalation
  enableGates: false             # Require human approval after plan completion

Failure Handling

If any stage fails, the pipeline stops and reports the failure. Pipeline state is persisted, so you can resume after fixing the issue:

1

telesis run <work-item-id> --resume

To investigate what went wrong, check the dispatch session logs:

1
2

telesis dispatch list
telesis dispatch show <session-id>

Or start fresh:

1

telesis run <work-item-id> --restart

Example Workflow

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# Import issues from GitHub
telesis intake github

# See what's available
telesis intake list

# Run the full pipeline on an issue
telesis run github-42

# Pipeline prompts for plan approval...
# Tasks execute with validation...
# Changes committed, pushed, PR created.