GitHub Projects Integration Guide

Status: capability #210. Foundation (#212/#216), features (#213/#214/#215/#217/#218), docs + backfill (#219/#220).

BoB can provision and maintain a GitHub Projects v2 board for any repo from a version-controlled template. The board is a derived planning surface — GitHub Issues remain the single source of truth. Nothing here changes how work is tracked; it adds a visual planning/execution layer that stays in sync with the issues.

The entrypoint is the cdproj CLI. Projects opt in declaratively through their provision manifest, so cdprov refresh keeps the board reconciled like any other piece of BoB tooling.

1. Quick start

# 1. Opt the project in: add a gh_project block to provisions/<project>.json
#    (cdi/cdprov can do this; or edit by hand — see §5)
#    { "gh_project": { "enabled": true, "profile": "standard" } }

# 2. Create + populate the GitHub Project from the template
cd ~/path/to/your/repo
cdproj init                 # creates the Project, fields, options; writes back number+owner

# 3. Check state / drift any time
cdproj status               # exit 0 aligned · 3 drift · 1 not-initialised · 2 not-found

# 4. Reconcile after editing the template (additive, never destructive)
cdproj update

# 5. Migrate existing issues onto the board
cdproj backfill --include-closed

cdprov refresh runs the right cdproj step automatically (init the first time, update afterwards) — see §5.

2. The `cdproj` CLI

Run from inside the target repo (cdproj reads the repo owner via gh). Templates and manifests are read from BOB_SOURCE.

Subcommand	What it does
`init`	Create the Project (or reconcile if it already exists), apply fields + single-select options, link the repo, and write `gh_project.number`/`owner` back into the manifest. Idempotent.
`update`	Diff the template against the live Project and apply additions only (new fields, missing options). Never deletes.
`status`	Print live state + drift vs the template. Exit code `3` when drift exists.
`reset --confirm`	Destructive. Delete and recreate the Project. Requires `--confirm`.
`item`	Set an issue’s field values: `cdproj item --issue N --status "In Progress" [--iteration current]`. The primitive warp-drive and the PM commands use.
`backfill`	Migrate existing repo issues onto the board, mapping labels/state to fields (§7).

Common flags: --owner <login> (default: repo owner), --profile <name> (default: manifest gh_project.profile), --project <name> (default: repo name / manifest key), -n/--dry-run, -v/--verbose.

Exit codes: 0 ok · 1 user error · 2 API/network · 3 drift (status).

cdproj requires the GitHub CLI (gh) authenticated with project scope (gh auth refresh -s project).

3. Canonical field conventions (#215)

All BoB Projects share one field vocabulary, defined once in templates/gh-projects/_base.json and inherited by every profile. This stable contract is what cross-project rollups and command integration rely on.

Field	Type	Values
Status	single-select	Triage → Backlog → Ready → In Progress → In Review → Done → Archived
Priority	single-select	Critical / High / Medium / Low (mirrors `p1-critical`–`p4-low` labels)
Type	single-select	Capability / Requirement / Bug / Todo / Decision / Lesson / Session-Summary / Warp-Drive-Chunk (mirrors labels)
Iteration	native iteration	one iteration per warp-drive session window (1 week, 12-iteration lookahead)
Capability	single-select	parent capability for `req` items; populated by user or `cdproj backfill`

Label → field mappings (used by backfill and documented for humans):

Priority: p1-critical→Critical, p2-high→High, p3-medium→Medium, p4-low→Low
Status from workflow labels: approved→Ready, in-progress→In Progress, blocked→Triage (the blocked label stays visible — the canonical set has no separate Blocked state), implemented→In Review, closed issue → Done

cdproj update never deletes fields you add manually in the UI — reconciliation only creates and extends.

4. Profiles (#213)

Profiles live in templates/gh-projects/profiles/ and each extends the _base partial for the canonical fields, then add their own views and auto_add rules.

Profile	For	Views	Iterations
`standard`	full dev projects (web-app, api, cli-tool, library, cms, mixed)	Backlog, Iteration Board, Bug Tracker, Roadmap, Retrospective	yes
`bug-tracker`	bug-focused repos	Triage, Active, By Severity, Closed	yes (omits Capability)
`roadmap-only`	vision/strategy repos with no code	Roadmap, Backlog	no (adds a Target DATE field)
`research`	research / docs / content projects	Backlog, Roadmap	no (simplified set)

Project-type → profile mapping (aligned with the orchestrator’s project_type categories, #157):

project_type	profile
`web-app`, `api`, `cli-tool`, `library`, `cms`, `mixed`	`standard`
`bug-tracker`	`bug-tracker`
`vision`, `strategy`, `roadmap-only`	`roadmap-only`
`research`, `docs`, `content`	`research`

When neither --profile nor gh_project.profile is set, cdproj defaults to standard.

The `extends` / `omit_fields` mechanism

A profile declares "extends": "_base" and inherits the base fields, iteration config, and workflow defaults. "omit_fields": ["Iteration"] drops inherited fields a profile doesn’t need (e.g. the no-iteration profiles). The merge is resolved by cdproj at load time and by make check-schemas, which validates each profile after merging. Files prefixed _ are partials, not standalone templates.

5. Manifest integration & `cdprov` (#216)

Opt a project in by adding a gh_project block to provisions/<project>.json:

{
  "_meta": { "project": "myrepo" },
  "skills": [], "commands": [], "agents": [],
  "gh_project": {
    "enabled": true,
    "profile": "standard",
    "number": 12,        // written back by cdproj init
    "owner": "paulirv"   // written back by cdproj init
  }
}

number and owner are populated automatically after the first cdproj init. Existing manifests without a gh_project block are unaffected (the field is additive and schema-validated by make check-schemas).

cdprov then drives cdproj — all steps are best-effort (a Project failure warns but never aborts the rest of provisioning), and skipped cleanly when gh is absent or the project hasn’t opted in:

`cdprov` action	GH Project behaviour
`refresh`	`cdproj init` (first time) or `cdproj update` (subsequent)
`diff`	`cdproj init --dry-run` — full plan preview
`status`	`cdproj status` — linked/drift report (drift surfaced, not fatal)

Deferred (#256): the cdi enable-prompt and the cdb dashboard “GitHub Project” row depend on shell/dashboard config outside BOB_SOURCE.

6. Warp-drive & PM command integration (#217, #218)

When a project is linked (gh_project.enabled + number), these tools mirror state into the board. Everything is gated on a linked Project, best-effort, and back-compatible — no behaviour change without a Project.

Warp-drive (#217):

Phase	Action
work pickup	requirement → Status `In Progress`, Iteration `current`
PR merged	requirement → Status `Done`
block / timeout	requirement → Status `Triage` (blocked label stays visible); the auto-filed `todo` joins the same iteration

The session-end report links the iteration view. Commit-level chunk items are opt-in via --track-chunks (default off).

PM commands (#218):

/what-next --source project|issues — default project when linked; ranks the current iteration’s items, falls back to issues on error.
/finish-work — sets the merged requirement to Done.
/journal, /session-summary — include the Project/iteration view URL.

7. Backfill (#220)

Migrate a repo’s existing issues onto the board:

cdproj backfill                  # open issues only
cdproj backfill --include-closed # also closed (closed → Status=Done)
cdproj backfill --dry-run -v     # preview every field write

For each issue it sets Type (from the label), Priority (from p1-critical–p4-low), and Status (from state/workflow labels, §3). Issues with Part of #NN in the body are reported as capability references — the Capability field’s options are dynamic and not auto-created, so add them in the UI and re-run (or set them manually). Backfill is idempotent and only sets values for fields that exist on the board.

8. GitHub Projects v2 API limitations

The public Projects v2 API cannot do everything a template describes. cdproj applies what it can and prints explicit manual advisories for the rest — it never silently skips:

Capability	API support	What cdproj does
Project, custom fields, single-select options (with colours)	✅	created/reconciled automatically
Repo link	✅	linked on init
Item field values (Status, Iteration)	✅	`cdproj item` / backfill
Saved views (board/table/roadmap layout, filters, visible fields)	❌	advisory — create them manually in the Project UI
Built-in workflows (auto-add, closed→Done, …)	❌ (public API)	advisory — enable under Project → Workflows
Iteration field config (duration, start day)	⚠️ limited	advisory — verify in the UI

After cdproj init, follow the printed advisories once to finish the board (views + workflows). Subsequent updates keep fields/options in sync.

9. Troubleshooting

gh ... failed / exit 2 — ensure gh auth status is healthy and has project scope: gh auth refresh -s project.
status exits 3 — drift; run cdproj update (or cdprov refresh) to reconcile.
Fields created but board is empty of views — expected; views are an API limitation (§8). Create them once from the template’s view list (printed by cdproj status).
Backfill didn’t set Capability — by design; dynamic options aren’t auto-created. Add the option, then re-run.