Implementation Progress Tracker

Implementation Progress Tracker

How to Use This Skill

1. Review the patterns and examples below
2. Apply the relevant patterns to your implementation
3. Follow the best practices outlined in this skill

Expert skill for tracking implementation progress across multi-file tasks with fuzzy path matching. Enables accurate progress reporting and checkpoint/resume capabilities.

When to Use

Use this skill when:

• Agent is implementing multiple files from a plan
• Need to track which files have been completed
• Implementing checkpoint/resume for long-running tasks
• Orchestrating multi-agent file implementation
• Displaying progress to users in todo lists
• Recovering from interrupted implementation sessions

Don't use this skill when:

• Single-file implementation (overhead not justified)
• Files don't follow predictable naming patterns
• Implementation is exploratory without a clear plan
• Real-time progress isn't needed

Core Algorithm

Fuzzy Path Matching

import os
from typing import List, Dict, Set, Optional
from dataclasses import dataclass, field
from datetime import datetime


@dataclass
class FileImplementationRecord:
    """Record of a file's implementation status"""
    planned_path: str
    implemented_path: Optional[str] = None
    status: str = "pending"  # pending, in_progress, completed, skipped
    started_at: Optional[datetime] = None
    completed_at: Optional[datetime] = None
    error: Optional[str] = None


class ImplementationTracker:
    """
    Track implementation progress with fuzzy path matching.

    Handles common path variations:
    - Full paths vs relative paths
    - Different base directories
    - Case sensitivity variations
    """

    def __init__(self, case_sensitive: bool = True):
        self.case_sensitive = case_sensitive
        self.planned_files: Dict[str, FileImplementationRecord] = {}
        self.implemented_files: Set[str] = set()

    def set_plan(self, planned_files: List[str]) -> None:
        """Set the list of files to be implemented"""
        self.planned_files = {
            path: FileImplementationRecord(planned_path=path)
            for path in planned_files
        }

    def _normalize_path(self, path: str) -> str:
        """Normalize path for comparison"""
        normalized = os.path.normpath(path)
        if not self.case_sensitive:
            normalized = normalized.lower()
        return normalized

    def _get_basename(self, path: str) -> str:
        """Get normalized basename"""
        basename = os.path.basename(path)
        if not self.case_sensitive:
            basename = basename.lower()
        return basename

    def is_implemented(self, plan_file: str, implemented_file: str) -> bool:
        """
        Check if implemented_file matches plan_file with fuzzy matching.

        Matching strategies (in order of preference):
        1. Exact match (after normalization)
        2. Partial path match (one ends with the other)
        3. Basename match (same filename)

        Args:
            plan_file: The file path from the plan
            implemented_file: The file path that was implemented

        Returns:
            True if the files match, False otherwise
        """
        plan_norm = self._normalize_path(plan_file)
        impl_norm = self._normalize_path(implemented_file)

        # Strategy 1: Exact match
        if plan_norm == impl_norm:
            return True

        # Strategy 2: Partial path match
        # Handle cases like "src/utils.py" matching "/project/src/utils.py"
        if plan_norm.endswith("/" + impl_norm) or plan_norm.endswith("\\" + impl_norm):
            return True
        if impl_norm.endswith("/" + plan_norm) or impl_norm.endswith("\\" + plan_norm):
            return True

        # Also check without leading separator
        if plan_norm.endswith(impl_norm) and (
            plan_norm[-len(impl_norm)-1] in "/\\" if len(plan_norm) > len(impl_norm) else True
        ):
            return True
        if impl_norm.endswith(plan_norm) and (
            impl_norm[-len(plan_norm)-1] in "/\\" if len(impl_norm) > len(plan_norm) else True
        ):
            return True

        # Strategy 3: Basename match
        plan_basename = self._get_basename(plan_file)
        impl_basename = self._get_basename(implemented_file)
        if plan_basename == impl_basename:
            return True

        return False

    def mark_implemented(self, implemented_file: str) -> Optional[str]:
        """
        Mark a file as implemented, matching against plan.

        Args:
            implemented_file: Path of the implemented file

        Returns:
            The matched plan file path, or None if no match found
        """
        self.implemented_files.add(implemented_file)

        for plan_path, record in self.planned_files.items():
            if record.status == "completed":
                continue

            if self.is_implemented(plan_path, implemented_file):
                record.status = "completed"
                record.implemented_path = implemented_file
                record.completed_at = datetime.now()
                return plan_path

        return None  # Implemented file not in plan (extra file)

    def mark_in_progress(self, plan_file: str) -> bool:
        """Mark a planned file as in progress"""
        if plan_file in self.planned_files:
            self.planned_files[plan_file].status = "in_progress"
            self.planned_files[plan_file].started_at = datetime.now()
            return True
        return False

    def mark_skipped(self, plan_file: str, reason: str = None) -> bool:
        """Mark a planned file as skipped"""
        if plan_file in self.planned_files:
            self.planned_files[plan_file].status = "skipped"
            self.planned_files[plan_file].error = reason
            return True
        return False

    def get_progress(self) -> Dict:
        """
        Get implementation progress statistics.

        Returns:
            Dictionary with progress metrics
        """
        total = len(self.planned_files)
        completed = sum(1 for r in self.planned_files.values() if r.status == "completed")
        in_progress = sum(1 for r in self.planned_files.values() if r.status == "in_progress")
        skipped = sum(1 for r in self.planned_files.values() if r.status == "skipped")
        pending = total - completed - in_progress - skipped

        return {
            "total": total,
            "completed": completed,
            "in_progress": in_progress,
            "skipped": skipped,
            "pending": pending,
            "completion_rate": completed / total if total > 0 else 0,
            "is_complete": pending == 0 and in_progress == 0,
        }

    def get_pending_files(self) -> List[str]:
        """Get list of files not yet implemented"""
        return [
            path for path, record in self.planned_files.items()
            if record.status == "pending"
        ]

    def get_completed_files(self) -> List[str]:
        """Get list of implemented files"""
        return [
            path for path, record in self.planned_files.items()
            if record.status == "completed"
        ]

Progress Display

def format_progress_display(tracker: ImplementationTracker) -> str:
    """
    Format progress for display in todo list or status message.

    Returns formatted string like:
    "Implementation Progress: 7/10 files (70%) | 2 pending | 1 in progress"
    """
    progress = tracker.get_progress()

    parts = [
        f"Implementation Progress: {progress['completed']}/{progress['total']} files",
        f"({progress['completion_rate']:.0%})",
    ]

    if progress['pending'] > 0:
        parts.append(f"| {progress['pending']} pending")

    if progress['in_progress'] > 0:
        parts.append(f"| {progress['in_progress']} in progress")

    if progress['skipped'] > 0:
        parts.append(f"| {progress['skipped']} skipped")

    return " ".join(parts)


def format_detailed_progress(tracker: ImplementationTracker) -> str:
    """
    Format detailed progress showing each file.

    Returns markdown-formatted checklist.
    """
    lines = ["## Implementation Progress\n"]

    progress = tracker.get_progress()
    lines.append(f"**Status:** {progress['completed']}/{progress['total']} complete ({progress['completion_rate']:.0%})\n")

    for path, record in tracker.planned_files.items():
        if record.status == "completed":
            checkbox = "[x]"
            suffix = f" -> {record.implemented_path}" if record.implemented_path != path else ""
        elif record.status == "in_progress":
            checkbox = "[-]"
            suffix = " (in progress)"
        elif record.status == "skipped":
            checkbox = "[~]"
            suffix = f" (skipped: {record.error})" if record.error else " (skipped)"
        else:
            checkbox = "[ ]"
            suffix = ""

        lines.append(f"- {checkbox} `{path}`{suffix}")

    return "\n".join(lines)

Checkpoint/Resume Support

import json
from typing import Any


def save_checkpoint(tracker: ImplementationTracker, checkpoint_path: str) -> None:
    """
    Save tracker state for checkpoint/resume.

    Args:
        tracker: The tracker to save
        checkpoint_path: Path to save checkpoint JSON
    """
    checkpoint = {
        "version": "1.0",
        "timestamp": datetime.now().isoformat(),
        "case_sensitive": tracker.case_sensitive,
        "planned_files": {
            path: {
                "status": record.status,
                "implemented_path": record.implemented_path,
                "started_at": record.started_at.isoformat() if record.started_at else None,
                "completed_at": record.completed_at.isoformat() if record.completed_at else None,
                "error": record.error,
            }
            for path, record in tracker.planned_files.items()
        },
        "implemented_files": list(tracker.implemented_files),
    }

    with open(checkpoint_path, 'w') as f:
        json.dump(checkpoint, f, indent=2)


def load_checkpoint(checkpoint_path: str) -> ImplementationTracker:
    """
    Load tracker state from checkpoint.

    Args:
        checkpoint_path: Path to checkpoint JSON

    Returns:
        Restored ImplementationTracker
    """
    with open(checkpoint_path, 'r') as f:
        checkpoint = json.load(f)

    tracker = ImplementationTracker(
        case_sensitive=checkpoint.get("case_sensitive", True)
    )

    for path, data in checkpoint["planned_files"].items():
        record = FileImplementationRecord(
            planned_path=path,
            status=data["status"],
            implemented_path=data.get("implemented_path"),
            error=data.get("error"),
        )
        if data.get("started_at"):
            record.started_at = datetime.fromisoformat(data["started_at"])
        if data.get("completed_at"):
            record.completed_at = datetime.fromisoformat(data["completed_at"])
        tracker.planned_files[path] = record

    tracker.implemented_files = set(checkpoint.get("implemented_files", []))

    return tracker

Integration Pattern

class OrchestratorWithTracking:
    """Orchestrator integration with implementation tracking"""

    def __init__(self, orchestrator, checkpoint_dir: str = ".coditect/checkpoints"):
        self.orchestrator = orchestrator
        self.tracker = ImplementationTracker()
        self.checkpoint_dir = checkpoint_dir
        self.task_id = None

    async def start_implementation(self, plan: List[str], task_id: str = None):
        """Start or resume implementation"""
        self.task_id = task_id or datetime.now().strftime("%Y%m%d_%H%M%S")
        checkpoint_path = f"{self.checkpoint_dir}/impl_{self.task_id}.json"

        # Try to resume from checkpoint
        if os.path.exists(checkpoint_path):
            self.tracker = load_checkpoint(checkpoint_path)
            print(f"Resumed from checkpoint: {format_progress_display(self.tracker)}")
        else:
            self.tracker.set_plan(plan)
            print(f"Starting implementation: {len(plan)} files planned")

    async def implement_file(self, plan_file: str):
        """Implement a single file with tracking"""
        self.tracker.mark_in_progress(plan_file)

        try:
            # Actual implementation
            result = await self.orchestrator.implement(plan_file)

            # Mark completed
            self.tracker.mark_implemented(result.output_path)

            # Save checkpoint
            checkpoint_path = f"{self.checkpoint_dir}/impl_{self.task_id}.json"
            save_checkpoint(self.tracker, checkpoint_path)

            # Update display
            print(format_progress_display(self.tracker))

            return result

        except Exception as e:
            self.tracker.mark_skipped(plan_file, str(e))
            raise

    async def implement_all(self, plan: List[str], task_id: str = None):
        """Implement all files with tracking and checkpoints"""
        await self.start_implementation(plan, task_id)

        for plan_file in self.tracker.get_pending_files():
            await self.implement_file(plan_file)

        return format_detailed_progress(self.tracker)

Usage Examples

Basic Tracking

# Create tracker
tracker = ImplementationTracker()

# Set plan
tracker.set_plan([
    "src/handlers/auth.py",
    "src/handlers/user.py",
    "src/models/user.py",
    "tests/test_auth.py",
])

# Mark files as implemented
tracker.mark_implemented("/project/src/handlers/auth.py")  # Exact match
tracker.mark_implemented("user.py")  # Basename match for models/user.py

# Check progress
print(format_progress_display(tracker))
# Output: Implementation Progress: 2/4 files (50%) | 2 pending

# Get pending files
for path in tracker.get_pending_files():
    print(f"Still need to implement: {path}")

With Checkpoint/Resume

# First session - partial implementation
tracker = ImplementationTracker()
tracker.set_plan(["file1.py", "file2.py", "file3.py"])
tracker.mark_implemented("file1.py")
save_checkpoint(tracker, ".coditect/checkpoints/task_001.json")

# Session interrupted...

# Second session - resume
tracker = load_checkpoint(".coditect/checkpoints/task_001.json")
print(f"Resuming: {tracker.get_progress()['completed']}/{tracker.get_progress()['total']} complete")
# Output: Resuming: 1/3 complete

# Continue implementation
for path in tracker.get_pending_files():
    tracker.mark_implemented(path)

Fuzzy Matching Examples

tracker = ImplementationTracker()

# These all match:
assert tracker.is_implemented("src/utils.py", "/home/user/project/src/utils.py")  # Partial
assert tracker.is_implemented("/full/path/file.py", "file.py")  # Basename
assert tracker.is_implemented("handlers/auth.py", "handlers/auth.py")  # Exact

# Case insensitive mode
tracker_ci = ImplementationTracker(case_sensitive=False)
assert tracker_ci.is_implemented("Auth.py", "auth.py")  # Case match

Best Practices

DO

• Set plan early - Define expected files before starting implementation
• Save checkpoints frequently - After each file completion
• Use fuzzy matching - Handles path variations gracefully
• Display progress - Keep users informed of status
• Handle interruptions - Always enable checkpoint/resume
• Track skipped files - Record why files weren't implemented

DON'T

• Don't require exact paths - Fuzzy matching is more robust
• Don't skip checkpoints - Token savings compound
• Don't ignore extra files - Track implemented files not in plan
• Don't rely on order - Files may be implemented out of order
• Don't hardcode paths - Use relative paths when possible

Configuration Options

# Default configuration
tracker = ImplementationTracker(
    case_sensitive=True  # Match file paths case-sensitively
)

# Case-insensitive (for Windows or mixed environments)
tracker = ImplementationTracker(case_sensitive=False)

Integration with CODITECT Agents

Recommended integration points:

Agent	Usage	Notes
orchestrator	Track multi-file task progress	Primary integration point
backend-development	Track API implementation	For multi-endpoint tasks
frontend-development	Track component implementation	For multi-component tasks
code-implementation	Track general file implementation	Default implementation agent

Success Metrics

Metric	Target	Measurement
Match accuracy	95%+	Correctly matches plan to implemented files
Checkpoint recovery	100%	All checkpoints successfully resume
Path variation handling	90%+	Handles common path differences
Progress display accuracy	100%	Displayed progress matches actual

Source Reference

This pattern was extracted from DeepCode (HKUDS/DeepCode) multi-agent system.

Original location: workflows/agents/code_implementation_agent.py (implementation tracking section)

Original codebase stats:

• 51 Python files analyzed
• 33,497 lines of code
• 12 patterns extracted

See /submodules/labs/DeepCode/DEEP-ANALYSIS.md for complete analysis.

Multi-Context Window Support

State Tracking

Checkpoint State (JSON):

{
  "checkpoint_id": "impl_20251214_103000",
  "version": "1.0",
  "timestamp": "2025-12-14T10:30:00Z",
  "planned_files": {
    "src/handlers/auth.py": {
      "status": "completed",
      "implemented_path": "/project/src/handlers/auth.py",
      "completed_at": "2025-12-14T10:15:00Z"
    },
    "src/handlers/user.py": {
      "status": "in_progress",
      "started_at": "2025-12-14T10:28:00Z"
    },
    "src/models/user.py": {
      "status": "pending"
    }
  }
}

Progress Notes (Markdown):

# Implementation Progress - 2025-12-14

## Task: Implement User Authentication System

**Status:** 2/4 files complete (50%)

- [x] `src/handlers/auth.py` -> /project/src/handlers/auth.py
- [-] `src/handlers/user.py` (in progress)
- [ ] `src/models/user.py`
- [ ] `tests/test_auth.py`

## Notes
- Auth handler completed with JWT support
- User handler in progress, adding role validation

Session Recovery

When starting a fresh context window:

1. Load checkpoint: Read .coditect/checkpoints/impl_[task_id].json
2. Display progress: Show current status to user
3. Continue from pending: Resume with next pending file
4. Save frequently: Checkpoint after each file

Token Savings: ~50% reduction on interrupted tasks by not re-implementing completed files

Success Output

When successful, this skill MUST output:

✅ SKILL COMPLETE: implementation-tracker

Completed:
- [x] Implementation tracker initialized with planned files
- [x] Fuzzy path matching configured (exact, partial, basename)
- [x] Progress tracking active with file status updates
- [x] Checkpoint saved for session recovery
- [x] Progress display formatted and verified

Outputs:
- Implementation tracker instance configured
- Checkpoint file: .coditect/checkpoints/impl_[task_id].json
- Progress report (X/Y files complete, Z% completion rate)
- Pending files list for next session
- Detailed progress markdown with file statuses

Completion Checklist

Before marking this skill as complete, verify:

• Tracker initialized with complete list of planned files
• Fuzzy path matching tested (exact, partial path, basename)
• File status transitions working (pending → in_progress → completed)
• Progress calculation accurate (total, completed, in_progress, skipped, pending)
• Checkpoint save/load tested successfully
• Progress display formatted correctly (percentage, counts)
• Pending files retrieval working
• Skipped files marked with reasons
• Case sensitivity configured appropriately for platform

Failure Indicators

This skill has FAILED if:

• ❌ Tracker initialized with zero planned files
• ❌ Fuzzy matching fails to match obvious paths (same filename)
• ❌ Progress percentage incorrect or NaN
• ❌ Checkpoint file not created or corrupted
• ❌ Checkpoint load fails or returns empty tracker
• ❌ File status stuck in "in_progress" without completion
• ❌ Implemented files not marked as completed
• ❌ Progress display missing key metrics (completion rate, pending count)

When NOT to Use

Do NOT use this skill when:

• Single-file implementation (overhead not justified)
• Files are not part of a planned list (exploratory development)
• Implementation is trivial and fast (completes in one session)
• No checkpoint/resume needed (short tasks)
• Files don't follow predictable naming patterns (can't match)
• Real-time progress tracking not required
• Team prefers manual progress tracking in project management tools
• Implementation is non-linear (can't predict file list upfront)

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Exact path matching only	Fails on path variations	Use fuzzy matching (partial, basename)
No checkpoints	Lost progress on interruption	Save checkpoint after each file
Hardcoded file paths	Breaks on different environments	Use relative paths with fuzzy matching
Missing progress display	Users unaware of status	Update progress after each file
No skipped file tracking	Silent failures	Mark skipped with reasons
Single checkpoint file	Concurrent tasks conflict	Use task_id in checkpoint filename
No case-insensitive mode	Fails on Windows	Configure case sensitivity per platform
Ignoring extra files	Untracked implementation	Log implemented files not in plan

Principles

This skill embodies:

• #2 Self-Provisioning - Auto-creates checkpoints without manual intervention
• #5 Eliminate Ambiguity - Clear file status and completion percentages
• #6 Clear, Understandable, Explainable - Progress reports with detailed breakdowns
• #8 No Assumptions - Fuzzy matching handles path variations gracefully
• #9 Keep It Simple - Minimal overhead for maximum benefit (checkpoint/resume)
• #10 Token Efficiency - 50% reduction by not re-implementing completed files

Full Standard: CODITECT-STANDARD-AUTOMATION.md