moonspec-tasks

name	moonspec-tasks
description	Generate a one-story, TDD-first MoonSpec `tasks.md` from `spec.md`, `plan.md`, and design artifacts. Use when the user asks to run or reproduce `/moonspec.tasks`, create or update an executable task breakdown, map one MoonSpec story to implementation tasks, require unit and integration tests before code, preserve source-design traceability, or include final `/moonspec.verify` work.
metadata	{"required-capabilities":["git"]}

MoonSpec Tasks

Use this skill to generate an executable tasks.md for one MoonSpec story.

Scope

Generate task artifacts only. Do not implement application code, run the implementation, create issues, or split broad designs. Use moonspec-breakdown for broad technical or declarative designs, moonspec-specify for creating a one-story spec, and moonspec-plan for planning artifacts.

The generated task list must:

• Cover exactly one independently testable story from spec.md.
• Follow TDD by default.
• Include unit tests and integration tests before production implementation.
• Include red-first confirmation tasks.
• Preserve traceability to the original request or source design preserved in spec.md.
• Carry forward docs-native packet provenance from spec.md: source document path, document class, viewpoint, owning surface, stable claim IDs, temporary-adapter role, and source issue traceability such as MM-933 / MM-927.
• Include final /moonspec.verify work after implementation and tests pass.
• Include a final doc-reconciliation task (moonspec-doc-reconcile) after /moonspec.verify when spec.md records a canonical source document under docs/.

tasks.md is an imperative, temporary execution artifact (see docs/Workflows/MoonSpecDocumentModel.md). Never copy its content into canonical docs/ files.

Inputs

• Treat the user's text as optional task-generation guidance.
• Work from the active feature directory resolved by the prerequisite script.
• Require spec.md and plan.md.
• Use templates/tasks-template.md as the output structure.
• Use absolute paths in reports.

Stop if spec.md is missing, plan.md is missing, or the spec contains more than one user story. Tell the user to run /moonspec.breakdown for broad designs or /moonspec.specify for a one-story replacement.

Pre-Tasks Hooks

Before generating tasks, check for extension hooks:

1. If .specify/extensions.yml exists, read it and look for hooks.before_tasks.
2. If the YAML cannot be parsed or is invalid, skip hook checking silently.
3. Ignore hooks where enabled is explicitly false; hooks without enabled are enabled.
4. Do not evaluate non-empty condition expressions. Treat hooks with no condition, null condition, or empty condition as executable. Skip hooks with non-empty conditions.
5. For each executable hook:
   • Optional hook (optional: true): print:

## Extension Hooks

**Optional Pre-Hook**: {extension}
Command: `/{command}`
Description: {description}

Prompt: {prompt}
To execute: `/{command}`

• Mandatory hook (optional: false): print:

## Extension Hooks

**Automatic Pre-Hook**: {extension}
Executing: `/{command}`
EXECUTE_COMMAND: {command}

Wait for the result of the hook command before proceeding to task generation.

If no hooks are registered or .specify/extensions.yml does not exist, skip silently.

Setup

Run the prerequisite script from the repository root:

.specify/scripts/bash/check-prerequisites.sh --json

Parse FEATURE_DIR and AVAILABLE_DOCS, then derive:

• SPEC = FEATURE_DIR/spec.md
• PLAN = FEATURE_DIR/plan.md
• TASKS = FEATURE_DIR/tasks.md
• optional docs from AVAILABLE_DOCS
• REPO_GUIDANCE = AGENTS.md when present

If shell arguments contain single quotes, use shell-safe escaping such as 'I'\''m Groot', or double quotes when possible.

Load Context

Read:

• plan.md: tech stack, libraries, project structure, unit test tooling, integration test tooling, constraints, validation commands, and any ## Requirement Status table.
• spec.md: preserved **Input**, ## Source Packet, single user story, goal, independent test, acceptance scenarios, edge cases, functional requirements, success criteria, assumptions, and source design mappings such as CLAIM-*, DESIGN-REQ-* or DOC-REQ-*.
• AGENTS.md when present: project principles, repo constraints, and test discipline.
• data-model.md when present: entities, relationships, validation rules, and state transitions.
• contracts/ when present: public interfaces and contract or integration test obligations.
• research.md when present: technical decisions that affect setup or implementation tasks.
• quickstart.md when present: validation commands and end-to-end scenarios.
• specs/breakdown.md when present: source design coverage and cross-spec dependency context.

Source Acceptance Coverage

When artifacts/moonspec/acceptance-assessment.json exists and its featureId matches the active feature, every missing, partial, conflict, or required-unverified row must map to tests and implementation or verification tasks. Each negative constraint row must be preserved as a test, verification task, or explicit non-repo-verifiable exclusion.

Build a traceability inventory before writing tasks:

• One row per FR-*.
• One row per acceptance scenario or SCN-*.
• One row per meaningful edge case.
• One row per measurable success criterion or SC-*.
• One row per in-scope stable source claim ID from ## Source Packet, such as CLAIM-*, DESIGN-REQ-* or DOC-REQ-*.
• One row per relevant AGENTS.md principle, repo constraint, or testing-discipline requirement that affects implementation or testing.

For each row, carry forward the matching ## Requirement Status entry from plan.md when present. Allowed statuses are missing, partial, implemented_unverified, and implemented_verified; if a row has no status, treat it as missing.

Status handling:

• missing: generate failing unit and/or integration test tasks, red-first confirmation tasks, and implementation tasks.
• partial: generate failing tests for the missing behavior, red-first confirmation tasks, and implementation tasks that complete the requirement.
• implemented_unverified: generate verification tests first, red-first confirmation tasks when the expected behavior is not already covered, and explicit fallback implementation tasks to run if verification fails.
• implemented_verified: do not generate new implementation tasks by default, but preserve traceability and include final validation so the existing evidence remains checked.

Each inventory row needs task coverage appropriate to its status and either unit or integration test coverage unless it is implemented_verified with strong existing evidence. Acceptance scenarios, external boundaries, workflows, persistence, contracts, CLI/API/UI behavior, and service interactions require integration test coverage unless the spec clearly makes integration irrelevant or the row is already implemented_verified by existing integration evidence.

Generate tasks.md

Create or replace FEATURE_DIR/tasks.md using templates/tasks-template.md. Preserve the template's structure, but replace all sample tasks with concrete tasks for the current story.

Fill:

• Feature name.
• Input paths.
• Prerequisites.
• Unit test command.
• Integration test command.
• Source traceability summary.
• Source packet summary: source document path, viewpoint, owning surface, stable claim IDs, temporary-adapter role, and source issue traceability when present.
• Story summary.
• Independent test.
• Story traceability IDs.
• Unit test plan.
• Integration test plan.
• Task phases.
• Dependencies and execution order.
• Parallel examples.
• Implementation strategy.

When plan.md includes ## Requirement Status, reflect those statuses in the source traceability summary and implementation strategy. The task list must distinguish code-and-test work, verification-only work, contingency implementation work, and already-verified rows.

The output must be immediately executable by an LLM without extra context.

Task Format

Every generated task must use this exact checklist shape:

- [ ] [TaskID] [P?] Description with file path

Rules:

• Start every task with - [ ].
• Use sequential task IDs: T001, T002, T003, and so on.
• Use [P] only for tasks that can run in parallel because they touch different files and do not depend on incomplete tasks.
• Include exact file paths.
• Include requirement, scenario, or stable source claim IDs when the task implements or validates behavior.
• Every task must map to stable claim IDs from ## Source Packet, DESIGN-REQ-*, or DOC-REQ-*, or state No source claim applies: <reason> in the task description.
• Do not include story labels such as [US1]; this task list covers one story.

Good examples:

- [ ] T001 Create project structure in src/ and tests/ per implementation plan
- [ ] T012 [P] Add failing unit test for validation FR-001 in tests/unit/test_user.py
- [ ] T013 [P] Add failing integration test for signup scenario SCN-001 in tests/integration/test_signup.py
- [ ] T014 Implement UserService for FR-001 in src/services/user_service.py

Bad examples:

- [ ] Create User model
T001 Create model
- [ ] [US1] Create User model
- [ ] T010 Write tests later if needed

Task Organization

Generate these phases.

Phase 1: Setup

Include project initialization and tool configuration:

• Shared project structure.
• Dependency or package configuration.
• Linting and formatting.
• Unit test tooling.
• Integration test tooling.

Phase 2: Foundational

Include only blocking prerequisites for the story:

• Shared infrastructure the story truly depends on.
• Base schema, migrations, fixtures, or seed data.
• Authentication, routing, middleware, configuration, logging, or error handling when required.
• Integration-only runtime dependencies such as Docker, service containers, external emulators, test fixtures, or contract harnesses.

No story implementation work can begin until this phase is complete.

Phase 3: Story

Create exactly one story phase. Include:

• Story summary.
• Independent test.
• Traceability IDs.
• Unit test plan.
• Integration test plan.
• Unit test tasks.
• Integration test tasks.
• Red-first confirmation tasks.
• Implementation tasks.
• Story validation task.

Order story work as:

1. Unit tests.
2. Integration tests.
3. Red-first confirmation.
4. Fallback implementation tasks for implemented_unverified rows, explicitly conditional on verification failure.
5. Models or entities.
6. Services or domain logic.
7. Endpoints, UI, CLI, public API, or contracts.
8. Integration wiring.
9. Story validation.

Unit and integration tests must be written and confirmed failing before implementation tasks for missing and partial rows. For implemented_unverified rows, verification tests should be run before fallback implementation tasks; if they pass, the fallback implementation tasks are skipped and final verification preserves traceability.

Final Phase: Polish And Verification

Include only work that strengthens the completed story without adding hidden scope:

• Refactoring.
• Documentation.
• Performance tuning.
• Security hardening.
• Additional edge-case coverage.
• Additional operational integration coverage.
• Quickstart validation.
• A final task to run /moonspec.verify after implementation and tests pass.

Coverage Rules

• Each FR-* with status missing or partial must map to at least one implementation task and at least one unit or integration test task.
• Each FR-* with status implemented_unverified must map to at least one verification test task and one conditional fallback implementation task.
• Each FR-* with status implemented_verified must map to existing evidence and a final validation task; do not add implementation work unless the user asks for stronger coverage.
• Each acceptance scenario must map to at least one integration test task unless it is implemented_verified by existing integration evidence.
• Each source design workflow or public boundary must map to at least one integration test task unless it is implemented_verified by existing integration evidence.
• Each source design rule, invariant, edge case, or failure mode must map to at least one unit test task where applicable unless it is implemented_verified by existing unit or integration evidence.
• Each explicit non-goal or constraint must map to a guardrail test, validation task, or documented scope check when it affects implementation.
• Each contract must map to a contract or integration test before implementation.
• Each task that validates behavior must name the file path and requirement/scenario/source IDs.
• Each implementation task must name stable claim IDs from ## Source Packet, DESIGN-REQ-*, or DOC-REQ-*, or state No source claim applies: <reason>.

Do not generate tasks for future stories, broad refactors, speculative infrastructure, or implementation layers that are not needed by the single story.

Parallelization Rules

Mark a task [P] only when:

• It touches different files from other parallel tasks.
• It has no dependency on incomplete work.
• Its output is not required by another task in the same parallel group.

Safe parallel candidates often include:

• Independent setup config files.
• Different unit test files.
• Different integration test files.
• Independent models.
• Independent documentation or polish tasks.

Do not mark tasks [P] when they modify the same file, share generated artifacts, require ordered red-first confirmation, or depend on a common uncompleted fixture.

Validation

Before reporting, verify:

• tasks.md exists in FEATURE_DIR.
• Every task follows - [ ] T### [P?] Description with file path.
• Task IDs are sequential.
• Exactly one story phase exists.
• No P1/P2/P3 or multi-story phases exist.
• Unit test tasks precede implementation tasks.
• Integration test tasks precede implementation tasks.
• Red-first confirmation tasks exist before production code tasks.
• Every traceability inventory row has task coverage.
• Every task maps to stable claim IDs or explicitly explains why none apply.
• ## Requirement Status rows from plan.md, when present, are reflected without forcing unnecessary implementation tasks for implemented_verified rows.
• implemented_unverified rows include fallback implementation tasks that are conditional on verification failure.
• Final /moonspec.verify task exists.
• Final moonspec-doc-reconcile task exists after /moonspec.verify when spec.md records a canonical source document under docs/.

If validation fails, update tasks.md and validate again before reporting.

Report

Report:

• tasks.md path.
• Total task count.
• Task count per phase.
• Parallel opportunities.
• Independent test criteria.
• Source design or original request coverage summary.
• Source packet provenance summary: source document path, viewpoint, owning surface, stable claim IDs, temporary-adapter role, and source issue traceability.
• Requirement status coverage summary, including code-and-test, verification-only, conditional fallback, and already-verified counts when plan.md provides statuses.
• Required unit and integration test coverage.
• Unit and integration test tooling.
• Final verification task status.
• Confirmation that the task list covers exactly one story.
• Format validation result.

Post-Tasks Hooks

After reporting, check .specify/extensions.yml for hooks.after_tasks using the same parsing, filtering, and condition rules as pre-tasks hooks. For each executable hook:

• Optional hook (optional: true): print:

## Extension Hooks

**Optional Hook**: {extension}
Command: `/{command}`
Description: {description}

Prompt: {prompt}
To execute: `/{command}`

• Mandatory hook (optional: false): print:

## Extension Hooks

**Automatic Hook**: {extension}
Executing: `/{command}`
EXECUTE_COMMAND: {command}

If no hooks are registered or .specify/extensions.yml does not exist, skip silently.

Key Rules

• Generate tasks for one story only.
• Keep TDD as the default strategy.
• Unit tests and integration tests are required.
• Red-first confirmation tasks are required before production code.
• Preserve traceability to spec.md **Input** and source design mappings.
• Preserve docs-native packet provenance from spec.md without treating generated artifacts as authoritative.
• Consume plan.md ## Requirement Status when present so tasks match planned code, verification-only, conditional fallback, or already-verified work.
• Use concrete file paths and requirement/scenario/stable claim IDs, or explain why no source claim applies.
• Include final /moonspec.verify.
• Do not implement code from this skill.