skill-todo

name	skill-todo
description	Archive completed and abandoned tasks with CHANGE_LOG.md updates and memory harvest suggestions
allowed-tools	Bash, Edit, Read, Write, Grep, AskUserQuestion
context	direct

Todo Skill

Direct execution skill for archiving tasks, updating CHANGE_LOG.md, and suggesting memory harvesting.

OpenCode task archival with changelog tracking and memory suggestions. Archive completed/abandoned tasks and track changes.

Direct execution skill for task archival operations with automated CHANGE_LOG updates and memory harvest suggestions.

Parse arguments, scan for archivable tasks, update states, generate CHANGE_LOG entries, suggest memory harvesting from completed task artifacts.

Parse command arguments 1. Check for --dry-run flag 2. Set dry_run = true if present 3. Validate no other arguments expected Scan for archivable tasks 1. Read specs/state.json 2. Identify tasks with status = "completed" 3. Identify tasks with status = "abandoned" 4. Read specs/TODO.md and cross-reference 5. Track counts: completed_count, abandoned_count Detect orphaned directories and TODO.md orphans 1. Scan specs/ for directories not tracked in state files: ```bash for dir in specs/[0-9]*_*/; do [ -d "$dir" ] || continue basename_dir=$(basename "$dir") project_num=$(echo "$basename_dir" | cut -d_ -f1)

       in_active=$(jq -r --arg n "$project_num" \
         '.active_projects[] | select(.project_number == ($n | tonumber)) | .project_number' \
         specs/state.json 2>/dev/null)

       in_archive=$(jq -r --arg n "$project_num" \
         '.completed_projects[] | select(.project_number == ($num | tonumber)) | .project_number' \
         specs/archive/state.json 2>/dev/null)

       if [ -z "$in_active" ] && [ -z "$in_archive" ]; then
         orphaned_in_specs+=("$dir")
       fi
     done
     ```

  2. Scan specs/archive/ for orphaned directories:
     ```bash
     for dir in specs/archive/[0-9]*_*/; do
       [ -d "$dir" ] || continue
       basename_dir=$(basename "$dir")
       project_num=$(echo "$basename_dir" | cut -d_ -f1)

       in_archive=$(jq -r --arg n "$project_num" \
         '.completed_projects[] | select(.project_number == ($num | tonumber)) | .project_number' \
         specs/archive/state.json 2>/dev/null)

       if [ -z "$in_archive" ]; then
         orphaned_in_archive+=("$dir")
       fi
     done
     ```

  3. Scan TODO.md for completed/abandoned tasks not tracked in state.json or archive:
     - Parse task headers (`### {N}.`) and status lines (`[COMPLETED]`/`[ABANDONED]`)
     - Cross-reference each against active_projects and archive completed_projects
     - Collect as `todo_md_orphans[]` if: status is completed/abandoned, not in either state file, and has a directory in specs/
</process>

Detect misplaced directories 1. Scan specs/ for directories tracked in archive state: ```bash for dir in specs/[0-9]*_*/; do [ -d "$dir" ] || continue basename_dir=$(basename "$dir") project_num=$(echo "$basename_dir" | cut -d_ -f1)

       in_active=$(jq -r --arg n "$project_num" \
         '.active_projects[] | select(.project_number == ($num | tonumber)) | .project_number' \
         specs/state.json 2>/dev/null)
       
       in_archive=$(jq -r --arg n "$project_num" \
         '.completed_projects[] | select(.project_number == ($num | tonumber)) | .project_number' \
         specs/archive/state.json 2>/dev/null)
       
       if [ -z "$in_active" ] && [ -n "$in_archive" ]; then
         misplaced_in_specs+=("$dir")
       fi
     done
     ```
</process>

Scan for roadmap references 0. Ensure specs/ROADMAP.md exists. If the file does not exist, create it with the default template: ```markdown # Project Roadmap

     ## Phase 1: Current Priorities (High Priority)

     - [ ] (No items yet -- add roadmap items here)

     ## Success Metrics

     - (Define success metrics here)
     ```
  1. Read specs/ROADMAP.md
  2. For each completed task, extract:
     - completion_summary from completion_data
     - roadmap_items if present
     - Task N references from summaries
  3. Match against ROADMAP.md items
  4. Track roadmap_matches array with confidence levels
</process>

Scan meta tasks for README.md suggestions 1. For each archived meta task: - Check completion_data.readme_suggestions - Filter out "none" values - Track actionable suggestions by type: * Add: Insert new content * Update: Replace existing content * Remove: Delete content Collect, deduplicate, and classify memory candidates from state.json 1. Collect candidates from state.json: - For each completed task in the archival batch: - Read `memory_candidates // []` from the task's state.json entry - Flatten into a single list, tagging each candidate with `task_number` provenance - If no candidates across all tasks, set `harvest_candidates = []` and skip to Stage 8

  2. Deduplicate against existing memory-index.json:
     - Read `.memory/memory-index.json` (if missing or empty, skip dedup -- all candidates are CREATE)
     - For each candidate, compute keyword overlap against every index entry:
       ```
       overlap = |candidate.suggested_keywords INTERSECT entry.keywords| / |candidate.suggested_keywords|
       ```
     - Classify dedup action:
       - overlap > 90%: mark `dedup_action = "NOOP"` (exclude from prompt)
       - overlap > 60%: mark `dedup_action = "UPDATE"` (present with warning label)
       - overlap <= 60%: mark `dedup_action = "CREATE"` (standard new memory)
     - If ALL candidates are NOOP after dedup, set `harvest_candidates = []` and skip to Stage 8

  3. Apply three-tier classification:
     - **Tier 1** (pre-selected): category in [PATTERN, CONFIG] AND confidence >= 0.8
     - **Tier 2** (shown, not pre-selected): category in [WORKFLOW, TECHNIQUE] AND confidence >= 0.5
     - **Tier 3** (hidden by default): category == INSIGHT OR confidence < 0.5
     - Assign `tier` (1, 2, or 3) to each non-NOOP candidate

  4. Store the classified candidate list as `harvest_candidates`:
     Each entry contains: `task_number`, `content`, `category`, `source_artifact`, `confidence`, `suggested_keywords`, `tier`, `dedup_action`
</process>

Display dry run preview if requested If dry_run = true: 1. Display comprehensive preview: - Tasks to archive (completed/abandoned counts) - Orphaned directories count - Misplaced directories count - Roadmap updates needed - README.md suggestions count - Memory candidates: tiered breakdown from `harvest_candidates` - Format: `Memory candidates: {T1} Tier 1, {T2} Tier 2, {T3} Tier 3 ({after_dedup} after dedup, {noop_count} NOOP excluded)` - If no candidates: `Memory candidates: none` 2. Exit after display Handle interactive prompts Present AskUserQuestion prompts for each detected condition: 1. **Orphaned directories**: track/skip options per directory 2. **Misplaced directories**: move/skip options per directory 3. **TODO.md orphans**: multiSelect list of completed/abandoned tasks not in state.json; store as `selected_todo_orphans` 4. **Memory harvest candidates** (from `harvest_candidates`): - If `harvest_candidates` is empty (no candidates or all NOOP), skip this sub-step entirely - Build multiSelect option list, ordered by tier: a. **Tier 1 candidates first** (pre-selected): Format each as: `[PRE-SELECTED] [TIER 1] [{CATEGORY}] Task {N}: {content first 80 chars}... (confidence: {X.XX})` If `dedup_action == "UPDATE"`, append: ` [WARNING: similar memory exists]` b. **Tier 2 candidates** (shown, not pre-selected): Format each as: `[TIER 2] [{CATEGORY}] Task {N}: {content first 80 chars}... (confidence: {X.XX})` If `dedup_action == "UPDATE"`, append: ` [WARNING: similar memory exists]` c. **Tier 3 expansion option**: If Tier 3 candidates exist, add a final option: `Show {count} more candidates (Tier 3 -- low confidence/insight)` - Present AskUserQuestion with multiSelect - If user selected the Tier 3 expansion option: - Re-prompt with ALL tiers visible (Tier 1 + Tier 2 + Tier 3), Tier 1 still pre-selected - Tier 3 candidates formatted as: `[TIER 3] [{CATEGORY}] Task {N}: {content first 80 chars}... (confidence: {X.XX})` - Store user-approved candidates as `approved_memories` for Stage 14 Archive tasks to completed_projects (includes mandatory vault check) For each task to archive: 1. Update specs/archive/state.json: - Add to completed_projects array - Include all task fields - Add archived timestamp

  2. Update specs/state.json:
     - Remove from active_projects array

  3. Update specs/TODO.md:
     - Remove archived entries (both regular and TODO.md orphans)
     - Pattern to match task entry start:
       ```lua
        -- Match "### N. " format
        local task_start_pattern = "###%s+(%d+)%.%s+"
       ```
     - For each task to remove:
       a. Find entry start (header line)
       b. Find entry end (next task header or end of Active Tasks section)
       c. Extract complete entry including all lines
       d. Validate entry matches expected format before removal
     - Use Edit tool to remove validated entries:
       ```lua
       -- Remove the matched section
       edit_file("specs/TODO.md", old_entry_content, "")
       ```
     - Note: next_project_number should NOT be decremented when removing orphans
       (numbering continues from highest used number)

  4. Move project directories to specs/archive/

  5. Remove archived task from Recommended Order section (non-blocking):
     ```bash
     # Remove archived task from Recommended Order section (non-blocking)
     if source "$PROJECT_ROOT/.opencode/scripts/update-recommended-order.sh" 2>/dev/null; then
         remove_from_recommended_order "$project_number" || echo "Note: Failed to update Recommended Order"
     fi
     ```

  6. Track orphaned directories (if approved)

  7. Move misplaced directories (if approved)

  8. Archive TODO.md orphans:
     For each selected orphan in `selected_todo_orphans`:
     a. Build archive entry from TODO.md data:
        ```json
        {
          "project_number": orphan.project_number,
          "project_name": orphan.project_name,
          "status": orphan.status,  // "completed" or "abandoned"
          "created_at": "TODO.md_orphan",  // Marker indicating source
          "archived_at": "YYYY-MM-DDTHH:MM:SSZ"
        }
        ```
     b. Add entry to specs/archive/state.json completed_projects array
     c. Move directory from specs/ to specs/archive/:
        ```bash
         source_dir="specs/${orphan.project_number}_${orphan.project_name}/"
        target_dir="specs/archive/$(basename "$source_dir")"
        mv "$source_dir" "$target_dir"
        ```
     d. Track orphan archival for CHANGE_LOG.md
     e. If no directory found, log warning:
        ```
        Warning: TODO.md orphan {N} has no directory in specs/
        Archive entry created but no files moved
        ```

  9. **Vault Threshold Check (MANDATORY)**

     **CRITICAL: ALWAYS EXECUTE - DO NOT SKIP**

     This sub-step MUST be executed unconditionally after archiving tasks.
     The bash block below produces output for BOTH vault-needed and vault-not-needed cases.

     Execute vault threshold detection:
     ```bash
     # UNCONDITIONAL VAULT CHECK - produces output in all cases
     PROJECT_ROOT="${PROJECT_ROOT:-.}"
     STATE_FILE="${PROJECT_ROOT}/specs/state.json"
     VAULT_THRESHOLD=1000

     next_num=$(jq -r '.next_project_number // 0' "$STATE_FILE")

     if [[ "$next_num" -gt "$VAULT_THRESHOLD" ]]; then
         echo ""
         echo "=============================================="
         echo "  VAULT THRESHOLD EXCEEDED"