ln-1000-pipeline-orchestrator

What this skill does

> **Paths:** File paths (`references/`, `../ln-*`) are relative to this skill directory.

**Type:** L1 Orchestrator
**Category:** 1000 Pipeline

# Pipeline Orchestrator

Drives a selected Story through the full pipeline (task planning -> validation -> execution -> quality gate) by invoking coordinators as Skill() calls in a single context and advancing from coordinator stage artifacts.

## Purpose & Scope
- Parse kanban board and show available Stories for user selection
- Ask business questions in ONE batch before execution; make technical decisions autonomously
- Drive selected Story through 4 stages: ln-300 -> ln-310 -> ln-400 -> ln-500
- Write stage notes + checkpoints after each stage for reporting and recovery
- Handle failures, retries, rework cycles, and escalation to user
- Generate pipeline report with branch name, git stats, agent review info

## Hierarchy

```
L0: ln-1000-pipeline-orchestrator (sequential Skill calls, single context)
  +-- Skill("ln-300") — task decomposition (internally manages stateful task-plan workers)
  +-- Skill("ln-310") — validation (internally launches configured external review agents when available)
  +-- Skill("ln-400") — execution (internally dispatches stateful task workers)
  +-- Skill("ln-500") — quality gate (internally runs artifact-first ln-510/ln-520, verdict, finalization)
```

**Key principle:** ln-1000 invokes coordinators via Skill tool. Each coordinator manages its own internal worker dispatch and emits a stage artifact. ln-1000 does NOT modify existing skills — it calls them exactly as a human operator would and treats coordinator artifacts as the primary completion signal.

## Task Storage Mode

**MANDATORY READ:** Load `references/environment_state_contract.md` and `references/storage_mode_detection.md`

Extract: `task_provider` = Task Management -> Provider (`linear` | `file`).

## When to Use
- One Story ready for processing — user picks which one
- Need end-to-end automation: task planning -> validation -> execution -> quality gate
- Want controlled Story processing with pipeline report

## Pipeline: 4-Stage State Machine

**MANDATORY READ:** Load `references/pipeline_states.md` for transition rules and guards.
**MANDATORY READ:** Load `references/loop_health_contract.md`

```
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
                                                                      Done    To Rework -> Stage 2
                                                               (branch pushed)  (max 2 cycles)
```

| Stage | Skill | Input Status | Output Status |
|-------|-------|-------------|--------------|
| 0 | ln-300-task-coordinator | Backlog (no tasks) | Backlog (tasks created) |
| 1 | ln-310-multi-agent-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 |

## Workflow

### Phase 0: Recovery Check

```
PIPELINE="{skill_repo}/ln-1000-pipeline-orchestrator/scripts/cli.mjs"
recovery = Bash: node $PIPELINE status

IF recovery.active == true:
  # Previous run interrupted — resume from CLI state
  1. Extract: story_id, stage, resume_action from recovery JSON
  2. Read already-written stage artifacts and runtime state
  3. Re-read kanban board -> secondary verification only
  4. IF recovery.state.worktree_dir exists: cd {recovery.state.worktree_dir}
  5. Jump to Phase 4, starting from resume_action

IF recovery.active == false:
  # Fresh start — proceed to Phase 1
```

### Phase 1: Discovery, Kanban Parsing & Story Selection

**MANDATORY READ:** Load `references/kanban_parser.md` for parsing patterns.

1. Auto-discover `docs/tasks/kanban_board.md` (or Linear API via storage mode operations)
2. 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" }
   ```
3. Parse all status sections: Backlog, Todo, In Progress, To Review, To Rework
4. Extract Story list with: ID, title, status, Epic name, task presence
5. Filter: skip Stories in Done, Postponed, Canceled
6. Detect task presence per Story:
   - Has `_(tasks not created yet)_` -> **no tasks** -> Stage 0
   - Has task lines (4-space indent) -> **tasks exist** -> Stage 1+
7. Determine target stage per Story (see `references/pipeline_states.md` Stage-to-Status Mapping)
8. 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."
   ```
9. Store selected story. Extract story brief for selected story only:
   ```
   description = tracker getStory(selected_story.id).body  // provider-specific transport per tracker_provider_contract.md
   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)

1. Load selected Story description (metadata only)
2. 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)
3. Collect ALL business questions into single AskUserQuestion
4. 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

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

### Phase 3: Pipeline Setup

#### 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."
```

#### 3.1 Pre-flight: Settings Verification

Verify `.claude/settings.local.json` in target project:
- `defaultMode` = `"bypassPermissions"` (required for Agent workers spawned by coordinators)

#### 3.2 Worktree Isolation

**MANDATORY READ:** Load `references/git_worktree_fall