Manage Task List

Guides implementation of task lists with structured completion tracking. This skill enforces a disciplined, step-by-step approach to working through tasks generated from PRDs.

Project Context

Task lists are located at .planning/[project-name]/tasks/tasks-[prd-name].md. Implementation code lives at the workspace root (not inside .planning/).

Operating Modes

Standard Mode (default)

Work on ONE sub-task at a time. Do NOT start the next sub-task until the user explicitly approves. Stop after each sub-task and wait for "yes", "go", "next", etc.

Batch Mode (GSD orchestrator only)

If your instructions say "BATCH MODE", complete all sub-tasks under your assigned parent task without pausing for approval between sub-tasks. Apply the full completion protocol (mark [x], update task file) after each sub-task, then immediately continue to the next. When the entire parent task is [x], follow the Parent Task Completion protocol (including the git commit), then stop and return a summary — do not start any other parent task.

Completion Protocol

Follow this protocol strictly when completing tasks:

When You Finish a Sub-Task

Mark the sub-task as completed: Change [ ] to [x] immediately
Update the task list file: Save the changes to the task list
Check parent task: If ALL subtasks under a parent are now [x], mark the parent as [x] too, then follow the Parent Task Completion protocol below
Pause (Standard Mode only): Stop and wait for user approval before starting the next sub-task. In Batch Mode, skip this step and continue immediately.

When You Complete a Parent Task

Once all sub-tasks under a parent are [x] and the parent itself is marked [x]:

Stage all changes: git add -A
Commit with a descriptive message:

git commit -m "$(cat <<'EOF'
[N.0] [Parent Task Title]

[2–4 bullet points summarising what was implemented, one per sub-task or logical group]
EOF
)"

Example:

git commit -m "$(cat <<'EOF'
1.0 Set up authentication module

- Created auth directory structure and base config
- Installed and configured JWT dependencies
- Added environment variable definitions for secrets
EOF
)"

Then pause for user approval (Standard Mode) or continue to the next parent task (Batch Mode).

Example Workflow

Before:
- [ ] 1.0 Parent Task
  - [x] 1.1 First sub-task (completed earlier)
  - [ ] 1.2 Second sub-task (just finished)
  - [ ] 1.3 Third sub-task (not started)

After (when 1.2 is complete):
- [ ] 1.0 Parent Task
  - [x] 1.1 First sub-task
  - [x] 1.2 Second sub-task
  - [ ] 1.3 Third sub-task (next up)

After (when 1.3 is complete and parent is done):
- [x] 1.0 Parent Task
  - [x] 1.1 First sub-task
  - [x] 1.2 Second sub-task
  - [x] 1.3 Third sub-task

Task List Maintenance

Update as You Work

Mark completed items: Update [x] for each finished task/sub-task
Add new tasks: If you discover additional work needed, add new tasks to the list
Keep files current: Maintain the "Relevant Files" section with accurate descriptions

Relevant Files Section

The "Relevant Files" section should be kept up to date:

List every file created or modified (implementation files at workspace root, planning files under .planning/)
Use full paths relative to workspace root (e.g., src/file.ts for code, .planning/[project-name]/tasks/tasks-prd-name.md for planning)
Provide a one-line description of each file's purpose
Add new files as they are created during implementation

Implementation Process

Before Starting Work

Read the task list from disk: Read the task file directly from its path on disk — do not rely on any in-context version. The user may have edited the file (added tasks, reworded sub-tasks, reordered items) since the plan was generated. Always use the on-disk state as the source of truth.
Identify the next sub-task: Find the first unchecked [ ] sub-task
Check for dependencies: Ensure previous tasks are completed
Understand the goal: Make sure you understand what the sub-task requires

During Implementation

Focus on current sub-task: Work only on the current sub-task
Implement thoroughly: Write code, tests, and documentation as needed
Test your work: Verify the implementation works correctly

After Completing a Sub-Task

Update task list: Mark the sub-task as [x]
Check parent task: If all sub-tasks done, mark parent as [x], then follow the Parent Task Completion protocol (commit before proceeding)
Update Relevant Files: Add any new files created
Save the task list file: Persist the changes
Report to user: Briefly describe what was completed
Request permission: Ask "Ready to move to the next sub-task?" or similar
Wait: Do not proceed until the user confirms

AI Instructions

When working with task lists, you must:

Regularly update the task list file after finishing any significant work
Follow the completion protocol:
- Mark each finished sub-task [x]
- Mark parent task [x] once all its subtasks are [x]
Add newly discovered tasks if additional work is identified
Keep "Relevant Files" accurate and up to date
Check which sub-task is next before starting work
Pause after each sub-task and wait for user approval

User Permission Phrases

Accept these as permission to continue to the next sub-task:

"yes"
"y"
"go"
"continue"
"next"
"proceed"
"keep going"

Do NOT continue if the user:

Asks questions
Requests changes
Wants to review something
Says "wait", "hold on", "stop", etc.

Handling Changes and Additions

Discovered Issues

If you discover issues while implementing:

Add a new task or sub-task to the list
Inform the user about the addition
Ask if they want to address it now or later

Task Modifications

If the user requests changes to the task list:

Update the task list as requested
Confirm the changes with the user
Resume from the current position

Skipping Tasks

If the user wants to skip a task:

Mark it with a note (e.g., - [ ] 2.3 [SKIPPED] Original description)
Continue to the next task
Update the parent task status appropriately

Quality Focus

This one-task-at-a-time approach ensures:

Thoroughness: Each task gets full attention
Quality: Work is reviewed before moving on
Alignment: User can course-correct at each step
Documentation: Progress is clearly tracked
Learning: Junior developers see proper implementation pace

Example Interaction

AI: "I've completed sub-task 1.2: Create login endpoint. The endpoint is now functional with proper error handling. I've marked it as complete in the task list. Ready to move to sub-task 1.3: Implement credential validation?"

User: "yes"

AI: [Proceeds to work on sub-task 1.3]

File Location

Task lists follow this structure:

Path: .planning/[project-name]/tasks/tasks-[prd-name].md
Example: .planning/my-auth-project/tasks/tasks-prd-user-authentication.md

Always work within the project's directory structure.

gsdl-execute-plan