Task Execution

Execute structured tasks phase-by-phase with automatic status tracking, testing, and progress reporting.

Core Workflow

Step 1: Determine Which Phase to Execute

If user specifies a phase number:

• •Use that specific phase (e.g., "execute phase 2")

If user says "continue task" or doesn't specify:

1. •Use task_status_reader.py to read the task file
2. •Find the last phase that is NOT pending (could be in-progress or completed)
3. •Execute the next pending phase after that

If user specifies a task file path:

• •Use that file, otherwise look in _tasks/ directory

Step 2: Read and Validate Task Status

python scripts/task_status_reader.py _tasks/Task-XXX_Name.md

Validation checks:

1. •Verify the task file exists and is readable
2. •Parse the phase to be executed
3. •Check all prerequisites are marked complete ([x])
4. •If prerequisites are not complete, ask user if they want to proceed anyway

Safety check for in-progress phases:

• •If the phase status is already in-progress, ask the user:
  • •"Phase X is already marked as in-progress. Do you want to continue where it left off or restart it?"

Step 3: Update Status to In-Progress

Before starting work, update the phase status:

python scripts/task_status_updater.py _tasks/Task-XXX_Name.md phase <phase_number> in-progress

Also update task-level status to in-progress if it's still pending:

python scripts/task_status_updater.py _tasks/Task-XXX_Name.md task in-progress

Step 4: Execute Phase Work

For each file listed in the phase:

1. •Files to Modify: Apply the changes described
2. •Files to Create: Create new files with appropriate content
3. •Files to Delete: Remove files as specified

As you work, progressively update the task file:

• •Check off deliverables as they are completed:
  bash

  python scripts/task_status_updater.py _tasks/Task-XXX_Name.md check <phase_number> deliverables "deliverable text"
  

Progress reporting:

• •Show what file you're currently working on
• •Report when each deliverable is completed
• •Keep the user informed of progress

Step 5: Run Tests (If Tests Exist in Project)

Important: Testing is ONLY required if the project has tests!

Determine which tests to run:

1. •Only run tests related to files that were modified or created
2. •Use the test commands specified in the phase's "Test Commands" section
3. •Parse the commands to identify specific test files/patterns

Test execution:

# Example: Run specific test file
npm test -- path/to/modified-feature.test.js

# Example: Run tests matching pattern
pytest tests/test_modified_feature.py

# Example: Run with coverage
dotnet test --filter FullyQualifiedName~ModifiedClass

If tests fail:

1. •Analyze the error messages
2. •Fix the issues in the code
3. •Re-run tests
4. •Repeat until all tests pass
5. •NEVER mark phase as failed - always fix and retry

After tests pass:

• •Check off test requirements:
  bash

  python scripts/task_status_updater.py _tasks/Task-XXX_Name.md check <phase_number> test_requirements "Unit tests"
  

If project has no tests:

• •Skip testing step entirely
• •Still check off test requirements to track completion

Step 6: Verify Phase Completion

Check that all items are complete:

• •All deliverables checked: [x]
• •All test requirements checked: [x] (if tests exist)
• •All files created/modified/deleted as specified

Verification script can help:

python scripts/task_status_reader.py _tasks/Task-XXX_Name.md

Step 7: Update Status to Completed

Mark the phase as completed:

python scripts/task_status_updater.py _tasks/Task-XXX_Name.md phase <phase_number> completed

Check if all phases are complete:

• •If this was the last phase, update task status to completed:
  bash

  python scripts/task_status_updater.py _tasks/Task-XXX_Name.md task completed
  

Step 8: Report Completion

Provide a summary:

• •Phase number and name
• •What was accomplished
• •Files modified/created/deleted
• •Test results (if tests were run)
• •Next phase preview (if any remaining)

Example completion report:

✅ Phase 2: Business Logic Implementation - COMPLETED

Accomplished:
- Created src/services/AuthService.js with authentication logic
- Modified src/controllers/UserController.js to integrate auth
- Added validation for user credentials

Tests: All 15 tests passed ✅

Next: Phase 3 - API Integration (status: pending)

Stop execution after completion - Do NOT automatically continue to next phase.

Guidelines

Only Execute What's Requested

• •Execute ONLY the specified phase
• •Never execute multiple phases in sequence automatically
• •If no phase specified, find next pending phase and execute only that one
• •Stop after phase completion and wait for user instruction

Continuous Status Updates

• •Update task file status throughout execution, not just at the end
• •Check off deliverables as they're completed
• •Keep timestamps current
• •Maintain accurate progress tracking

Testing Strategy

Key principle: Only test what changed!

• •Only run tests for modified/created files
• •Don't run the entire test suite unless necessary
• •Testing is optional - skip if project has no tests
• •Parse test commands to find specific tests to run

Error correction approach:

• •Never mark phases as failed
• •Always attempt to fix test failures
• •Analyze error messages and correct the code
• •Re-run tests until they pass
• •Keep trying until phase completes successfully

Prerequisite Validation

• •Always check prerequisites before starting
• •If not all checked, warn user but allow override
• •Prerequisites from previous phases should already be complete
• •Verify critical dependencies exist

Safety Features

Before starting:

1. •Confirm which phase to execute
2. •Validate prerequisites
3. •Check for in-progress conflicts
4. •Verify task file integrity

During execution:

1. •Regular progress updates
2. •Continuous status tracking
3. •Immediate error reporting
4. •Clear communication with user

After completion:

1. •Comprehensive summary
2. •Test results (if applicable)
3. •Next steps preview
4. •Stop and wait for instruction

Progress Visibility

Show progress clearly:

• •"🔄 Working on: src/services/AuthService.js"
• •"✅ Completed: User validation logic"
• •"🧪 Running tests: npm test -- auth.test.js"
• •"✅ All tests passed (12/12)"

Regular updates keep user informed:

• •Current file being worked on
• •Deliverables completed
• •Test execution status
• •Any issues encountered and fixes applied

Script Reference

task_status_reader.py

Parse task files and extract current status.

Usage:

python scripts/task_status_reader.py <task_file_path>

Output:

• •Task metadata (id, title, status, priority)
• •All phases with their status
• •Prerequisites and deliverables completion
• •Next phase to execute

task_status_updater.py

Update phase status, task status, and checkboxes.

Update phase status:

python scripts/task_status_updater.py <task_file> phase <phase_num> <status>
# Example: python scripts/task_status_updater.py _tasks/Task-001.md phase 2 in-progress

Update task status:

python scripts/task_status_updater.py <task_file> task <status>
# Example: python scripts/task_status_updater.py _tasks/Task-001.md task completed

Check individual checkbox:

python scripts/task_status_updater.py <task_file> check <phase_num> <section> <item_text>
# Example: python scripts/task_status_updater.py _tasks/Task-001.md check 2 deliverables "Create service"

Check all checkboxes in section:

python scripts/task_status_updater.py <task_file> check-all <phase_num> <section>
# Example: python scripts/task_status_updater.py _tasks/Task-001.md check-all 2 test_requirements

Sections:

• •prerequisites
• •deliverables
• •test_requirements

Status values:

• •Phase: pending, in-progress, completed
• •Task: pending, in-progress, completed

Common Patterns

Execute Next Pending Phase

# 1. Read task status
python scripts/task_status_reader.py _tasks/Task-001_Feature.md

# 2. Identify next pending phase (e.g., Phase 2)

# 3. Update to in-progress
python scripts/task_status_updater.py _tasks/Task-001_Feature.md phase 2 in-progress

# 4. Do the work...

# 5. Run relevant tests
npm test -- feature.test.js

# 6. Mark completed
python scripts/task_status_updater.py _tasks/Task-001_Feature.md phase 2 completed

Execute Specific Phase

# User: "Execute phase 3 of Task-001"

# 1. Read and validate
python scripts/task_status_reader.py _tasks/Task-001_Feature.md

# 2. Check if phase 3 prerequisites are met

# 3. Update status
python scripts/task_status_updater.py _tasks/Task-001_Feature.md phase 3 in-progress

# 4. Execute phase work...

# 5. Complete
python scripts/task_status_updater.py _tasks/Task-001_Feature.md phase 3 completed

Continue After Interruption

# User: "Continue the task"

# 1. Read current status
python scripts/task_status_reader.py _tasks/Task-001_Feature.md

# 2. Find last non-pending phase (e.g., Phase 2 is completed)

# 3. Execute next phase (Phase 3)
python scripts/task_status_updater.py _tasks/Task-001_Feature.md phase 3 in-progress

# ... work continues

Example Execution Flow

User request: "Continue Task-001"

Step 1 - Determine phase:

$ python scripts/task_status_reader.py _tasks/Task-001_UserAuth.md
Task: Task-001 - User Authentication
Status: in-progress
Phases (4):
  ✅ Phase 1: Foundation [completed]
  ✅ Phase 2: Business Logic [completed]
  ⏸️ Phase 3: API Integration [pending]
  ⏸️ Phase 4: Testing & Documentation [pending]

Next phase to execute: Phase 3 - API Integration

Step 2 - Validate and start:

$ python scripts/task_status_updater.py _tasks/Task-001_UserAuth.md phase 3 in-progress
✅ Phase 3 status updated to 'in-progress'

Step 3 - Execute work:

🔄 Starting Phase 3: API Integration

Prerequisites check:
✅ All prerequisites met

Working on deliverables:
🔄 Creating src/routes/auth.routes.js...
✅ Deliverable 1/3 completed

🔄 Modifying src/app.js to register routes...
✅ Deliverable 2/3 completed

🔄 Adding authentication middleware...
✅ Deliverable 3/3 completed

Step 4 - Test:

🧪 Running tests for modified files...
$ npm test -- auth.routes.test.js

✅ All 8 tests passed

Checking test requirements...
✅ Unit tests
✅ Integration tests

Step 5 - Complete:

$ python scripts/task_status_updater.py _tasks/Task-001_UserAuth.md phase 3 completed
✅ Phase 3 status updated to 'completed'

Step 6 - Report:

✅ Phase 3: API Integration - COMPLETED

Accomplished:
- Created authentication routes (src/routes/auth.routes.js)
- Integrated routes into main app
- Added JWT middleware for protected endpoints

Files:
- Created: 1 file
- Modified: 2 files

Tests: 8/8 passed ✅

Next: Phase 4 - Testing & Documentation (status: pending)