Long-term Task Progress Management (LTPM)

# Long-term Task Progress Management (LTPM)

**Skill Name**: `long-term-task-progress`

**Version**: 2.1

**License**: MIT-0

**Author**: OpenClaw Community

**Purpose**: A universal protocol for managing long-term, multi-stage projects in OpenClaw. Ensures that any project can be resumed seamlessly after days or weeks of pause.

**Trigger**: When user initiates a project that will span multiple sessions, or explicitly asks for progress management.

---

Overview

The **LTPM (Long-term Task Progress Management)** protocol transforms OpenClaw's short-term conversation memory into structured long-term documents. It ensures that when you return to a project after days or weeks, you can instantly understand:

1. **What** the project aims to achieve

2. **Where** you left off

3. **What** needs to be done next

Design Philosophy

This skill is designed for **OpenClaw's always-on background service** architecture:

---

Quick Start

When you start a new long-term project:

1. Create the project directory structure (see below)

2. Initialize the Core Triad documents

3. Configure auto-save settings

4. Update MEMORY.md with project index

# Example project initialization
projects/
└── {project_name}/
    ├── MISSION.md        # Required: Project goals
    ├── PROGRESS.md       # Required: Current status
    └── NEXT_STEPS.md     # Required: Action items

---

1. Universal Project Structure

Core Triad (Required for ALL projects)

These three documents are **mandatory** for any project managed under LTPM:

| File | Purpose | Updates |

|------|---------|---------|

| **`MISSION.md`** | Project definition: goals, success criteria, deliverables, constraints | Only when goals change |

| **`PROGRESS.md`** | Current status: stage, completed milestones, blockers, recent activity | Every session / milestone |

| **`NEXT_STEPS.md`** | Action queue: prioritized atomic tasks, next immediate action | After each work session |

Optional Extensions (By Project Type)

Add folders/files as needed based on project nature:

| Project Type | Optional Folders/Files |

|--------------|------------------------|

| **Code Development** | `architecture.md`, `docs/`, `tests/`, `src/` |

| **Artistic Creation** | `assets/`, `references/`, `style_guide.md` |

| **Long-form Writing** | `outline.md`, `research/`, `chapters/` |

| **Business Operations** | `config/`, `scripts/`, `logs/` |

| **Research** | `hypothesis.md`, `findings/`, `data/` |

---

2. Document Templates

MISSION.md Template

# {Project Name}

**Created**: {YYYY-MM-DD}
**Version**: {x.y}
**Status**: Active / Paused / Completed

## Vision
What are we building/creating? Why does it matter?

## Success Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Deliverables
- Primary: {main output}
- Secondary: {supporting outputs}

## Constraints
- Budget / Time / Resources
- Technical limitations
- Dependencies

## Stakeholders
- Owner: {name}
- Contributors: {names}

PROGRESS.md Template

# Progress Tracker: {Project Name}

**Last Updated**: {YYYY-MM-DD HH:MM}
**Overall Progress**: {x%}

## Current Stage
{Stage Name} - {Brief description}

## Milestones

### ✅ Completed
- [YYYY-MM-DD] Milestone 1
- [YYYY-MM-DD] Milestone 2

### 🔄 In Progress
- [YYYY-MM-DD] Current task...

### ⏳ Pending
- [ ] Future milestone 1
- [ ] Future milestone 2

## Blockers
- 🚧 Blocker 1: {description}
- 🚧 Blocker 2: {description}

## Recent Activity
- {YYYY-MM-DD HH:MM}: {What was accomplished}
- {YYYY-MM-DD HH:MM}: {What was discussed}

## Notes
{Cross-session context that must be preserved}

NEXT_STEPS.md Template

# Next Steps: {Project Name}

**Last Updated**: {YYYY-MM-DD HH:MM}

## Immediate Priority (Next Session)
1. [ ] {Atomic task 1}
2. [ ] {Atomic task 2}

## Short-term (This Week)
- [ ] Task A
- [ ] Task B

## Medium-term (This Month)
- [ ] Task C
- [ ] Task D

## Waiting On
- ⏳ {Item}: Waiting for {who/what}

---

3. Dual-Track Auto-Save Mechanism

This skill implements a **dual-track collaboration** mechanism, combining passive background monitoring with active milestone tracking:

Track A: Passive Snapshot (利用 HEARTBEAT.md)

**Design Philosophy**: Designed for OpenClaw's always-on background service. This is a **low-power, high-compatibility** solution that works transparently without requiring user intervention.

**Trigger**: Detection of `HEARTBEAT.md` changes + time threshold exceeded

**Action**:

1. Monitor HEARTBEAT.md for updates (background service behavior)

2. When heartbeat updates but PROGRESS.md hasn't been synced for a while:

- Read current workspace state (last modified files, recent error logs)

- Record `[Auto-Sync]` snapshot in `PROGRESS.md`

3. **Advantage**: Prevents progress loss without user awareness, saves token consumption

**Technical Implementation**:

#### 3.1 Dynamic Threshold Configuration

Silence thresholds are **adaptive** based on project complexity and session activity:

**Project Complexity Factors**:

| Complexity | File Count | Indicators | Base Threshold |

|------------|:----------:|------------|----------------|

| Simple | < 10 files | Single module | 15 min |

| Medium | 10-50 files | Multiple modules | 10 min |

| Complex | 50-200 files | Multi-layer architecture | 5 min |

| Very Complex | > 200 files | Distributed system | 3 min |

**Session Activity Indicators**:

**Adaptive Threshold Calculation**:

effective_threshold = base_threshold × activity_multiplier × complexity_factor

**Silence Thresholds** (configurable, default values):

**Configuration File** (`.ltpm/config.json`):

{
  "thresholds": {
    "simple": 15,
    "medium": 10,
    "complex": 5,
    "very_complex": 3
  },
  "activity_multipliers": {
    "high": 0.5,
    "normal": 1.0,
    "low": 2.0
  }
}

#### 3.2 Passive Trigger Optimization (File Watcher Fallback)

When system resource consumption is low, use **file system watcher** instead of heartbeat mechanism:

**Detection Logic**:

# Pseudocode for trigger mode selection
if system_resources_available():
    use_file_watcher = True
    trigger_mode = "file_watcher"  # fswatch/inotify
else:
    use_file_watcher = False
    trigger_mode = "heartbeat"  # Default HEARTBEAT.md

**File Watcher Configuration**:

| Tool | Platform | Command |

|------|----------|---------|

| `fswatch` | macOS/Linux | `fswatch -o projects/` |

| `inotifywait` | Linux | `inotifywait -m -r projects/` |

| `FileSystemWatcher` | Windows | PowerShell API |

**File Watcher Behavior**:

**Resource Check**:

#### 3.3 Conflict Resolution

**Last-Write-Wins + Timestamp-Based Detection**:

**Conflict Detection**:

def detect_conflict(progress_file):
    current_mtime = get_modified_time(progress_file)
    last_known_mtime = get_stored_mtime(progress_file)

    if current_mtime != last_known_mtime:
        # External modification detected
        return True
    return False

**Resolution Strategy**:

1. **Timestamp Comparison**: Compare file modification times

2. **Last-Write-Wins**: The most recent write always wins

3. **Backup Preservation**: Keep `.auto-save` backup before overwriting

**Conflict Resolution Flow**:

[Write Attempt]
    ↓
[Check if file modified since last read]
    ↓ (yes)
[Create .auto-save backup]
    ↓
[Write new content]
    ↓
[Update stored timestamp]

**Backup File Naming**:

Track B: Active Milestone (主动增强)

**Design Philosophy**: Complement to passive mechanism. Ensures important decision paths are precisely captured.

**Trigger**:

**Action**:

1. Call `update_progress` directive

2. Record:

- Achieved goals

- Verified logic

- Encountered obstacles

- Next correction plan

3. **Advantage**: Precisely captures decision logic, provides high-quality context for handoff

#### 3.4 Backup Mechanism (.auto-save)

**Automatic Backup**:

**Backup Configuration**:

{
  "backup": {
    "enabled": true,
    "max_count": 5,
    "directory": "."
  }
}

**Backup Restoration**:

# List backups
ls -la PROGRESS.md.auto-save.*

# Restore from backup
cp PROGRESS.md.auto-save.20240315-143022 PROGRESS.md

#### 3.5 Explicit Active Trigger Prompts

Add clear trigger prompts to remind users when to actively record:

**Trigger Prompt Template (EN)**:

┌─────────────────────────────────────────────────────────────┐
│ 📌 **Time to Record Progress!**                             │
│                                                             │
│ Consider updating PROGRESS.md when you:                     │
│ ✓ Complete a significant task (file edits, code changes)   │
│ ✓ Make an important decision or discover something         │
│ ✓ Finish a work session / "talk to you later"              │
│ ✓ Achieve a milestone or stage completion                   │
│                                                             │
│ Quick Commands:                                              │
│   /checkpoint - Save current progress                      │
│   /mark_milestone - Mark key milestone                      │
└─────────────────────────────────────────────────────────────┘

**触发提示模板 (中文)**:

┌─────────────────────────────────────────────────────────────┐
│ 📌 **记录进度时机!**                                         │
│                                                             │
│ 以下情况请主动更新 PROGRESS.md：                             │
│ ✓ 完成重要任务（文件编辑、代码修改）                         │
│ ✓ 做出重要决定或发现新信息                                  │
│ ✓ 结束工作会话 / "下次再聊"                                 │
│ ✓ 达成里程碑或阶段完成                                      │
│                                                             │
│ 快速命令：                                                  │
│   /checkpoint - 保存当前进度                                │
│   /mark_milestone - 标记关键里程碑                          │
└─────────────────────────────────────────────────────────────┘

**When to Show Trigger Prompts**:

#### 3.6 Natural Language Triggers

**Chinese Triggers** (触发词):

| Category | Keywords |

|----------|----------|

| Start | "开始项目", "新建任务", "启动" |

| Progress | "进度", "完成", "做到了", "搞定了" |

| Pause | "暂停", "先这样", "下次继续" |

| End | "结束", "再见", "回头聊", "先撤了" |

| Milestone | "里程碑", "阶段完成", "搞定了" |

**English Triggers**:

| Category | Keywords |

|----------|----------|

| Start | "start project", "new task", "begin" |

| Progress | "progress", "completed", "done", "finished" |

| Pause | "pause", "continue later", "talk later" |

| End | "end", "goodbye", "see you", "bye" |

| Milestone | "milestone", "stage done", "achieved" |

**Trigger Detection Logic**:

def detect_trigger_intent(user_message):
    chinese_triggers = {
        "start": ["开始", "新建", "启动"],
        "progress": ["进度", "完成", "搞定"],
        "pause": ["暂停", "先这样", "下次"],
        "end": ["结束", "再见", "回头"],
        "milestone": ["里程碑", "阶段"]
    }
    # Return matched category

#### 3.7 Structured Format Support (JSON/YAML)

**Optional Format Configuration**:

{
  "format": {
    "default": "markdown",
    "supported": ["markdown", "json", "yaml"]
  }
}

**JSON Format Template**:

{
  "project": {
    "name": "Project Name",
    "created": "2024-01-01",
    "version": "1.0",
    "status": "active"
  },
  "progress": {
    "overall": 75,
    "current_stage": "API Implementation",
    "milestones": {
      "completed": [
        {"date": "2024-01-01", "description": "Initial setup"},
        {"date": "2024-01-15", "description": "Database design"}
      ],
      "in_progress": [
        {"date": "2024-02-01", "description": "API endpoints"}
      ],
      "pending": [
        {"description": "Frontend integration"}
      ]
    },
    "blockers": [
      {"description": "API key pending", "severity": "high"}
    ]
  },
  "activity": [
    {"timestamp": "2024-02-01T10:30:00Z", "action": "Completed user auth module"}
  ],
  "next_steps": {
    "immediate": [
      {"task": "Write unit tests", "priority": 1}
    ]
  }
}

**YAML Format Template**:

project:
  name: Project Name
  created: 2024-01-01
  version: 1.0
  status: active

progress:
  overall: 75
  current_stage: API Implementation
  milestones:
    completed:
      - date: 2024-01-01
        description: Initial setup
      - date: 2024-01-15
        description: Database design
    in_progress:
      - date: 2024-02-01
        description: API endpoints
    pending:
      - description: Frontend integration

blockers:
  - description: API key pending
    severity: high

activity:
  - timestamp: 2024-02-01T10:30:00Z
    action: Completed user auth module

next_steps:
  immediate:
    - task: Write unit tests
      priority: 1

**Format Conversion**:

# Convert Markdown to JSON
ltpm convert --from md --to json projects/myproject/

# Convert JSON to YAML
ltpm convert --from json --to yaml projects/myproject/

**When to Trigger Active Milestone**:

Status Identifiers

In PROGRESS.md, introduce status identifiers:

| Identifier | Source | Meaning |

|------------|--------|---------|

| `[Auto-Sync]` | Passive | Auto-generated snapshot by background mechanism |

| `[Milestone]` | Active | Key milestone recorded by Agent |

---

4. Context Compression Strategy

**Problem**: As progress chains grow, context window may overflow

**Solution**: When PROGRESS.md records exceed 5 milestones, Agent MUST execute `consolidate_progress`:

1. Convert old details into "known facts"

2. Store in LEARNINGS.md or PROGRESS.md archive section

3. Keep only: current state + lessons learned + next steps

---

5. Document Boundary Matrix

This matrix defines **where** each type of information should be stored:

| Information Type | PROGRESS.md | NEXT_STEPS.md | MISSION.md | Separate Doc |

|------------------|:-----------:|:--------------:|:----------:|--------------|

| **Todo - Current 3 items** | ✅ Summary | ✅ Full list | ❌ | ❌ |

| **Todo - Backlog** | ❌ | ✅ Full list | ❌ | ❌ |

| **Decisions - Conclusion** | ✅ Summary | ❌ | ✅ Archive | ❌ |

| **Decisions - Reasoning** | ❌ | ❌ | ✅ Archive | ✅ (if complex) |

| **Issues - Active Blockers** | ✅ Current | ❌ | ❌ | ❌ |

| **Issues - All Known** | ❌ Summary | ❌ | ❌ | ✅ (ISSUE.md) |

| **Notes - Meeting Points** | ❌ | ❌ | ❌ | ✅ (notes/) |

| **Technical Details** | ❌ | ❌ | ✅ (if core) | ✅ (docs/) |

| **Changelog - Recent 5** | ✅ | ❌ | ❌ | ❌ |

| **Changelog - Full** | ❌ | ❌ | ❌ | ✅ (CHANGELOG.md) |

| **References** | ❌ | ❌ | ✅ (if key) | ✅ (refs/) |

Key Principles

1. **PROGRESS.md = Dynamic**: Only contains what's actively being worked on

2. **NEXT_STEPS.md = Actionable**: Contains only tasks ready to execute

3. **MISSION.md = Foundational**: Project goals and major decisions

4. **Separate Docs = Archival**: Full details that don't fit in progress tracking

---

6. Workflow Integration

Starting a New Project

1. Ask user: "What is the project goal? What's the success criteria?"

2. Create directory: `projects/{project_name}/`

3. Initialize Core Triad

4. Update MEMORY.md with project index

During Active Work

1. Update `NEXT_STEPS.md` before tackling each task

2. Mark completed items in `PROGRESS.md` after each milestone

3. Document decisions in MISSION.md when made

4. Use active milestone triggers after key actions

Before Ending Session

1. Review `NEXT_STEPS.md` - ensure next action is clear

2. Update `PROGRESS.md` with current status

3. Summarize recent activity in PROGRESS.md

4. Update MEMORY.md project index

When Resuming After Pause

1. Read MEMORY.md to find project index

2. Read PROGRESS.md to understand current state

3. Read NEXT_STEPS.md to know what to do next

4. If blockers exist, address them before proceeding

---

7. Multi-Agent Collaboration

Since OpenClaw workspace may have multiple roles (小白, Code-Pilot, Nimo), establish clear principles:

---

8. Example Project Structure

projects/
└── campaign_system/
    ├── MISSION.md           # Project goals
    ├── PROGRESS.md          # Current status
    ├── NEXT_STEPS.md        # Action queue
    ├── architecture.md      # Technical design
    ├── docs/
    │   └── api_spec.md
    ├── src/
    │   └── (code files)
    └── logs/
        └── (development logs)

projects/
└── novel_writing/
    ├── MISSION.md           # Book vision
    ├── PROGRESS.md          # Current chapter
    ├── NEXT_STEPS.md        # Next scenes
    ├── outline.md           # Story outline
    ├── research/
    │   └── (background materials)
    └── chapters/
        ├── chapter_01.md
        └── chapter_02.md

---

9. Commands Reference

| Command | Description |

|---------|-------------|

| `init_project {name}` | Initialize LTPM structure for new project |

| `checkpoint` | Manually trigger progress save (active) |

| `sync_memory` | Force MEMORY.md update |

| `resume {project}` | Load project context from docs |

| `next` | Show next immediate action |

| `mark_milestone {desc}` | Mark a key milestone (active) |

| `auto_sync_status` | Check if current state is safely synced |

---

10. Best Practices

1. **Atomic Tasks**: Break NEXT_STEPS into tasks taking < 30 min each

2. **Percentage Accuracy**: Keep PROGRESS.md percentage within 5% accuracy

3. **Blocker Visibility**: Always surface blockers in PROGRESS.md "Current Stage"

4. **Decision Traceability**: Every major decision = summary in MISSION.md

5. **Memory Index**: Keep MEMORY.md as the "table of contents" for all projects

6. **Dual-Track**: Both passive (HEARTBEAT.md) and active (milestone) mechanisms work together

7. **Context Compression**: Consolidate progress when too many milestones accumulate

---

11. MEMORY.md Index Format

Use compact format in MEMORY.md project index:

## 活跃项目索引 (LTPM)
- [P] **Campaign System** (75%) | Next: `Confirm API` | Blocker: None
- [P] **Novel writing** (12%) | Next: `Chapter 3 outline` | Blocker: Research needed
- [On-Hold] **Legacy project** | Reason: Waiting external approval

---

12. Requirements

This section lists all tools, skills, and installations required to use the extended features of LTPM v2.1.

12.1 System Tools (Installs)

| Tool | Purpose | Installation |

|------|---------|--------------|

| **fswatch** | File system watcher for macOS/Linux | `brew install fswatch` (macOS) / `apt install fswatch` (Linux) |

| **inotify-tools** | File system watcher for Linux | `apt install inotify-tools` (Linux) |

| **jq** | JSON processing | `brew install jq` (macOS) / `apt install jq` (Linux) |

| **python3** | Script execution | Pre-installed on most systems |

| **pyyaml** | YAML parsing | `pip install pyyaml` |

12.2 Required Skills

| Skill | Purpose |

|-------|---------|

| `file_operations` | Read/write project documents |

| `memory_management` | Update MEMORY.md index |

| `task_tracking` | Manage NEXT_STEPS.md |

| `auto_completion` | Background monitoring |

12.3 Configuration Files

Create `.ltpm/config.json` in project root:

{
  "version": "2.1",
  "thresholds": {
    "simple": 15,
    "medium": 10,
    "complex": 5,
    "very_complex": 3
  },
  "activity_multipliers": {
    "high": 0.5,
    "normal": 1.0,
    "low": 2.0
  },
  "trigger_mode": "auto",
  "backup": {
    "enabled": true,
    "max_count": 5,
    "directory": "."
  },
  "format": {
    "default": "markdown",
    "supported": ["markdown", "json", "yaml"]
  },
  "file_watcher": {
    "enabled": true,
    "debounce_seconds": 2,
    "ignore_patterns": [".git/*", "node_modules/*", "__pycache__/*"]
  },
  "natural_language": {
    "enabled": true,
    "languages": ["en", "zh-CN"]
  }
}

12.4 Optional CLI Commands

For advanced users, add these commands to your shell:

# Initialize LTPM in current directory
ltpm init

# Convert between formats
ltpm convert --from md --to json

# Check sync status
ltpm status

# Force backup
ltpm backup

# Restore from backup
ltpm restore --latest

---

*This skill is designed to be shared across users. It creates a universal protocol for long-term task management in OpenClaw.*

**Version History**: