| name | hapo:sync |
| description | Dumb-proof status tracker and file synchronizer. Updates spec.json, task_registry, and tasks/*.md without breaking structural schemas. Includes Auto-Audit. |
| user-invocable | true |
| when_to_use | Invoke to synchronize spec state, docs, or task tracking after changes. |
| category | utilities |
| keywords | ["sync","state","tracking","consistency"] |
| argument-hint | <feature_name> <task_id|task-file> <status> [blocker] | phase <feature_name> <next_phase> | audit <feature_name> |
| metadata | {"author":"haposoft","version":"1.0.0"} |
Sync (State Tracking Protocol)
This skill safely bridges the gap between active development state and physical documentation files (spec.json + task_registry + tasks/task-R*.md). Instead of relying on risky raw AI edits, this skill executes precise contextual replacements.
Supported Commands
1. Task Synchronization
Update a specific task's status and automatically check its relevant sub-checkboxes.
Usage: /hapo:sync <feature_name> <task_id|task-file> <status> ["optional blocker msg"]
- Example 1:
/hapo:sync auth R0-02 done
- Example 2:
/hapo:sync payment task-R1-03-chunks-api.md blocked "API Endpoint Down"
2. Phase Advancement
Advance the entire project to the next logical phase.
Usage: /hapo:sync phase <feature_name> <next_phase>
- Example:
/hapo:sync phase shopping_cart test
3. State Audit
Scans the spec.json against all physical task-R*.md files to detect mismatches between task_files, task_registry, and markdown task headers, then repairs them.
Usage: /hapo:sync audit <feature_name>
- Example:
/hapo:sync audit auth
Directives
- Precision Edits: Never overwrite the entire
spec.json string blindly. Update only the required keys, while keeping JSON valid.
- Machine + Human Sync: Every task status update MUST modify both
spec.json.task_registry[...] and the matching markdown task file header/status section.
- Markdown Integrity: When marking a task
done, only then turn [ ] into [x] inside ## Steps / ## Implementation Steps and relevant Completion Criteria / Evidence checkboxes that have actual proof. Task Test Plan & Verification Evidence and legacy Verification & Evidence sections are supported.
- Verification Receipt Rule:
done is illegal without a human-readable verification receipt already present in ## Evidence, ## Task Test Plan & Verification Evidence, or legacy ## Verification & Evidence (commands executed, artifact/runtime proof, or equivalent concrete evidence). If proof is missing, keep the task in_progress or blocked.
- Task Docs Hook: Every time
hapo:sync marks a task as done, it must flag that a task-level docs checkpoint is now due for that verified task.
- Phase Prompt Rule: When
hapo:sync marks the final pending task in the whole feature as done, it should automatically prompt the user if they'd like to advance the phase, but only after the docs checkpoint for that last completed task has been considered.
References
Read references/sync-protocols.md for exact Search/Replace regex patterns and JSON schema expectations before acting on the files.
