Ln 300 Task Coordinator

> **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.
7. Read only the final `task-plan` artifact and record it through runtime `record-plan`.

Coordinator context to pass to workers:

- `idealPlan`: the full ideal plan from Phase 2
- `traceabilityTablePath`: path to materialized traceability table
- `discoveryContext`: Phase 1 findings
- In ADD mode: specify which tasks to create

### Phase 6: Verify

Verify the worker result and the resulting task set only. Do not reopen decomposition unless verification proves the worker output is invalid.

**Template compliance gate:** Fetch each created Task via the configured tracker provider (`getTask` operation per `references/tracker_provider_contract.md`). Run `validateTemplateCompliance(description, 'task')` from `planning-runtime/lib/template-compliance.mjs`. All tasks must pass (7 sections in order). Record `template_compliance_passed` in state. Guard blocks SELF_CHECK without it.

Checkpoint payload:
- `verification_summary`
- `final_result`
- `template_compliance_passed`

After verification succeeds, write a Stage 0 coordinator artifact with:
- `stage=0`
- `story_id`
- `status=completed`
- `final_result`
- `story_status`
- `readiness_score`
- `warnings`

### Phase 7: Self-Check

Confirm:
- phase coverage
- readiness gate was respected
- worker result was recorded
- verification completed
- Stage 0 coordinator artifact was recorded

Checkpoint payload:
- `pass`
- `final_result`

## Pending Decisions

Use runtime `PAUSED + pending_decision` for:
- ambiguous `ADD` vs `REPLAN`
- readiness approval for score `4-5`
- missing critical Story context

## Worker Contract

Workers:
- do not know the coordinator
- do not read runtime state
- remain standalone
- managed runs require both `runId` and `summaryArtifactPath`
- return the shared `task-plan` summary envelope and write the artifact before terminal outcome

Expected summary kind:
- `task-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 |
|-------|--------|---------|
| 5 | `ln-301-task-creator` | CREATE or ADD path |
| 5 | `ln-302-task-replanner` | REPLAN path |

```text
node references/scripts/task-plan-worker-runtime/cli.mjs start --skill {worker} --story {storyId} --manifest-file .hex-skills/task-planning/{worker}--{storyId}_manifest.json --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}
node references/scripts/task-planning-runtime/cli.mjs checkpoint --story {storyId} --phase PHASE_5_DELEGATE --payload '{"child_run":{"worker":"{worker}","run_id":"{childRunId}","summary_artifact_path":"{childSummaryArtifactPath}"}}'
Skill(skill: "{worker}", args: "{storyId} --ideal-plan {idealPlanJSON} --traceability {tablePath} --discovery {discoveryJSON} --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")
Read {childSummaryArtifactPath}
node references/scripts/task-planning-runtime/cli.mjs record-plan --story {storyId} --payload '{...task-plan summary...}'
```

## TodoWrite format (mandatory)

```text
- Phase 1: Discover Story context (pending)
- Phase 2: Build ideal task plan (pending)
- Phase 3: Run readiness gate (local score first, external validation only if triggered) (pending)
- Phase 4: Detect mode (pending)
- Phase 5: Start child runtime, checkpoint child metadata, and perform the single worker handoff (pending)
- Phase 6: Verify worker result (pending)
- Phase 7: Self-check (pending)
```

## Critical Rules

- Build the ideal plan before looking at existing tasks.
- Readiness gate is the only source of delegation readiness.
- Do not create test or refactoring tasks in this skill.
- Do not keep approval state in chat-only form.
- Consume worker summaries, not free-text worker prose.
- If Story affects existing code and hex-graph is available, do one graph discovery pass before decomposition.
- Use graph output to reduce planning ambiguity; do not invent affected components when symbol or module evidence is available.

## Definition of Done

- [ ] Runtime started with Story-scoped identifier
- [ ] Discovery checkpointed
- [ ] Ideal plan checkpointed
- [ ] Readiness gate checkpointed
- [ ] Mode detection checkpointed
- [ ] Child task-plan runtime started with deterministic `runId`
- [ ] Child run metadata checkpointed before delegation
- [ ] Task-plan worker summary recorded
- [ ] Verification checkpointed
- [ ] Template compliance passed for all created Tasks
- [ ] Final result recorded
- [ ] 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.

---
**Version:** 4.0.0
**Last Updated:** 2026-02-03