Story Execution Orchestrator

Executes a Story end-to-end by looping through its tasks in priority order and delegating quality gates to ln-500-story-quality-gate.

Purpose & Scope

• Load Story + task metadata (no descriptions) and drive execution.
• Process tasks in order: To Review -> To Rework -> Todo (foundation-first within each status).
• Delegate per task type: ln-402-task-reviewer (independent context for unbiased review), ln-403-task-rework, ln-401-task-executor, ln-404-test-executor.
• Delegate Story quality to ln-500-story-quality-gate (Pass 1/Pass 2) and loop if new tasks are created.

Task Storage Mode

This skill supports dual-mode task storage:

Aspect	Linear Mode	File Mode
Detection	Default (MCP Linear available)	docs/tasks/epics/ directory exists
Load tasks	list_issues(parentId=Story.id)	Glob("docs/tasks/epics/*/stories/*/tasks/*.md") + parse status
Source of truth	Linear API	Task files + kanban_board.md

Auto-detection: Check if docs/tasks/epics/ exists → File Mode, otherwise Linear Mode.

File Mode status parsing: Extract **Status:** {value} from ## Status section in each task file.

Status values: Backlog, Todo, In Progress, To Review, To Rework, Done, Canceled

When to Use

• Story is Todo or In Progress and has implementation/refactor/test tasks to finish.
• Need automated orchestration through To Review and quality gates.

Plan Mode Support

When invoked in Plan Mode (agent cannot execute actions), this skill operates differently:

Phase 1-2: Same as normal mode (Discovery + Load metadata)

Phase 3-4 (Plan Mode only): Instead of executing, generate execution plan:

1. Build task execution sequence by priority (To Review → To Rework → Todo)
2. For each task, show:
   • Task ID, Title, current Status
   • Worker to be invoked (ln-401/ln-402/ln-403/ln-404)
   • Expected status after worker
3. Include Quality Gate phases (ln-500 Pass 1/Pass 2)
4. Write plan to plan file (if available)
5. Call ExitPlanMode for user approval

Plan Output Format:

## Execution Plan for Story {STORY-ID}: {Title}

### Tasks ({N} total)

| # | Task ID | Title | Status | Executor | Reviewer |
|---|---------|-------|--------|----------|----------|
| 1 | {ID} | {Title} | {Status} | ln-40X | ln-402 |

### Sequence

1. [Execute] {Task-1} via ln-401-task-executor
2. [Review] {Task-1} via ln-402-task-reviewer
...
N. [Quality Gate Pass 1] via ln-500-story-quality-gate
N+1. [Quality Gate Pass 2] → Story Done

After approval: User exits Plan Mode, invokes skill again → normal execution.

Workflow (concise)

• Phase 1 Discovery: Auto-discover Team ID/config from kanban_board.md + CLAUDE.md. Check current git branch: if not feature/{story-id}-{story-slug}, create/switch to it.

• Phase 2 Load: Fetch Story metadata and all child task metadata (ID/title/status/labels only).

  • Linear Mode: list_issues(parentId=Story.id)
  • File Mode: Glob("docs/tasks/epics/*/stories/{story-slug}/tasks/*.md") + parse **Status:** from each file

  Summarize counts (e.g., "2 To Review, 1 To Rework, 3 Todo"). NO analysis — proceed immediately to Phase 3/4.

• Phase 3 Context Review (before each Todo task execution): Before delegating a Todo task to ln-401/ln-404, verify its plan against current codebase:

  1. Load task description (get_issue or Read task file)
  2. Extract referenced files from task plan (files to create/modify)
  3. Check current state:
     • Do referenced files still exist?
     • Have related files changed significantly since task creation?
     • Are patterns/approaches mentioned still valid in current code?
  4. Decision:
     • No conflicts → proceed to execution
     • Minor changes → update task description with current context, then execute
     • Major conflicts → flag task, ask user whether to replan or proceed

  What to check:

  • Files mentioned in "Files to modify" section
  • Import patterns and dependencies
  • Related tests and fixtures
  • API contracts if integrating with other components

  Skip Context Review for:

  • To Review tasks (already executed, just need review)
  • To Rework tasks (reviewer provided specific fixes)
  • Test tasks (ln-404) when implementation tasks are freshly Done
  • Tasks created in same session (< 24h ago)

• Phase 4 Loop (immediate delegation via Skill tool, one task at a time):

  1. To Review → Use Skill tool to invoke ln-402-task-reviewer. Reload metadata after worker.
  2. To Rework → Use Skill tool to invoke ln-403-task-rework. After worker, verify status = To Review, then MANDATORY: immediately use Skill tool to invoke ln-402-task-reviewer on that same task. Reload metadata.
  3. Todo → pick first Todo; if label "tests" use Skill tool to invoke ln-404-test-executor else use Skill tool to invoke ln-401-task-executor. After worker, verify status = To Review (not Done/In Progress), then MANDATORY: immediately use Skill tool to invoke ln-402-task-reviewer on that same task. Reload metadata. Repeat loop; never queue multiple tasks in To Review—review right after each execution/rework.

⚠️ STRICT RULE: Every task execution MUST be followed by review. NO EXCEPTIONS. Execute → Review → Next task. Never skip review. Never batch reviews. Never proceed to next task without completing review of current task.

TodoWrite format (mandatory): For each task, add BOTH steps to todos before starting execution:

1. Execute [Task-ID]: [Title] — mark in_progress when starting executor
2. Review [Task-ID]: [Title] — mark in_progress after executor completes, completed after ln-402

Git branch management (mandatory): Before starting any task execution, ensure working in correct branch:

1. Get Story identifier from Linear (e.g., PROJ-42) and title
2. Generate branch name: feature/{identifier}-{story-title-slug}
   • story-title-slug: lowercase, spaces→dashes, remove special chars
3. Check current branch: git branch --show-current
4. If not matching:
   • Check if branch exists: git branch --list "feature/{identifier}-*"
   • If exists: git checkout feature/{identifier}-{slug}
   • If not: git checkout -b feature/{identifier}-{slug}
5. Confirm branch before proceeding to Phase 2

• Phase 5 Quality Delegation: Ensure all implementation tasks Done, then use Skill tool to invoke ln-500-story-quality-gate Pass 1. If it creates tasks (test/refactor/fix), return to Phase 4 to execute them. When test task is Done, set Story In Progress -> To Review and use Skill tool to invoke ln-500-story-quality-gate Pass 2. If Pass 2 fails and creates tasks, loop to Phase 4; if Pass 2 passes, Story goes To Review -> Done via ln-500.

Critical Rules

• Branch isolation: all Story work MUST happen in feature/{story-id}-{story-slug} branch. Never commit directly to main/master.
• Metadata first: never load task descriptions in Phase 2; only workers load full text.
• No pre-analysis: after Phase 2 counts, pick ONE task by priority (To Review > To Rework > Todo) and delegate immediately. Do not plan, analyze, or reason about other tasks until they become next in queue.
• Single-task operations: each worker handles only the passed task ID; ln-400 never bulk-updates tasks.
• Mandatory review after every task (ZERO COMPROMISE): After ln-401/ln-403/ln-404, task MUST go to ln-402 review IMMEDIATELY. No batching, no skipping, no "I'll review later". Execute → Review → Next. Only ln-402 may set Done. Stop and report if any worker leaves task Done or In Progress.
• Source of truth: trust Linear metadata (Linear Mode) OR task files (File Mode) for orchestration decisions. Kanban_board.md is for navigation only.
• Story status ownership: ln-400 moves Todo -> In Progress (first execution) and In Progress -> To Review (all tasks Done); ln-500 handles To Review -> Done.
• Independent review context: ln-402 runs as subagent with isolated context. Orchestrator passes ONLY task ID—reviewer loads all context independently from Linear. This ensures unbiased "fresh eyes" review without executor's assumptions.

Worker Invocation (MANDATORY)

CRITICAL: All worker delegations MUST use Skill tool. DO NOT execute tasks directly or do manual reviews.

Status	Worker to Invoke	How
To Review	ln-402-task-reviewer	Use Skill tool: ln-402-task-reviewer
To Rework	ln-403-task-rework	Use Skill tool: ln-403-task-rework
Todo (tests)	ln-404-test-executor	Use Skill tool: ln-404-test-executor
Todo (impl)	ln-401-task-executor	Use Skill tool: ln-401-task-executor
Quality Gate	ln-500-story-quality-gate	Use Skill tool: ln-500-story-quality-gate

❌ FORBIDDEN SHORTCUTS (Anti-Patterns):

• Running mypy/ruff/pytest directly instead of invoking ln-500/ln-501/ln-502
• Doing "minimal quality check" and asking "Want me to run the full skill?"
• Marking Quality Gate as "completed" in todo without actually invoking ln-500
• Any "self-service" execution that bypasses Skill tool invocation
• Partial workflow: "I ran linters, skipped manual testing" — NO, invoke full ln-500
• Skipping review: Executing multiple tasks before review — NO, every task gets reviewed IMMEDIATELY
• Batching reviews: "I'll review all tasks at the end" — NO, review after EACH task
• Self-review bypass: Marking task Done without ln-402 — NO, only ln-402 can set Done

✅ CORRECT BEHAVIOR:

• Use Skill(skill: "ln-500-story-quality-gate") — ALWAYS, NO EXCEPTIONS
• Wait for skill completion before proceeding
• Reload metadata after each skill invocation
• If skill creates tasks → return to Phase 4 loop

ZERO TOLERANCE: If you find yourself running commands (mypy, ruff, pytest) directly instead of invoking the appropriate skill, STOP immediately and use Skill tool instead.

Independent Context Pattern (Architecture Decision)

Review delegation uses isolated subagent context for quality:

Aspect	Implementation	Benefit
Data passed	Task ID only	No executor bias leaked
Context loading	ln-402 fetches from Linear	Fresh perspective
Assumptions	Reviewer has none	Catches implicit bugs
Timing	IMMEDIATELY after execution	No context drift, no forgotten issues

Analogy: External code reviewer who wasn't involved in implementation—sees only the result, not the "journey".

Why immediate review matters:

• Fresh context = accurate review (delay = context loss)
• One task at a time = focused quality check
• No batching = no "rubber stamp" reviews
• Independent subagent = unbiased assessment every time

Definition of Done

• Working in correct feature branch feature/{story-id}-{story-slug} (verified in Phase 1).
• Story metadata and task metadata loaded via list_issues (no get_issue in Phase 2); counts shown.
• Context Review (Phase 3) performed for each Todo task before execution (or skipped with justification for fresh tasks).
• Loop executed (Phase 4): all To Review via ln-402; all To Rework via ln-403 then immediate ln-402 on the same task; all Todo via ln-401/ln-404 then immediate ln-402 on the same task (validated To Review after each worker).
• If tasks were created by ln-500: executed through the loop.
• ln-500 Pass 1 invoked when impl tasks Done; Pass 2 invoked when test task Done or not needed. Result handled (pass/fail -> loop).
• Story status transitions applied (Todo -> In Progress -> To Review) and kanban updated by workers/ln-500.
• Final report with task counts and next step (if any).

Reference Files

• Quality orchestration: ../ln-500-story-quality-gate/SKILL.md
• Executors: ../ln-401-task-executor/SKILL.md, ../ln-403-task-rework/SKILL.md, ../ln-404-test-executor/SKILL.md, ../ln-402-task-reviewer/SKILL.md
• Auto-discovery: CLAUDE.md, docs/tasks/kanban_board.md

---

Version: 3.3.0 (Added Phase 3 Context Review to verify task plan against current codebase before execution) Last Updated: 2026-01-15