Execution Tracking

Execution Tracking

Status file management and progress reporting for the implementation plugin.

Overview

This skill provides comprehensive execution tracking capabilities including status file initialization, task completion tracking, progress calculation, report generation, and metrics aggregation. Manages execution state in .claude/execution/ directory with JSON-based status files.

When to Use This Skill

Use this skill when:

• Initializing execution tracking for a feature implementation
• Updating task completion status during execution
• Generating progress reports showing current state
• Calculating completion metrics and percentages
• Tracking layer-by-layer execution progress
• Monitoring overall feature implementation status
• Identifying next actions and pending tasks
• Logging execution errors and warnings

Core Capabilities

1. Initialize Execution Tracking

Script: scripts/update-status.sh init <spec-id>

Creates new execution status file from layered tasks specification.

What it does:

• Reads specs/<spec>/layered-tasks.md to extract task structure
• Creates .claude/execution/<spec>.json status file
• Initializes all layers with "pending" status
• Sets up task tracking for each layer
• Calculates total task count

Example:

bash scripts/update-status.sh init F001
# Creates: .claude/execution/F001.json

2. Update Task Status

Script: scripts/update-status.sh update <spec> <layer> <task-index> <status>

Updates individual task completion status.

Supported statuses:

• complete - Task successfully completed
• failed - Task execution failed
• skipped - Task skipped (dependency issue)
• in_progress - Task currently executing

What it does:

• Updates task status and timestamp
• Records execution duration (if complete)
• Recalculates layer metrics
• Recalculates overall progress
• Updates last_updated timestamp

Example:

bash scripts/update-status.sh update F001 L1 2 complete
# Marks third task in L1 as complete

3. Mark Layer Complete

Script: scripts/update-status.sh complete-layer <spec> <layer>

Marks entire layer as complete and advances to next layer.

What it does:

• Verifies all layer tasks are complete
• Sets layer status to "complete"
• Records layer completion timestamp
• Advances current_layer to next layer
• Recalculates overall metrics

Example:

bash scripts/update-status.sh complete-layer F001 L0
# Marks L0 complete, advances to L1

4. Log Execution Error

Script: scripts/update-status.sh error <spec> <layer> <task-index> <error-message>

Logs execution errors for troubleshooting.

What it does:

• Adds error to errors array
• Records layer, task, and timestamp
• Categorizes error severity
• Updates task status to "failed"
• Generates error report

Example:

bash scripts/update-status.sh error F001 L1 3 "API endpoint creation failed: invalid path syntax"

5. Generate Progress Report

Script: scripts/update-status.sh report <spec>

Creates comprehensive progress report from status file.

Report includes:

• Overall progress percentage
• Layer-by-layer status breakdown
• Current executing task
• Next pending tasks
• Recent errors (if any)
• Estimated time remaining
• Next recommended action

Output:

Feature F001: AI Chat Interface
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Overall Progress: 38% (5/13 tasks)
Time Elapsed: 30 minutes
Estimated Remaining: 49 minutes

Layer 0 (Infrastructure):  ✅ Complete (2/2 tasks)
Layer 1 (Core Services):   🔄 In Progress (3/5 tasks)
Layer 2 (Features):        ⏳ Pending (0/4 tasks)
Layer 3 (Integration):     ⏳ Pending (0/2 tasks)

Currently Executing:
- Create message API endpoint (fastapi-agent, medium) - Started 5m ago

Next 3 Pending Tasks:
1. [L1] Implement chat storage (supabase-agent, easy)
2. [L1] Add user authentication (auth-agent, medium)
3. [L2] Build chat UI component (react-agent, hard)

Errors: 0

Next Action: Continue L1 execution with /implementation:execute F001 --layer=L1

Status File Schema

Location

.claude/execution/<spec>.json (e.g., .claude/execution/F001.json)

Complete Schema

{
  "feature": "F001",
  "feature_name": "AI Chat Interface",
  "started_at": "2025-11-17T12:00:00Z",
  "last_updated": "2025-11-17T12:30:00Z",
  "status": "in_progress",
  "current_layer": "L1",
  "total_tasks": 13,
  "completed_tasks": 5,
  "failed_tasks": 0,
  "skipped_tasks": 0,
  "completion_percentage": 38,
  "average_task_duration_ms": 1450,
  "estimated_remaining_ms": 11600,
  "layers": {
    "L0": {
      "name": "Infrastructure",
      "status": "complete",
      "total_tasks": 2,
      "completed_tasks": 2,
      "failed_tasks": 0,
      "started_at": "2025-11-17T12:00:00Z",
      "completed_at": "2025-11-17T12:10:00Z",
      "duration_ms": 600000,
      "tasks": [
        {
          "index": 0,
          "description": "Setup database schema",
          "command": "/supabase:create-schema chat",
          "agent": "supabase-agent",
          "complexity": "easy",
          "status": "complete",
          "started_at": "2025-11-17T12:00:00Z",
          "completed_at": "2025-11-17T12:05:00Z",
          "duration_ms": 300000,
          "output": "Created schema successfully",
          "files_created": ["supabase/migrations/001_chat_schema.sql"]
        },
        {
          "index": 1,
          "description": "Initialize API structure",
          "command": "/fastapi-backend:init api",
          "agent": "fastapi-agent",
          "complexity": "easy",
          "status": "complete",
          "started_at": "2025-11-17T12:05:00Z",
          "completed_at": "2025-11-17T12:10:00Z",
          "duration_ms": 300000,
          "output": "API structure initialized",
          "files_created": ["backend/app/main.py", "backend/app/routers/__init__.py"]
        }
      ]
    },
    "L1": {
      "name": "Core Services",
      "status": "in_progress",
      "total_tasks": 5,
      "completed_tasks": 3,
      "failed_tasks": 0,
      "started_at": "2025-11-17T12:10:00Z",
      "tasks": [...]
    },
    "L2": {
      "name": "Features",
      "status": "pending",
      "total_tasks": 4,
      "completed_tasks": 0,
      "failed_tasks": 0,
      "tasks": [...]
    },
    "L3": {
      "name": "Integration",
      "status": "pending",
      "total_tasks": 2,
      "completed_tasks": 0,
      "failed_tasks": 0,
      "tasks": [...]
    }
  },
  "errors": [],
  "warnings": [],
  "next_action": "Continue L1: 2 tasks remaining"
}

Metrics Calculation Formulas

Overall Progress

completion_percentage = (completed_tasks / total_tasks) * 100

Layer Progress

layer_percentage = (layer.completed_tasks / layer.total_tasks) * 100

Average Task Duration

avg_task_duration = sum(all_completed_task_durations) / completed_tasks

Estimated Time Remaining

remaining_tasks = total_tasks - completed_tasks
estimated_remaining = avg_task_duration * remaining_tasks

Success Rate

attempted_tasks = completed_tasks + failed_tasks + skipped_tasks
success_rate = (completed_tasks / attempted_tasks) * 100

Layer Duration

layer_duration = layer.completed_at - layer.started_at

Status Indicators

Layer Status Icons

• ✅ Complete - 100% tasks complete, layer finished
• 🔄 In Progress - 1-99% tasks complete, actively working
• ⏳ Pending - 0% complete, not yet started
• ❌ Failed - Has failed tasks, execution blocked

Overall Status Values

• pending - Not started (0% complete)
• in_progress - Some tasks complete (1-99%)
• paused - Execution paused (manual intervention needed)
• complete - All tasks done (100% complete)
• failed - Critical error, cannot continue

Task Status Values

• pending - Not yet started
• in_progress - Currently executing
• complete - Successfully finished
• failed - Execution failed
• skipped - Skipped due to dependency

Usage Patterns

From /implementation:execute Command

# Initialize tracking
bash scripts/update-status.sh init F001

# Update tasks as they complete
bash scripts/update-status.sh update F001 L0 0 complete
bash scripts/update-status.sh update F001 L0 1 complete

# Mark layer complete
bash scripts/update-status.sh complete-layer F001 L0

# Generate report
bash scripts/update-status.sh report F001

From progress-tracker Agent

# Agent reads status file
status=$(cat .claude/execution/F001.json)

# Agent updates task status
bash scripts/update-status.sh update F001 L1 2 complete

# Agent generates report for user
bash scripts/update-status.sh report F001

Error Handling

# Log error when task fails
bash scripts/update-status.sh error F001 L1 3 "Database connection timeout"

# Check error count before continuing
error_count=$(jq '.errors | length' .claude/execution/F001.json)
if [ "$error_count" -gt 5 ]; then
  echo "Too many errors, pausing execution"
  bash scripts/update-status.sh pause F001
fi

Templates

See templates/ directory for:

• execution-status.json - Complete status file template with all fields
• status-report.md - Progress report template for formatting
• error-log.json - Error entry template with severity levels

Examples

See examples/ directory for:

• status-examples.md - Example status files at different execution stages
• workflow-integration.md - How to integrate tracking into execution workflow
• error-scenarios.md - Common error scenarios and recovery patterns

Best Practices

1. Initialize before execution - Always create status file before starting implementation
2. Update after each task - Keep status current by updating immediately after task completion
3. Log all errors - Record errors for debugging and troubleshooting
4. Generate reports regularly - Create reports to show progress to users
5. Calculate metrics accurately - Use formulas consistently for accurate percentages
6. Handle edge cases - Account for skipped tasks, failed tasks, and paused execution
7. Preserve history - Don't delete status files, archive them after completion
8. Use timestamps consistently - All timestamps in ISO 8601 UTC format

Integration Points

Used by:

• /implementation:execute command - Main execution orchestrator
• progress-tracker agent - Real-time progress monitoring
• error-handler agent - Error logging and recovery
• /implementation:status command - Status reporting

Depends on:

• layered-tasks.md - Source of task definitions
• features.json - Feature metadata
• Bash shell - Script execution environment

Location: plugins/implementation/skills/execution-tracking/ Purpose: Comprehensive execution status management Complexity: Medium - Requires JSON manipulation and metric calculation