pm-sync

PM Sync Skill

This skill uses abstract PM operations. The actual PM adapter (ClickUp, Jira, etc.) is configured in ~/.shield/projects/<project>/pm.json.

Before calling any pm_* tool, call pm_get_capabilities to check which operations the adapter supports. Skip unsupported operations gracefully.

Overview

Orchestrate project management operations through abstract PM adapters — sync plan documents, create story cards in bulk, and track sprint progress.

Core principle: Always sync before mutating. Show the user the diff, get confirmation, then execute.

When to Use

• Syncing plan docs to PM tool (creating/updating stories)
• Bulk operations on PM tasks (create, update, reorder)
• Sprint status checks and epic progress tracking
• Setting EPIC relationship fields on tasks

When NOT to Use

• Individual task updates — use PM tool UI directly
• Creating plan documents — use the plan-review skill
• Non-sprint project management

Available Tools

Tool	Purpose
pm_get_capabilities	Check which operations the configured adapter supports
pm_sync_sidecar	Diff plan.json sidecar against PM tool state (read-only) — requires plan_json_path arg
pm_backfill_ids	Write created ClickUp task ids/urls back into plan.json (makes re-sync idempotent)
pm_bulk_create	Create multiple tasks + set EPIC relationships
pm_link_story_to_epic	Set list_relationship custom fields directly
pm_bulk_update	Batch update status/assignee/priority
pm_get_status	Get epic overview with stats
pm_action_log	Query past operations

Rules

1. Check capabilities first. Always call pm_get_capabilities before any other pm_* call. If an operation is unsupported, inform the user and skip it.
2. Sync before mutating. Always call pm_sync_sidecar first. Present the diff and get confirmation.
3. Use bulk operations. Never create tasks one-by-one. Use pm_bulk_create with set_relationships: true.
4. Read config, don't hardcode. All IDs come from ~/.shield/projects/<project>/pm.json. Never hardcode PM tool IDs.
5. Always locate and read plan sidecar JSONs first. Read output_dir from .shield.json (default docs/shield), then run Glob("{output_dir}/*/plan.json") to find all sidecars. Read the relevant sidecar for story data — not raw HTML or plan docs. If multiple plans exist and no name specified, list them and ask. Never claim sidecars don't exist without searching first. The MCP tool pm_sync_sidecar now takes the full plan_json_path as an explicit argument — the skill resolves the path and passes it in.
6. Confirm before mutating. Show the user exactly what will happen and ask for confirmation.
7. Surface errors clearly. If tools report failure, it's real. Show which operations succeeded vs failed.
8. Present results as tables. After any operation, show task names, IDs, statuses, and any failures.
9. Never use raw PM tool APIs for sprint write operations. Always use pm_bulk_create / pm_bulk_update / pm_link_story_to_epic — raw API calls bypass the action log and skip naming/relationship logic.