**Files to create**: [list] **Files to modify**: [list] **Description**: [what to implement] **Tests**: [what to test] **Depends on**: [none or task IDs] ### Task 2: ... ``` ### Step 4: Generate dev-tasks.json Save to `<project_root>/dev-tasks.json`: ```json { "project": "<Project Name>", "source_document": "docs/<project-slug>-plan.md", "project_root": "/absolute/path/to/project", "test_framework": "pytest", "created_at": "<today's date>", "status": "pending", "instructions": "<key patterns and constraints for Claude>", "tasks": [ { "id": "1-task-slug", "step": 1, "title": "Task Title", "description": "Detailed description of what to implement. Include context, patterns to follow, and exact expected behavior.", "files_to_create": ["path/relative/to/project_root/file.py"], "files_to_modify": ["path/relative/to/project_root/existing.py"], "test_file": "tests/test_file.py", "depends_on": [], "status": "pending", "attempts": 0, "errors": [] } ] } ``` ### Step 5: Confirm and Hand Off After writing both files, tell the user: - How many tasks were generated - Where the files were saved - The command to launch: `~/.claude/skills/plan-to-code-async/scripts/launch.sh <project_root>/dev-tasks.json` - Or: "Now run `/plan-to-code-async` to execute this plan" ## Task Design Guidelines **Good task descriptions** include: - What exactly to implement (specific function/class names) - Which existing patterns to follow (reference existing files) - What the output should look like (API shape, behavior, test expectations) - What NOT to do (don't break X, don't modify Y) **Good task sizing**: - Each task should be completable in 1-3 Claude turns - Max ~5 files per task - One clear, testable outcome per task - No "write 500 lines of code" tasks — split them **Dependency ordering**: - Models/schemas first - Core logic second - Integration/wiring third - UI/API endpoints last - Tests can be in the same task or immediately after ## Examples of Well-Formed Tasks ```json { "id": "1-spending-model", "step": 1, "title": "Create spending tracker data model", "description": "Create state/spending/{username}.json schema and SpendingTracker class in telegram_bot/services/spending_tracker.py. Follow the pattern from session_manager.py for file-based state. Methods: record_spend(amount, model, request_type), get_daily_total(), get_monthly_total(), get_summary(). Use atomic writes with tmp file + rename.", "files_to_create": ["telegram_bot/services/spending_tracker.py"], "files_to_modify": [], "test_file": "tests/test_spending_tracker.py", "depends_on": [], "status": "pending", "attempts": 0, "errors": [] } ``` ## After Completion Hand off to `/plan-to-code-async`: ``` The plan is ready. Run /plan-to-code-async to start building. Task file: <project_root>/dev-tasks.json Tasks: N tasks, estimated ~X hours autonomous execution ```

--- name: build-plan-doc-and-tasks description: | Transform a project idea, requirement, or description into a structured development plan and a ready-to-run dev-tasks.json for /plan-to-code-async. Interviews the user if needed, creates a planning document, breaks it into ordered tasks with dependencies, and outputs the task file. Use BEFORE running /plan-to-code-async. This is step 1 of the plan-to-code workflow. allowed-tools: Read, Write, Edit, Bash, Glob, Grep --- # build-plan-doc-and-tasks — Project Planner This skill converts a project idea into a structured `dev-tasks.json` ready for `/plan-to-code-async`. **This is Step 1. Run this first. Then run `/plan-to-code-async` with the output.** ## What This Skill Does 1. **Understands the project** — reads any document provided, or asks clarifying questions 2. **Creates a planning document** — saves `docs/-plan.md` in the project root 3. **Breaks it into tasks** — ordered, with dependencies, files, and test specs 4. **Writes `dev-tasks.json`** — ready to pass to `/plan-to-code-async` ## How to Use Simply invoke this skill and describe your project. Examples: ``` /build-plan-doc-and-tasks I want to add a spending tracker to my Telegram bot /build-plan-doc-and-tasks [attach a document describing the feature] /build-plan-doc-and-tasks Build a WhatsApp outreach system with lead scoring ``` ## Process (Follow This Exactly) ### Step 1: Gather Requirements Ask the user (or read the document) to understand: - **What** to build (feature/system description) - **Where** (project root directory — absolute path) - **Language/Framework** (Python, Node, etc.) - **Test framework** (pytest, jest, vitest, etc.) - **Special constraints** (env vars, patterns to follow, files not to touch) If a document is attached, read it fully before asking questions. Only ask questions that aren't answered in the document. ### Step 2: Explore the Codebase Before writing the plan, explore the target project: - Read key files to understand architecture patterns - Find existing similar features to match conventions - Identify files that will need to be created or modified - Check for existing tests to understand test patterns ### Step 3: Write the Planning Document Save to `/docs/-plan.md`: ```markdown # — Implementation Plan ## Overview [2-3 sentences: what we're building and why] ## Architecture [How the feature fits into the existing system] ## Tasks ### Task 1: **Files to create**: [list] **Files to modify**: [list] **Description**: [what to implement] **Tests**: [what to test] **Depends on**: [none or task IDs] ### Task 2: ... ``` ### Step 4: Generate dev-tasks.json Save to `<project_root>/dev-tasks.json`: ```json { "project": "<Project Name>", "source_document": "docs/<project-slug>-plan.md", "project_root": "/absolute/path/to/project", "test_framework": "pytest", "created_at": "<today's date>", "status": "pending", "instructions": "<key patterns and constraints for Claude>", "tasks": [ { "id": "1-task-slug", "step": 1, "title": "Task Title", "description": "Detailed description of what to implement. Include context, patterns to follow, and exact expected behavior.", "files_to_create": ["path/relative/to/project_root/file.py"], "files_to_modify": ["path/relative/to/project_root/existing.py"], "test_file": "tests/test_file.py", "depends_on": [], "status": "pending", "attempts": 0, "errors": [] } ] } ``` ### Step 5: Confirm and Hand Off After writing both files, tell the user: - How many tasks were generated - Where the files were saved - The command to launch: `~/.claude/skills/plan-to-code-async/scripts/launch.sh <project_root>/dev-tasks.json` - Or: "Now run `/plan-to-code-async` to execute this plan" ## Task Design Guidelines **Good task descriptions** include: - What exactly to implement (specific function/class names) - Which existing patterns to follow (reference existing files) - What the output should look like (API shape, behavior, test expectations) - What NOT to do (don't break X, don't modify Y) **Good task sizing**: - Each task should be completable in 1-3 Claude turns - Max ~5 files per task - One clear, testable outcome per task - No "write 500 lines of code" tasks — split them **Dependency ordering**: - Models/schemas first - Core logic second - Integration/wiring third - UI/API endpoints last - Tests can be in the same task or immediately after ## Examples of Well-Formed Tasks ```json { "id": "1-spending-model", "step": 1, "title": "Create spending tracker data model", "description": "Create state/spending/{username}.json schema and SpendingTracker class in telegram_bot/services/spending_tracker.py. Follow the pattern from session_manager.py for file-based state. Methods: record_spend(amount, model, request_type), get_daily_total(), get_monthly_total(), get_summary(). Use atomic writes with tmp file + rename.", "files_to_create": ["telegram_bot/services/spending_tracker.py"], "files_to_modify": [], "test_file": "tests/test_spending_tracker.py", "depends_on": [], "status": "pending", "attempts": 0, "errors": [] } ``` ## After Completion Hand off to `/plan-to-code-async`: ``` The plan is ready. Run /plan-to-code-async to start building. Task file: <project_root>/dev-tasks.json Tasks: N tasks, estimated ~X hours autonomous execution ```