StateForge DPT

Plan visually. Track delivery. Share your plan through Git.

StateForge DPT (Development Progress Tracking) is a local web app for planning and tracking work across GitHub repositories. Create steps, connect dependencies, and see what is ready to build next—all in a visual workspace.

Your plan lives alongside your code in Git. Issues, pull requests, and merges provide the delivery evidence. Each computer keeps its own local working copy.

Why DPT?

• Visual planning. Describe a result, choose a repository, and select prerequisite cards. DPT handles step IDs, ordering, and dependency validation.
• A connected roadmap. Explore dependency stages or a graph, with search and repository filters.
• An actionable work queue. See ready, pending, in-review, blocked, and completed work, with assigned contributors and their profile photos.
• GitHub context in one place. Read formatted descriptions, comments, reviews, and activity. Open issues, create planned branches and PRs, or jump to GitHub to start a review.
• Git-backed collaboration. Share the complete plan in STATEFORGE_DPT.md and import it on another computer from a participating clone.
• Safe synchronization. Refresh the shared plan without switching branches. Conflicts and unpublished local edits are surfaced, not silently overwritten.

Installation

Requires Python 3.11+ and Git 2.31+ on your PATH. Runs on Linux, macOS, and Windows. The browser interface is included; Node.js is not needed.

python -m pip install stateforge-dpt
stateforge-dpt run

Open http://127.0.0.1:8463 in your browser. Start DPT from any directory, keep the terminal open, and press Ctrl+C to stop it.

On macOS/Linux, use python3 if needed. On Windows, use py -m pip install stateforge-dpt and py -m stateforge_dpt run if the console command is not on your PATH.

Use a virtual environment for an OS-managed Python. If you already use pipx, pipx install stateforge-dpt is another option.

Your first project

1. Connect GitHub—or start locally. Choose Continue with GitHub and approve the one-time code. Local mode supports planning without signing in; refreshing GitHub delivery evidence requires a connected account.
2. Add repositories. Create a project, then attach existing clones or choose Clone for me.
3. Build the plan. In Plan editor, create a step, describe its expected result, and choose its repository. Select prerequisite cards to connect work across repositories—no dependency IDs to memorize.
4. Follow delivery. Explore Roadmap and Work queue. Open a step for its GitHub actions and details; reconcile to refresh shared plans and status.

Joining an existing project? Choose Import from repository on the projects page and select a local clone containing a published STATEFORGE_DPT.md. DPT previews the complete plan before importing it.

Share a plan across computers

Collaborate through your repositories, not a separate planning server:

1. Choose Review & publish in Plan editor to preview and write the next plan revision into your attached clones.
2. Commit and push the generated files with Git, then merge them into the project's shared plan source branch, configured in Settings.
3. On another computer, install DPT and import the project from any participating clone. Attach or clone the remaining repositories; the steps and dependencies are already there.
4. Connect GitHub and reconcile to fetch newer plan revisions and delivery evidence—even while working on a feature branch.

The source branch can be your default branch or another shared parent, such as mvp/implementation. Publishing writes local files; it does not commit, push, or merge them. Reconciliation does not rebase or change your working tree. Conflicting revisions or unpublished local edits require your resolution.

Progress backed by GitHub

DPT uses project, release, and step labels to match GitHub activity to the plan:

Without matched evidence, prerequisites determine whether work is ready or blocked. Reconciliation flags workflow findings, such as a PR opened before its dependencies are complete. Perform reviews on GitHub using the shortcut to the PR's Files changed tab.

Local by design

Working copies, cached GitHub activity, and encrypted credentials live under ~/.stateforge-dpt/. New clones default to:

~/.stateforge-dpt/projects/<PROJECT_NAME>/<REPOSITORY_NAME>

The shared plan excludes credentials, cached conversations, and local clone paths. Each collaborator uses their own account and clones. Remote cloning, shared-plan fetching, and GitHub updates require network access.

Update DPT with:

python -m pip install --upgrade stateforge-dpt

DPT is an early-stage release. Keep generated plan changes in Git for review and recovery through your normal development workflow.

Documentation

• Configuration and troubleshooting
• Architecture and plan format
• Development and release guide
• Issue tracker

GitHub documentation and the issue tracker require access to the project repository.