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
Pull latest — run the sync skill first. Stop on merge conflicts.
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.
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.
Read codebase reality — git log --oneline -30. For items claimed done, verify deliverables exist (file checks, grep for key identifiers). Flag ambiguous cases.
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)
Apply changes — create/move cards via poketo kanban, edit roadmap docs. Re-fetch board to confirm.
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.
1---2name: sync-roadmap-kanban3description: Reconcile kanban board state with roadmap docs and codebase reality — sync cards, steps, and git history so they agree.4---5
6# Sync Roadmap ↔ Kanban
7
8Invoke as `$sync-roadmap-kanban`.
9
10Reconcile the kanban board, roadmap docs, and codebase state so all three reflect the same reality.
11
12## Process
13
141. **Pull latest** — run the sync skill first. Stop on merge conflicts.
15
162. **Read kanban state** — run `poketo kanban boards` to list all boards. Auto-detect the project board:
17 - If `tasks/.kanban-board` exists and contains a valid board ID, use it after verifying via `poketo kanban board <id>`.
18 - Otherwise, match board names against `basename $(pwd)` (case-insensitive substring). If exactly one match, use it and save the ID to `tasks/.kanban-board`.
19 - 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`.
20 - Run `poketo kanban board <id>` to get the full board state.
21
223. **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.
23
244. **Read codebase reality** — `git log --oneline -30`. For items claimed done, verify deliverables exist (file checks, grep for key identifiers). Flag ambiguous cases.
25
265. **Reconcile** using these rules:
27 - **Done on kanban + code confirms** → check off in roadmap
28 - **Done in roadmap + code confirms** → move kanban card to Done
29 - **New roadmap items, no card** → create kanban cards (backlog or in-progress)
30 - **Record/recurring task items** → report counts only; do not create ordinary Todo cards unless the item has already been promoted into `tasks/todo.md`
31 - **Orphaned cards** → flag (do NOT delete)
32 - **Claimed done, code doesn't support** → flag as discrepancy (do NOT uncheck)
33
346. **Apply changes** — create/move cards via `poketo kanban`, edit roadmap docs. Re-fetch board to confirm.
35
367. **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.
37
38## Constraints
39
40- Do not auto-resolve discrepancies — report and let the user decide.
41- Do not delete kanban cards.
42- Do not modify code — sync metadata only.
43- Do not proceed on a dirty tree with merge conflicts.
44- Match cards to roadmap items by name similarity; ask when ambiguous.
45- If the poketo CLI is unavailable or the gateway fails, report the error and stop.
46
47
48## Alignment Page
49
50When 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`.
51
52## Default Shipping Contract
53
54Follow the shared shipping contract convention in CLAUDE.md.
GeorgeQLe