Skip to main content

Repo + Tracker Consolidation

Use when merging split code+issues+Kanban to one repo. Consolidate a multi-agent build whose code, GitHub issues/milestones, and linked Kanban board are scattered across two repos (or whose local repo points at the wrong remote) onto ONE repo and ONE board. Every step is readback-verified. Full step-by-step in references/consolidation-playbook.md.

Complements: github-repo-management (remotes/repos), github-token-access-verification (which credential reaches what), github-issues (issue CRUD). This skill is the orchestration of all three for a migration.

When to use​

  • Local repo's origin points at a repo you never successfully pushed to, and the real destination is a different repo.
  • Issues/milestones live on repo A but code should live on repo B (or vice versa).
  • A Kanban board is named/slugged after the old repo and needs to follow the code.

Golden rules (the ones that bite if ignored)​

  1. The three surfaces are independent facts — probe each separately. Code push access, REST issue access, and "is the remote populated" are NOT the same signal. Real case: a repo whose git push returned 403 "Write access not granted" still had 36 issues reachable via REST HTTP 200. Never conclude "empty" or "no issues" from a single failing signal. permissions.push == true from GET /repos/O/R is the go/no-go for the code push.

  2. git smart-HTTP auth header format ≠ REST header format. REST takes Authorization: token <PAT>. Git transport (ls-remote/fetch/push via http.extraheader) needs Authorization: Basic <base64 of x-access-token:PAT> — the token form yields remote: invalid credentials. One-off reads can use https://x-access-token:$T@github.com/O/R.git.

  3. Repoint remotes non-destructively. git remote set-url origin <new> then git push --force-with-lease=main:<target-current-sha> origin <localbranch>:main. Confirm the local branch name first — it is often work/..., not main (git rev-parse --abbrev-ref HEAD). Nothing is lost if the old remote never accepted a push.

  4. Preserve historical evidence verbatim. Do NOT sed the old repo name across committed artifacts/, logs, or evidence — they record what was true at execution time; rewriting them falsifies the record and violates evidence-integrity expectations. Retarget ONLY forward-looking config/docs (manifests, plan/spec, mapping JSON, README). Add a RETARGET.md recording the split.

  5. Idempotent + readback on every mutation. Key issues/cards on a stable id prefix (e.g. AF-NN); skip if the target already has the item. After creating/closing/linking, re-fetch and verify counts, distinct ids, no dupes, milestone attachment, and zero stale old-repo references.

  6. Close, don't delete, superseded issues. PATCH {state:closed, state_reason:not_planned} with a pointer comment to the consolidated issue. Preserves history and backlinks.

Kanban board slug is immutable​

hermes kanban boards rename <slug> <name> changes only the display name. To change the slug, export/import:

hermes kanban boards export <old-slug> -o /tmp/board.tar.gz
hermes kanban boards import /tmp/board.tar.gz --as <new-slug>   # preserves card ids, history, links
hermes kanban boards rename <new-slug> "Display Name"
hermes kanban boards switch <new-slug>
hermes kanban boards rm <old-slug>            # archives to _archived/ (recoverable), does NOT delete
hermes kanban boards switch <new-slug>        # rm flips active board to 'default' — re-switch

Verify the imported board's task count + PROGRAM id + issue links match before archiving the old one. Card body text and board.json description may still name the old repo — fix separately.

Sequence (high level)​

  1. Establish true state per surface. 1. Repoint remote + push code (force-with-lease). 2. Recreate milestones then issues on target (idempotent, provenance footer, readback). 3. Close old issues with pointers. 4. Re-link live Kanban DB (back up first). 5. Rename board slug via export/import.
  2. Commit forward-looking retargets + RETARGET.md; push; verify remote SHA == local HEAD.
  3. Final reconciliation report with real counts from all three surfaces.

Ask-first, don't guess​

Migrations have irreversible-feeling steps (force-push to main, creating/closing dozens of issues, mutating a live board). When the true state contradicts the user's stated instruction (e.g. "retarget to repo B" but the backlog is already live on repo A), surface the real state and confirm the reconciliation approach before executing — don't silently pick one.

Supporting files: this skill's supporting files are held in the docsite at docs/15-skills/_support/github/repo-and-tracker-consolidation/ — fetch them fresh from jknash/docsite main alongside this page. Source: jknash/hermes-shared-skills · branch hermes-jkdev001 @ 1d0d545c3970 · skills/github/repo-and-tracker-consolidation/ · view source · Imported 2026-10-03. Supporting files (references, scripts) remain in the source repository.

version 1.0.0 · author Hermes Agent · license MIT.

Published by Muse · 2026-10-03.