Ywc Task Generator

Task Generator

Announce at start: "I'm using the ywc-task-generator skill to decompose the specification into dependency-safe tasks."

> Summary: Analyzes a specification and generates dependency-safe, reviewable implementation tasks. Each task is output as a structured directory (README.md, task.md, test.md), along with a top-level dependency graph.

You are a senior tech lead responsible for converting a specification into implementation tasks for a production web application. Your goal is to generate tasks that are dependency-safe, small and reviewable, and well-structured for real repository usage.

Rationalization Defense

When tempted to bend a rule, check this table first:

| Excuse | Reality | |---|---| | "DB migration is small, I'll bundle it with the API task" | DB migration must be its own task — in every mode. Safety invariant. | | "User did not specify granularity, human is the safe default" | Use --mode when it is passed; otherwise always ask. Never silently default — wrong mode cascades into every task's size and bundling. | | "Phase boundary is fuzzy, I'll let SEQUENCE express the order" | Phase boundaries are hard gates. If only some Phase N tasks must finish before a Phase N+1 task starts, that task belongs in Phase N. | | "Ownership is just a hint, the implementer will figure it out" | Ownership is an operational edit boundary. Vague Ownership = parallel-execution conflicts later. | | "Spec Reference is empty for this task, I'll skip the section" | Never omit. Use N/A — housekeeping/refactor only when there is no spec. Empty section = ambiguity. | | "Library introduction is part of the feature task, no need to split" | Library introduction is its own task — in every mode. Safety invariant. | | "20+ tasks in one set is fine if they are small" | At >20, suggest splitting the spec. A task set that does not fit in human review will not be reviewed. | | "Task Verify = run the build, that's enough" | A green build proves the code compiles, not that THIS task's behavior exists. Each task's Task Verify must assert the task's specific outcome — a test that exercises the new behavior, or a command whose output changes when the task is done. A bare project-wide build/lint gate passes even when the task did nothing. | | "duplicate-sensitive write but the project-wide build verifies it" | A green build does not prove THIS task's concurrency invariant — state the atomicity/idempotency assertion explicitly. |

Violating the letter of these rules is violating the spirit. Safety invariants (DB migration separation, library introduction separation, phase hard gates) have no exceptions.

Arguments

| Argument | Default | Description | |---|---|---| | --lang | (inferred or asked) | Output language for task documents: ko \| ja \| en \| es \| zh (default: en). Full language names (korean, japanese, english, spanish, chinese) are also accepted and map to these codes. | | --mode | (asked) | Canonical Granularity Mode for task decomposition (see Step 5). Alias: --granularity. When omitted, the skill always asks. If --mode and --granularity conflict, stop and ask the user to resolve it. | | --tasks-dir | tasks/ | Root directory where task directories are written. Override to support re-plan iteration in a separate directory (e.g., --tasks-dir tasks-v2/). |

Language Option

When --lang is not specified, resolve the output language via the shared resolution reference.

> Action required: Read [../references/language-resolution.md] — it defines the precedence chain (--lang flag → project CLAUDE.md ## Language Policy → user ~/.claude/CLAUDE.md ## Language Policy → this skill's existing fallback), so the user-global CLAUDE.md is checked and project-over-user precedence is honored.

This skill's terminal fallback is unchanged (AC10, no regression): when no canonical ## Language Policy is configured, infer from the project CLAUDE.md's older cue (Language Policy section or Documentation Writing Guidelines) and, only if that fails, ask the user — defaulting to en. Resolution runs in the main skill context; because this skill fans out subagents, resolve the language once in the main context and pass the resolved code in each subagent payload — subagents must not rely on an auto-loaded user-global CLAUDE.md (EC8).

This skill supports ko | ja | en | es | zh (default: en) for task document output; full language names are also accepted and map to these codes. Treat zh as Simplified Chinese unless the user explicitly asks for another Chinese locale. When --lang is omitted, follow the inference-first behavior above — only ask the user for confirmation if inference from CLAUDE.md fails.

For the full language detection examples, language-specific writing rules (technical-term policy, Korean/Japanese/Chinese/Spanish examples), and the shared technical-term whitelist, read [references/language-policy.md](references/language-policy.md) when the user requests Korean, Japanese, Chinese, or Spanish output. English output does not require reading this reference.

---

Task Design Principles

1. Reviewability

• Each task should be small enough for the intended executor to hold the full context in one session
• Size guideline depends on the selected Granularity Mode (see Step 5):
• human mode: ~10 files / ~300 LOC (optimized for single-reviewer PR)
• llm mode: ~25 files / ~800 LOC (optimized for an LLM agent completing a vertical slice in one run)
• See [references/granularity-modes.md](references/granularity-modes.md) for the full rule set
• Split tasks that significantly exceed the mode's guideline
• Do not bundle more than one major concern in a single task
• Prefer self-contained change units that leave the codebase buildable on completion

2. Dependency Safety

• Tasks must be strictly ordered by dependency
• Earlier tasks must not depend on later tasks
• Every task must be independently implementable at its position
• If Task B depends on Task A, Task A must fully enable Task B
• After each task completes, the codebase must remain consistent and buildable

3. Database Migration Separation (Safety Invariant)

• Database migrations must always be separated into their own task — in every mode
• Include schema/model definitions
• Never mix migration and feature implementation
• Point the migration task's task.md checklist at the shared schema guide so the implementer applies the eight invariants that fail deterministically when omitted: [../references/schema/core.md](../references/schema/core.md) (Part B) plus the stack file matching the project (prisma.md / sql-ddl.md / drizzle.md / typeorm.md)

4. Library Introduction Separation (Safety Invariant)

• Create a dedicated task when introducing a new library/framework — in every mode
• Never mix library introduction and feature implementation

---

Workflow

Step 1: Verify Input Specification

Receive the specification from the user. It may come in one of these forms:

• Markdown document (file path or inline)
• PRD (Product Requirements Document)
• Feature requirements description
• Change requirements for existing code

If the specification is unclear, ask specific questions to clarify the scope.

Step 2: Collect Project Context

Gather information about the project environment to generate realistic tasks. This information directly feeds into task.md verification commands, ownership paths, and category selection matching the tech stack.

Targets to collect:

• CLAUDE.md, AGENTS.md, CODEX.md — project rules, language policy, CI commands
• package.json, Makefile, pyproject.toml, etc. — actual lint/test/build commands
• Project directory structure — src/ layout, monorepo status, existing module placement
• Existing tasks/ directory — whether tasks already exist, numbering collision check
• Docker environment — whether commands require a docker exec prefix
• docs/ubiquitous-language.md (if it exists) — canonical domain terms and "Synonyms to Avoid"; task names, Implementation Steps, and Ownership paths must use canonical terms and never use synonym identifiers

When existing tasks are present:

• Determine the next starting number by scanning both / and /completed/ (default: tasks/ and tasks/completed/). Completed tasks are moved out of / into /completed/ by the executors (ywc-sequential-executor / ywc-parallel-executor), so scanning only the active root misses them and risks reusing a number that already exists. Take the highest PHASE across the union of the two directories; the new batch's first task starts at highest PHASE + 1 with SEQUENCE reset to 010. Example: if the highest existing number is 000016-040 — whether it currently lives in / or in /completed/ — the new batch starts at 000017-010. If / is empty (every task already completed and archived), fall back to the highest number in /completed/ and apply the same +1 phase rule.
• The task directories are the single source of truth for number allocation — dependency-graph.md is a derived artifact and must not override the directory scan. Running scripts/next-task-number.sh [tasks-dir] performs the scan above and, when /dependency-graph.md exists, additionally cross-checks the graph's highest full-ID PHASE against the directory result, emitting a STDERR warning on mismatch (the directory result still wins). A warning signals the graph has drifted from the actual task directories — reconcile the graph before generating the new batch, but never trust the graph's number over the directories.
• Identify dependency relationships with existing tasks and reflect them in the new tasks' Depends On

Step 3: Spec Review

Review the specification for completeness and verify that sufficient information exists for decomposition. The goal is not to demand a perfect spec, but to confirm that the key information needed to determine task boundaries is present.

Checklist:

• Are the boundaries of major features clear? (What is in scope for this spec?)
• Is the tech stack specified? (Affects category selection and dependencies)
• If there are external system integrations, is the scope defined? (Determines whether to split into separate tasks)
• Are there implicitly assumed existing infrastructure or features?

When unclear areas are found:

• Ask the user specific questions before starting task decomposition
• Frame questions as choices ("Is it A or B?") rather than vague observations ("This part is unclear")
• If the spec is sufficiently clear, skip this step and proceed directly

Step 4: Confirm Language

If --lang is provided, skip this step. Otherwise resolve via [../references/language-resolution.md](../references/language-resolution.md) (project ## Language Policy → user ## Language Policy → the older CLAUDE.md cue). Only if resolution yields nothing, ask:

> "Which language should the task documents be written in? (ko / ja / en / es / zh)"

Step 5: Confirm Granularity Mode

If --mode (or its alias --granularity) is provided, use it directly and skip the prompt. If both --mode and --granularity are provided with different values, stop and ask the user to resolve the conflict. Otherwise always ask the user which granularity mode to apply — do not silently default. The correct mode depends on who will execute the tasks.

> "Which granularity mode should the tasks be generated in? > - human — small, single-PR reviewable units (~10 files / ~300 LOC) > - llm — larger vertical slices optimized for a single LLM agent run (~25 files / ~800 LOC)"

Mode selection criteria (share with the user if they are unsure):

• Choose human when a person will implement and code-review each task in sequence
• Choose llm when tasks will be executed autonomously by an LLM agent (Claude Code, Codex, etc.) in isolated worktrees, and reviewed in aggregate after completion

Safety invariants — DB migration separation, Library introduction separation, Phase hard gate, post-task buildability — apply in both modes. Only size and internal bundling differ.

See [references/granularity-modes.md](references/granularity-modes.md) for the full mode specification.

Persist the decision. After confirmation, record the selected mode in a re-checkable location (e.g., a top-line scratchpad note, or write_memory("granularity_mode", ) when Serena MCP is available) and apply it consistently through Steps 6–9 (size, bundling, Ownership scope, Implementation Steps depth, test.md inclusion). Mode drift mid-generation produces inconsistent task directories.

Step 6: Task Decomposition

Analyze the specification and decompose it into tasks following the Task Design Principles and the selected Granularity Mode.

Scale guidelines (task counts scale down in llm mode due to vertical bundling):

• Small (1–3 tasks expected): A single phase is sufficient. Do not force multiple phases.
• Medium (4–15 tasks in human mode, ~3–8 in llm mode): Organize into 2–3 phases. This is the typical case.
• Large (15+ tasks in human mode, 8+ in llm mode): Suggest to the user that the spec itself be split into multiple features. A single task set exceeding 20 tasks becomes difficult to manage.

Planning Advisor (optional, Pattern C)

For Medium and Large specs, phase boundary decisions and task size splits benefit from frontier judgment. A wrong Phase boundary cascades into every subsequent dependency declaration and is expensive to undo once the task directories are generated.

This skill applies Pattern C from [advisor-pattern.md](../references/advisor-pattern.md): a single upfront Opus advisor call before writing any task directories. The executor handles everything else — Task Naming, Directory Generation, Dependency Graph, and Final Validation.

When to invoke:

• Scale is Medium (4–15 tasks) or Large (15+ tasks), AND
• At least one of: phase boundary is non-obvious, multiple DB migrations or library introductions compete for Phase 1, or the spec touches more than two concurrent feature areas.
• Skip for Small specs (1–3 tasks) — a single-phase decomposition is obvious and does not benefit from frontier reasoning. Adding an Opus call here wastes budget.

How to invoke: Use the Task tool with model: opus. Pass the following as context payload:

• Spec summary — ≤20 lines distilled from your Spec Review in Step 3 (not the full spec).
• First-pass task list — task name + one-line description for each candidate task from your Step 6 decomposition.
• Known conflicts / shared surfaces — any Ownership overlaps or Shared Surfaces you identified.
• Project context essentials — monorepo structure, existing phases in tasks/, tech-stack constraints affecting dependency order.

Ask the advisor for three things:

1. Phase boundary recommendations — which tasks belong to which phase, and why each boundary is a hard gate.
2. Task size verification — any task likely to exceed ~10 files or ~300 LOC that should be split further.
3. Dependency cycle risk — any tasks with circular implicit dependencies the first-pass missed.

Budget: exactly 1 Opus call per invocation of this skill. Pattern C explicitly rules out re-invocation during execution — if the initial plan proves wrong, re-run the whole skill with refined input rather than calling Opus mid-generation. This rule exists because mid-generation re-planning leads to inconsistent task directories; a fresh start is cleaner and more auditable.

Payload rules: the summary and task list together must not exceed ~200 lines of payload. If the first-pass decomposition is already larger, narrow it before the advisor call (split the spec into sub-specs and plan each separately). Never forward the full spec verbatim.

Advisor output format (≤300 wo

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yongwoon
• Source: yongwoon/ywc-agent-toolkit
• License: MIT

Install and usage instructions live in the source repository linked above.