Process & Registry
Family Roadmap board
One GitHub Project, Amoleo Family Roadmap (https://github.com/users/ValadAmoleo/projects/29), that shows every product's backlog in one place so the family can be planned across products. Added 1 Oct 2026.
Not to be confused with family-roadmap.md ("Build Roadmap"), which is a written decision about which repo to build next. This is a live board of the work items in all of them.
What it contains
- Every issue on every product's own backlog board (
Amoleo-Pets Backlog,Amoleo-Accounts Backlog, and so on): the repos listed insourceBoardsintools/roadmap-board/config.json. - The issues logged on Amoleo-Family itself, which has no backlog board of its own.
An item is on its product board and the roadmap at once. It is the same issue, not a copy; closing or editing the issue shows everywhere.
Not on it: items archived on a product board, draft items, and the legacy
boards (#1, #3, #5, #24), listed under ignoredBoards.
Fields
| Field | Behaviour |
|---|---|
| Status | Mirrored. Copied from the product board on each sync; edits on the roadmap are overwritten. |
| Effort | Mirrored, same rule. |
| Priority | Roadmap-only, blank to start. The family-wide priority; deliberately not the repo's own Priority, since "P1" in Budget and "P1" in Accounts aren't comparable. Never read or written by sync. |
| Target date | Roadmap-only. Never read or written by sync. |
The rule behind the split: a fact about the work (its stage, its size) has one owner, the product board, and the roadmap reads it. A decision about the whole family (priority, when) has no home in any one repo, so it lives only here.
How it stays current
One-way, product board to roadmap, hourly by the Roadmap sync GitHub
Action (.github/workflows/roadmap-sync.yml), and on demand from the Actions
tab ("Run workflow") or locally:
node tools/roadmap-board/sync.mjs sync --dry # preview, writes nothing
node tools/roadmap-board/sync.mjs sync
It adds items that are missing, then overwrites Status and Effort where they differ. It never removes an item and never touches Priority or Target date. It is idempotent: a second run reports 0 differences.
The roadmap therefore lags a product board by up to an hour. The Action
authenticates with a classic PAT (scopes repo and project) stored as the
repo secret ROADMAP_SYNC_TOKEN, because the built-in GITHUB_TOKEN cannot
see user-owned Projects. If that token expires or is revoked the run fails
with a red X rather than silently going stale. Rotate it by replacing the
secret.
Things that behave oddly
- Sub-issues arrive uninvited. GitHub's "auto-add sub-issues" project setting adds an issue's sub-issues when the parent is added, including closed ones archived on the product board. The first sync pulled in 15 and they were removed by hand; if it recurs, turn that setting off for the board in the UI.
- An issue on two source boards (Accounts#62 is on Accounts' and Connections') takes the later board's values. The sync warns when it sees one.
- The API cannot create views. Roadmap timeline, per-repo grouping and a Priority board are set up in the GitHub UI.
Adding a repo
A new repo's board has to be registered, or its work never appears. The
github-project-backlog skill does it at the end of setup (since 1.22.0):
add the board's project number to sourceBoards in
tools/roadmap-board/config.json, then run the sync. The sync warns on
every run about any * Backlog board that is neither in sourceBoards nor
ignoredBoards, so a forgotten registration is loud rather than silent.
What each repo's tooling says
Every family repo's docs/Backlog.md and its CLAUDE.md backlog block carry a
short section describing the above, generated from the skill's
templates/family-roadmap-section.md and templates/family-roadmap-claude-md.md.
Repos set up before skill 1.22.0 get it the next time the skill is run on
them (section "Adding the Family Roadmap to an existing Amoleo family repo").
Generated from docs/family-roadmap-board.md. Edit there and re-run npm run build in docs-site-src/ — never hand-edit a page.