progress-tracking

name	progress-tracking
description	Multi-step task tracking system: todo hierarchy, status protocol, cross-agent status sharing, session-boundary recovery, and visual progress reporting.

Progress Tracking

Structured system for tracking multi-step tasks across agents, sessions, and context window limits. Mirrors Hermes Agent's todo tool discipline — every task has a lifecycle, status, and owner.

Core Model

Every unit of work follows this lifecycle:

BACKLOG → TODO → IN_PROGRESS → REVIEW → DONE
                                    ↓
                                 CANCELLED (explicit only)

Status	Meaning
BACKLOG	Known but not started
TODO	Ready to start
IN_PROGRESS	Actively being worked on
REVIEW	Submitted, awaiting verification or user sign-off
DONE	Verified complete
CANCELLED	Explicitly abandoned (with reason)
BLOCKED	Waiting on external dependency

Rule: Only ONE task can be IN_PROGRESS per agent at a time.

Task Tracking via Todowrite

OpenCode provides a todowrite tool. Use it as the primary task store within a session. Every task item MUST have a stable ID.

Task ID Convention

Use a hierarchical ID for cross-reference:

<agent-prefix>-<number>

Prefixes:
FE  = frontend (nuxt / react / angular)
BE  = backend (node / ci3 / laravel / java / go / python / rust / swift / dotnet / cpp)
DB  = database
DS  = designer
QA  = code review / quality
OP  = devops / deploy
SEC = security
GEN = general / research

Examples: FE-001, BE-012, DB-003, QA-002

Task Entry Format

Every todowrite entry MUST include this structure:

{ID}: {short description} | priority:{P0|P1|P2|P3} | depends:{IDs or -} | assignee:{@agent}

Example:

FE-001: Create NotificationBell component | priority:P1 | depends:BE-002 | assignee:@frontend-nuxt
BE-002: Build notification API endpoint | priority:P1 | depends:DB-001 | assignee:@node-developer
DB-001: Create notifications table migration | priority:P1 | depends:- | assignee:@database

When using todowrite, include dependencies and assignee in the item description or as structured context.

Visual Progress Report

When the user asks about status (or after completing a task), produce a progress table:

## Progress Report

| ID | Task | Status | Priority | Dependencies | Owner |
|----|------|--------|----------|--------------|-------|
| DB-001 | Create notifications table | ✅ DONE | P1 | — | @database |
| BE-002 | Build notification API | 🔄 IN PROGRESS | P1 | DB-001 | @node-developer |
| FE-001 | NotificationBell component | ⏳ TODO | P1 | BE-002 | @frontend-nuxt |
| FE-002 | NotificationList modal | ⏳ TODO | P2 | FE-001 | @frontend-nuxt |

Blockers:
- (none)

Overall: 1/4 done, 0 blocked

Status emoji convention:

• ⬜ BACKLOG or unstarted
• ⏳ TODO (ready)
• 🔄 IN PROGRESS
• 🔍 REVIEW
• ✅ DONE
• ❌ CANCELLED
• 🚫 BLOCKED

Session Start Handoff

When starting a new session after previous work was done, reconstruct task state:

1. Check agentmemory: memory_recall(query: "task-status") or memory_smart_search(query: "progress tracking current state")
2. Check file-based fallback: Read .opencode/memory/task-status.json if agentmemory is unavailable
3. Infer from codebase: Check recent git commits, modified files, open branches
4. Report to user: "I see you were working on X. Last status was: [summary]. Shall I continue?"

Task Status Save Format (for session end / checkpoint)

Save to agentmemory (or file fallback) at every significant checkpoint:

memory_save(
  content: JSON.stringify({
    timestamp: "2025-03-21T14:30:00Z",
    active_tasks: [
      { id: "BE-002", status: "in_progress", description: "Build notification API" },
      { id: "FE-001", status: "todo", description: "NotificationBell component", depends_on: "BE-002" }    
    ],
    completed_tasks: ["DB-001"],
    blocked_tasks: []
  }),
  concepts: ["task-status", "progress", "current-state"],
  files: [],
  type: "session"
)

Cross-Agent Status Protocol

When IT Leader delegates to subagents:

1. Before delegation: IT Leader reports the current task list in the delegation contract (see agent-delegation-contract skill)
2. During work: Subagent updates progress inside its own session using todowrite
3. After completion: Subagent returns completion status in the DELEGATION RESULT
4. Integration: IT Leader updates the master task list with subagent's results

Single-Agent Task Stack

When working directly (not delegating), maintain a mental task stack:

Current: BE-002 Build notification API (in progress)
  └─ 1. Create route handler
  └─ 2. Add validation middleware  ← CURRENT
  └─ 3. Write tests

Next:    FE-001 NotificationBell component
Pending: FE-002 NotificationList modal

The CURRENT marker shows exactly where you are. After finishing a substep, move the marker.

Context Window Recovery

When approaching context limits and compression is needed, the progress tracking data is in the Critical retention tier:

## Task State (RETAIN DURING COMPRESSION)

In progress: BE-002 (notification API — route handler done, validation pending)
TODO: FE-001 (blocked on BE-002), FE-002
Completed: DB-001
Blocked: none

Compression note: dropped substep details for BE-002. Validation needs Zod schema + middleware.

Status Commands

The .opencode/commands/ directory includes commands for common progress actions:

/status

Invoke to produce a visual progress report and check for blocked tasks.

/continue

Invoke after session resume to reconstruct task state from agentmemory and report to user.