feat(task-utils): consolidate todo plugins with provider-based sync

[nsheaps]

Summary

Consolidates todo-plus-plus, todo-sync, and task-parallelization into a single task-utils plugin with provider-based task sync architecture.

Discord thread: https://discord.com/channels/1490863845252665415/1497254984696205445
Milestone: 999 - plugin consolidation

Changes

• Spec at plugins/task-utils/docs/spec.md — provider architecture, 7 hooks, MVP scope
• Deletes plugins/todo-plus-plus/, plugins/todo-sync/, plugins/task-parallelization/
• Creates plugins/task-utils/ with full scaffold: hooks, skills, lib, README
• Provider interface: FilesystemProvider + GitHubIssuesProvider (haiku sub-agent for find-or-update)
• Migrated hooks: check-uncommitted (full), session-start (extended), stop-guard (commented out)
• Migrated skills: task-parallelization, new task-management skill

Related issues

Closes #319 Closes #320
Related: #330 #370 #138 #64 #65

Test plan

• Install task-utils, verify hooks fire on TaskCreate/TaskUpdate/TaskCompleted
• Verify commit check blocks completion with uncommitted changes
• Verify stop guard warns (when enabled) on session exit with in-progress tasks
• Verify old plugins can be safely removed

Co-Authored-By: Jack Oat <jack-nsheaps[bot]@users.noreply.github.com>

[github-actions]

Plugin Version Status

Versions are auto-bumped in PRs. Manual bumps to higher versions are preserved.

Plugin	Base	Current	Action
task-utils	0.0.0	0.1.0	Already bumped

[henry-nsheaps]

👍 Round 3 — all round-2 blockers addressed; ready to merge

✅ Self-contradicting "keep todo-sync installed" note removed from README
✅ Inert config knobs now explicitly flagged "Not yet implemented" in README and spec
✅ MVP scope table marks 4 stub features as Stub (no-op, v1.1) instead of "In scope"
✅ PreToolUse no-op un-wired from hooks.json and marked deferred in spec
✅ session-start.sh header corrected — no longer claims "restores in-progress tasks"
✅ Spec frontmatter status: in-progress (was draft)
✅ Branch is MERGEABLE (was DIRTY)
🟢 Spec source attribution for Stop hook — still says "todo-plus-plus Stop hook" but todo-plus-plus had no Stop hook; non-blocking doc nit
🟢 stop-guard.sh header comment says "Commented out initially" but hook is wired; non-blocking doc nit

🖱️ Click to expand for full details

Context

f348856 resolved every blocking item from my round 2 review. This re-review verified the fixes against the shipped code at 6a31371 and confirmed merge-readiness. Most prior threads have been resolved; two minor doc-accuracy nits remain as non-blocking inline comments.

What was verified this round

• git show main:plugins/todo-plus-plus/hooks/hooks.json — confirmed the deleted todo-plus-plus hook config registered only TaskCompleted and SessionStart (no Stop), so the spec source attribution at spec.md:117 is still inaccurate. Fix is a one-line wording change; flagged inline.
• git show HEAD:.claude/settings.json — todo-sync@ai-mktpl removed from enabledPlugins. todo-plus-plus@ai-mktpl and task-parallelization@ai-mktpl were never in this file's enabled list (no removal needed in this repo's local settings).
• .claude-plugin/marketplace.json — three deleted plugins removed, task-utils@0.1.0 added with correct source and merged keyword set.
• plugins/task-utils/lib/log.sh — symlink to ../../../shared/lib/log.sh, matching the convention of the other 17 plugins per .claude/rules/shared-libs.md.
• plugins/task-utils/.release-it.js — present, mirrors the canonical pattern (extends: "../../.release-it.base.json" + @release-it/bumper for plugin.json).
• plugins/task-utils/.claude-plugin/plugin.json — "version": "0.1.0", appropriate for scaffold release.
• plugins/task-utils/hooks/hooks.json — PreToolUse removed; remaining 5 entries (TaskCompleted, SessionStart, Stop, PostToolUse:TaskCreate, PostToolUse:TaskUpdate) are intentional per the spec's Hook table.
• plugins/task-utils/README.md — Configuration section now leads with "Not yet implemented" disclaimer; "keep todo-sync installed" advice removed; feature list marks 3 hooks explicitly as (scaffold — no-op in this release).
• plugins/task-utils/docs/spec.md — frontmatter status: in-progress; MVP scope table marks 4 rows as Stub (no-op, v1.1); PreToolUse row notes "script exists but is not wired."
• plugins/task-utils/hooks/scripts/session-start.sh — header comment no longer claims restore behavior; only emits the static systemMessage heredoc.
• grep -rn "plugin_get_config\|plugin_is_enabled" plugins/task-utils/ — confirmed zero hits in scripts (the only mention is a self-disclosure in spec.md:161).

Remaining non-blocking items

1. Spec source attribution (spec.md:117) — still misattributes the Stop hook to todo-plus-plus. Inline comment with a one-line suggestion block. Doc accuracy only.
2. stop-guard.sh:6 stale comment — says "Commented out initially" but the hook is registered and runs as a no-op. Inline comment with a suggestion block aligning the comment with spec.md:120's wording.

Both are pure documentation; the shipped behavior is correct.

Scoring rationale

• Code Quality (92%) — Up from 80% in round 2. All structural and accuracy concerns resolved. Migrated code (commit guard, session awareness, parallelization skill) is faithful and clean. Docked 8% for two stale-comment / source-attribution nits and the lingering Stop no-op stub firing on session end (per-event cost is negligible, so this isn't worth blocking on).
• Security (N/A) — Plugin scaffold; no new auth or trust surface.
• Simplicity (92%) — Up from 85%. README/spec/code now agree on what's implemented vs. deferred, which removes the confusion that drove the previous score. Six hook entry points where 3 are placeholders is still a structural choice the v1.1 work will validate.
• Confidence (93%) — Up from 88%. Verified each fix against the actual file in HEAD, ran git show main: for deleted-file verification, confirmed symlink target via readlink, and confirmed the auto-bump github-app line in marketplace.json is just a stale auto-bump artifact (no actual code change in plugins/github-app/). Cannot verify .tool_response vs .tool_result against a live Claude Code hook payload, but that uncertainty is now appropriately tracked in the script's TODO.

Auto-bump artifact note

plugins/github-app/.claude-plugin/plugin.json ships a 0.3.1 → 0.3.2 bump in this PR with no corresponding code changes. This is a stale auto-bump artifact from earlier in the branch's life, not author-introduced. Won't affect anything functionally; flagging for awareness in case future review tooling queries "why did github-app bump in a task-utils PR?"

What I couldn't verify

• Live Claude Code hook payload schema for PostToolUse:TaskCreate / TaskUpdate (whether .tool_response or .tool_result is the canonical field). The script TODO comment at sync-task-create.sh:22 already calls this out as a follow-up; acceptable for a stub.
• That TaskCompleted, TaskCreate, TaskUpdate matchers continue to fire in the current Claude Code version. They were active in todo-plus-plus historically.

Recommended follow-ups (non-blocking, for v1.1):

• File a tracked issue to verify hook payload schema (.tool_response vs .tool_result) against a live PostToolUse invocation, and link it from sync-task-create.sh:22 and sync-task-update.sh:22. The two stubs use different shapes (.tool_result.taskId vs .tool_input.id) so they will need a single source of truth before either provider can sync correctly.
• Consider a smoke-test mise task (mise run test:task-utils) that pipes minimal stdin JSON into each hook script and asserts exit codes — would catch shell regressions and protect against schema drift at provider-implementation time.
• The "ALWAYS use TaskCreate on EVERY action request even for simple one-offs" framing in task-management/SKILL.md:12 is heavy — consider softening once the skill has had real-world usage. Carrying forward as a v1.1 judgment call rather than a blocker.

Notes:¹²³⁴⁵

Footnotes

1. Workflow Run: https://github.com/nsheaps/ai-mktpl/actions/runs/24958799575/attempts/1 ↩

2. PR: nsheaps/ai-mktpl#430 ↩

3. Shared libs convention: .claude/rules/shared-libs.md ↩

4. Hook output patterns: .claude/rules/hook-output-patterns.md ↩

5. Versioning rules: .claude/rules/versioning.md ↩

[henry-nsheaps]

🟢 Source attribution still inaccurate (carry-forward from round 1)

todo-plus-plus never had a Stop hook. Verified against the deleted plugins/todo-plus-plus/hooks/hooks.json — only TaskCompleted and SessionStart were registered there.

The hook script header at plugins/task-utils/hooks/scripts/stop-guard.sh:5 already attributes correctly:

# Source: migrated from agent repo (was in .claude/rules as a hook, not a plugin hook).

Recommend matching the spec to that:

Suggested change

	**Source**: todo-plus-plus `Stop` hook — **migrated from agent repo to plugin**
	**Source**: Migrated from agent repo `.claude/rules`/hook configuration (not part of the deleted todo-plus-plus plugin)

Non-blocking for this PR — pure documentation accuracy. Flagging because the same incorrect attribution would otherwise propagate into anyone reading this spec as the canonical history of the consolidation.

[henry-nsheaps]

🟢 Stale header comment — script is wired in hooks.json, not commented out

The header still says "Commented out initially pending validation in plugin context" but hooks.json:28-39 registers this script on Stop with matcher * and a 10s timeout. The script is firing on every session-stop, just no-op'ing.

Recommend aligning the comment with the spec's wording (spec.md:120 says "Registered as a no-op stub, full logic deferred to v1.1"):

Suggested change

	# Commented out initially pending validation in plugin context — see spec.
	# Source: migrated from agent repo (was in .claude/rules as a hook, not a plugin hook).
	# Registered as a no-op stub — full logic deferred to v1.1 pending validation in plugin context.

Non-blocking, doc accuracy only. The Stop hook firing once per session is negligible overhead so the per-call concern that drove un-wiring PreToolUse doesn't apply here.