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:

• Passive Mechanism (保底):利用 HEARTBEAT.md 原生机制，防止非预期中断导致的进度丢失
• Active Mechanism (增强): 关键里程碑时的主动记录，确保重要决策路径被精准保留
• Dual-track Collaboration: 被动保底 + 主动增强，平衡系统健壮性与 Token/上下文资源开销

---

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

bash

# 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:

FilePurposeUpdates**MISSION.mdProject definition: goals, success criteria, deliverables, constraintsOnly when goals changePROGRESS.mdCurrent status: stage, completed milestones, blockers, recent activityEvery session / milestoneNEXT_STEPS.md**Action queue: prioritized atomic tasks, next immediate actionAfter each work session

Optional Extensions (By Project Type)#

Add folders/files as needed based on project nature:

Project TypeOptional Folders/FilesCode Developmentarchitecture.md, docs/, tests/, src/Artistic Creationassets/, references/, style_guide.mdLong-form Writingoutline.md, research/, chapters/Business Operationsconfig/, scripts/, logs/Researchhypothesis.md, findings/, data/

---

2. Document Templates#

MISSION.md Template#

markdown

# {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#

markdown

# 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#

markdown

# 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:

• This can be integrated into OpenClaw's HEARTBEAT.md mechanism
• Or implemented as a periodic background check

3.1 Dynamic Threshold Configuration

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

Project Complexity Factors:

ComplexityFile CountIndicatorsBase ThresholdSimple< 10 filesSingle module15 minMedium10-50 filesMultiple modules10 minComplex50-200 filesMulti-layer architecture5 minVery Complex> 200 filesDistributed system3 min

Session Activity Indicators:

• High Activity (frequent tool calls, file edits): Reduce threshold by 50%
• Normal Activity: Use base threshold
• Low Activity (long idle periods): Increase threshold by 100%

Adaptive Threshold Calculation:

text

effective_threshold = base_threshold × activity_multiplier × complexity_factor

Silence Thresholds (configurable, default values):

• Simple Project + High Activity: 7 minutes → Generate incremental session summary → update PROGRESS.md "Recent Activity"
• Medium Project + Normal Activity: 10 minutes → Generate incremental session summary → update PROGRESS.md "Recent Activity"
• Complex Project + High Activity: 3 minutes → Generate incremental session summary → update PROGRESS.md "Recent Activity"
• 60 minutes (any project): Update progress percentage → sync to MEMORY.md project index

Configuration File ( .ltpm/config.json):

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:

python

# 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:

ToolPlatformCommandfswatchmacOS/Linuxfswatch -o projects/``inotifywaitLinuxinotifywait -m -r projects/``FileSystemWatcherWindowsPowerShell API

File Watcher Behavior:

• Monitor: ., *.md, *.json, *.yaml in project directory
• Trigger: Any file change → check if PROGRESS.md needs update
• Debounce: Wait 2 seconds after last change to batch updates
• Filter: Ignore .git/, node_modules/, __pycache__/

Resource Check:

• CPU usage < 20%: Enable file watcher
• Memory usage < 50%: Enable file watcher
• Otherwise: Fall back to heartbeat mechanism

3.3 Conflict Resolution

Last-Write-Wins + Timestamp-Based Detection:

Conflict Detection:

python

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:

text

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

Backup File Naming:

• Format: PROGRESS.md.auto-save.{timestamp}
• Retention: Keep last 5 backups
• Cleanup: Delete oldest when exceeding limit

Track B: Active Milestone (主动增强)#

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

Trigger:

• Agent completes key items in NEXT_STEPS.md
• Agent achieves阶段性成果 through execution instructions

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:

• Trigger: Before any write operation to PROGRESS.md
• Location: Same directory as PROGRESS.md
• Naming: PROGRESS.md.auto-save.{YYYYMMDD-HHMMSS}
• Retention: Keep last 5 backups (configurable)

Backup Configuration:

json

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

Backup Restoration:

bash

# 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):

text

┌─────────────────────────────────────────────────────────────┐
│ 📌 **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                      │
└─────────────────────────────────────────────────────────────┘

触发提示模板 (中文):

text

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

When to Show Trigger Prompts:

• On session start (first message after idle > 30 min)
• Before session end (user says goodbye)
• After completing >3 file modifications
• After running scripts > 60 seconds

3.6 Natural Language Triggers

Chinese Triggers (触发词):

CategoryKeywordsStart"开始项目", "新建任务", "启动"Progress"进度", "完成", "做到了", "搞定了"Pause"暂停", "先这样", "下次继续"End"结束", "再见", "回头聊", "先撤了"Milestone"里程碑", "阶段完成", "搞定了"

English Triggers:

CategoryKeywordsStart"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:

python

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:

json

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

JSON Format Template:

json

{
  "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:

yaml

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:

bash

# 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:

• After completing any tool call that modifies >3 files
• After executing a time-consuming script (>60s)
• When user says "Goodbye", "Talk later", or "Next time"
• When task goal is met

Status Identifiers#

In PROGRESS.md, introduce status identifiers:

IdentifierSourceMeaning[Auto-Sync]PassiveAuto-generated snapshot by background mechanism[Milestone]ActiveKey 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 TypePROGRESS.mdNEXT_STEPS.mdMISSION.mdSeparate DocTodo - 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:

• Source of Truth: Project directory's Core Triad documents are the single source of truth
• Handoff Protocol: When switching between agents, first step MUST be resume {project} (reading the three MD files)
• Context Transfer: When handing over, include PROGRESS.md summary in the context

---

8. Example Project Structure#

text

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)

text

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#

CommandDescriptioninit_project {name}Initialize LTPM structure for new projectcheckpointManually trigger progress save (active)sync_memoryForce MEMORY.md updateresume {project}Load project context from docsnextShow next immediate actionmark_milestone {desc}Mark a key milestone (active)auto_sync_statusCheck 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:

markdown

## 活跃项目索引 (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)#

ToolPurposeInstallationfswatchFile system watcher for macOS/Linuxbrew install fswatch (macOS) / apt install fswatch (Linux)inotify-toolsFile system watcher for Linuxapt install inotify-tools (Linux)jqJSON processingbrew install jq (macOS) / apt install jq (Linux)python3Script executionPre-installed on most systemspyyamlYAML parsingpip install pyyaml

12.2 Required Skills#

SkillPurposefile_operationsRead/write project documentsmemory_managementUpdate MEMORY.md indextask_trackingManage NEXT_STEPS.mdauto_completionBackground monitoring

12.3 Configuration Files#

Create .ltpm/config.json in project root:

json

{
  "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:

bash

# 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:

• v1.0: Initial version
• v2.0: Added dual-track mechanism (passive + active), context compression, multi-agent collaboration principles
• v2.1: Added dynamic thresholds, file watcher, explicit triggers, conflict resolution, backup mechanism, JSON/YAML formats, natural language triggers