# Sync Roadmap Kanban

> Reconcile kanban board state with roadmap docs and codebase reality — sync cards, steps, and git history so they agree.

- Skill: `georgeqle/sync-roadmap-kanban` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add georgeqle/sync-roadmap-kanban`
- Raw SKILL.md: https://api.skillmd.com/api/skills/georgeqle/sync-roadmap-kanban/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: GeorgeQLe (https://skillmd.com/u/georgeqle)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/georgeqle/sync-roadmap-kanban

---


# Sync Roadmap ↔ Kanban

Invoke as `$sync-roadmap-kanban`.

Reconcile the kanban board, roadmap docs, and codebase state so all three reflect the same reality.

## Process

1. **Pull latest** — run the sync skill first. Stop on merge conflicts.

2. **Read kanban state** — run `poketo kanban boards` to list all boards. Auto-detect the project board:
   - If `tasks/.kanban-board` exists and contains a valid board ID, use it after verifying via `poketo kanban board <id>`.
   - Otherwise, match board names against `basename $(pwd)` (case-insensitive substring). If exactly one match, use it and save the ID to `tasks/.kanban-board`.
   - If zero or multiple matches, list boards, ask the user to pick, and save their choice to `tasks/.kanban-board`. If the session is already in Plan mode and there are 2-3 concrete choices, prefer `request_user_input`.
   - Run `poketo kanban board <id>` to get the full board state.

3. **Read roadmap docs** — read `tasks/roadmap.md`, `tasks/todo.md`, and `tasks/manual-todo.md` (if it exists). Read `tasks/record-todo.md` and `tasks/recurring-todo.md` only for advisory counts. List execution/manual items with checked/unchecked status.

4. **Read codebase reality** — `git log --oneline -30`. For items claimed done, verify deliverables exist (file checks, grep for key identifiers). Flag ambiguous cases.

5. **Reconcile** using these rules:
   - **Done on kanban + code confirms** → check off in roadmap
   - **Done in roadmap + code confirms** → move kanban card to Done
   - **New roadmap items, no card** → create kanban cards (backlog or in-progress)
   - **Record/recurring task items** → report counts only; do not create ordinary Todo cards unless the item has already been promoted into `tasks/todo.md`
   - **Orphaned cards** → flag (do NOT delete)
   - **Claimed done, code doesn't support** → flag as discrepancy (do NOT uncheck)

6. **Apply changes** — create/move cards via `poketo kanban`, edit roadmap docs. Re-fetch board to confirm.

7. **Report** — synced items, discrepancies needing human judgment, updated board state, roadmap progress, manual task status (from `tasks/manual-todo.md` if it exists), and advisory record/recurring counts if those files exist.

## Constraints

- Do not auto-resolve discrepancies — report and let the user decide.
- Do not delete kanban cards.
- Do not modify code — sync metadata only.
- Do not proceed on a dirty tree with merge conflicts.
- Match cards to roadmap items by name similarity; ask when ambiguous.
- If the poketo CLI is unavailable or the gateway fails, report the error and stop.


## Alignment Page

When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page following `ALIGNMENT-PAGE.md` in this skill's directory. Output: `alignment/sync-roadmap-kanban-{topic}.html`.

## Default Shipping Contract

Follow the shared shipping contract convention in CLAUDE.md.