--- name: Create Task description: "Use when: writing a task document for a developer subagent. Interviews the user to extract goal, scope, affected modules, definition of done, and required tests. Splits complex work into phases. Saves the result as a structured markdown task file ready to be handed to a developer subagent." model: claude-sonnet-4-6 tools: - Read - Write - Glob - Grep - Bash argument-hint: "Optional: brief description of the task (e.g. 'add hunger stat to animals'). You may also pass a custom ticker prefix (e.g. 'SE-1291 add hunger stat to animals') to override the auto-generated ticker. Omit entirely to start an interactive interview." --- # Create Task ## Purpose Produce a well-structured markdown task document that a developer subagent can execute without further clarification. The document must be precise enough that an agent can implement it correctly without asking follow-up questions. --- ## Workflow ### Step 1 — Gather Information If an argument was provided, parse it as follows: - If it begins with a token that looks like a custom ticker (e.g. `SE-1291`, `PROJ-42`, `FOO-7`) — extract and store that ticker for use in Step 5, then treat the remainder as the task description. - Otherwise treat the whole argument as the task description. Use the extracted description as starting context. Then ask the user for any missing information using targeted questions. Cover: 1. **Goal** — What should be different after this task is done? (one sentence) 2. **Working directory** — Which repository or workspace folder does this task operate in? If the workspace contains multiple repositories, identify the root path for each phase. If every phase uses the same root, one answer covers all phases. 3. **Scope** — Which modules, files, or subsystems are affected? 4. **Complexity** — Is this a single coherent change, or does it have multiple distinct stages that must happen in sequence? 5. **Tests** — What new tests should be written? What behaviour must they verify? 6. **Definition of done** — What observable outcomes confirm the task is complete? Do not ask for information that can be inferred from the codebase. Use `Glob`, `Grep`, and `Read` to look up relevant context before asking. --- ### Step 2 — Locate the Task Directory and Read Environment README Immediately after gathering the initial goal, determine where tasks are saved and read any environment-specific guidance before doing anything else. **Determine the save directory** by checking workspace root directories in this order: 1. `tasks/` — use if it exists 2. `notes/` — use if it exists 3. `var/` — use if it exists 4. `tmp/` — use if it exists 5. None found — create `tasks/` and use it **Then check for a README** in that directory (e.g. `tasks/README.md`). If it exists, read it in full. It may contain: - Naming conventions or ticker formats specific to this project - Required sections or fields beyond the defaults in this skill - Agent invocation patterns (e.g. which developer subagent to use) - Environment constraints (build system, test commands, CI requirements) - Example tasks or a project-specific template Incorporate any relevant guidance into all subsequent steps. If no README exists, continue silently. --- ### Step 3 — Determine Structure Always produce a main task file and at least one phase file, even for atomic changes. This keeps the structure consistent and makes it easy to add phases later. **One phase** if the task is a contained, atomic change (e.g. rename a field, add one config option, fix one bug). **Multiple phases** if the task involves: - Changes to more than two subsystems that must land in a specific order - A new feature that requires scaffolding before implementation - A refactor followed by feature work - Any step that would break the build if applied without a subsequent step Phases must be independently verifiable — each phase should leave the codebase in a working, test-passing state. Each phase should have a Definition of Done that can be verified by a test or observable behaviour. --- ### Step 4 — Draft the Task Documents Always produce: 1. A **main task file** — overview, affected modules, phase index, and definition of done. 2. A **separate phase file** for each phase (minimum one) — detailed steps, tests, and a link back to the main file. #### Main task file template ```markdown # ## Goal ## Background ## Affected Modules | Module / File | Change | |---------------|--------| | `path/to/file.ext` | | ## Phases - [Phase 1 — ](phase-1.md) - [Phase 2 — ](phase-2.md) ## Definition of Done - [ ] - [ ] - [ ] All pre-existing tests pass - [ ] No new compiler warnings or linter errors introduced ``` #### Phase file template ```markdown # — Phase : > Part of [](main.md) ## Working Directory `` ## Goal ## Steps 1. 2. 3. ... ## Tests to add - `` — verifies that . ## Definition of Done - [ ] - [ ] All pre-existing tests pass - [ ] No new compiler warnings or linter errors introduced ``` --- ### Step 5 — Choose a Task Name and Confirm Location Determine the ticker: - If a custom ticker was extracted in Step 1 (e.g. `SE-1291`), use it as-is. - Otherwise generate one (e.g. `T001`, `T002`, etc.) by counting existing task directories in the save directory: ```bash ls -d tasks/*/ 2>/dev/null | wc -l ``` Convert the task title to kebab case (e.g. "Add Water Surfaces" → "add-water-surfaces"). Directory and file naming convention: - Task directory: `-/` (e.g. `tasks/T004-fix-water-shader/`) - Main task file: `-/main.md` - Phase files: `-/phase-.md` All files live inside the task directory. Ask the user to confirm or override the chosen directory and file names before writing. --- ### Step 6 — Save and Confirm Write all files using the `Write` tool (main task file and one phase file per phase). Then show the user: - All file paths written - A one-sentence summary of the task - The phase breakdown with links to each phase file - The suggested invocation, pointing to the **phase file** for the first phase: ``` tasks/-/phase-1.md ``` Note the appropriate developer subagent to hand this to (detected from the project stack, or ask the user if unclear). --- ## Quality Checklist Before saving, verify the documents pass these checks: - [ ] Goal is one sentence and unambiguous - [ ] Every affected file or module is listed in the main task file - [ ] At least one phase file exists inside the task directory - [ ] Every phase file contains a back-link to `main.md` - [ ] Every phase file specifies a `## Working Directory` with an unambiguous path - [ ] The main task file lists links to all phase files using relative filenames - [ ] Every phase ends in a verifiable, working state - [ ] Every phase has at least one test described - [ ] Definition of done has at least one measurable criterion beyond "tests pass" - [ ] No step says "update as needed" or similarly vague language - [ ] No placeholder text remains If any check fails, revise the document before saving.