Repo-Native Project Management
import { Card, CardGrid } from ‘@astrojs/starlight/components’;
The idea in one paragraph
Section titled “The idea in one paragraph”GitHub, GitLab, and every web forge store issues in a webapp database that you cannot see,
cannot version, cannot audit offline, and cannot sync without the vendor’s permission. ProGit
moves project state into the repository itself — .project/ as plain JSON, tracked in git —
and uses git as the sync transport. No webapp database between your team and your project
state. Just git.
The stage-and-flush model
Section titled “The stage-and-flush model”The mechanic mirrors git’s own mental model. Nothing new to learn.
| Git concept | ProGit board equivalent |
|---|---|
| Working tree (edited files) | .project/issues/*.json mutated by drags or CLI |
git add (staging) | Implicit — every board mutation stages automatically |
git commit | Flush — bundles all pending issue changes into one atomic commit |
git push | Sync — propagates the commit to origin; every clone sees it on next pull |
Why not commit on every move?
Section titled “Why not commit on every move?”A board is not a keystroke. A sprint planning session moves forty cards. Committing on every drag would spam the git log with noise and saturate the network with unwanted pushes. The board is a working tree; you decide when the working tree becomes history.
Flush triggers
Section titled “Flush triggers”- Explicit —
prog sync. You say “now.” One commit, one push. - Automatic — app exit. The TUI flushes before quitting so you never lose a planning session.
The sync loop
Section titled “The sync loop”machine A machine B───────── ─────────prog issue create --json →prog board (move card) →prog sync (commit + push) ──────→ git pull prog board → sees the change prog issue list --json → agent re-adjustsThe propagation surface is ordinary git. .project/ is tracked content; git pull is enough
to receive. No special protocol, no daemon, no vendor API.
Single source of truth = git history
Section titled “Single source of truth = git history”.project/issues/*.json is the working tree — current state, mutable, local.
The git commit graph is the history — auditable, immutable, shared.
git log -- .project/ is your project management timeline. Every status change, every actor,
every transition, preserved forever, attributable, diffable. No webapp gives you that.
Forge federation as a peer transport
Section titled “Forge federation as a peer transport”Git-native is the spine. Forgejo and GitLab REST sync ride alongside as a peer transport — useful for federation with teams still on a forge, and for one-way migration off GitHub/GitLab Issues. The bridge exists, but it is no longer the spine.
prog sync(no args) → git-native flush.prog sync --to forgejo→ forge-REST push (existing behavior).