| name | execution-tracking |
| description | Execution status management and reporting for implementation plugin. Use when initializing execution tracking, updating task status, generating progress reports, calculating completion metrics, tracking layer execution, monitoring feature implementation progress, or when user mentions execution status, progress tracking, or implementation monitoring. |
| allowed-tools | Bash, Read, Write, Edit, Glob |
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
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 completedfailed - Task execution failedskipped - 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
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
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 startedin_progress - Currently executingcomplete - Successfully finishedfailed - Execution failedskipped - Skipped due to dependency
Usage Patterns
From /implementation:execute Command
bash scripts/update-status.sh init F001
bash scripts/update-status.sh update F001 L0 0 complete
bash scripts/update-status.sh update F001 L0 1 complete
bash scripts/update-status.sh complete-layer F001 L0
bash scripts/update-status.sh report F001
From progress-tracker Agent
status=$(cat .claude/execution/F001.json)
bash scripts/update-status.sh update F001 L1 2 complete
bash scripts/update-status.sh report F001
Error Handling
bash scripts/update-status.sh error F001 L1 3 "Database connection timeout"
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
- Initialize before execution - Always create status file before starting implementation
- Update after each task - Keep status current by updating immediately after task completion
- Log all errors - Record errors for debugging and troubleshooting
- Generate reports regularly - Create reports to show progress to users
- Calculate metrics accurately - Use formulas consistently for accurate percentages
- Handle edge cases - Account for skipped tasks, failed tasks, and paused execution
- Preserve history - Don't delete status files, archive them after completion
- Use timestamps consistently - All timestamps in ISO 8601 UTC format
Integration Points
Used by:
/implementation:execute command - Main execution orchestratorprogress-tracker agent - Real-time progress monitoringerror-handler agent - Error logging and recovery/implementation:status command - Status reporting
Depends on:
layered-tasks.md - Source of task definitionsfeatures.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
