task-sync

name	task-sync
description	Manage a local task/backlog list (tasks.json + a generated TASKS.md) for the current repo and reconcile it with GitHub or Gitea issues, via the bundled task-sync Python tool. Supports direct commands (list/add/edit/done/remove/ status/init) and a plan-decide-apply sync that surfaces creates, pushes, pulls, conflicts, and confidentiality findings for review before anything leaves the machine, with a public-repo push warning and a --dry-run mode. Suggest when — the user wants to see or manage this repo's tasks or backlog, sync tasks with GitHub/Gitea issues, mentions a local task tracker or TASKS.md, or asks to push/pull/reconcile tasks against issues; keywords — task list, backlog, sync issues, task-sync, todo list, reconcile issues.
argument-hint	[sync|list|add|edit|done|remove|status|init] [args...] [--dry-run]
effort	medium
allowed-tools	Read, Write, Edit, Glob, Bash

Task Sync

Local-first task tracking backed by a canonical tasks.json (with a generated, read-only TASKS.md view) that optionally reconciles with GitHub or Gitea issues. All logic lives in the bundled task_sync Python tool — this skill's job is invocation, table rendering, and human-in-the-loop decisions (conflict resolution, confidentiality review, the public-repo push warning). The tool never auto-resolves a conflict and never pushes anything without an explicit plan the user has seen.

Setup

The tool is bundled at tools/task-sync/src. Resolve the plugin root the same way other bundled-tool skills do, then invoke every subcommand through python3 -m task_sync:

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(find ~ -path '*/plugins/personal-plugin' -type d 2>/dev/null | head -1)}"
TOOL_SRC="$PLUGIN_DIR/tools/task-sync/src"

PYTHONPATH="$TOOL_SRC" python3 -m task_sync status

tasks.json lives at the target repo's root by default (--tasks tasks.json, resolved relative to the working directory). Pass --tasks <path> for any other location.

First Run: Auto-Init

Before any subcommand, check whether tasks.json exists at the target repo root. If not, run init first (this is a no-op if it already exists, so it is always safe to run):

PYTHONPATH="$TOOL_SRC" python3 -m task_sync init

init detects the provider (github, gitea, or none for local-only) from the origin git remote, writes the tasks.json header (provider, repo, last_sync_at: null, and a config block with prune_closed_after_days: 30 and an empty sensitive_terms list), and generates TASKS.md. After init, also make sure TASKS.md is gitignored in the target repo (it is a generated view, regenerated after every mutating command — never hand-edit it, never commit it):

grep -qxF 'TASKS.md' .gitignore 2>/dev/null || echo 'TASKS.md' >> .gitignore

Commands

Direct subcommand invocation and natural-language requests both route to the same tool calls. Full flag reference: references/command-reference.md.

Command	Aliases	Natural language	Mutates?
sync	—	"sync my tasks", "push/pull tasks", "reconcile with issues"	plan→decide→apply, see below
list	ls	"show my tasks", "what's open", "list backlog"	no
add "title"	—	"add a task to …", "track this as a task"	yes
edit <id|#>	—	"update task …", "change the priority of …"	yes
done <id|#>	close	"mark … done", "close task …"	yes
remove <id|#>	rm	"delete task …", "drop …"	yes
status	—	"task status", "how many open tasks"	no
init	—	"set up task tracking here"	yes (first run only)

For a bare command (list, add "…", edit, done, remove, status, init), run init if needed (see above), then invoke the subcommand and report its output directly — no plan/decide/apply cycle applies to these; store.save + TASKS.md regeneration happen inside the tool itself.

<id|#> accepts either a task id (t-ab12cd) or an issue number, optionally #-prefixed (42 or #42) — whichever the user gave.

When the user just says "sync" (or gives no subcommand and a tracker is configured), run the full plan→decide→apply flow below.

Plan → Decide → Apply (sync)

Never call sync --apply blind. Always build and show a plan first, get explicit decisions for anything ambiguous, then apply.

1. Build the plan

PYTHONPATH="$TOOL_SRC" python3 -m task_sync sync --plan --json

This is strictly read-only — it never writes tasks.json or TASKS.md and never calls the tracker's write API. If the repo has no tracker remote, the tool prints "local-only mode" and exits 0; there is nothing to plan.

Parse the JSON: creates, pushes, pulls, conflicts, confidentiality_findings. Field shapes: references/sync-semantics.md.

2. Render the plan as tables

Show the user what would happen, grouped by section, before asking for any decision:

• Creates — local tasks with no issue yet → new issues (title, priority, labels, milestone).
• Pushes — local edits → update an existing issue (#<issue_number>, what changed).
• Pulls — remote-only or remote-changed issues → adopted or updated locally (#<issue_number>, resulting status/title).
• Conflicts — both sides changed since the last sync; render as a side-by-side table (local vs remote, each field) with the tool's recommendation (last-write-wins) called out, but never pre-select it.

If every section is empty, report "already in sync" and stop — there is nothing to decide or apply.

3. Confidentiality scan

The plan JSON from step 1 already carries the scan results — no separate scan step is needed. Before building the plan, the tool itself scans every creates/pushes task's current title/body for secrets, structural identifiers (emails, internal hostnames, ticket/asset ids), and any per-repo sensitive_terms from tasks.json's config, skipping a task whose prior review still covers its content unchanged. Just read confidentiality_findings off the plan you already fetched. Field shapes and detector details: references/confidentiality-flow.md.

Render every finding as a table (task, field, category, severity, preview — never the full secret) and ask the user to disposition each one. CRITICAL findings (real secret/token shapes) need an explicit decision; do not let a push proceed past them silently.

4. Prompt for every decision

For each conflict, ask the user to pick local or remote (showing the recommendation as a hint, not a default). For each confidentiality finding, ask for keep, redact, remove, or anonymize. Do not guess — an unanswered conflict is left untouched by apply and simply resurfaces next sync, so it is always safe to defer one the user is unsure about.

Write the conflict decisions to a JSON file (flat {task_id: "local"|"remote"}, or {"decisions": {...}}):

cat > /tmp/task-sync-decisions.json <<'JSON'
{"t-ab12cd": "local", "t-ef34gh": "remote"}
JSON

Apply confidentiality dispositions immediately (before sync --apply) using the disposition-apply script from references/confidentiality-flow.md — this directly saves tasks.json and regenerates TASKS.md. (Disposition apply is not yet a dedicated CLI subcommand; scanning is — the plan already did that part in step 3.)

5. Public-repo visibility guardrail

Before the first push or create in this session, check the repo's visibility and warn loudly if it is public:

gh repo view --json visibility --jq .visibility 2>/dev/null

(For a Gitea remote, check the repo's private field via its REST API using the token from ~/.config/tea/config.yml, the same source the tool's own Gitea adapter uses.)

If the result is PUBLIC (GitHub) or private: false (Gitea), show:

Warning: <owner>/<repo> is a PUBLIC repository.
Creating/updating N issue(s) will publish this content publicly.
Continue? (yes / no / show plan again)

Do not proceed to apply without an explicit "yes". A private repo needs no extra confirmation beyond the normal plan review.

6. Apply

PYTHONPATH="$TOOL_SRC" python3 -m task_sync sync --apply --decisions /tmp/task-sync-decisions.json

This executes creates/pushes/pulls, applies only the decided conflicts (undecided ones are left exactly as-is), prunes done tasks whose issue closed more than prune_closed_after_days ago, refreshes last_sync_at, and saves tasks.json + regenerates TASKS.md — all inside the tool, atomically. Report the printed summary (counts of creates/pushes/pulls, conflicts surfaced) to the user.

--dry-run

sync --dry-run (or sync with no mode flag — this is the default) prints a short human summary of the same plan and writes nothing. Use it whenever the user wants a preview without going through the decide/apply steps: run it, show the summary, and stop. Do not build a decisions file or call --apply.

Confidentiality Flow (summary)

Four dispositions, applied deterministically by the tool and remembered by content hash (keep is a no-op; redact masks a span; remove deletes it; anonymize swaps in a stable <<TERM_xxxxxx>> token so the same term always maps to the same token). A previously-reviewed task is skipped on re-scan unless its content changed — the scan itself runs inside sync --plan/ --dry-run now, so there is nothing to invoke separately for it. Full flow, output shapes, and the disposition-apply script: references/confidentiality-flow.md.

Sync Semantics (summary)

Three-way classification against the last synced base: exactly one side changed → applied automatically in that direction; both sides changed → surfaced as a conflict, recommendation is last-write-wins but nothing is auto-applied. Full classify/resolve/prune rules: references/sync-semantics.md.

Config (tasks.json)

Header fields (provider, repo, last_sync_at, config) and the config block (prune_closed_after_days, sensitive_terms, optional gitea_url): references/config-reference.md.

Error Handling

• No tasks.json for a non-init command: run init first (see "First Run: Auto-Init"), then retry the original command.
• gh/Gitea auth failure during sync: report the tool's error verbatim (it names the missing credential — gh auth login or tea login) and stop; do not retry blind.
• Unresolved conflicts after apply: expected, not an error — they were left untouched on purpose and will resurface on the next sync --plan.
• add/edit validation error (bad status/priority): the tool rejects it with a clear message; relay it and ask the user to correct the value.

References

• references/command-reference.md — full flag reference for every subcommand.
• references/sync-semantics.md — 3-way classify, last-write-wins, conflicts, prune.
• references/confidentiality-flow.md — scan/disposition flow and exact inline scripts.
• references/config-reference.md — tasks.json header and config shape.