cy-create-tasks

name

cy-create-tasks

description

Decomposes PRDs and TechSpecs into robust, independently implementable task files, assigning every test case from _tests.md to exactly one task and enriching tasks from codebase exploration. Use when a PRD or TechSpec exists and needs to be broken down into executable tasks, or when task files need enrichment with implementation context. Do not use for PRD creation, TechSpec generation, or direct task execution.

Create Tasks

Decompose requirements into robust, independently implementable task files with codebase-informed enrichment.

Task Sizing

Every task becomes one full agent run: a fresh context that re-reads the spec corpus, re-explores the codebase, and rebuilds its model of the system from zero before the first edit. That ramp-up is the expensive part of a run — many small tasks pay it over and over and discard the accumulated reasoning at every boundary, while a robust task keeps it working.

• Default to fewer, larger tasks. A task is a complete vertical slice — implementation, wiring, and its assigned tests — delivered end-to-end in one run.
• Split only at real boundaries:
  • Dependency: a contract (schema, interface, protocol) must exist before its consumers can build on it.
  • Parallelization: two slices touch disjoint files and can run as parallel waves via _tasks.md edges.
  • Domain: different toolchains or deliverables (backend vs frontend vs SDK vs docs).
• File count is never a split reason: a task spanning 20+ files is healthy when they form one coherent slice, and one agent run handles it comfortably.
• A typical feature lands at 3-7 robust tasks. A breakdown with 10+ tasks almost always contains slices that belong together — merge them before presenting.

Required Inputs

• Feature name identifying the .compozy/tasks/<name>/ directory.
• At minimum, _prd.md or _techspec.md in that directory.
• When present: _tests.md (test contract) and _user_stories.md (story catalog).

Workflow

1. Choose the task taxonomy.

   • Prefer the standard work-type slugs: frontend, backend, docs, test, infra, refactor, chore, bugfix, qa-report, and qa-execution.
   • When the specification needs a distinct category, define one concise lowercase hyphenated slug in the proposed breakdown and use it consistently. Task type is free-form; ordered loops.defaults.delivery.runtime_rules[].match.type entries own type-based runtime routing.

2. Load context.

   • Read _prd.md, _techspec.md, _user_stories.md, and _tests.md from .compozy/tasks/<name>/.
   • Read existing ADRs from .compozy/tasks/<name>/adrs/ to understand the decision context behind requirements and design choices.
   • Resolve every local artifact path or glob cited as a contract, including repo-relative and absolute paths outside the task directory. Read textual contracts and use eng-ui-screenshot to render and inspect named visual artifacts; a path mention is an input, not optional background.
   • If _techspec.md is missing:
     • Warn the user that tasks will be higher-level without TechSpec implementation guidance.
     • Derive tasks from PRD functional requirements and the _user_stories.md catalog instead of TechSpec implementation sections.
     • During enrichment, rely more heavily on codebase exploration to fill ## Implementation Details, ### Relevant Files, and ### Dependent Files.
     • Mark <requirements> with PRD-derived behavioral requirements instead of TechSpec-derived technical requirements.
     • Explicitly call out missing implementation detail gaps in the task body instead of inventing specifics.
   • If both _prd.md and _techspec.md are missing, stop and ask the user to create at least one first.
   • Spawn an Agent tool call to explore the codebase for files to create or modify, test patterns, and coding conventions.

3. Break down into tasks.

   • Apply the Task Sizing doctrine above: slice the TechSpec's Build Order into the smallest number of robust tasks the real boundaries allow.

Error Handling

• If both _prd.md and _techspec.md are missing, stop and ask the user to create at least one first.
• If the user rejects the task breakdown, incorporate all feedback before presenting again.
• If codebase exploration reveals task boundaries that do not match the TechSpec, note the discrepancy and ask the user how to proceed.
• If a test case in _tests.md fits no task, the breakdown is missing a slice — fix the breakdown rather than dropping the case.
• If the target directory does not exist, create it.
• If a task file already exists and is fully enriched, skip it and move to the next.
• If a named visual reference is missing or cannot be rendered, stop before generating the affected task; do not downgrade it to prose guidance.