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.
• Regression-resistant implementation. Define cross-repository context, protected behavior, and verification before work begins; review the exact change surface and retain relevant bug history afterward.
• A first-class AI interface. The same local process exposes DPT through MCP, so coding agents can inspect roadmaps, blockers, repository context, and implementation packages without scraping the browser. Agents may propose plan edits, but an exact digest-bound proposal needs human confirmation.

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.

Use DPT from an AI coding agent

stateforge-dpt run also serves a local Streamable HTTP MCP endpoint:

http://127.0.0.1:8463/mcp

For the Codex desktop app, install DPT's personal local plugin once:

stateforge-dpt setup-codex

Then keep DPT running, restart the Codex app, and start a new chat. The setup command preserves other personal marketplace entries, registers the loopback MCP endpoint, and configures proposal application and rejection to prompt for confirmation in Codex. Rerun it after changing DPT's configured port, or pass the matching endpoint with --url.

Connect an MCP-capable coding client to that URL while DPT is running. The agent can read projects, dependency stages, the work queue, GitHub blockers, managed repository trees, approved context contracts, and implementation packages. File access is limited to Git-tracked text resources in attached repositories and bounded by a configurable read limit.

Discovery tools intentionally return compact milestone and blocker cards. Agents call get_work_item only for the selected item's complete GitHub, context, and review evidence, keeping routine planning queries small.

Plan editing uses a proposal boundary. The agent submits typed operations; DPT validates the complete resulting plan and returns an immutable review package with a semantic diff, consequences, version, and SHA-256 review digest. After you review it in the conversation, the agent may call the consequential apply tool. Keep per-call tool confirmation enabled in your MCP client—never auto-approve apply_plan_change_proposal. The same proposals can be inspected, applied, or rejected in Plan editor → AI proposals.

Applying a proposal changes only the local SQLite working plan. It never writes STATEFORGE_DPT.md, publishes a revision, commits, pushes, opens a pull request, reviews, or merges. Those remain separate human-owned workflows. Run with --no-mcp to disable the agent interface. See the AI agent interface guide for the complete tool and safety model.

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
• AI regression-resistance workflow
• AI agent interface
• Development and release guide
• Issue tracker

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