Paths: File paths (
shared/
,
references/
,
../ln-*
) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

Pipeline Orchestrator

Meta-orchestrator that reads the kanban board, shows available Stories, lets the user pick one to process, and drives it through the full pipeline (task planning -> validation -> execution -> quality gate) using Claude Code Agent Teams.

Purpose & Scope

Parse kanban board and show available Stories for user selection
Ask business questions in ONE batch before execution; make technical decisions autonomously
Spawn worker via TeamCreate for selected Story (single worker)
Drive selected Story through 4 stages: ln-300 -> ln-310 -> ln-400 -> ln-500
Sync with develop + generate report after quality gate PASS; merge only on user confirmation
Handle failures, retries, and escalation to user

Hierarchy

L0: ln-1000-pipeline-orchestrator (TeamCreate lead, delegate mode, single story)
  +-- Worker (fresh per stage, shutdown after completion, one at a time)
       |   All stages: Opus 4.6  |  Effort: Stage 0 = low | Stage 1,2 = medium | Stage 3 = medium
       +-- L1: ln-300 / ln-310 / ln-400 / ln-500 (invoked via Skill tool, as-is)
            +-- L2/L3: existing hierarchy unchanged

Key principle: ln-1000 does NOT modify existing skills. Workers invoke ln-300/ln-310/ln-400/ln-500 through Skill tool exactly as a human operator would.

MCP Tool Preferences

When

mcp__hashline-edit__*

tools are available, workers MUST prefer them over standard file tools:

Standard Tool	Hashline-Edit Replacement	Why
`Read`	`mcp__hashline-edit__read_file`	Hash-prefixed lines enable precise edits
`Edit`	`mcp__hashline-edit__edit_file`	Atomic validation prevents corruption
`Write`	`mcp__hashline-edit__write_file`	Same behavior, consistent interface
`Grep`	`mcp__hashline-edit__grep`	Results include hashline refs for follow-up edits

Fallback: If hashline-edit MCP unavailable (tools not in ToolSearch), use standard tools. No error.

Task Storage Mode

MANDATORY READ: Load

shared/references/storage_mode_detection.md

for Linear vs File mode detection and operations.

When to Use

One Story ready for processing — user picks which one
Need end-to-end automation: task planning -> validation -> execution -> quality gate -> merge confirmation
Want controlled Story processing with user confirmation before merge

Pipeline: 4-Stage State Machine

MANDATORY READ: Load

references/pipeline_states.md

for transition rules and guards.

Backlog       --> Stage 0 (ln-300) --> Backlog      --> Stage 1 (ln-310) --> Todo
(no tasks)        create tasks         (tasks exist)      validate            |
                                                          | NO-GO             |
                                                          v                   v
                                                       [retry/ask]    Stage 2 (ln-400)
                                                                             |
                                                                             v
                                                                      To Review
                                                                             |
                                                                             v
                                                                      Stage 3 (ln-500)
                                                                       |          |
                                                                      PASS       FAIL
                                                                       |          v
                                                                PENDING_MERGE  To Rework -> Stage 2
                                                                  (sync+report)  (max 2 cycles)
                                                                       |
                                                                  [user confirms?]
                                                                   yes  |  no
                                                                   v       v
                                                                Done    Done
                                                              (merged) (branch kept)

Stage	Skill	Input Status	Output Status
0	ln-300-task-coordinator	Backlog (no tasks)	Backlog (tasks created)
1	ln-310-story-validator	Backlog (tasks exist)	Todo
2	ln-400-story-executor	Todo / To Rework	To Review
3	ln-500-story-quality-gate	To Review	Done / To Rework

Team Lead Responsibilities

This skill runs as a team lead in delegate mode. The agent executing ln-1000 MUST NOT write code or invoke skills directly.

Responsibility	Description
Coordinate	Assign stages to worker, process completion reports, advance pipeline
Verify board	Re-read kanban/Linear after each stage. Workers update via skills; lead ASSERTs expected state transitions
Escalate	Route failures to user when retry limits exceeded
Sync & confirm	Sync with develop after quality gate PASS, ask user for merge confirmation
Shutdown	Graceful worker shutdown, team cleanup

NEVER do as lead: Invoke ln-300/ln-310/ln-400/ln-500 directly. Edit source code. Skip quality gate. Force-kill workers.

Workflow

Phase 0: Recovery Check

IF .pipeline/state.json exists AND complete == false:
  # Previous run interrupted — resume from saved state
  1. Read .pipeline/state.json → restore: selected_story_id, story_state, worker_map,
     quality_cycles, validation_retries, crash_count,
     story_results, infra_issues, worktree_map,
     stage_timestamps, git_stats, pipeline_start_time, readiness_scores, merge_status
  2. Read .pipeline/checkpoint-{selected_story_id}.json → validate story_state consistency
     (checkpoint.stage should match story_state[id])
  3. Re-read kanban board → verify selected story still exists
  4. Read team config → verify worker_map members still exist
  5. Set suspicious_idle = false (ephemeral, reset on recovery)
  6. IF story_state[id] == "PENDING_MERGE":
     # Re-ask user for merge confirmation (Phase 4 post-loop)
     Jump to Phase 4 POST-LOOP
  7. IF story_state[id] IN ("STAGE_0".."STAGE_3"):
     IF checkpoint.agentId exists → Task(resume: checkpoint.agentId)
     ELSE → respawn worker with checkpoint context (see checkpoint_format.md)
  8. Jump to Phase 4 event loop

IF .pipeline/state.json NOT exists OR complete == true:
  # Fresh start — proceed to Phase 1

Phase 1: Discovery, Kanban Parsing & Story Selection

MANDATORY READ: Load

references/kanban_parser.md

for parsing patterns.

Auto-discover
```
docs/tasks/kanban_board.md
```
(or Linear API via storage mode detection)

Extract project brief from target project's CLAUDE.md (NOT skills repo):

project_brief = {
  name: <from H1 or first line>,
  tech: <from Development Commands / tech references>,
  type: <inferred: "CLI", "API", "web app", "library">,
  key_rules: <2-3 critical rules>
}
IF not found: project_brief = { name: basename(project_root), tech: "unknown" }

Parse all status sections: Backlog, Todo, In Progress, To Review, To Rework
Extract Story list with: ID, title, status, Epic name, task presence
Filter: skip Stories in Done, Postponed, Canceled
Detect task presence per Story:
- Has
```
_(tasks not created yet)_
```
  → no tasks → Stage 0
- Has task lines (4-space indent) → tasks exist → Stage 1+
Determine target stage per Story (see
```
references/pipeline_states.md
```
Stage-to-Status Mapping)

Show available Stories and ask user to pick ONE:

Project: {project_brief.name} ({project_brief.tech})

Available Stories:
| # | Story | Status | Stage | Skill | Epic |
|---|-------|--------|-------|-------|------|
| 1 | PROJ-42: Auth endpoint | To Review | 3 | ln-500 | Epic: Auth |
| 2 | PROJ-55: CRUD users | Backlog (no tasks) | 0 | ln-300 | Epic: Users |
| 3 | PROJ-60: Dashboard | Todo | 2 | ln-400 | Epic: UI |

AskUserQuestion: "Which story to process? Enter # or Story ID."

Store selected story. Extract story brief for selected story only:

description = get_issue(selected_story.id).description
story_briefs[id] = parse <!-- ORCHESTRATOR_BRIEF_START/END --> markers
IF no markers: story_briefs[id] = { tech: project_brief.tech, keyFiles: "unknown" }

Phase 2: Pre-flight Questions (ONE batch)

Load selected Story description (metadata only)
Scan for business ambiguities — questions where:
- Answer cannot be found in codebase, docs, or standards
- Answer requires business/product decision (payment provider, auth flow, UI preference)

Collect ALL business questions into single AskUserQuestion:

"Before starting Story {selected_story.id}:
 Which payment provider? (Stripe/PayPal/both)
 Auth flow — JWT or session-based?"

Technical questions — resolve using project_brief:
- Library versions: MCP Ref / Context7 (for
```
project_brief.tech
```
  ecosystem)
- Architecture patterns:
```
project_brief.key_rules
```
- Standards compliance: ln-310 Phase 2 handles this
Store answers in shared context (pass to worker via spawn prompt)

Skip Phase 2 if no business questions found. Proceed directly to Phase 3.

Phase 3: Team Setup

MANDATORY READ: Load

references/settings_template.json

for required permissions and hooks.

3.0 Linear Status Cache (Linear mode only)

IF storage_mode == "linear":
  statuses = list_issue_statuses(teamId=team_id)
  status_cache = {status.name: status.id FOR status IN statuses}

  REQUIRED = ["Backlog", "Todo", "In Progress", "To Review", "To Rework", "Done"]
  missing = [s for s in REQUIRED if s not in status_cache]
  IF missing: ABORT "Missing Linear statuses: {missing}. Configure workflow."

  # Persist in state.json (added in 3.2) and pass to workers via prompt CONTEXT

3.1 Pre-flight: Settings Verification

Verify

.claude/settings.local.json

in target project:

```
defaultMode
```
=
```
"bypassPermissions"
```
(required for workers)
```
hooks.Stop
```
registered →
```
pipeline-keepalive.sh
```
```
hooks.TeammateIdle
```
registered →
```
worker-keepalive.sh
```

If missing or incomplete → copy from

references/settings_template.json

and install hook scripts via Bash

cp

(NOT Write tool — Write produces CRLF on Windows, breaking

#!/bin/bash

shebang):

# Preflight: verify dependencies
which jq || ABORT "jq is required for pipeline hooks. Install: https://jqlang.github.io/jq/download/"

mkdir -p .claude/hooks
Bash: cp {skill_repo}/ln-1000-pipeline-orchestrator/references/hooks/pipeline-keepalive.sh .claude/hooks/pipeline-keepalive.sh
Bash: cp {skill_repo}/ln-1000-pipeline-orchestrator/references/hooks/worker-keepalive.sh  .claude/hooks/worker-keepalive.sh

Hook troubleshooting: If hooks fail with "No such file or directory":

Verify hook commands use
```
bash .claude/hooks/script.sh
```
(relative path, no env vars —
```
$CLAUDE_PROJECT_DIR
```
is NOT available in hook shell context)
Verify
```
.claude/hooks/*.sh
```
files exist and have
```
#!/bin/bash
```
shebang
On Windows: ensure LF line endings in .sh files (see hook installation above — use Bash
```
cp
```
, not Write tool)

3.2 Initialize Pipeline State

Write .pipeline/state.json (full schema — see checkpoint_format.md):
  { "complete": false, "selected_story_id": "<selected story ID>",
    "stories_remaining": 1, "last_check": <now>,
    "story_state": {}, "worker_map": {}, "quality_cycles": {}, "validation_retries": {},
    "crash_count": {},
    "worktree_map": {}, "story_results": {}, "infra_issues": [],
    "status_cache": {<status_name: status_uuid>},    # Empty object if file mode
    "stage_timestamps": {}, "git_stats": {}, "pipeline_start_time": <now>, "readiness_scores": {},
    "skill_repo_path": <absolute path to skills repository root>,
    "team_name": "pipeline-{YYYY-MM-DD}",
    "business_answers": {<question: answer pairs from Phase 2, or {} if skipped>},
    "merge_status": "pending",
    "storage_mode": "file"|"linear",
    "project_brief": {<name, tech, type, key_rules from Phase 1 step 2>},
    "story_briefs": {<storyId: {tech, keyFiles, approach, complexity} from Phase 1 step 9>} }   # Recovery-critical
Write .pipeline/lead-session.id with current session_id   # Stop hook uses this to only keep lead alive

3.2a Sleep Prevention (Windows only)

IF platform == "win32":
  Bash: cp {skill_repo}/ln-1000-pipeline-orchestrator/references/hooks/prevent-sleep.ps1 .claude/hooks/prevent-sleep.ps1
  Bash: powershell -ExecutionPolicy Bypass -WindowStyle Hidden -File .claude/hooks/prevent-sleep.ps1 &
  sleep_prevention_pid = $!
  # Script polls .pipeline/state.json — self-terminates when complete=true
  # Fallback: Windows auto-releases execution state on process exit

3.3 Create Team & Prepare Branch

Worktree: Worker gets its own worktree with a named feature branch (

feature/{id}-{slug}

). Created in Phase 4 before spawning.

Model routing: All stages use

model: "opus"

. Effort routing via prompt:

effort_for_stage(0) = "low"

effort_for_stage(1) = "medium"

effort_for_stage(2) = "medium"

effort_for_stage(3) = "medium"

. Crash recovery = same as target stage. Thinking mode: always enabled (adaptive).

Ensure

develop

branch exists:

IF `develop` branch not found locally or on origin:
  git branch develop $(git symbolic-ref --short HEAD)   # Create from current default branch
  git push -u origin develop
git checkout develop               # Start pipeline from develop

Create team:

TeamCreate(team_name: "pipeline-{YYYY-MM-DD}-{HHmm}")

Worker is spawned in Phase 4 after worktree creation.

Phase 4: Execution Loop

MANDATORY READ: Load

references/message_protocol.md

for exact message formats and parsing regex. MANDATORY READ: Load

references/worker_health_contract.md

for crash detection and respawn rules.

Lead operates in delegate mode — coordination only, no code writing.

MANDATORY READ: Load

references/checkpoint_format.md

for checkpoint schema and resume protocol.

# --- INITIALIZATION (single story) ---
selected_story = <from Phase 1 selection>
quality_cycles[selected_story.id] = 0       # FAIL→retry counter, limit 2
validation_retries[selected_story.id] = 0   # NO-GO retry counter, limit 1
crash_count[selected_story.id] = 0          # crash respawn counter, limit 1
suspicious_idle = false                      # crash detection flag
story_state[selected_story.id] = "QUEUED"
worker_map = {}                              # {storyId: worker_name}
worktree_map = {}                            # {storyId: worktree_dir | null}
story_results = {}                           # {storyId: {stage0: "...", ...}} — for pipeline report
infra_issues = []                            # [{phase, type, message}] — infrastructure problems
heartbeat_count = 0                          # Heartbeat cycle counter (ephemeral, resets on recovery)
stage_timestamps = {}                        # {storyId: {stage_N_start: ISO, stage_N_end: ISO}}
git_stats = {}                               # {storyId: {lines_added, lines_deleted, files_changed}}
pipeline_start_time = now()                  # ISO 8601 — wall-clock start for duration metrics
readiness_scores = {}                        # {storyId: readiness_score} — from Stage 1 GO

# Helper functions — see phase4_heartbeat.md Helper Functions for full definitions
# skill_name_from_stage(stage), predict_next_step(stage), stage_duration(id, N)

# --- SPAWN SINGLE WORKER ---
id = selected_story.id
target_stage = determine_stage(selected_story)    # See pipeline_states.md guards
worker_name = "story-{id}-s{target_stage}"

worktree_dir = ".worktrees/story-{id}"
git worktree add -b feature/{id}-{slug} {worktree_dir} develop

worktree_map[id] = worktree_dir
project_root = Bash("pwd")           # Absolute path for PIPELINE_DIR in worktree mode
Task(name: worker_name, team_name: "pipeline-{date}",
     model: "opus", mode: "bypassPermissions",
     subagent_type: "general-purpose",
     prompt: worker_prompt(selected_story, target_stage, business_answers, worktree_dir, project_root))
worker_map[id] = worker_name
story_state[id] = "STAGE_{target_stage}"
stage_timestamps[id] = {}
stage_timestamps[id]["stage_{target_stage}_start"] = now()
Write .pipeline/worker-{worker_name}-active.flag     # For TeammateIdle hook
Update .pipeline/state.json
SendMessage(recipient: worker_name,
            content: "Execute Stage {target_stage} for {id}",
            summary: "Stage {target_stage} assignment")

# --- EVENT LOOP (driven by Stop hook heartbeat, single story) ---
# HOW THIS WORKS:
# 1. Lead's turn ends → Stop event fires
# 2. pipeline-keepalive.sh reads .pipeline/state.json → complete=false → exit 2
# 3. stderr "HEARTBEAT: ..." → new agentic loop iteration
# 4. Any queued worker messages (SendMessage) delivered in this cycle
# 5. Lead processes messages via ON handlers (reactive) + verifies done-flags (proactive)
# 6. Lead's turn ends → Go to step 1
#
# The Stop hook IS the event loop driver. Each heartbeat = one iteration.
# Lead MUST NOT say "waiting for messages" and stop — the heartbeat keeps it alive.
# If no worker messages arrived: output brief status, let turn end → next heartbeat.
#
# --- CONTEXT RECOVERY PROTOCOL ---
# Claude Code may compress conversation history during long pipelines.
# When this happens, you lose SKILL.md instructions and state variables.
# The Stop hook includes "---PIPELINE RECOVERY CONTEXT---" in EVERY heartbeat stderr.
#
# IF you see this block and don't recall the pipeline protocol:
#   Follow CONTEXT RECOVERY PROTOCOL in references/phases/phase4_heartbeat.md (7 steps).
#   Quick summary: state.json → SKILL.md(FULL) → handlers → heartbeat → known_issues → ToolSearch → resume
#
# FRESH WORKER PER STAGE: Each stage transition = shutdown old worker + spawn new one.
#
# BIDIRECTIONAL HEALTH MONITORING:
# - Reactive: ON handlers process worker completion messages
# - Proactive: Verify done-flags without messages (lost message recovery)
# - Defense-in-depth: Handles network issues, context overflow, worker crashes

WHILE story_state[id] NOT IN ("DONE", "PAUSED", "PENDING_MERGE"):

  # 1. Process worker messages (reactive message handling)
  #
  **MANDATORY READ:** Load `references/phases/phase4_handlers.md` for all ON message handlers:
  - Stage 0 COMPLETE / ERROR (task planning outcomes)
  - Stage 1 COMPLETE (GO / NO-GO validation outcomes with retry logic)
  - Stage 2 COMPLETE / ERROR (execution outcomes)
  - Stage 3 COMPLETE (PASS/CONCERNS/WAIVED/FAIL quality gate outcomes with rework cycles)
  - Worker crash detection (3-step protocol: flag → probe → respawn)

  Handlers include sender validation and state guards to prevent duplicate processing.

  # 2. Active done-flag verification (proactive health monitoring)
  #
  **MANDATORY READ:** Load `references/phases/phase4_heartbeat.md` for bidirectional health monitoring:
  - Lost message detection (done-flag exists but state not advanced)
  - Synthetic recovery from checkpoint + kanban verification (all 4 stages)
  - Fallback to probe protocol when checkpoint missing
  - Structured heartbeat output (single story status line)
  - Helper functions (skill_name_from_stage, predict_next_step)

  # 3. Heartbeat state persistence
  #
  ON HEARTBEAT (Stop hook stderr: "HEARTBEAT: ..."):
    Write .pipeline/state.json with ALL state variables.
    # See phase4_heartbeat.md for persistence details

# --- POST-LOOP: Handle PENDING_MERGE ---
IF story_state[id] == "PENDING_MERGE":
  # Phase 4a Section B: Ask user for merge confirmation
  # (Section A: sync+report already executed by Stage 3 PASS handler)
  AskUserQuestion:
    "Story {id} completed. Quality Score: {score}/100. Verdict: {verdict}.
     Branch: feature/{id}-{slug}
     Files changed: {git_stats[id].files_changed}, +{git_stats[id].lines_added}/-{git_stats[id].lines_deleted}
     Report: docs/tasks/reports/pipeline-{date}.md

     Merge feature/{id}-{slug} to develop?"

  IF user confirms:
    Execute phase4a_git_merge.md Section C: merge_to_develop(id)
    # Sets story_state = "DONE", merge_status = "merged"
  ELSE:
    Execute phase4a_git_merge.md Section D: decline_merge(id)
    # Sets story_state = "DONE", merge_status = "declined"

determine_stage(story)
routing: See

references/pipeline_states.md

Stage-to-Status Mapping table.

Phase 4a: Git Sync, Report & Merge Confirmation

MANDATORY READ: Load

references/phases/phase4a_git_merge.md

for full procedure:

Section A: Sync with develop (rebase → fallback to merge), collect metrics, append story report, verify kanban/Linear — executed automatically after Stage 3 PASS
Section B: Ask user for merge confirmation (AskUserQuestion) — post-loop
Section C: Squash merge into develop, worktree cleanup, context refresh — only if user confirms
Section D: Preserve branch, output manual merge instructions — if user declines

Triggered after Stage 3 PASS/CONCERNS/WAIVED verdict from ln-500-story-quality-gate.

Phase 5: Cleanup & Self-Verification

# 0. Signal pipeline complete (allows Stop hook to pass)
Write .pipeline/state.json: { "complete": true, ... }

# 1. Self-verify against Definition of Done
verification = {
  story_selected:   selected_story_id is set              # Phase 1 ✓
  questions_asked:  business_answers stored OR none        # Phase 2 ✓
  team_created:     team exists                            # Phase 3 ✓
  story_processed:  story_state[id] IN ("DONE", "PAUSED") # Phase 4 ✓
  sync_completed:   feature branch synced with develop     # Phase 4a Section A ✓
  merge_status:     "merged" | "declined" | "paused"       # Phase 4a Section C/D ✓
}
IF ANY verification == false: WARN user with details

# 2. Finalize pipeline report
Prepend summary header to docs/tasks/reports/pipeline-{date}.md:
  # Pipeline Report — {date}
  | Metric | Value |
  |--------|-------|
  | Story | {selected_story_id}: {title} |
  | Final State | {story_state[id]} |
  | Merge Status | {merge_status} |
  | Quality rework cycles | {quality_cycles[id]} |
  | Validation retries | {validation_retries[id]} |
  | Crash recoveries | {crash_count[id]} |
  | Infrastructure issues | {len(infra_issues)} |

# 2b. Stage Duration Breakdown
Append Stage Duration section:
  ## Stage Duration Breakdown
  | Stage 0 | Stage 1 | Stage 2 | Stage 3 | Total | Bottleneck |
  |---------|---------|---------|---------|-------|------------|
  durations = {N: stage_timestamps[id]["stage_{N}_end"] - stage_timestamps[id]["stage_{N}_start"]
               FOR N IN 0..3 IF both timestamps exist}
  total = sum(durations.values())
  bottleneck = key with max(durations)
  | {durations[0] or "—"} | {durations[1] or "—"} | {durations[2] or "—"} | {durations[3] or "—"} | {total} | Stage {bottleneck} |

# 2c. Code Output Metrics
Append Code Output section (if git_stats available):
  ## Code Output Metrics
  | Files Changed | Lines Added | Lines Deleted | Net Lines |
  |--------------|-------------|---------------|-----------|
  | {git_stats[id].files_changed} | +{git_stats[id].lines_added} | -{git_stats[id].lines_deleted} | {net} |

# 2d. Cost Estimate
Append Cost Estimate section:
  ## Cost Estimate
  | Metric | Value |
  |--------|-------|
  | Wall-clock time | {now() - pipeline_start_time} |
  | Total worker spawns | {count of Task() calls in session} |
  | Hashline-edit usage | {count mcp__hashline-edit__* calls in Stage 2 workers} / {total file edits} |

# 2e. Collect infrastructure issues
# Analyze pipeline session for non-fatal problems:
# hook/settings failures, git conflicts, worktree errors, merge issues,
# Linear sync mismatches, worker crashes, permission errors.
# Populate infra_issues = [{phase, type, message}] from session context.

Append Infrastructure Issues section:
  ## Infrastructure Issues
  IF infra_issues NOT EMPTY:
    | # | Phase | Type | Details |
    |---|-------|------|---------|
    FOR EACH issue IN infra_issues:
      | {N} | {issue.phase} | {issue.type} | {issue.message} |
  ELSE:
    _No infrastructure issues._

Append Operational Recommendations section (auto-generated from counters):
  ## Operational Recommendations
  - IF quality_cycles[id] > 0: "Needed {N} quality cycles. Improve task specs or acceptance criteria."
  - IF validation_retries[id] > 0: "Failed validation. Review Story/Task structure."
  - IF crash_count[id] > 0: "Worker crashed {N} times. Check for context-heavy operations."
  - IF story_state[id] == "PAUSED": "Story requires manual intervention."
  - IF infra_issues with type "hook": "Hook configuration errors. Verify settings.local.json and .claude/hooks/."
  - IF infra_issues with type "git": "Git conflicts encountered. Rebase feature branches more frequently."
  - IF all DONE with 0 retries AND no infra_issues: "Clean run — no issues detected."

# 3. Show pipeline summary to user

Pipeline Complete:

Story	Stage 0	Stage 1	Stage 2	Stage 3	Merged	Final State
{id}	{stage0}	{stage1}	{stage2}	{stage3}	{merge_status}	{story_state[id]}

Report saved: docs/tasks/reports/pipeline-{date}.md

# 4. Shutdown worker (if still active)
IF worker_map[id]:
  SendMessage(type: "shutdown_request", recipient: worker_map[id])

# 5. Cleanup team
TeamDelete

# 6. Worktree cleanup
IF merge_status == "merged":
  # Worktree already removed in Phase 4a Section C
  pass
ELSE IF merge_status == "declined":
  # Preserve worktree — user needs it for manual merge
  Output: "Worktree preserved at .worktrees/story-{id}/"
ELSE IF story_state[id] == "PAUSED":
  IF merge_status == "pending" AND worktree_map[id]:
    # Merge conflict — preserve worktree for manual resolution
    Output: "Worktree preserved at {worktree_map[id]}/ for merge conflict resolution"
  ELSE IF worktree_map[id]:
    git worktree remove {worktree_map[id]} --force
    rm -rf .worktrees/

# 7. Switch to develop (only if merged)
IF merge_status == "merged":
  git checkout develop

# 8. Remove pipeline state files

# 8a. Stop sleep prevention (Windows safety net — script should have self-terminated)
IF sleep_prevention_pid:
  kill $sleep_prevention_pid 2>/dev/null || true
Delete .pipeline/ directory

# 9. Report results and report location to user

Kanban as Single Source of Truth

Lead = single writer to kanban_board.md. Workers report results via SendMessage; lead updates the board
Re-read board after each stage completion for fresh state
Update algorithm: Follow
```
shared/references/kanban_update_algorithm.md
```
for Epic grouping and indentation

Error Handling

Situation	Detection	Action
ln-300 task creation fails	Worker reports error	Escalate to user: "Cannot create tasks for Story {id}"
ln-310 NO-GO (Score <5)	Worker reports NO-GO	Retry once (ln-310 auto-fixes). If still NO-GO -> ask user
Task in To Rework 3+ times	Worker reports rework loop	Escalate: "Task X reworked 3 times, need input"
ln-500 FAIL	Worker reports FAIL verdict	Fix tasks auto-created by ln-500. Stage 2 re-entry. Max 2 quality cycles
Worker crash	TeammateIdle without completion msg	Re-spawn worker, resume from last stage
Business question mid-execution	Worker encounters ambiguity	Worker -> lead -> user -> lead -> worker (message chain)
Merge conflict (sync)	git rebase/merge fails	Escalate to user, Story PAUSED, worktree preserved for resolution

Critical Rules

Single Story processing. One worker at a time. User selects which Story to process
Delegate mode. Lead coordinates only — never invoke ln-300/ln-310/ln-400/ln-500 directly. Workers do all execution
Skills as-is. Never modify or bypass existing skill logic. Workers call
```
Skill("ln-310-story-validator", args)
```
exactly as documented
Kanban verification. Workers update Linear/kanban via skills. Lead re-reads and ASSERTs expected state after each stage. In file mode, lead resolves merge conflicts
Quality cycle limit. Max 2 quality FAILs per Story (original + 1 rework cycle). After 2nd FAIL, escalate to user
Merge only on confirmation. After quality gate PASS, sync with develop and ask user. Merge only if confirmed. Feature branch preserved if declined
Re-read kanban. After every stage completion, re-read board for fresh state. Never cache
Graceful shutdown. Always shutdown workers via shutdown_request. Never force-kill

Known Issues

MANDATORY READ: Load

references/known_issues.md

for production-discovered problems and self-recovery patterns.

Anti-Patterns

Running ln-300/ln-310/ln-400/ln-500 directly from lead instead of delegating to workers
Processing multiple stories without user selection
Auto-merging to develop without user confirmation
Lead skipping kanban verification after worker updates (workers write via skills, lead MUST re-read + ASSERT)
Skipping quality gate after execution
Merging to develop before quality gate PASS
Caching kanban state instead of re-reading
Reading
```
~/.claude/teams/*/inboxes/*.json
```
directly (messages arrive automatically)
Using
```
sleep
```
+ filesystem polling for message checking
Parsing internal Claude Code JSON formats (permission_request, idle_notification)
Reusing same worker across stages (context exhaustion — spawn fresh worker per stage)
Processing messages without verifying sender matches worker_map (stale message confusion from old/dead workers)

Plan Mode Support

When invoked in Plan Mode, show available Stories and ask user which one to plan for:

Parse kanban board (Phase 1 steps 1-7)
Show available Stories table
AskUserQuestion: "Which story to plan for? Enter # or Story ID."
Show execution plan for selected Story
Write plan to plan file, call ExitPlanMode

Plan Output Format:

## Pipeline Plan for {date}

**Story:** {ID}: {Title}
**Current Status:** {status}
**Target Stage:** {N} ({skill_name})

### Execution Sequence
1. TeamCreate("pipeline-{date}")
2. Create worktree + feature branch: feature/{id}-{slug}
3. Spawn worker -> Stage {N} ({skill_name})
4. Drive through remaining stages until quality gate
5. Sync with develop, generate report
6. Ask for merge confirmation
7. Cleanup

Definition of Done (self-verified in Phase 5)

#	Criterion	Verified By
1	User selected Story from kanban board	`selected_story_id` is set
2	Business questions asked in single batch (or none found)	`business_answers` stored OR skip
3	Team created, single worker spawned	Worker spawned for selected Story
4	Selected Story processed: state = DONE or PAUSED	`story_state[id] IN ("DONE", "PAUSED")`
5	Feature branch synced with develop. Merged if user confirmed	`merge_status` = "merged" or "declined"
6	Pipeline summary shown to user	Phase 5 table output
7	Team cleaned up (worker shutdown, TeamDelete)	TeamDelete called

Reference Files

Phase 4 Procedures (Progressive Disclosure)

Message handlers:
```
references/phases/phase4_handlers.md
```
(Stage 0-3 ON handlers, crash detection)
Heartbeat & verification:
```
references/phases/phase4_heartbeat.md
```
(Active done-flag checking, structured heartbeat output)
Git flow:
```
references/phases/phase4a_git_merge.md
```
(Sync, report, merge confirmation, worktree cleanup)

Core Infrastructure

Known issues:
```
references/known_issues.md
```
(production-discovered problems and self-recovery)
Message protocol:
```
references/message_protocol.md
```
Worker health:
```
references/worker_health_contract.md
```
Checkpoint format:
```
references/checkpoint_format.md
```
Settings template:
```
references/settings_template.json
```

Hooks:

references/hooks/pipeline-keepalive.sh

references/hooks/worker-keepalive.sh

Kanban parsing:
```
references/kanban_parser.md
```
Pipeline states:
```
references/pipeline_states.md
```
Worker prompts:
```
references/worker_prompts.md
```

Kanban update algorithm:

shared/references/kanban_update_algorithm.md

Storage mode detection:

shared/references/storage_mode_detection.md

Auto-discovery patterns:

shared/references/auto_discovery_pattern.md

Delegated Skills

```
../ln-300-task-coordinator/SKILL.md
```
```
../ln-310-story-validator/SKILL.md
```
```
../ln-400-story-executor/SKILL.md
```
```
../ln-500-story-quality-gate/SKILL.md
```

Version: 2.0.0 Last Updated: 2026-02-25

ln-1000-pipeline-orchestrator

NPX Install

Tags

SKILL.md Content

Pipeline Orchestrator

Purpose & Scope

Hierarchy

MCP Tool Preferences

Task Storage Mode

When to Use

Pipeline: 4-Stage State Machine

Team Lead Responsibilities

Workflow

Phase 0: Recovery Check

Phase 1: Discovery, Kanban Parsing & Story Selection

Phase 2: Pre-flight Questions (ONE batch)

Phase 3: Team Setup

3.0 Linear Status Cache (Linear mode only)

3.1 Pre-flight: Settings Verification

3.2 Initialize Pipeline State

3.2a Sleep Prevention (Windows only)

3.3 Create Team & Prepare Branch

Phase 4: Execution Loop

Phase 4a: Git Sync, Report & Merge Confirmation

Phase 5: Cleanup & Self-Verification

Kanban as Single Source of Truth

Error Handling

Critical Rules

Known Issues

Anti-Patterns

Plan Mode Support

Definition of Done (self-verified in Phase 5)

Reference Files

Phase 4 Procedures (Progressive Disclosure)

Core Infrastructure

Delegated Skills