Boards & Sync

The board is a working tree. prog sync is commit + push. Together they form the propagation surface — the half of repo-native PM that makes agent writes and human board moves flow between machines via git.

The model

Git concept	ProGit board equivalent
Working tree	`.project/issues/*.json` mutated by drags or CLI
`git add`	Implicit — every mutation stages automatically
`git commit`	Flush — one atomic commit bundling pending changes
`git push`	Sync — propagate to origin; every clone sees it on next pull

`prog sync`

The primary flush trigger. Stages every pending .project/ change, commits it as one atomic unit, and pushes to origin.

$ prog board          # you move abc123 and def456 during planning

$ prog sync
✓ committed 2 issue changes to .project/
✓ pushed to origin
  → every clone sees the new board state on next pull

Commit message format:

progit: sync 2 issue changes

- issue abc123: backlog → in-progress (agent:voxis)
- issue def456: created (human:markus)

Actor: mixed (1 agent, 1 human)

What a flush commits

Only files under .project/:

.project/issues/*.json
.project/events.jsonl
.project/config.kdl (only if changed)

What a flush never commits

Code changes in the working tree (.project/ only — never src/).
.progit/ or .ops/ local runtime state.
Plugin caches or artifacts.

Exit flush

When prog ui exits with pending uncommitted changes, ProGit flushes before quitting. This is the “don’t lose my planning session” safety net.

Remote configured → commit + push.
No remote → commit locally so nothing is lost.

Receiving changes

No special command is needed to receive. .project/ is ordinary tracked content:

# machine B
$ git pull
$ prog board        # reflects the pulled state automatically

Agent re-adjustment

An agent that needs to react to another machine’s changes reads the new state through the CLI:

# machine B, after git pull
$ prog issue list --status in-progress --json
$ prog issue get abc123 --json
$ prog issue set abc123 --status done --actor agent:jarvis --json
$ prog sync   # push the reaction back

git pull && prog issue list is a complete reactive loop. The events.jsonl log provides full causal history for any agent that wants to reason about drift.

Peer transport: forge federation

Git-native is the spine. Forgejo and GitLab REST sync ride alongside as a peer transport:

prog sync (no args) → git-native flush.
prog sync --to forgejo → forge-REST push.

See Forge Federation for the bridge details.