name: cy-create-tasks description: Decomposes Specs 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 spec exists and needs to be broken down into executable tasks, or when task files need enrichment with implementation context. Do not use for spec creation 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, _spec.md in that directory.
• When present: _tests.md (test contract), _user_stories.md (story catalog), _dx.md (developer-experience contract), and _uiux.md (UI change map).

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 _spec.md, _user_stories.md, _dx.md, _uiux.md (when present), 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 _spec.md lacks a Technical part (Part II):
     • Warn the user that tasks will be higher-level without implementation guidance.
     • Derive tasks from Part I functional requirements and the _user_stories.md catalog instead of Part II implementation sections.
     • During enrichment, rely more heavily on codebase exploration to fill ## Implementation Details, ### Relevant Files, and ### Dependent Files.
     • Mark <requirements> with behavior-derived requirements instead of design-derived technical requirements.
     • Explicitly call out missing implementation detail gaps in the task body instead of inventing specifics.
   • If _spec.md is missing, stop and ask the user to create it first via cy-create-spec.
   • 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 spec's Build Order into the smallest number of robust tasks the real boundaries allow.
   • Each task MUST be independently implementable when all dependencies declared in _tasks.md graph edges are met. No task may require undeclared work from another task. If two tasks share a tight coupling, merge them — or extract the shared piece into a dependency task only when a real boundary separates it.
   • No circular dependencies. If task A depends on task B, task B must NOT depend on task A (directly or transitively).
   • Each task must have: title, type, complexity, and dependency relationships in the graph plan.
   • Complexity rates implementation risk, not size — and is never a reason to split:
     • low: contained change on well-trodden patterns, low regression risk.
     • medium: new interfaces or integration points, moderate coordination.
     • high: new subsystem, concurrency, or a broad integration surface.
     • critical: cross-cutting change with high regression risk, requires coordination with other tasks.
   • When a task directly implements or is constrained by a specific ADR, include the ADR reference in the task's "Related ADRs" section under Implementation Details.
   • Tests live inside the task that implements the behavior they verify; never create tasks dedicated solely to testing.
   • For every task that implements visible UI from a named visual reference, define an explicit Visual Contract: one row per reference state and required viewport, with the implementation target, fidelity, and source-authorized differences. Never use “all states,” “match the mock,” or “screenshot parity” as a substitute for enumerating rows.
   • Follow the structure defined in references/task-template.md and the metadata definitions in references/task-context-schema.md.

4. Assign the test contract.

   • Assign every UT-, IT-, and E2E- ID from _tests.md to exactly one task — the task that implements the behavior the case verifies. Integration and E2E cases go to the task that completes the flow they exercise.
   • Done when every ID in _tests.md appears in exactly one task's planned ## Tests section: no orphan IDs, no duplicates.
   • If _tests.md is missing: warn the user, then write concrete inline cases per task instead — each naming the exact input, condition, and expected result (e.g., "POST /job/done with unknown job ID returns 404"), never a vague "test the happy path".

5. Present the task breakdown for interactive approval.

   • Show every task with: title, type, complexity, a one-line scope summary, dependency chains, and assigned test-ID counts.
   • Wait for user feedback before proceeding; revise and present again until the user explicitly approves.

6. Generate task files.

   • Write _tasks.md as the canonical task graph manifest. It MUST start with this YAML frontmatter shape:

     ---
     schema_version: "compozy.tasks/v2"
     workflow: [feature-name]
     graph:
       nodes:
         - id: task_01
           file: task_01.md
       edges:
         - from: task_01
           to: task_02
     ---
     
     # [Feature Name] Task List
     

   • _tasks.md is the only place dependency relationships are stored. Each edge means from must finish before to can start.
   • Include every task in graph.nodes, using canonical sequential ids (task_01, task_02, ...) and matching files (task_01.md, task_02.md, ...).
   • Use edges: [] when there are no dependencies.
   • Write individual task files as task_01.md through task_N.md (the task_ prefix has no leading underscore).
   • Each file must start with YAML frontmatter containing only task-owned metadata: status, title, type, and complexity. Dependency information lives only in _tasks.md.
   • Task numbering must be sequential and consistent between _tasks.md and individual files.

7. Enrich each task file.

   • For each task file, check whether it already has ## Overview, ## Deliverables, and ## Tests sections, plus a complete ## Visual Contract when it implements visible UI from a named reference. Skip enrichment only when every required and conditional section is complete.
   • Map the task to Part I requirements, user stories, Part II guidance, the _dx.md/_uiux.md surface contracts, and its subset of the _spec.md File References index.
   • Spawn an Agent tool call to discover relevant files, dependent files, integration points, and project rules for this specific task.
   • Fill ALL template sections from references/task-template.md. Every task file MUST contain each of the following sections — omitting any is a failure:
     • ## Overview: what slice of the system the task delivers and why, in 2-3 sentences.
     • <critical> block: the standard critical reminders block from the template.
     • <requirements> block: specific, numbered technical requirements using MUST/SHOULD language.
     • ## Subtasks: checklist items describing WHAT, not HOW — one per coherent unit of work, typically 5-12 for a robust task.
     • ## Implementation Details: file paths to create or modify, integration points. Reference _spec.md Part II for patterns.
     • ### Relevant Files: discovered paths from codebase exploration with brief reasons.
     • ### Dependent Files: files that will be affected by this task with brief reasons.
     • ### External References: this task's vendored-source entries copied from _spec.md File References — same paths, never paraphrased; omit the subsection when the spec cites none.
     • ### Related ADRs: links to relevant ADRs if any exist, or omit the subsection if none apply.
     • ## Deliverables: concrete outputs, including every assigned test case implemented and passing.
     • ## Tests: the assigned test-case IDs grouped by level with the behavior they cover; full case definitions stay in _tests.md.
     • ## Success Criteria: measurable outcomes including "Every assigned test case implemented and passing".
   • When the task implements visible UI from a named visual reference, also include ## Visual Contract from the template. Its deliverables and success criteria MUST require the durable eng-ui-screenshot evidence bundle for every row; implementation-only captures are invalid evidence.
   • Reassess complexity based on exploration findings and update if changed.
   • Update the task file in place with enriched content.
   • If enrichment fails for one task, continue to the next and report all failures at the end.

8. Audit the resulting task package.

   • Audit the test assignment: every ID in _tests.md appears in exactly one task file's ## Tests section. Fix any orphan or duplicate and re-audit.
   • Audit visual references: every visible UI task that cites one has an explicit Visual Contract row for each required state/viewport, and each row names the durable evidence bundle. Fix vague or missing rows before finishing.

Error Handling

• If _spec.md is missing, stop and ask the user to create it first via cy-create-spec.
• If the user rejects the task breakdown, incorporate all feedback before presenting again.
• If codebase exploration reveals task boundaries that do not match the spec, 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.