Find Next Task

Overview

This skill helps you find the next executable task from writing-plans-plus compatible JSON plan files. It understands task dependencies, status tracking, and plan file organization.

Announce at start: "I'm using the find-next-task skill to locate the next task."

Prerequisite Check

First, verify that the project has compatible plan files:

Look for plan files in this priority order:

• docs/plans/*.json

• *.json (project root)

• **/*.json (full project search) ONLY if the user explicitly asks for exhaustive search or the repo is known to be small

If you do a full project search, apply safety limits:

• Stop after finding 50 candidate JSON files

• Skip JSON files larger than ~1MB

• Prefer reading just enough to confirm a top-level tasks array exists before fully parsing

Validate writing-plans-plus format for each candidate file:

• Must have a top-level tasks array

• Each task must have: id , title , description , steps , passes

• The passes field must be boolean (true/false)

• If a candidate file is invalid JSON, skip it and record a warning

If no valid plan files found:

• Output a JSON object with an error field and stop.

Step 1: Find and Select Plan

List Candidate Plans

For all valid plan files found:

• Read each file's content

• Calculate progress: (number of tasks with passes: true ) / (total tasks)

• Group plans into categories:

• In progress: Some tasks completed, some remaining

• Not started: All tasks passes: false

• Completed: All tasks passes: true

Detect Plan Ordering

Check if plan filenames have obvious sequential patterns:

• Look for: phase1 , phase2 , phase3 , etc.

• Look for: part1 , part2 , step1 , step2 , etc.

• Look for: v1 , v2 , v1.1 , v1.2 , etc.

• Look for numeric prefixes: 01- , 02- , etc.

Plan Selection Logic

If obvious sequential pattern exists:

• Process plans in that order

• Find the first plan that is NOT fully completed

• Use that plan

If no obvious order AND multiple in-progress/not-started plans:

• Output JSON with selection_required: true and include candidates with progress

• Do NOT output prose outside JSON

If only one plan has pending tasks:

• Automatically select that plan

If all plans are completed:

• Output JSON with next_task: null and a completed summary

Step 2: Analyze Plan and Find Next Task

Once a plan is selected:

Read and Parse the Plan

Read the JSON file content. You need to understand:

• The plan's overall goal/description

• All tasks with their full details

• Dependency relationships (depends_on field)

Task Readiness Check

For each task in the plan (in ID order):

A task is ready if:

• passes: false (not completed)

• All dependencies (from depends_on array) are satisfied:

• For each dependency ID in depends_on :

• Find that task in the plan

• Verify its passes is true

• If no depends_on field or empty array, this condition is automatically satisfied

If a dependency ID is missing from the plan, treat the task as not ready and record it as blocked by missing dependencies in the output.

Find the Next Task

• Iterate through tasks in ID order

• Find the FIRST task that is ready (as defined above)

• If no tasks are ready but some are incomplete:

• This means there are tasks waiting on dependencies

• Output a JSON object with next_task: null and include blocked reasons in task_summary

• If you detect a circular dependency, set cycle_detected: true and include a best-effort list of tasks involved

Step 3: Output the Result

Output Format

Always output a single JSON object and nothing else (no prose, no markdown fences). Use this structure:

{ "plan_file": "/absolute/path/to/plan.json", "plan_name": "User Authentication Implementation", "plan_progress": { "completed": 3, "total": 10, "percentage": 30 }, "selection_required": false, "plan_candidates": null, "cycle_detected": false, "warnings": [], "error": null, "next_task": { "id": 4, "title": "Login Page Implementation", "description": "Create the login page with email/password form and validation", "steps": [ "Create login page component", "Add form validation", "Connect to Supabase auth", "Add error handling" ], "passes": false, "depends_on": [1, 2, 3], "validation_criteria": [ "Login form renders without errors", "Email validation works correctly", "Successful login redirects to dashboard", "Error messages are displayed properly" ], "skills": ["using-superpowers", "test-driven-development"], "files": { "create": ["app/login/page.tsx", "app/login/components/LoginForm.tsx"], "modify": ["app/layout.tsx"], "test": ["app/login/login.test.tsx"] } }, "task_summary": [ { "id": 1, "title": "Project Setup", "passes": true }, { "id": 2, "title": "Supabase Client Setup", "passes": true }, { "id": 3, "title": "Database Schema", "passes": true }, { "id": 4, "title": "Login Page Implementation", "passes": false, "ready": true }, { "id": 5, "title": "Register Page", "passes": false, "ready": false, "blocked_by": [4] } ] }

Error and Warning Schemas

Use stable, machine-parseable structures:

{ "error": { "code": "NO_PLAN_FOUND", "message": "No writing-plans-plus compatible plan files found.", "details": { "searched": ["docs/plans/.json", ".json"] } }, "warnings": [ { "code": "INVALID_JSON_SKIPPED", "message": "Skipped invalid JSON candidate plan.", "file": "docs/plans/bad.json" } ] }

• error MUST be either null or an object: { code, message, details? }

• warnings MUST be an array of objects: { code, message, file? }

Recommended error.code values:

• NO_PLAN_FOUND

• PLAN_SELECTION_REQUIRED

• PLAN_PARSE_FAILED

• PLAN_SCHEMA_INVALID

Recommended warnings[].code values:

• INVALID_JSON_SKIPPED

• PLAN_SCHEMA_INVALID_SKIPPED

• MISSING_DEPENDENCY

• CYCLE_DETECTED

Field Explanations

• plan_file: Absolute path to the selected plan JSON file

• plan_name: The project name or description from the plan

• plan_progress: Statistics about overall plan completion

• selection_required: If true, next_task must be null and plan_candidates must be present

• plan_candidates: Array of candidate plans when selection is required, otherwise null

• warnings: Non-fatal issues encountered (invalid JSON candidates skipped, missing dependency IDs, etc.)

• error: Fatal error object or null

• next_task: The full task object of the next ready task (or null if none)

• task_summary: Brief status of all tasks in the plan

Include All Task Fields

When outputting next_task , include ALL fields present in the original task, not just the ones shown in the example. This includes optional fields like issue , completed_at , completed_by , notes , tags , estimated_time , etc.

Special Cases

Tasks with Issues

If a task has an issue field (array of strings):

• Include it in the JSON output

• Include it as-is in next_task.issue and/or enrich the corresponding entry in task_summary with issues for visibility

• Still treat it as a normal task (follow user's instruction: "按正常顺序处理")

Multiple Ready Tasks

If multiple tasks are ready (no dependencies or dependencies satisfied):

• Pick the one with the smallest ID

• The others are ready but not "next"

• In the task_summary, mark them as "ready": true but don't select them as next_task

Quick Reference: Checklist

Before outputting the result, verify:

• Found at least one valid writing-plans-plus JSON file

• Selected the appropriate plan (sequential order or user-selected)

• Correctly identified task readiness (passes: false AND dependencies satisfied)

• Output is valid JSON with all required fields

• Included ALL task fields from the original plan

• Output contains no extra prose outside the JSON object