project-sync — Canonical Playbook

Mirror the current state of all docs/PHASE_XX.md task checkboxes to GitHub Issues and a GitHub Projects v2 Kanban board. Idempotent — safe to run on every commit or on demand.

This document is the single source of truth for the project-sync workflow.

In an integrated project, runtime wrappers under .claude/skills/project-sync/SKILL.md (Claude Code) and plugins/sdd-workflow/{commands,skills}/project-sync/… (Codex) point here. The wrappers are thin stubs — every workflow detail lives in this file.

Input

/project-sync — sync all phases to the GitHub board /project-sync [XX] — sync single phase (two-digit, e.g. 01) /project-sync --dry-run — print diff without applying any changes /project-sync --setup — create GitHub Project + columns + sdd-workflow label; write config to docs/STACK.md /project-sync [XX] --dry-run — dry-run for a single phase

• XX — zero-padded phase number (e.g. 01). If omitted, all discovered docs/PHASE_XX.md files are processed.
• --dry-run — compute and print the full change queue but do not call any GitHub write API.
• --setup — one-time initialisation: creates a GitHub Project, status columns, and the sdd-workflow label; writes config to docs/STACK.md § GitHub Project. Must be run before the first sync.

Source of truth

The markdown files are always the source of truth. The GitHub board is a read-only view. Writing back from GitHub to markdown (e.g. issue closed on GitHub → uncheck box) is out of scope to avoid two-source-of-truth problems.

Required reads

• docs/PHASE_XX.md (all, or specified) — task checkboxes and phase status
• docs/STATE.md — phase status cross-check (informational only)
• docs/STACK.md § GitHub Project — project number and field IDs written by --setup

Idempotency mechanism

Every GitHub Issue created by this workflow has a hidden marker in its body:

```

```

On every run the workflow fetches all issues labelled sdd-workflow, parses their markers, builds a lookup map (PHASE_XX/KEY) → {issue_number, state, project_item_id}, diffs against current markdown state, and applies only the delta.

Task key derivation

• If a scope item contains an explicit bracket ID (e.g. **[B1]**, [F2], [I3]): use that as the key verbatim (e.g. B1, F2).
• Otherwise: derive a positional key T01, T02, … (sequential index within ## Scope, 1-based, zero-padded to two digits).
• Key format in the marker: PHASE_XX/B1 or PHASE_XX/T01.

Status → Project column mapping

Markdown state	Project column
task [ ], phase ⏳ pending	Todo
task [ ], phase 🔄 in-progress	In Progress
task [ ], phase ⚠️ NEEDS_REVIEW	Needs Review
task [ ], phase ❌ blocked	Blocked
task [x] (any phase status)	Done

Full lifecycle operations

Trigger	Operation
Task in markdown, no matching issue	Create issue + add to project + set column
Task title changed (same key)	Update issue title
Task [ ], matching issue is closed (not sdd-removed)	Reopen issue + set column
Task [x], matching issue is open	Close issue + set column to Done
Issue column differs from expected	Set column
Task removed from ## Scope	Close issue + add label sdd-removed
No change	No-op

Procedure

Step 1 — Prerequisite check

1. If --setup flag is present: run the Setup sub-procedure (§ below), then stop.
2. Check gh auth status. If not authenticated, stop:

   "Not authenticated. Run gh auth login first, then re-run /project-sync."

3. Confirm remote is GitHub: git remote get-url origin. Extract <owner>/<repo>. If the remote is not a github.com URL, stop with a clear message.
4. Read docs/STACK.md § GitHub Project. If the section does not exist, stop:

   "GitHub Project not configured. Run /project-sync --setup first."

5. Extract from the section: project_number, status_field_id, and option IDs for each column (Todo, In Progress, Needs Review, Blocked, Done).

Step 2 — Parse markdown state

1. Discover phase files: docs/PHASE_XX.md matching the pattern (all, or only the specified XX).
2. For each phase file extract:
3. phase_number — from filename (e.g. 01)
4. phase_title — from the # PHASE XX — … header line
5. phase_status — from the Status row of ## Phase Metadata table (emoji + word)
6. scope_items[] — every - [ ] or - [x] line under ## Scope:
   • key — explicit [ID] from the line if present, else T<NN> (positional)
   • title — text of the checkbox item, stripped of the ID prefix
   • checked — true if [x] or [X], false if [ ]

Step 3 — Fetch GitHub state

1. Run: bash gh issue list --repo <owner>/<repo> --label sdd-workflow --state all --limit 500 \ --json number,title,state,body,labels
2. For each issue, parse <!-- sdd-sync: PHASE_XX/KEY --> from the body.
3. Build lookup map: (PHASE_XX/KEY) → {number, state}.
4. To get project_item_id for column updates: query the project's items via gh project item-list <project_number> --owner <owner> --format json --limit 500 and join on issue URL.

Step 4 — Compute diff

For each scope item in each phase file:

1. Compute target_column from the status mapping table above.
2. Look up (PHASE_XX/KEY) in the GitHub map:
3. Not found → QUEUE create
4. Found, title differs → QUEUE update-title
5. Found, issue closed (not sdd-removed) + task unchecked → QUEUE reopen
6. Found, issue open + task checked → QUEUE close
7. Found, open + unchecked, column differs from target → QUEUE set-column
8. Otherwise → no-op

For each GitHub issue whose (PHASE_XX/KEY) is NOT present in any parsed phase file:

• If issue does NOT already have label sdd-removed → QUEUE archive

Step 5 — Dry-run check

If --dry-run was passed: print the full diff queue (all queued operations with their type, phase, key, and title). Print a summary count per operation type. Stop. Do not call any write API.

Step 6 — Apply changes

Execute queued operations in this order: create → update-title → archive → close → reopen → set-column.

create

```bash gh issue create \ --repo / \ --title "[PHASE_XX][KEY]