Ywc Task Generator

---
name: ywc-task-generator
description: >-
  (ywc) Use when converting a specification into implementation tasks. Task documents can be written in Korean, Japanese, English, Chinese, or Spanish. Triggers: "task 생성", "タスク生成", "spec to tasks", "task breakdown", "작업 분해", "仕様からタスク生成", "implementation tasks", "스펙 분해", "从规范生成任务", "中文任务", "generar tareas", "tareas en español", or any spec-to-task decomposition request. Do not use for direct code implementation, spec review (use ywc-spec-validate), or planning without a written specification.
---

# 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. |
| "This repository has one user, so initials are overkill" | The moment a second worktree exists, the collision happens silently with no merge conflict. A one-time question costs nothing; skipping it costs unrecoverable numbering ambiguity. |
| "it's just changing one column so it's a small task" | The whole caller set is the blast radius. A codebase-wide mechanical change is Principle 5's Wide Refactor Exception — sequence it expand → migrate(batch) → contract, not one bundled task. |

**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 <code>` | _(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 <human\|llm>` | _(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 <path>` | `tasks/` | Root directory where task directories are written. Override to support re-plan iteration in a separate directory (e.g., `--tasks-dir tasks-v2/`). |
| `--initials <value>` | _(resolved or asked)_ | Collaborator initials used as the task-ID `[INITIALS]` segment. Validated against `^[a-z0-9]{2,4}$`. Takes **highest precedence** — it wins over a cached `## Task Initials` section in the project `CLAUDE.md` and suppresses derivation and the confirmation prompt. See Step 2. |

## Language Option

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

> Run `bash claude-code/skills/scripts/resolve-language.sh [--lang <code>]`.
> Resolved code → use it directly. `UNRESOLVED` → fall through to this skill's own fallback below.

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

### 5. Wide Refactor Exception (Expand-Contract)
- A mechanical change whose blast radius spans the whole codebase (column rename, shared-type retype, API-signature change across all callers) is an **exception** to Principle 1's vertical-slice bundling — packing every call site into one task would blow past the mode's size guideline, so sequence it **expand → migrate → contract** instead
- **expand**: add the new shape alongside the old so both coexist and nothing breaks (one task)
- **migrate**: split the blast radius into batches, each an independent task that keeps CI green; migrate batches run **serially** — each batch task chains to the previous one via `Depends On` (never parallel migrate batches, so every intermediate state stays buildable)
- **contract**: remove the old shape — only after every migrate batch is complete (one task)
- Each expand/migrate/contract task's category follows the **primary nature of the change** rule (Step 7); a migrate batch needs no new category
- This relaxes only Reviewability bundling — it does **not** relax the DB Migration or Library Introduction Safety Invariants; a schema-touching expand/contract step still lives in its own `db` task

---

## 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

**Resolve collaborator initials first.** Run this **on every invocation**, regardless of whether any tasks already exist — Step 7 naming always requires the `[INITIALS]` segment, so a fresh repository needs the value just as much as one with a hundred archived tasks.

> If `--initials <s>` was **not** supplied, check the project `CLAUDE.md` for an existing valid
> `## Task Initials` section first (rung 2 of `references/initials-resolution.md`'s precedence
> chain — the script below deliberately never reads project files, so this caller-side check is
> what makes rung 2 real). A valid cached value wins outright: use it, no confirmation, no
> script call needed.
> Otherwise (an explicit `--initials` was supplied, or no cached section exists) run
> `bash claude-code/skills/ywc-task-generator/scripts/resolve-initials.sh [--initials <s>]`
> (handles rung 1, the flag, and rung 3, derivation — an explicit flag always wins outright).
> `RESOLVED <s>` → use it, no confirmation. `NONE` → proceed without initials (legacy numbering; never blocks).
> `NEEDS_CONFIRM <candidate>` → show the collision advisory below, then confirm once before use — the script never confirms or caches.

- **Caching is create-or-replace.** Writing the resolved value updates the project `CLAUDE.md` `## Task Initials` section in place, leaving **exactly one** such section. Appending a second heading is forbidden; if duplicates already exist, update the first and remove the rest.
- **The confirmation prompt carries the collision advisory.** Before confirming a derived value, present the disk-scanned list of initials already in use with their task counts. Obtain it with `bash claude-code/skills/ywc-task-generator/scripts/next-task-number.sh <tasks-dir> --list-initials`, which prints one `<initials> <count>` line per distinct prefix across the same worktree union (empty output, exit 0, means none are in use). Do not hand-roll the scan. A match **warns without blocking** — the user may keep the value or override it.
- A resolved value from `--initials` or an existing valid `## Task Initials` section suppresses both derivation and the confirmation prompt. When neither is present, derive and ask for **exactly one** confirmation. Absence of every source never blocks generation.
- **Allocation failure modes.** The drift `WARN` below is advisory (exit 0). Three conditions instead exit **1** and allocate nothing: initials failing `^[a-z0-9]{2,4}$`; an **unborn HEAD** (a `git init`-ed repository with no commit, or no repository at all), because the reservation cannot anchor a ref — commit once and retry, or omit the initials argument to fall back to legacy unprefixed numbering; and reservation-retry exhaustion after 100 attempts, which reports the `refs/ywc/task-phase/<initials>/` ref count and indicates a corrupt ledger rather than contention.
- **Reservations are a permanent local ledger.** A run that aborts after reserving keeps its number; the next run computes the same value, is rejected, and takes the next one. **Gaps in the PHASE sequence are therefore expected and correct — never "repair" them.** The guarantee spans the current worktree and every linked worktree (they share one git common dir); two separate *clones* do not share reservations and can still collide.

Then 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** `<tasks-dir>/` and `<tasks-dir>/completed/` (default: `tasks/` and `tasks/completed/`). Completed tasks are moved out of `<tasks-dir>/` into `<tasks-dir>/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 (legacy, no-initials path): if the highest existing number is `000016-040` — whether it currently lives in `<tasks-dir>/` or in `<tasks-dir>/completed/` — the new batch starts at `000017-010`. Under an initials-scoped scan the same logic applies within the resolved namespace — `yk-000016-040` yields `yk-000017-010` — because unprefixed entries are out of scope (see the next bullet). If `<tasks-dir>/` is empty (every task already completed and archived), fall back to the highest number in `<tasks-dir>/completed/` and apply the same `+1 phase` rule.
- **Proactive compaction gate**: after resolving the starting number above, check the resolved `<tasks-dir>/dependency-graph.md` line count (`wc -l`; `<tasks-dir>` defaults to `tasks`). If it exceeds **300 lines**, run `python3 claude-code/skills/ywc-task-generator/scripts/compact-dependency-graph.py <tasks-dir>` before generating any new task. Report the before/after line count; if it remains above 300, active/planned work accounts for the size and no further action is needed. The gate only removes phases whose every task is in `<tasks-dir>/completed/` and never touches a phase with outstanding or unresolvable work.
- **The scan is scoped to the resolved initials.** Only entries carrying the resolved `<initials>-` prefix are compared for the maximum PHASE; other collaborators' prefixes and legacy unprefixed entries are out of scope. The scan unions the current worktree with every linked worktree from `git worktree list`, applies the legacy seed rule when the resolved namespace is empty but legacy entries exist, and atomically reserves the chosen PHASE so two concurrent runs cannot claim the same number. The rule bodies live in [../references/initials-resolution.md](../references/initials-resolution.md) and the script's own comments — do not restate them here.
- 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] [initials]` performs the scan above — passing `[initials]` enables the initials-scoped comparison, the worktree union, the legacy seed rule, and the atomic reservation; omitting it leaves the legacy unprefixed allocation unchanged — and, when `<tasks-dir>/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", <value>)` 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 words):
- Phase boundary plan with one-line rationale per boundary
- Task size concerns (if any)
- Cycle/ordering warnings (if any)
- Single "proceed" or "reconsider with refinements" verdict

After receiving the verdict, the executor either continues to Step 7 (Task Naming) with the adjusted plan, or surfaces the "reconsider" verdict to the user for refinement before proceeding.

### Step 7: Task Naming

Each task name follows this format:

```
[INITIALS]-[PHASE]-[SEQUENCE]-[CATEGORY]-[SHORT-DESCRIPTION]
```
> Example: `yk-000001-010-db-create-user-table` = INITIALS `yk` + PHASE `000001` + SEQUENCE `010` + category + description.

**Numbering Rules:**
- INITIALS: 2–4 lowercase alphanumeric characters (`^[a-z0-9]{2,4}$`) — the collaborator initials resolved in Step 2
- PHASE: **6-digit** number (`000001`, `000002`, ...) — the wider width reserves headroom for multi-year project growth
- SEQUENCE: 3-digit number (`010`, `020`, `030`, ...)
- Sequence increments by 10 (allows inserting tasks later without renumbering)
- Always use hyphen (`-`) to separate PHASE and SEQUENCE for readability
- **Starting PHASE for a new batch**: when any tasks already exist, scan both `<tasks-dir>/` and `<tasks-dir>/completed/` (default: `tasks/` and `tasks/completed/`), take the highest PHASE across the union, and start the new batch at `highest PHASE + 1` with SEQUENCE `010` (see Step 2). A freshly generated batch never reuses a number that was already used and then archived into `<tasks-dir>/completed/`.
- **Legacy IDs stay valid.** Unprefixed task IDs generated before initials namespacing (`000001-010-db-create-user-table`) remain valid, are parsed as-is, and are **never renumbered retroactively**. Prefixed and unprefixed IDs coexist in the same repository.

**Category:**
- `lib` — New library/framework introduction
- `db` — Database migration, schema change
- `api` — API endpoint implementation
- `domain` — Business logic, service layer
- `worker` — Background job, async processing
- `ui` — Frontend component, page
- `test` — Test-only task (e2e, load test, etc.)
- `refactor` — Code structure improvement with no behavior change
- `infra` — CI/CD, deployment, configuration
- `config` — Environment variables, feature flags, `.env` setup (distinct from infra: infra covers CI/CD pipelines and deployment, config covers application-level settings)

**Category Selection Guidelines:**
- When a task seems to fit multiple categories, choose based on the **primary nature of the change**
- If creating an API endpoint also requires a DB migration → split into separate tasks (db + api), even in `llm` mode (Safety Invariant)
- Tasks that only set environment variables use `config`; tasks modifying deployment pipelines use `infra`
- Auth/security logic is not a category on its own — choose based on implementation location: `api` (endpoint), `domain` (logic), or `lib` (library introduction)
- In `llm` mode, a single task may bundle `domain` + `api` for one feature — label it with the dominant category (usually `api` when an endpoint is exposed, otherwise `domain`)

**Naming Quality Rules:**
- Use only lowercase and hyphens
- Keep names concise, descriptive, and filesystem-friendly
- Express exactly one primary concern (in `llm` mode, "one primary concern" may cover a vertical slice of a single feature)
- Avoid vague names
- Do not use "and" in task names — use a unifying noun instead (e.g., `user-auth` rather than `registration-and-login`)

**Examples:**
- `yk-000001-010-db-create-user-table`
- `yk-000001-020-lib-setup-auth-library`
- `yk-000001-030-api-user-registration`
- `yk-000002-010-ui-login-form`

### Step 8: Phase Organization

- PHASE represents a meaningful dependency stage (e.g., `000001` = foundation, `000002` = core features, `000003` = integration)
- Do not create phases arbitrarily — a new phase means "all tasks in the previous phase must be complete before this phase can start"
- Tasks within the same phase may have internal ordering via SEQUENCE, but conceptually belong to the same stage

**Phase Boundary Rules:**
- Phase boundaries are **hard gates**. No task in Phase N+1 can start before all tasks in Phase N are complete
- Dependencies between tasks within the same phase are allowed (order expressed via SEQUENCE)
- If only some tasks in Phase N need to be complete before a specific Phase N+1 task can start, that task should be placed in Phase N instead
- Criterion for splitting phases: "Do all outputs from this stage need to be in place for the next stage's work to be meaningful?"

### Step 9: Directory and File Generation

Use the resolved `--tasks-dir` path specified by the user for output. If not specified, default to `tasks/`.

Generate the following structure for each task:

```
<tasks-dir>/[TASK_NAME]/
├── README.md
├── task.md
└── test.md (optional — included when manual verification is needed)
```

Refer to templates in the `references/` directory when writing files:
- `references/README.md.template` — Task overview and dependency documentation
- `references/task.md.template` — Implementation checklist
- `references/test.md.template` — Manual test plan
- `references/dependency-graph.md.template` — Top-level dependency summary

#### README.md Core Elements

Each README.md must include the following:

- **Purpose**: What this task achieves
- **Scope**: What is included
- **Spec Reference**: Specification/design documents that must be consulted before implementation (see "Spec Reference Rules" below)
- **Dependencies**: Bidirectional dependency tracking
  - **Depends On**: Predecessor tasks this task depends on (specify what each provides)
  - **Depended By**: Successor tasks that depend on this task (specify what each needs)
- **Key Files**: List of files expected to be created or modified
- **Notes**: Important considerations, design decisions, and **Assumptions** — any spec ambiguity resolved during decomposition, with the interpretation chosen, so the implementer can challenge it instead of inheriting a silent guess
- **Out of Scope**: What is intentionally excluded
- **Parallel Execution Metadata**:
  - **Ownership**: Files, directories, modules, contracts this task may modify
  - **Shared Surfaces**: Shared boundaries that may cause merge or design conflicts
  - **Conflicts With**: Tasks that must not run in parallel
  - **Parallelizable After**: Minimum merged baseline before isolated execution can safely start
  - **Task Verify**: Exact commands that prove this task is complete

Bidirectional dependency tracking matters because developers executing a task can immediately see which downstream tasks are affected, allowing them to consider downstream requirements when designing interfaces.

#### Spec Reference Rules

Every task's README.md must include a `## Spec Reference` section with three subsections: **Primary Sources** (links to source-of-truth docs, project-relative by default), **Summary** (2–5 sentence orientation), and **Out of Scope (from spec)** (scope-creep guardrail).

**Hard rule**: never leave Spec Reference empty or omitted — use `N/A — no external spec (housekeeping / refactor / config only)` when no spec exists.

For the full structure, the external-URL policy, the link-vs-summary drift protocol, and the cross-task scope-handoff convention, **read [references/spec-reference-rules.md](references/spec-reference-rules.md)**.

#### Parallel Execution Metadata Rules

When tasks may be executed via `git worktree`, Codex, Claude Code, or other isolated worker setups, every task's README.md must declare:

- **Ownership** — concrete edit boundary (file paths, globs, modules, contracts). Bad: `backend`, `frontend related files`. Good: `api/src/routes/metrics.ts`, `OpenAPI contract: /api/v1/metrics`.
- **Shared Surfaces** — shared boundaries (DB schema, API contracts, event payloads, workspace config, CI config) that may cause conflicts even without direct file overlap.
- **Conflicts With** — tasks that must not run in parallel even when dependencies allow. Write `(None identified)` if none.
- **Parallelizable After** — the minimum merged baseline for safely starting isolated execution (often, but not always, the same as `Depends On`).
- **Task Verify** — task-specific commands that prove completion (avoid project-wide gates only).

For the full rule set including good/bad Ownership examples, the complete shared-surfaces taxonomy, and the dependency-graph Parallel Execution Notes format, **read [references/parallel-execution-metadata.md](references/parallel-execution-metadata.md)**.

#### task.md Core Elements

Each task.md must include the following:

- **Prerequisites**: Predecessor task completion status to verify before starting (checkbox format)
- **Allowed Edit Scope**: A brief restatement of the `README.md` Ownership as an operational boundary
- **Stop Conditions**: Conditions under which the implementer should stop and report rather than continuing
- **Acceptance Criteria**: The task's verifiable behavioral goal in `When <trigger>, system does <behavior>, observable as <concrete check>` form — distinct from the imperative Implementation Steps below. This is the declarative success target the implementer loops against; the steps are one way to reach it.
- **Implementation Steps**: Specific implementation steps (checkbox format)
  - Each step must reference specific files, modules, functions, or behaviors
  - Do not use generic placeholders like "implement core logic" or "handle edge cases"
  - Example: `Create src/models/user.ts with User entity definition`
- **Task Verify**: Task-specific verification command checklist — each command must assert this task's specific outcome (a test exercising the new behavior, or a command whose output changes), never only a project-wide `build`/`lint` gate
  - **Duplicate-sensitive write flows** (stock/balance/order/payment/provisioning/quota writes): Task Verify must additionally cover concurrent-write behavior, partial-failure rollback, and idempotent retry. When the spec requires a specific mechanism (atomic conditional update / row lock / optimistic lock / idempotency key / unique constraint / persisted request/result record), the task must name the chosen mechanism and its expected observable outcome. If the project has no practical concurrency harness, state an alternative verification (e.g., a targeted unit assertion on the atomic update or a documented manual concurrent-request check) rather than omitting it.
- **Verification**: Confirm lint, typecheck, test, and build pass (use the project's actual commands)

#### test.md (optional)

Write structured scenario-based tests (Steps + Expected Result).

**Include when:**
- UI component or screen behavior verification → always include
- External service integration (S3, Email, Payment, etc.) → always include
- Browser-dependent features → always include
- Complex user workflows (multi-step) → recommended

**May omit when:**
- Pure API endpoints (coverable by unit + integration tests)
- Database migrations (schema application verified via task.md Verification)
- Library introduction tasks (import and basic operation verified via Verification)

### Step 10: Generate Dependency Graph

After generating all tasks, create `<tasks-dir>/dependency-graph.md` at the top level. This file serves as the single source of truth for execution order.

Refer to `references/dependency-graph.md.template` for format. List tasks by phase and express each task's dependencies using arrow notation.

This graph must be consistent with the Dependencies sections in individual README.md files.
Once every task in a phase reaches `<tasks-dir>/completed/`, the shared completion marker automatically compacts that phase (see `claude-code/skills/ywc-task-generator/scripts/compact-dependency-graph.py`) — no special markup is required; the script reads the `## Phase [<initials>-]NNNNNN` (both prefixed and legacy unprefixed), `## Parallel Execution Notes`, and `## Visual Dependency Graph` headings directly, grouping phases on the full prefixed key so two collaborators' identically-numbered phases never merge.

### Step 11: Final Validation

After generating all tasks, verify the following:

**Dependency & Structure:**
- [ ] No forward dependencies (earlier tasks do not depend on later tasks)
- [ ] No circular dependencies
- [ ] Phase boundaries correctly set as hard gates
- [ ] Database migrations and library introductions separated into their own tasks (Safety Invariant in both modes)
- [ ] No numbering collisions with existing tasks (if any)

**Naming & Size:**
- [ ] Naming convention followed (`[INITIALS:2-4]-[PHASE:6]-[SEQUENCE:3]-[CATEGORY]-[SHORT-DESCRIPTION]`)
- [ ] PHASE is 6 digits, SEQUENCE is 3 digits, separated by hyphen
- [ ] INITIALS matches the value resolved in Step 2 and the full segment widths are correct (2–4 lowercase alphanumerics, 6 digits, 3 digits)
- [ ] Exactly one `## Task Initials` section exists in the project `CLAUDE.md` (`grep -c '^## Task Initials' CLAUDE.md` returns `1`)
- [ ] No task name contains "and" (single concern check)
- [ ] Each task fits within the selected Granularity Mode's size guideline
- [ ] Selected Granularity Mode applied consistently (bundling, Implementation Steps depth, Ownership scope)

**README.md Quality:**
- [ ] Both "Depends On" and "Depended By" included
- [ ] Parallel Execution Metadata included (Ownership, Shared Surfaces, Conflicts With, Parallelizable After, Task Verify)
- [ ] Ownership is narrow enough to serve as an actual edit boundary, not just a restatement of Key Files
- [ ] **Spec Reference** section included — Primary Sources, Summary, and Out of Scope (from spec) all filled in or explicitly marked `N/A`
- [ ] If Primary Sources include external URLs, only if the project allows it (default is project-relative paths only)

**task.md Quality:**
- [ ] Specific Implementation Steps included (no generic placeholders)
- [ ] Prerequisites section included
- [ ] Allowed Edit Scope and Stop Conditions included
- [ ] Acceptance Criteria included in `When <trigger>, does <behavior>, observable as <check>` form (distinct from Implementation Steps)
- [ ] Each task's Task Verify includes ≥1 task-specific assertion that fails if the task's behavior is absent (not only a project-wide gate like bare `build`/`lint`)
- [ ] For a duplicate-sensitive write flow, Task Verify covers concurrent-write behavior, partial-failure rollback, and idempotent retry — naming the spec-required mechanism (atomic conditional update / row lock / optimistic lock / idempotency key / unique constraint / persisted request/result record) and its expected observable outcome
- [ ] Verification commands match the project's actual commands (based on context collected in Step 2)

**Consistency:**
- [ ] Dependency Graph Summary matches individual README.md files
- [ ] If the task set is intended for parallel execution, Dependency Graph includes Parallel Execution Notes
- [ ] Codebase is buildable after each task completes
- [ ] Selected language's writing rules are followed

---

## Output Format

The final output includes:

1. **Task list summary**: A table organizing all tasks by phase
2. **Directory generation**: Task directories and files created under `<tasks-dir>/` (default: `tasks/`)
3. **Dependency Graph**: `<tasks-dir>/dependency-graph.md` generated — single source of truth for execution order
4. **Parallel Execution Notes**: Included in `<tasks-dir>/dependency-graph.md` when parallel worktree execution is expected

When parallel execution is expected, verify that each task is safe for isolated worktree or agent execution.

---

## Example

User input: "Break down the user authentication spec into tasks. `--lang ko --mode human`"

---

## Task Execution Convention

For execution rules after task generation (completion handling, directory moves, etc.), see `references/execution-convention.md`.