Execute Tasks

Execute-Tasks Skill

Purpose

Sequentially execute tasks from ai-state/active/tasks.yaml with proper context gathering, phase-appropriate testing, automatic test organization, status tracking, and comprehensive logging.

When to Use

Use this skill when:

• After /write-plan creates tasks.yaml
• Starting development work
• Resuming work after breaks
• Processing task backlog
• Executing sprint work

CRITICAL: Logging Requirements

BEFORE YOU DO ANYTHING ELSE, LOG IT!

Use the unified logging system via .claude\scripts\log_task.bat (Windows) or log_operation.py:

# Simple format (Windows):
.claude\scripts\log_task.bat TYPE TASK_ID "message"

# Full format (cross-platform):
python .claude/scripts/log_operation.py --type TYPE --task TASK_ID "message"

Required logging for EVERY task:

1. Log "Step X: [Step Name]" BEFORE starting each major step (1-8)
2. Log narrative BEFORE executing each substep that modifies state
3. Log all mandatory operation events (task.started, context.gathered, etc.)

Example logging sequence for Step 2:

# Log step header
.claude\scripts\log_task.bat narrative task-001-fastapi-setup "Step 2: Gather Context"

# Log substep 2.1
.claude\scripts\log_task.bat narrative task-001-fastapi-setup "Step 2.1: Load relevant files"

# Log substep 2.2
.claude\scripts\log_task.bat narrative task-001-fastapi-setup "Step 2.2: Save context snapshot"

# Log narrative before action (substep 2.3)
.claude\scripts\log_task.bat narrative task-001-fastapi-setup "Gathering context from backend standards and checking existing project files"

# Log completion (substep 2.4)
.claude\scripts\log_task.bat context task-001-fastapi-setup

DO NOT skip these logs! They provide visibility into your execution process.

See .claude/scripts/LOGGING_GUIDE.md for complete reference.

Step-by-Step Execution Process

For each task with status: pending in tasks.yaml, follow these steps in exact order:

Step 1: Load and Prepare Task

FIRST: Log this step header

.claude\scripts\log_task.bat narrative {task_id} "Step 1: Load and Prepare Task"

1.1 Read the task and sprint context:

• Read ai-state/active/tasks.yaml
• Extract top-level: phase
• Navigate into sprints array, find current sprint
• Extract sprint context: sprint, milestone, complexity_range
• Find first task with status: pending within the sprint's tasks
• Extract task fields: id, status, complexity, context, who, where, what, how, goal, check, close

1.2 Update status to in_progress:

• Use Edit tool to change task status from pending to in_progress in tasks.yaml
• Save the file

1.3 Log task start:

.claude\scripts\log_task.bat started {task_id} "{what}"

1.4 Create progress tracking:

• Use TodoWrite to create entry for this task with status in_progress

Step 2: Gather Context

FIRST: Log this step header

.claude\scripts\log_task.bat narrative {task_id} "Step 2: Gather Context"

2.1 Load relevant files:

.claude\scripts\log_task.bat narrative {task_id} "Step 2.1: Load relevant files"

• Read files mentioned in task's where field
• Read standards from ai-state/standards/{standard}.md if referenced in how
• Search for related code in codebase

2.2 Save context snapshot:

.claude\scripts\log_task.bat narrative {task_id} "Step 2.2: Save context snapshot"

• Create ai-state/contexts/{sprint}/{task_id}.md with:
  • Full task specification
  • Relevant code snippets
  • Standards being followed
  • Dependencies noted
• NOTE: Contexts are organized by sprint folder for better organization

2.3 Log narrative action:

.claude\scripts\log_task.bat narrative {task_id} "Gathering context from backend standards and checking existing project files"

2.4 Log context gathering:

.claude\scripts\log_task.bat context {task_id}

Step 3: Execute Implementation

FIRST: Log this step header

.claude\scripts\log_task.bat narrative {task_id} "Step 3: Execute Implementation"

3.1 Implement the feature:

• Follow the what description exactly
• Achieve the goal criteria
• Reference standards from how field
• Write files to locations in where field

3.2 Use appropriate tools:

• Write tool for new files
• Edit tool for existing files
• Follow coding standards from the how field

3.3 Log narrative action:

.claude\scripts\log_task.bat narrative {task_id} "Creating requirements.txt and main.py with FastAPI initialization"

3.4 Log implementation:

.claude\scripts\log_task.bat implemented {task_id}

Step 4: Write Phase-Appropriate Tests

FIRST: Log this step header

.claude\scripts\log_task.bat narrative {task_id} "Step 4: Write Phase-Appropriate Tests"

4.1 Determine required test count: Read .khujta/phase.json and write tests based on phase:

• Prototype: 2 tests (smoke + happy path)
• MVP: 4 tests (smoke, happy, error, auth)
• Growth: 5 tests (+ edge cases)
• Scale: 6-8 tests as needed

4.2 Create test file:

• Name: test_{component}.py (or appropriate for stack)
• Location: Project root directory (will move later)
• Use Write tool to create file

4.3 Write test cases:

• Test 1 (smoke): Basic functionality from check.valid
• Test 2 (happy path): Main use case from goal
• Additional tests per phase requirements
• Cover check.error scenarios

4.4 Log narrative action:

.claude\scripts\log_task.bat narrative {task_id} "Writing 2 tests (smoke + happy path) for FastAPI server startup validation"

4.5 Log test creation:

.claude\scripts\log_task.bat tests-written {task_id} "2 tests"

Step 5: Run Tests and Verify

FIRST: Log this step header

.claude\scripts\log_task.bat narrative {task_id} "Step 5: Run Tests and Verify"

5.1 Execute tests:

• Use Bash tool: pytest test_{component}.py -v
• Capture output

5.2 If tests FAIL:

1. Debug the issue
2. Fix implementation or test
3. Re-run tests
4. Repeat until ALL tests pass
5. DO NOT proceed until tests pass

5.3 Log test results:

.claude\scripts\log_task.bat tests-passed {task_id} "2/2 passing"

Step 6: Organize Tests into Regressions

FIRST: Log this step header

.claude\scripts\log_task.bat narrative {task_id} "Step 6: Organize Tests into Regressions"

6.1 Determine destination:

• Use task's context field (backend/frontend/database/devops)
• Destination: ai-state/regressions/{context}/

6.2 Create directory if needed:

• Use Bash: mkdir -p ai-state/regressions/{context}

6.3 Log narrative action:

.claude\scripts\log_task.bat narrative {task_id} "Moving tests to ai-state/regressions/backend/ directory for organization"

6.4 Move test file:

• Use Bash: mv test_{component}.py ai-state/regressions/{context}/

6.5 Verify tests still work:

• Run: pytest ai-state/regressions/{context}/test_{component}.py -v
• Update imports if paths changed

6.6 Log organization:

.claude\scripts\log_task.bat tests-organized {task_id} "ai-state/regressions/{context}/"

Step 7: Complete Task

7.1 Verify completion criteria:

• Check task meets the close criteria
• Verify all check requirements passed

7.2 Update status to completed:

• Use Edit tool to change status from in_progress to completed in tasks.yaml
• Save tasks.yaml

7.3 Log completion:

.claude\scripts\log_task.bat completed {task_id} "{close}"

7.4 Update progress tracking:

• Use TodoWrite to mark task as completed

Step 8: Proceed to Next Task

8.1 Check sprint boundary:

• Read tasks.yaml and identify current sprint (sprint with in_progress or just-completed tasks)
• Check if current sprint has any remaining status: pending tasks
• If current sprint is complete BUT next sprint has pending tasks:
  • STOP EXECUTION - Do not proceed to next sprint automatically
  • Show message: "Sprint {N} complete. Run /core:execute-tasks again to start Sprint {N+1}"
  • This allows human review of sprint completion before starting next sprint

8.2 Find next task in CURRENT sprint:

• Look for next task with status: pending in the current sprint only
• Check task's when field for dependencies
• If dependencies not met, skip to next available task in current sprint

8.3 Repeat process:

• If pending task found in current sprint: Return to Step 1 with the new task
• If no pending tasks in current sprint: Proceed to Step 9

8.4 When current sprint complete:

• If no more pending tasks in current sprint, proceed to Step 9: Sprint Completion
• Do NOT automatically continue to next sprint

Step 9: Sprint Completion (When Current Sprint Done)

TRIGGER: When no more pending tasks remain in the current sprint

9.1 Verify sprint completion:

• Count tasks with status: completed in current sprint
• Count tasks with status: blocked or failed in current sprint
• Confirm all tasks in current sprint have a final status (no pending remain)

9.2 Run sprint completion script:

python .claude/scripts/complete_sprint.py

This automatically generates:

1. Test runner scripts: ai-state/regressions/{context}/run.bat and run.sh
2. Sprint report: ai-state/reports/{sprint}-report.md
3. Test results: ai-state/reports/{sprint}-test-results.json
4. Human docs: ai-state/human-docs/{sprint}-summary.md
5. Operations log entry: Sprint completion logged

9.3 Verify outputs:

• Check that all regression tests passed
• Review sprint report for completeness
• Confirm human docs are stakeholder-ready

9.4 Check for next sprint:

• If more sprints exist in tasks.yaml with pending tasks:
  • Display message: "✅ Sprint {N} complete! Review reports in ai-state/reports/ and ai-state/human-docs/"
  • Display message: "📋 Sprint {N+1} is ready. Run /core:execute-tasks when ready to start."
  • STOP - Do not continue automatically
• If no more sprints:
  • Display message: "🎉 All sprints complete! Project ready for next phase."

NOTE: Sprint completion runs in ALL phases including prototype. It's no longer just for Growth/Scale phases.

Required Log Entries Per Task

Every task execution MUST create these log entries in ai-state/operations.log:

Mandatory Operation Logs (7 minimum)

1. [timestamp] [phase] [sprint] task.started: {task_id} - {what}
2. [timestamp] [phase] [sprint] context.gathered: {task_id}
3. [timestamp] [phase] [sprint] implementation.complete: {task_id}
4. [timestamp] [phase] [sprint] tests.written: {task_id} - {count} tests
5. [timestamp] [phase] [sprint] tests.passed: {task_id} - {count}/{count} passing
6. [timestamp] [phase] [sprint] tests.organized: {task_id} → ai-state/regressions/{context}/
7. [timestamp] [phase] [sprint] task.completed: {task_id} - {close}

Narrative Logs (4 minimum - logged BEFORE executing each major step)

Before Step 2: [timestamp] [phase] [sprint] narrative: {task_id} - {description of what you're about to do} Before Step 3: [timestamp] [phase] [sprint] narrative: {task_id} - {description of implementation about to execute} Before Step 4: [timestamp] [phase] [sprint] narrative: {task_id} - {description of tests about to write} Before Step 6: [timestamp] [phase] [sprint] narrative: {task_id} - {description of test organization}

Examples of narrative logs:

• "narrative: task-001 - Gathering context from backend standards and checking existing files"
• "narrative: task-001 - Creating requirements.txt and main.py with FastAPI initialization"
• "narrative: task-001 - Writing 2 tests (smoke + happy path) for server startup validation"
• "narrative: task-001 - Moving tests to ai-state/regressions/backend/ directory"

Total minimum log entries per task: 11 (7 mandatory operations + 4 narratives)

Log Format:

• [timestamp]: ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
• [phase]: Phase from top-level tasks.yaml (e.g., prototype, mvp)
• [sprint]: Sprint name from sprints array (e.g., sprint-1)
• {task_id}: Task identifier (e.g., task-001-fastapi-setup)
• Additional context as specified per entry

Phase Requirements Reference

Prototype (0-100 users, 30 min to ship):

• Tests: 2 (smoke + happy path)
• Coverage: 40%
• Quality: 6.0/10

MVP (100-1K users, 1-2 hours):

• Tests: 4 (+ errors + auth)
• Coverage: 60%
• Quality: 7.0/10

Growth (1K-10K users, 2-4 hours):

• Tests: 5 (+ edge cases)
• Coverage: 70%
• Quality: 7.5/10

Scale (10K+ users, 4-8 hours):

• Tests: 6-8 as needed
• Coverage: 80%
• Quality: 8.0/10

Error Handling

If implementation fails:

1. Log error to operations.log: [timestamp] [epic] [sprint] task.failed: {task_id} - {error}
2. Update status to blocked in tasks.yaml
3. Create note in ai-state/debt/{task_id}-failure.md
4. Skip to next task

If tests fail after 3 attempts:

1. Log: [timestamp] [epic] [sprint] tests.failed: {task_id} - {failure_details}
2. Mark task as blocked
3. Save test output to ai-state/debt/{task_id}-test-failures.txt
4. Skip to next task

If dependencies missing:

1. Log: [timestamp] [epic] [sprint] task.blocked: {task_id} - waiting for {dependency}
2. Update status to blocked
3. Skip to next available task

Files Modified

Reads from:

• ai-state/active/tasks.yaml
• .khujta/phase.json
• ai-state/standards/{standard}.md
• Files mentioned in task's where

Writes to:

• ai-state/operations.log (append all operations)
• ai-state/active/tasks.yaml (update status fields)
• ai-state/contexts/{sprint}/{task_id}.md (save context)
• ai-state/regressions/{context}/ (move test files)
• Implementation files per task's where field
• ai-state/reports/{sprint}-*.md (on sprint completion)
• ai-state/human-docs/{sprint}-*.md (on sprint completion)

Tools Required

• Read: Load tasks, context, standards
• Write: Create new implementation files, tests, context docs
• Edit: Modify existing files, update tasks.yaml status
• Bash: Run tests, create directories, move files
• TodoWrite: Track real-time progress

Success Criteria

A successful execution produces:

✅ All pending tasks now completed or blocked with documented reason ✅ All tests passing and organized in ai-state/regressions/{context}/ ✅ Complete operations.log with minimum 11 entries per task (7 operations + 4 narratives) ✅ Updated tasks.yaml with all status changes ✅ Context preserved in ai-state/contexts/{sprint}/{task_id}.md for each task ✅ TodoWrite list reflects final state ✅ Sprint completion reports generated (when all tasks done)

Critical Rules

• Sequential only: Execute one task at a time, never skip ahead
• Status updates required: Always update tasks.yaml before and after each task
• Tests must pass: Never mark task completed if tests are failing
• Tests must be organized: Always move tests to ai-state/regressions/
• Logging is mandatory: Every operation AND narrative must be logged to operations.log (min 11 per task)
• Narrative before action: Always log narrative description BEFORE executing each major step
• TodoWrite for visibility: Use TodoWrite for real-time progress tracking
• Phase/Sprint context: Always extract and include phase/sprint in ALL log entries

Example Log Entries

For task-001-fastapi-setup in prototype phase, sprint-1:

[2025-11-07T01:35:00Z] [prototype] [sprint-1] task.started: task-001-fastapi-setup - Setup FastAPI project structure
[2025-11-07T01:35:10Z] [prototype] [sprint-1] narrative: task-001-fastapi-setup - Gathering context from backend standards and checking existing project files
[2025-11-07T01:35:15Z] [prototype] [sprint-1] context.gathered: task-001-fastapi-setup
[2025-11-07T01:36:00Z] [prototype] [sprint-1] narrative: task-001-fastapi-setup - Creating requirements.txt and main.py with FastAPI initialization
[2025-11-07T01:36:30Z] [prototype] [sprint-1] implementation.complete: task-001-fastapi-setup
[2025-11-07T01:36:45Z] [prototype] [sprint-1] narrative: task-001-fastapi-setup - Writing 2 tests (smoke + happy path) for server startup validation
[2025-11-07T01:37:00Z] [prototype] [sprint-1] tests.written: task-001-fastapi-setup - 2 tests
[2025-11-07T01:37:10Z] [prototype] [sprint-1] tests.passed: task-001-fastapi-setup - 2/2 passing
[2025-11-07T01:37:15Z] [prototype] [sprint-1] narrative: task-001-fastapi-setup - Moving tests to ai-state/regressions/backend/ directory
[2025-11-07T01:37:20Z] [prototype] [sprint-1] tests.organized: task-001-fastapi-setup → ai-state/regressions/backend/
[2025-11-07T01:37:25Z] [prototype] [sprint-1] task.completed: task-001-fastapi-setup - Server running on localhost:8000

This format enables easy filtering:

• grep "prototype" operations.log - All operations for this phase
• grep "sprint-1" operations.log - All operations for this sprint
• grep "task-001" operations.log - All operations for specific task
• grep "task.completed" operations.log - All completed tasks
• grep "narrative:" operations.log - All narrative descriptions showing what was done