OpenParable
Skip to content
← Back to skills

Skill Status Sync

Productivity
skill-status-sync

Skill Status Sync is an Agent Skill for productivity published in the majiayu000/claude-skill-registry repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Atomically update task status across TODO.md and state.json. Invoke when task status changes.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/majiayu000/claude-skill-registry/blob/HEAD/skills/skills/skill-status-sync-benbrastmckie-modelchecker-2/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/skill-status-sync, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Status Sync Skill

Atomic status updates across TODO.md and state.json.

Trigger Conditions

This skill activates when:

  • Task status needs to change
  • Artifacts are added to a task
  • Task metadata needs updating

Two-Phase Commit Pattern

Phase 1: Prepare

  1. Read Current State (using jq/grep for efficiency)

    # Read task from state.json via jq (fast, ~12ms)
    task_data=$(jq -r --arg num "$task_number" \
      '.active_projects[] | select(.project_number == ($num | tonumber))' \
      .claude/specs/state.json)
    
    # Read next_project_number for create operations
    next_num=$(jq -r '.next_project_number' .claude/specs/state.json)
    
    # Find task section in TODO.md via grep
    task_line=$(grep -n "^### ${task_number}\." .claude/specs/TODO.md | cut -d: -f1)
    
  2. Validate Task Exists

    • Check task_data is not empty (state.json)
    • Check task_line is found (TODO.md)
    • If not in both: Error
  3. Prepare Updates

    • Calculate new status
    • Prepare jq update for state.json
    • Prepare Edit for TODO.md task entry
    • For create operations: also prepare frontmatter update
    • Validate both are consistent

Phase 2: Commit

  1. Write state.json First

    • Machine state is source of truth
    • Faster to query and validate
  2. Write TODO.md Second

    • User-facing representation
    • May have formatting variations
  3. Verify Both Updated

    • Re-read both files
    • Confirm changes applied

Rollback (if needed)

If any write fails:

  1. Log the failure
  2. Attempt to restore original state
  3. Return error with details

Status Mapping

OperationOld StatusNew StatusSets Timestamp
Start researchnot_startedresearchingstarted (if null)
Complete researchresearchingresearchedresearched
Start planningresearchedplanning-
Complete planningplanningplannedplanned
Start implementplannedimplementing-
Complete implementimplementingcompletedcompleted
Block taskanyblocked-
Abandon taskanyabandoned-

Timestamp Fields

Lifecycle timestamps track when each phase completed:

  • started: ISO date (YYYY-MM-DD) when work began
  • researched: ISO date when research completed
  • planned: ISO date when planning completed
  • completed: ISO date when implementation completed

Task Creation (Special Case)

When creating a new task, BOTH files require additional updates beyond task entries:

state.json Updates

jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  '.next_project_number = ($next_num | tonumber) + 1 |
   .active_projects = [{new_task_object}] + .active_projects' \
  .claude/specs/state.json > /tmp/state.json && \
  mv /tmp/state.json .claude/specs/state.json

TODO.md Updates (TWO parts)

  1. Frontmatter: Update next_project_number in YAML frontmatter

    # Use sed or Edit to update frontmatter
    sed -i 's/^next_project_number: [0-9]*/next_project_number: NEW_NUM/' \
      .claude/specs/TODO.md
    
  2. Task Entry: Add entry under appropriate priority section

CRITICAL: next_project_number MUST match in both files after creation.

Update Formats

state.json Update

{
  "project_number": N,
  "status": "new_status",
  "last_updated": "ISO_TIMESTAMP",
  "started": "YYYY-MM-DD",
  "researched": "YYYY-MM-DD",
  "planned": "YYYY-MM-DD",
  "completed": "YYYY-MM-DD",
  "artifacts": ["path1", "path2"]
}

TODO.md Update

### {N}. {Title}
- **Status**: [{NEW_STATUS}]
- **Started**: {YYYY-MM-DD}
- **Researched**: {YYYY-MM-DD}
- **Planned**: {YYYY-MM-DD}
- **Completed**: {YYYY-MM-DD}
- **{Artifact}**: [link](path)

Timestamp Update Patterns

Set Timestamp (state.json)

# Set a specific timestamp field
jq --arg ts "$(date +%Y-%m-%d)" \
  '(.active_projects[] | select(.project_number == '$task_number')) |= . + {
    "started": $ts,
    "last_updated": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"
  }' .claude/specs/state.json > /tmp/state.json && \
  mv /tmp/state.json .claude/specs/state.json

Set Timestamp (TODO.md)

Use Edit tool to add/update timestamp line in task entry:

- **Started**: 2026-01-10

Add Artifact (state.json)

# Add artifact to artifacts array
jq --arg path "$artifact_path" \
  '(.active_projects[] | select(.project_number == '$task_number')) |= . + {
    "artifacts": ((.artifacts // []) + [$path]),
    "last_updated": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"
  }' .claude/specs/state.json > /tmp/state.json && \
  mv /tmp/state.json .claude/specs/state.json

Task Counts Management

Calculate task_counts

# Calculate counts from active_projects
active=$(jq '[.active_projects[] | select(.status != "completed" and .status != "abandoned")] | length' .claude/specs/state.json)
completed=$(jq '[.active_projects[] | select(.status == "completed")] | length' .claude/specs/state.json)
in_progress=$(jq '[.active_projects[] | select(.status == "implementing" or .status == "researching" or .status == "planning")] | length' .claude/specs/state.json)

Update TODO.md Frontmatter task_counts

After calculating, update the frontmatter:

task_counts:
  active: {active}
  completed: {completed}
  in_progress: {in_progress}

When to Update task_counts

  • After task creation (/task)
  • After task completion (/implement)
  • After task archival (/todo)

Execution Flow

1. Receive update request:
   - task_number
   - new_status
   - artifacts (optional)
   - metadata (optional)

2. Phase 1 - Prepare:
   - Read both files
   - Validate task exists
   - Prepare updates

3. Phase 2 - Commit:
   - Write state.json
   - Write TODO.md
   - Verify success

4. Return result

Return Format

{
  "status": "completed|failed",
  "summary": "Updated task #N to [STATUS]",
  "task_number": N,
  "old_status": "previous",
  "new_status": "current",
  "files_updated": [
    ".claude/specs/state.json",
    ".claude/specs/TODO.md"
  ]
}

Error Handling

File Read Error

{
  "status": "failed",
  "error": "Could not read state.json",
  "recovery": "Check file exists and permissions"
}

Task Not Found

{
  "status": "failed",
  "error": "Task #N not found",
  "recovery": "Verify task number, check if archived"
}

Write Failure

{
  "status": "failed",
  "error": "Failed to write TODO.md",
  "recovery": "Check permissions, state.json may be updated"
}

Inconsistency Detected

{
  "status": "failed",
  "error": "TODO.md and state.json inconsistent",
  "recovery": "Run /task --sync to reconcile"
}