/spec-write-tasks

name: spec-write-tasks
description: "Public workflow entrypoint (spec-write-tasks): compile a settled local spec-plan into an optional derived task pack for spec-work, or validate an existing local task pack before execution. Use for explicit plan-splitting/task-doc requests or high-complexity work suitability; do not use for plan authoring, implementation execution, unresolved scope, small low-risk plans, progress/approval state, remote/generic task lists, or generated runtime mirror edits. Keep the plan as single source of truth; tasks are derived and optional."

`spec-write-tasks`

`spec-write-tasks` is an optional derived layer between `spec-plan` and `spec-work`. It does not execute code. It either compiles a settled source plan into a derived task pack, validates an existing task pack, or returns a no-task-pack decision.

It is a public workflow with the unified entrypoint `spec-write-tasks`.

Purpose

Decide whether a derived task pack is worthwhile, compile one when it reduces execution risk or context load, and validate existing task packs before they reach `spec-work`.

Workflow Contract Summary

When To Use

Use when a settled local source plan is too large or dependent for direct execution, when the user explicitly asks to split a plan into tasks, or when an existing local task pack needs validation before `spec-work`.

When Not To Use

Do not use for unresolved product or architecture scope, small changes that do not need a derived layer, remote repositories or package names, marketplace skill lookup, or implementation prompts that should go directly to `spec-work`.

Inputs

A local source plan path, existing task-pack path, or clear task-splitting request that resolves to one local source plan. Inputs must stay local and source-owned; remote repos, packages, marketplace identifiers, and generic task lists are rejected.

Outputs

One of: executable derived task pack, validated existing task-pack handoff, `skip`, `return-to-plan`, `draft-only`, or `validate-only` envelope. Task packs are derived execution indexes and never replace the source plan.

Artifacts

Executable task packs live under `docs/tasks/` and must carry an artifact-root-relative POSIX `source_plan`, canonical `source_plan_hash`, `generated_by: spec-write-tasks`, `mode: derived`, and a valid `Task Pack Contract` JSON block. Executable identity is `source-plan-path+body-hash`; `spec_id` is an optional compatibility trace rather than a required identity field.

Failure Modes

Use machine-readable reason codes: `source_plan_missing`, `ambiguous_plan`, `wrong_chain`, `stale_hash`, `unverifiable_hash`, `invalid_contract`, `repo_scope_missing`, or `scope_gap`.

Workflow

Classify input, verify plan identity and repo scope, choose one branch (`compile`, `skip`, `return-to-plan`, `draft-only`, `validate-only`), use bounded source orientation only when it improves task boundaries, write or validate the task pack, then return the final decision envelope.

Downstream Consumers

`spec-work`, high-risk `spec-doc-review` handoff, human reviewers, and later code-review/compound workflows.

Scenario Capability

Follows `docs/contracts/workflows/scenario-capability-matrix.md` (default).

Overrides: none

Core Rules

1. `spec-plan` is always the single source of truth. 2. A task pack may rearrange execution slices, but must not change scope, acceptance criteria, non-goals, repo ownership, or product decisions. 3. A task pack is not progress state, approval state, a lifecycle database, or a second plan. 4. `context_refs` are bounded reading pointers, not scope authority. Whole-plan or whole-directory refs are low-quality unless paired with narrower anchors. 5. If parent-workspace scope is present, the plan or task pack must name `target_repo` at top level or per task. Missing repo scope returns to `spec-plan`. 6. Source orientation is advisory and bounded: source plan sections, plan-declared files, nearby tests, and precise local contracts only when they improve task boundaries. 7. Scripts validate identity, freshness, structure, hashes, concrete paths, and same-wave overlap. LLM/reviewers judge semantic task quality. 8. Do not hand-edit `.claude/`, `.codex/`, or `.agents/skills/` as source fixes. 9. `--repo <artifact-root>` selects the artifact/source resolution root only. It does not authorize or select the downstream mutation `target_repo`. 10. Compile executable tasks only from `status: active`. `completed`, `partially-shipped`, and `superseded` plans return `source_plan_non_active`; do not hash them into a new executable task pack or route them to `spec-work`. A legacy plan without managed status remains a visible `source-plan-lifecycle-unmanaged` limitation.

Input Paths

• Source plan path: read the source plan frontmatter and focused sections: Requirements, Scope Boundaries, Technical Approach, Implementation Units, Files, Test Scenarios, Verification, and Deferred to Implementation.
• Existing task-pack path: read the task pack, source plan, and `Task Pack Contract`; validate identity/freshness/structure before treating it as executable.
• Bare task-splitting request: resolve exactly one local source plan; if resolution is ambiguous, ask for the path.

Use [Task Quality Guide](references/task-quality-guide.md) for accepted/rejected input classes, task-ready source plan rules, source orientation, traceability, vertical slices, `context_refs`, `done_signal`, `stop_if`, and review-intent quality guidance.

Branches

• `compile`: plan is task-ready and a task pack reduces execution risk or context load.
• `skip`: direct `spec-work` is cheaper and safer than adding a derived layer.
• `return-to-plan`: scope, acceptance, architecture, verification, or repo ownership is unresolved.
• `draft-only`: a non-executable outline may help discussion but cannot be handed to `spec-work`.
• `validate-only`: an existing task pack is checked before execution.

Use [Execution Hando