tasks-md-generator

name	tasks-md-generator
description	Generate implementation TASKS.md plans from one design document or from all feature documents in a directory.
disable-model-invocation	true

TASKS.md Generator

Quick Start

1. Accept one user-provided path (file or directory).
2. Run python3 .cursor/scripts/discover_targets.py <path> to map input to output target files.
3. Read each target's source docs and write TASKS.md in the same directory.
4. Run python3 .cursor/scripts/validate_tasks_md.py <target>/TASKS.md before finalizing.

Input Modes

Single Document Mode

Use when the input path is a single markdown file.

• Treat the file's parent directory as the feature directory.
• Create or update <parent>/TASKS.md.
• Prioritize the provided file, then load companion docs in the same folder.

Feature Directory Mode

Use when the input path is one feature directory (for example docs/login).

• Create or update <dir>/TASKS.md.
• Load docs in this priority order when present:
  • PRD.md
  • USER_FLOW.md
  • BACKEND_ARCHITECTURE.md
  • FRONTEND_DESIGN.md
  • README.md
  • any other .md files except TASKS.md

Batch Directory Mode

Use when the input path is a parent docs folder containing multiple feature directories.

• Detect child directories that include planning docs.
• Create or update one TASKS.md per detected feature directory.
• Skip directories with no planning docs unless explicitly requested.

Build Process

1. Derive scope from source docs only.
2. Split work into independent backend and frontend tracks where possible.
3. Assign global task IDs (T1, T2, ... TN) in strict execution order.
4. Group tasks into tiers that maximize parallel work.
5. Add dependency edges so each Blocked by reference points only to earlier tasks.
6. Include testing and verification tiers as explicit tasks.

Output Contract

Follow .cursor/references/tasks_format.md exactly.

Required top-level sections in this order:

1. # <Feature Name> - Implementation Tasks
2. <N> tasks organized into <M> tiers ...
3. ## Dependency Graph with ASCII tier graph in a fenced code block
4. Tier sections (## TIER <n> - <name>) with task cards
5. ## Summary with tier table and file impact tables

Required per-task structure:

• Heading: ### T<n>: <area>: <title>
• Metadata table with at least:
  • Blocked by
  • Blocks
  • Files
  • Reference when source references exist
• Concrete implementation bullets (API contracts, model changes, tests, edge cases)

Guardrails

• Preserve intent from source docs; do not invent features or architecture.
• Keep tasks implementation-ready and testable.
• Prefer additive changes; call out migrations when models/schema change.
• Keep dependencies acyclic and explicit.
• Keep output deterministic: same inputs should yield the same task IDs and tiering.

Validation

Run structural checks:

python3 .cursor/scripts/validate_tasks_md.py <path-to-TASKS.md>

If validation fails, fix ordering, task numbering, missing sections, or bad references.

References

• .cursor/references/tasks_format.md: canonical TASKS.md skeleton and constraints.
• .cursor/scripts/discover_targets.py: target discovery for file, feature-dir, and batch-dir modes.
• .cursor/scripts/validate_tasks_md.py: structural validator for generated TASKS.md output.