Skip to content

v1.37.0 ·

A workflow that had never run

The problem

Turning on roadmap.sync puts every roadmap item on GitHub as a labelled issue, and then stops. A GitHub Project board added on top shows every issue in one column, with nothing to move it. Two repositories have hit this: this one on 2026-09-08 (55 issues, one column) and fieldmodel-apps on 2026-09-28.

The stop is deliberate. Writing a Project's Status field needs a token with project: write, and the workflow's own GITHUB_TOKEN cannot do it at any permission level. The answer — a small workflow that reads the aidlc:<status> label and sets the column — exists in this repository at .github/workflows/project-status.yml, and nowhere a user of the package can find it.

Checked on 2026-09-28, that workflow has never written to a board. Every run on record is skipped or cancelled: AIDLC_PROJECT_NUMBER was never set. This repository's own board (project 3) still shows 16 Inbox and 17 On Hold, three weeks after those statuses were emptied into backlog. "Working" in the backlog item was an untested claim.

Two defects are visible without running it:

  • It needs gh 2.97.0 or later (2026-07-31), the first release where gh project item-edit takes --url and --field. An older runner image would fail with an unknown-flag error.
  • It hard-codes the discovery label aidlc, while roadmap.sync.label lets a project rename it. On such a project every run would skip, green, having written nothing.

How it could be solved

Three decisions, each about how much of the job the tool should take on.

The first was where the workflow should live so people could find it. The obvious place was the documentation pages, and those are only in this repository; a project that installs the package never sees them. The tool itself is always there. So the workflow now ships inside the package and a command prints it. Copying it into every project on each update was considered and turned down: most projects never want a board, and a file the tool copies is a file the tool must then keep in step and clean up.

The second was whether the tool should install the workflow, or skip the workflow and move the board itself. Both would feel more finished. Installing it saves the smallest part of the job, because the token is the real setup cost, and it would make this project responsible for CI running in other people's repositories with their tokens. Moving the board from the sync command would be better product, but it puts a token that can write to projects in the sync path for every user, for a need that one person has asked for twice. That waits until someone else asks.

The third was whether to trust the workflow at all. The backlog item called it working. Checking showed it had never run: every run on record was skipped, because the project number had never been set. So before shipping, its steps were run against a real board, and a real card moved. That check also found the two defects the release fixes, and neither would have shown up in this repository, which uses the default label and a recent gh.

How AIDLC solves it

A roadmap projected onto GitHub issues can now drive a Project board. Run aidlc roadmap board-workflow and it prints a GitHub Actions workflow; save it under your repository's workflows folder, store a token that can write to projects, set the project number, and each issue's card follows its roadmap status label.

The tool prints the file and never installs it. Moving a board needs a token that the workflow's own token cannot be, so the real setup cost is creating one, and CI that runs in your repository with your token is yours to own.

The workflow is the one this repository already had, with two fixes found on the way out. It read the discovery label as a fixed word, so a project that renamed it would have skipped every issue and reported success. It now reads a variable. And it relied on a gh flag that arrived in 2.97.0, so it now checks the runner's gh first and names the version if it is too old.

The status labels are now a stated promise: renaming or removing one is a breaking change. A test fails if the workflow's column map misses any status, and another fails if this repository's copy of the workflow drifts from the one that ships.

Before this release the workflow had never written to a board. It has now: run against this repository's own board, it moved issue #56 from Inbox to In Progress.