ln-300-task-coordinator

What this skill does

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

# Task Coordinator

**Type:** L2 Domain Coordinator
**Category:** 3XX Planning

Runtime-backed task planning coordinator. The runtime owns readiness gating, pause/resume, and worker result tracking.

**MANDATORY READ:** Load `references/coordinator_runtime_contract.md`, `references/task_planning_runtime_contract.md`, `references/coordinator_summary_contract.md`, and `references/task_plan_worker_runtime_contract.md`
**MANDATORY READ:** Load `references/environment_state_contract.md`, `references/storage_mode_detection.md`, `references/problem_solving.md`, and `references/creation_quality_checklist.md`
**MANDATORY READ:** Load `references/agent_delegation_pattern.md` when Phase 3 external validation is triggered
**MANDATORY READ:** Load `references/researchgraph_mcp_usage.md` when the Story references H/G/run IDs or implementation readiness depends on project hypotheses.
Tool policy: follow host AGENTS.md MCP preferences; load `references/mcp_tool_preferences.md` and `references/mcp_integration_patterns.md` only when host policy is absent or MCP behavior is unclear.

## Purpose

- resolve Story context once
- build an ideal implementation task plan before checking existing tasks
- run a deterministic readiness gate
- detect `CREATE`, `ADD`, or `REPLAN`
- delegate to standalone workers

## Inputs

| Parameter | Required | Description |
|-----------|----------|-------------|
| `storyId` | Yes | Story to plan |
| `autoApprove` | No | If false, runtime may pause for readiness approval |

## Runtime

Runtime family: `task-planning-runtime`

Identifier:
- `story-{storyId}`

Phases:
1. `PHASE_0_CONFIG`
2. `PHASE_1_DISCOVERY`
3. `PHASE_2_DECOMPOSE`
4. `PHASE_3_READINESS_GATE`
5. `PHASE_4_MODE_DETECTION`
6. `PHASE_5_DELEGATE`
7. `PHASE_6_VERIFY`
8. `PHASE_7_SELF_CHECK`

Terminal phases:
- `DONE`
- `PAUSED`

Coordinator stage artifact:
- write `summary_kind=pipeline-stage` after verification
- `ln-1000` consumes this artifact as the Stage 0 completion signal

## Phase Map

### Phase 1: Discovery

Resolve Story and collect only the inputs required for task planning:
- Story AC
- Technical Notes
- Context
- project architecture and tech stack
- task provider

Do NOT load existing tasks here. Existing tasks load in Phase 4 only.

- For Stories that modify existing code in supported languages, build graph context once:
  - `index_project(path=project_root)`
  - `analyze_architecture(path=project_root, verbosity="minimal")`
  - `find_symbols` + `inspect_symbol` for named components from Story AC or Technical Notes, but only after narrowing `path` where possible; if symbol discovery is truncated, refine to `name + file` or `workspace_qualified_name` before planning from it
- Use graph context to confirm real affected modules and entrypoints before decomposition
- For Stories that cite hypotheses, goals, or run evidence, run `verify_index` and then inspect only the referenced `H##`/`G##` IDs or proposed candidates.
- Use `hex-research` to confirm hypothesis implementation status, refinement gaps, and proposal readiness; keep `hex-graph` as the source for code symbol and module boundaries.

Checkpoint payload:
- `discovery_ready`

### Phase 2: Decompose

Build the ideal task plan from ACs only. Do not read or reference existing tasks.

Order of operations:

1. Build AC-to-Scenario traceability table with these columns: AC | Actor | (1) Trigger | (2) Entry Point | (3) Discovery | (4) Usage Context | (5) Outcome
2. Scan Entry Point, Discovery, and Usage Context cells for buildable artifacts
3. Group buildable artifacts by architectural layer using segment boundaries:
   - **Foundation:** the internal logic, data model, or service that does the work (what Entry Point calls into)
   - **Invocation:** the Entry Point itself — the named mechanism the actor uses
   - **Knowledge:** the Usage Context — what the actor needs to correctly invoke the mechanism
   - **Wiring:** Discovery + integration — how the system finds/loads the mechanism and connects components
4. Each layer group becomes at least one task. A single task MUST NOT span more than one layer unless trivially small.
5. When graph context exists, use it to:
   - split tasks by actual modules or symbol ownership, not guessed file groups
   - keep dependency order aligned with real callers, framework entrypoints, and public APIs
   - enrich Affected Components with real modules/symbols returned by graph analysis
6. Verify foundation-first ordering and 1-8 task count
7. Save the traceability table and layer grouping to `.hex-skills/task-planning/{identifier}_traceability.md`

Rules:
- implementation tasks only
- 1-8 tasks
- no tests or refactoring tasks here
- preserve foundation-first order
- assign meaningful verification intent
- infrastructure-only tasks do not satisfy ACs that require something to *use* that infrastructure
- an invocation-layer task does not satisfy ACs that require the actor to *know how* to use that mechanism — that is a knowledge-layer artifact
- see #17b, #17c, #17d in creation_quality_checklist.md

Checkpoint payload:
- `ideal_plan_summary`
- `traceability_table_path`

### Phase 3: Readiness Gate

Score the plan before delegation.

#### Step 1: Self-score

Scoring policy:
- `6-7` -> continue
- `4-5` -> `PAUSED` for approval or improvement
- `<4` -> blocked until plan is corrected

Self-check: verify each layer (Foundation, Invocation, Knowledge, Wiring) has at least one task when the traceability table contains buildable artifacts in the corresponding segments.

#### Step 2: Conditional external traceability validation

Run this step only when at least one trigger is true:
- readiness score is `4-5`
- mode looks ambiguous (`ADD` vs `REPLAN`)
- AC-to-task coverage is incomplete
- task boundaries or layer ownership still conflict after self-score

If triggered:
1. Run agent health check: `node references/agents/agent_runner.mjs --health-check --json`
2. If advisor agent available:
   a. Build validation prompt from `references/agents/prompt_templates/traceability_validator.md`
   b. Fill placeholders with Phase 1 discovery and Phase 2 output
   c. Save filled prompt to `.hex-skills/task-planning/{identifier}_traceability_prompt.md`
   d. Launch agent via agent_runner.mjs:

      ```bash
      node references/agents/agent_runner.mjs \
        --agent {advisor_agent} \
        --prompt-file .hex-skills/task-planning/{identifier}_traceability_prompt.md \
        --output-file .hex-skills/task-planning/{identifier}_traceability_result.json \
        --cwd {project_dir}
      ```

   e. Parse result JSON for gaps
   f. For each MISSING gap: readiness_score -= 1
   g. For each BUNDLED gap: readiness_score -= 0.5
   h. If MISSING gaps found: re-enter Phase 2. Max 1 re-decomposition.
3. If no agent available: log and keep the local score with degraded confidence.

If not triggered:
- set `traceability_validation = self_check_only`
- advance without external validation

Checkpoint payload:
- `readiness_score`
- `readiness_findings`
- `traceability_validation` — one of: `agent_validated`, `self_check_only`, `redecomposed`

### Phase 4: Mode Detection

Detect:
- `CREATE`
- `ADD`
- `REPLAN`

Pause when mode is ambiguous.

Checkpoint payload:
- `mode_detection`

### Phase 5: Delegate

Single mutation handoff. Delegate to exactly one worker:
- `ln-301-task-creator`
- `ln-302-task-replanner`

Managed delegation sequence:
1. Compute `childRunId = {parent_run_id}--{worker}--{storyId}`.
2. Compute `childSummaryArtifactPath = .hex-skills/runtime-artifacts/runs/{parent_run_id}/task-plan/{worker}--{storyId}.json`.
3. Materialize child manifest at `.hex-skills/task-planning/{worker}--{storyId}_manifest.json`.
4. Start `task-plan-worker-runtime` with both `--run-id` and `--summary-artifact-path`.
5. Checkpoint `child_run` metadata before invoking the worker.
6. Invoke the worker through Skill tool with both transport inputs.