ln-220-story-coordinator

SKILL.md

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

Story Coordinator

Type: L2 Domain Coordinator
Category: 2XX Planning

Runtime-backed Story planning coordinator. The runtime owns flow control, pause/resume, and worker result tracking.

MANDATORY READ

Load these before execution:

references/coordinator_runtime_contract.md

references/story_planning_runtime_contract.md

references/coordinator_summary_contract.md

references/environment_state_contract.md

references/storage_mode_detection.md

references/problem_solving.md

MANDATORY READ: Load references/researchgraph_mcp_usage.md when the Epic, source docs, or existing Stories cite H/G/run IDs or when a researchgraph layout can change Story decomposition.

Purpose

assemble Epic planning context

perform focused standards research when it changes Technical Notes

build the ideal Story plan before checking existing Stories

detect routing and mode per epic group

batch child manifest/artifact preparation before delegation

delegate creation or replanning to standalone workers

Inputs

Parameter
Required
Description

epicId
Yes
Epic to decompose

autoApprove
No
If false, runtime pauses on preview confirmation

Runtime

Runtime family: story-planning-runtime

Identifier:

epic-{epicId}

Phases:

PHASE_0_CONFIG

PHASE_1_CONTEXT_ASSEMBLY

PHASE_2_RESEARCH

PHASE_3_PLAN

PHASE_4_ROUTING

PHASE_5_MODE_DETECTION

PHASE_6_DELEGATE

PHASE_7_FINALIZE

PHASE_8_SELF_CHECK

Terminal phases:

DONE

PAUSED

Summary flow:

consume child story-plan-worker artifacts from ln-221 / ln-222

write coordinator story-plan artifact during PHASE_7_FINALIZE

Phase Map

Phase 1: Context Assembly

Resolve Epic and assemble only the planning inputs that change Story decomposition:

Epic scope

success criteria

known personas and constraints

project task provider

Checkpoint payload:

context_ready

Phase 2: Research

Do focused research only when it changes Story Technical Notes or implementation constraints.

Do not let research expand Story scope.

If a researchgraph layout exists, use verify_index first and then query only the relevant goals, hypotheses, evidence, or runs. Use graph results to ground Story scope, readiness, and Technical Notes; do not create new Story scope just because graph debt exists.

Checkpoint payload:

research_status

research_file

Phase 3: Plan

Build the ideal Story plan before looking at existing Stories.

Rules:

vertical slices only

5-10 Stories when Epic warrants it

concise Story statements and observable ACs

no orchestration prose inside the plan

delegate ACs must specify what equips the actor (context, instructions, tools, configuration), not just what the actor does

Checkpoint payload:

ideal_plan_summary

Phase 4: Routing

Route planned Stories to epic groups.

Fast path:

all Stories stay in the resolved Epic

Pause only when routing is ambiguous or requires confirmation.

Checkpoint payload:

routing_summary

Phase 5: Mode Detection

Determine mode per epic group:

CREATE

REPLAN

ADD

Checkpoint payload:

epic_group_modes

Phase 6: Delegate

Phase 6 has two internal steps.

Phase 6a: Prepare delegation

finalize routing groups

materialize worker manifests

precompute run_id and summary_artifact_path for each child

checkpoint the expected worker set before execution

Phase 6b: Execute delegation

Delegate by group:

ln-221-story-creator

ln-222-story-replanner

Workers remain standalone-capable. In managed mode the coordinator starts them through planning-worker-runtime, passes runId + summaryArtifactPath, stores the launch metadata in child_run, then records the resulting worker artifact through record-epic.

Worker summary kind:

story-plan-worker

Phase 7: Finalize

Finalize only after all expected worker summaries are recorded.

Coordinator output:

build one story-plan summary for the parent runtime

write it through node references/scripts/story-planning-runtime/cli.mjs record-plan-summary

persist the artifact before advancing to PHASE_8_SELF_CHECK

Template compliance gate: Fetch each created Story via the configured tracker provider (getStory operation per references/tracker_provider_contract.md). Run validateTemplateCompliance(description, 'story') from planning-runtime/lib/template-compliance.mjs. All stories must pass (9 sections in order). Record template_compliance_passed in state. Guard blocks SELF_CHECK without it.

Checkpoint payload:

final_result

template_compliance_passed

Phase 8: Self-Check

Confirm:

phase coverage

planned vs produced Story counts

no missing epic groups

Checkpoint payload:

pass

final_result

Pending Decisions

Use runtime PAUSED + pending_decision for:

missing context

routing confirmation

ambiguous ADD vs REPLAN

preview confirmation when autoApprove=false

Do not hold these decisions only in chat.

Worker Contract

Workers:

do not know the coordinator

do not read runtime state

remain standalone

may receive summaryArtifactPath

return shared summary envelope either way

Expected summary kind:

child workers: story-plan-worker

coordinator output: story-plan

Worker Invocation (MANDATORY)

Host Skill Invocation: Skill(skill: "...", args: "...") is mandatory delegation.

Claude: call the Skill tool exactly as shown.

Codex: if no Skill tool exists, locate the named skill in available skills, read its SKILL.md, treat args as $ARGUMENTS, execute that skill workflow, then return here with its result/artifact.

Do not inline worker logic or mark the worker complete without executing the target skill.

Phase
Worker
Context

6
ln-221-story-creator
CREATE or ADD path

6
ln-222-story-replanner
REPLAN path

node references/scripts/planning-worker-runtime/cli.mjs start --skill {worker} --identifier {identifier} --manifest-file {workerManifestPath} --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}
child_run = { skill, run_id, identifier, summary_artifact_path }
childSummaryArtifactPath = .hex-skills/runtime-artifacts/runs/{parent_run_id}/story-plan-worker/{worker}--{identifier}.json
Skill(skill: "{worker}", args: "{identifier} --ideal-plan {idealPlanJSON} --epic {epicId} --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")
Read {childSummaryArtifactPath}
node references/scripts/story-planning-runtime/cli.mjs record-epic --epic {epicId} --payload-file {childSummaryArtifactPath}
node references/scripts/story-planning-runtime/cli.mjs record-plan-summary --epic {epicId} --payload-file {coordinatorSummaryPath}

TodoWrite format (mandatory)

- Phase 1: Assemble context (pending)
- Phase 2: Research only what changes Technical Notes (pending)
- Phase 3: Build ideal Story plan (pending)
- Phase 4: Route Stories by Epic (pending)
- Phase 5: Detect mode per group (pending)
- Phase 6a: Prepare delegation batch (pending)
- Phase 6b: Execute worker(s) sequentially (pending)
- Phase 7: Finalize result (pending)
- Phase 8: Self-check (pending)

Critical Rules

Build the ideal plan before checking existing Stories.

Use research only to improve Technical Notes and implementation realism.

Do not keep routing or preview approvals in chat-only state.

Batch only read-only preparation. Do not parallelize Story mutations across routed groups unless runtime semantics explicitly allow it.

Do not create or update Stories directly when a worker should do it.

Consume worker summaries, not free-text worker prose.

Definition of Done

 Runtime started with Epic-scoped identifier

 Context assembly checkpointed

 Research checkpointed or explicitly minimal

 Ideal plan checkpointed

 Routing checkpointed

 Mode detection checkpointed

 All expected worker summaries recorded

 Coordinator story-plan summary recorded

 Final result checkpointed

 Template compliance passed for all created Stories

 Self-check passed

Meta-Analysis

Optional reference: load references/meta_analysis_protocol.md only when the user asks for post-run meta-analysis or protocol-formatted run reflection.

Skill type: planning-coordinator. When requested, run after all phases complete. Output to chat using the protocol format.

Reference Files

references/environment_state_contract.md

references/storage_mode_detection.md

references/replan_algorithm.md

Version: 5.0.0
Last Updated: 2026-02-03