pipeline

pipeline

Self-contained TypeScript skill that advances a GitHub issue (or PR's linked issue) through a 10-stage label-driven state machine, ending at pipeline:ready-to-deploy. The pipeline does NOT auto-merge — the user owns the merge button.

State machine

backlog → ready → planning → implementing
              → review-1 → fix-1 → review-2 → fix-2
              → pre-merge → ready-to-deploy

Each item carries one pipeline:<stage> label and at most one blocked label. Stage transitions are driven by structured outcomes from the stage handlers in scripts/stages/. The skill owns the labels — it sets, removes, and transitions them as side-effects of running the underlying stage logic. There is no separate orchestrator process.

backlog is a triage marker (e.g. set by /sweep). /pipeline starts work at ready and only acts on items that already carry a pipeline:* label.

Modes

/pipeline N                              advance loop (default; up to 12 transitions)
/pipeline N --status                     read-only — print stage, blocker, PR, last review
/pipeline N --unblock "<answer>"         post answer + clear blocked label
/pipeline N --once                       advance one stage and stop
/pipeline N --dry-run                    log what would happen; no harness calls, no GitHub writes
/pipeline N --domain <d>                 override domain name in lock/log paths
/pipeline N --base <branch>              override base branch
/pipeline N --repo-path <path>           target a different repo working tree

The number is auto-detected as an issue or PR via the GitHub API. PRs are resolved to their linked closing issue (the pipeline is issue-centric). PRs without a Closes #N reference are refused with an explanation.

Setup (zero install after first run)

The skill is a Node 24+ TypeScript codebase under ${CLAUDE_PLUGIN_ROOT}/skills/pipeline/core/scripts/, run via native type-stripping (no build step). First-ever invocation runs npm install automatically.

Required:

• gh CLI authenticated against the target repo
• claude CLI on PATH (for the implementer/reviewer harness when configured to claude)
• codex CLI on PATH (for the harness when configured to codex)
• Node 24+
• The user's Claude Code subscription provides the LLM budget — this skill never reads ANTHROPIC_API_KEY

Per-repo config

A repo can opt-in to overrides by committing .github/pipeline.yml:

base_branch: main                # default 'main'
worktree_root: .worktrees        # relative to repo root
max_concurrent_worktrees: 5
auto_merge: false                # always false in v2; do not enable
auto_recovery_max_retries: 2
implementation_timeout: 1200     # seconds
review_timeout: 1200
fix_timeout: 1200
ci_timeout: 900
ci_poll_interval: 30
harnesses:
  implementer: claude            # legacy key accepted but ignored
  reviewer: codex                # legacy key accepted but ignored
models:
  planning: sonnet
  review: opus
  fix: sonnet
conventions_md_path: CLAUDE.md   # excerpt embedded in prompts
domain_name: lyric-utils
domain_description: a quantitative finance Python library

If absent, defaults from core/scripts/types.ts:DEFAULT_CONFIG apply. The Claude-side pipeline is harness-relative: Claude Code is always primary for planning, implementation, fixes, and docs update; Codex is always secondary for review/adversarial review. Legacy .github/pipeline.yml harnesses keys are accepted for compatibility but ignored so repo config cannot invert a Claude-invoked pipeline run.

Run flow

For every invocation:

1. Resolve target

1. The numeric arg is fed to gh api /repos/{repo}/issues/{N} to detect issue vs PR. PRs follow the closingIssuesReferences link.
2. Refuse PRs without a closing reference.

2. Pre-flight checks

• Kill switch at /tmp/pipeline-{domain}.disabled — if present, exit.
• Lock at /tmp/pipeline-{domain}.lock — PID-based, auto-recovers stale.
• Pipeline label gate — refuses items without any pipeline:* label with a message explaining how to opt in (pipeline:ready manually).

3. Advance loop

while iter < 12 and not at ready-to-deploy and not blocked:
  read current stage from labels
  dispatch to the stage handler (planning, review, fix, pre_merge, …)
  print one-line transition
  if --once: break

Each iteration may block for up to ~20 minutes (heavy stages run implementer/reviewer harnesses against the full repo). Worst-case full path is 9 transitions, ~2 hours.

4. Orchestration pattern (Claude-side, for default-mode advance)

A foreground bash invocation will be killed at the harness's 10-minute timeout — long before a planning stage finishes (~20 min cap each). For the default advance mode, Claude must orchestrate the run as follows:

a. Status pre-check (fast, synchronous)

node ${CLAUDE_PLUGIN_ROOT}/skills/pipeline/scripts/pipeline.mjs <N> --status

Confirms target exists, has a pipeline:* label, isn't already at a terminal/blocked state. If anything looks wrong, surface it and stop — do not start an advance.

b. Background the advance with logging

cd <repo_dir>
node ${CLAUDE_PLUGIN_ROOT}/skills/pipeline/scripts/pipeline.mjs <N> \
  > /tmp/pipeline-<domain>-<N>.log 2>&1

Run with run_in_background: true. The bash tool returns the task ID immediately; the pipeline runs detached.

c. Stream stage transitions via Monitor

Arm a persistent Monitor on the log file with this filter (matches the pipeline.ts transition lines + structured failure markers):

tail -f /tmp/pipeline-<domain>-<N>.log | grep -E --line-buffered \
  "^\[pipeline\]|^\[exit code|FAILED|timed out|blocked label|approved|needs-attention|→ "

Set persistent: true, timeout_ms: 3600000 (1 hour — re-arm if needed). Each emitted line lands in Claude's notification stream.

Known false-positives to ignore:

• Traceback: and verdict and other prompt content echoed verbatim through the harness's stdout. These are NOT real stage events — they're the prompt being read back by claude/codex during streaming. The grep matches them anyway because we deliberately broaden the filter to catch real failures (FAILED, timed out, etc.). The real stage signal is always a line starting with [pipeline].

d. Push notification on every [pipeline] event

For every Monitor event that is a real [pipeline] line (i.e., not the known prompt-echo false-positives), call PushNotification with a short one-line message. The state machine has only 9 transitions max and each emits ≤2 visible [pipeline] lines, so this caps at ~12–18 pushes per full run — coarse enough to not be spammy, fine enough that the user never wonders "is anything happening?" between major arrows.

Examples that DO push:

• [pipeline] #N: starting at stage=<x>
• [pipeline] #N: planning (impl=claude)
• [pipeline] #N: worktree at <path>
• [pipeline] #N: implementation done (Xs, harness=Y)
• [pipeline] #N: PR #M created
• [pipeline] #N: ready → review-1: PR #M opened
• [pipeline] #N: review-1 by codex
• [pipeline] #N: verdict=approve findings=0
• [pipeline] #N: review-1 → review-2: standard review approved
• … and so on, all the way through → ready-to-deploy

Examples that do NOT push (false-positives the grep filter still catches):

• Traceback: and verdict and other prompt content echoed verbatim through the harness's stdout. Real stage signals always start with [pipeline]. If a Monitor event line doesn't start with [pipeline], surface in chat for context but skip the push.
• Repeated polling-loop sub-events — pre_merge.advancePolling re-enters the gate check every ci_poll_interval seconds (default 30s) and emits [pipeline] #N: pre-merge gate each time. Push the FIRST occurrence per stage entry; suppress subsequent identical lines in the same polling burst. The next material event is the eventual → ready-to-deploy or → blocked transition — don't bury it under 30 spam pushes.

The "err toward not sending" guidance in the PushNotification docs is about ambient noise — but /pipeline N is a foreground operation the user explicitly invoked, not background ambient state. They asked for this push stream; deliver it.

e. Stop the Monitor when the background bash completes

The harness fires a separate task-notification for the background bash with <status>completed</status> when pipeline.ts exits. On that event, call TaskStop with the Monitor's task_id and surface the final summary inline by reading the tail of the log.

f. Final summary

Read the last 30 lines of /tmp/pipeline-<domain>-<N>.log and surface inline: starting stage → ending stage, transitions made, wall-clock elapsed, PR URL if one was opened. Also send one final PushNotification with the terminal state.

5. Modes that DON'T need this orchestration

• --status — read-only, completes in seconds
• --unblock "<answer>" — one comment + label clear, completes in seconds
• --dry-run — logs what would happen, no harness calls

Run those synchronously, no Monitor, no background, no Push.

--once still needs the orchestration because a single heavy stage (planning especially) can hit its 20-min timeout. Use the same background + Monitor + Push pattern as default mode; just expect at most one transition before the run exits.

6. Optional HTML report artifact

For multi-stage runs, blocked runs with substantial context, or any run whose final state is easier to understand visually, generate a self-contained HTML report in artifacts/reports/pipeline-<N>.html inside the target repo/worktree. Keep the chat summary short and include the artifact path.

The report should include:

• stage timeline
• issue/PR links
• branch and worktree path
• changed files
• review findings
• CI/check status
• blockers or terminal state

HTML report constraints: inline CSS/SVG/JS only; no external scripts, stylesheets, CDNs, tracking, network calls, or remote assets. If the report includes interactive controls, include a copy/export block that serializes the selected state back to Markdown/JSON/prompt text.

Do not create HTML for simple /pipeline N --status, --dry-run, or one-step summaries unless the user asks.

7. Final summary

When the loop ends, the skill prints:

• Starting stage → ending stage
• Number of transitions
• Wall-clock elapsed
• For terminal: PR URL + ready-to-deploy summary
• For blocked: latest blocker comment + the unblock command
• For waiting: short reason + "re-run /pipeline N when ready"

Failure modes

• gh not authenticated → tell user gh auth login, exit.
• No git repo at cwd / repo-path → exit 2 with "run from inside a checkout".
• Issue # doesn't exist → surface gh error, exit 1.
• PR has no linked issue → refuse with the explanation.
• No pipeline:* label → refuse with opt-in instructions.
• Stage handler error → posts a blocked label + structured comment with reason; loop terminates and shows the latest blocker.
• Primary harness fails (planning/implementation/fix/docs) → blocked unless the stage explicitly defines a safe fallback.

What this skill never does

• Auto-merge PRs (cfg.auto_merge is honored as false only).
• Bypass the pipeline:* opt-in label gate.
• Run more than one transition under --once.
• Touch the GitHub repo in --dry-run mode.
• Read or send ANTHROPIC_API_KEY.
• Write outside the repo's worktree directory or the target issue/PR.

Reference

• core/scripts/types.ts — STAGES, PipelineConfig, Outcome, ReviewVerdict
• core/scripts/config.ts — load .github/pipeline.yml + defaults
• core/scripts/gh.ts — typed wrappers for the gh CLI
• core/scripts/worktree.ts — pipeline-{N}-{slug} worktree lifecycle
• core/scripts/harness.ts — invoke("claude" | "codex", cwd, prompt)
• core/scripts/lock.ts — PID-based lock at /tmp/pipeline-{domain}.lock
• core/scripts/stages/*.ts — one file per stage (planning, review, fix, pre_merge, deploy_ready, auto_recover)
• core/scripts/prompts/*.md — prompt templates with {{placeholders}}
• core/scripts/pipeline.ts — top-level orchestrator + CLI
• README.md — human-facing docs