Send your roadmap to GitHub Issues and a Project board

Copy your roadmap items to GitHub Issues with one command. Items in backlog/, in-progress/ and done/ become issues; inbox/ and hold/ stay private. The copy is one way: the files in .aidlc/roadmap/ stay the source, and GitHub follows them. Moving cards on a Project board is an optional extra, and it must be set up first.

1. Install the GitHub CLI and sign in. AIDLC uses its login and never asks for a token:

   gh auth login
   

2. Turn the sync on. roadmap sync does nothing until .aidlc/config.yaml has a roadmap.sync section. aidlc init offers to write it, or add it yourself:

   roadmap:
     sync:
       provider: github
       statuses: [backlog, in-progress, done]
   

   statuses must include done. Add repo: <owner/name> to target a repository other than the one your folder points at.

3. Optional — if you want a Project board, set it up now, before the first sync. A label change made before the board is ready is skipped and never replayed. Do these in order:

   • Create the Project on GitHub with a Status column for each state you sync.

   • Save the workflow AIDLC ships, then commit it and push it:

     aidlc roadmap board-workflow > .github/workflows/aidlc-project-status.yml
     

   • In your repository's settings, store a classic token as the secret AIDLC_PROJECT_TOKEN, with <your-github-token> as the value. Give it the project and read:org scopes (add repo if the repository is private). Never paste it into a file you commit. Use a classic token because a fine-grained one cannot reach a project on a personal account.

   • Set the repository variable AIDLC_PROJECT_NUMBER to your project's number — the digits in its URL.

   The top of the workflow file lists the Status columns it expects and how to rename them.

4. Preview what would change. This writes nothing:

   aidlc roadmap sync --dry-run
   

5. Apply it:

   aidlc roadmap sync
   

   It shows the plan and asks before it writes. Run it again whenever items move — it updates labels, and closes an issue when its item reaches done/.

Open your repository's Issues tab on GitHub. You should see one issue per roadmap item in backlog/, in-progress/ and done/, each labelled aidlc. If you set up the board, move an item and run aidlc roadmap sync again: once the workflow run shows in your Actions tab, its card should be in the new column.