Shared issue state + deterministic agent delivery

Keep issue operations close to code — without tracker sprawl.

ISSUES.md gives teams a shared DB-backed issue system, scratch Markdown import/export, and one-click autonomous agent delivery inside managed GitHub repo workspaces.

Start setup Explore features 
cp configs/env.issue-manager.dev.example configs/.env.issue-manager.dev
cp configs/env.issues-frontend.dev.example configs/.env.issues-frontend.dev
./scripts/up.sh

Shared issue authority

Issues live in the DB and stay visible across teammates working in the same repo.

Repo-native delivery

  • Push to default branch or open a PR
  • Stack new PRs on existing work
  • Reconcile on Sync

Agent handoff

Assemble prompts from repo context and run Codex, Claude, or Gemini inside your managed workspace.

What matters in the MVP

The product is built around shared issue authority, explicit delivery modes, and black-box-validated execution.

Shared DB-backed issue state

Teammates see the same issues, the same revisions, and the same reconciled status transitions per repo.

Scratch Markdown maintenance

Open the raw editor to export issue state to scratch Markdown, then import on explicit save.

One-click autonomous agents

Run Codex, Claude, or Gemini against real repo context in the managed workspace.

Deterministic delivery modes

Execution succeeds only by pushing to the default branch or by opening a pull request.

Context-aware prompts

Choose AGENTS, POLICY, README, and docs files that should shape every execution prompt.

Per-user workspaces

Issue state is shared, but branches, terminals, and in-flight execution work remain isolated per user.

How it works

The app separates DB-backed issue management from git-bearing code delivery.

1) Sign in and clone Authenticate with GitHub and clone a managed repo into the service workspace.
2) Initialize the repo Create or refresh `.mprl/` operating files so the repo is ready for the app workflow.
3) Manage shared issues Create, edit, polish, clean up, or reorder issues in the DB-backed shared issue list.
4) Choose delivery mode Execute into the default branch or open a PR, including stacked PR continuation when needed.
5) Validate before publish Run discovered repo gates locally, retry with findings, and publish only after local success.
6) Reconcile with Sync Refresh GitHub PR state, return to the default branch, and update visible issue statuses.

Supported agents

Configure defaults per repo, override per issue, and choose provider-specific models and effort settings.

Codex CLI Claude CLI Gemini CLI

Operational confidence

Delivery, Sync, and stacked-PR behavior are backed by browser, service, and Docker black-box tests.

Quick setup

Docker Compose is the simplest way to run the ISSUES Managing Director locally.

Run

git clone https://github.com/tyemirov/ISSUES.md
cd ISSUES.md
cp configs/env.issue-manager.dev.example configs/.env.issue-manager.dev
cp configs/env.issues-frontend.dev.example configs/.env.issues-frontend.dev
./scripts/up.sh

Open the frontend URL selected by the startup script after the stack is ready.

Configure

The core settings surface covers managed repo storage, backend database path, GitHub auth, and agent binaries.

ISSUES_SERVER_SETTINGS_PROJECTS_ROOT ISSUES_SERVER_SETTINGS_DATABASE_PATH ISSUES_GITHUB_CLIENT_ID ISSUES_AGENTS_BINARIES_*

FAQ

Short answers to the main questions about the DB-first MVP workflow.

Is ISSUES.md a replacement for GitHub Issues?

It is a different tradeoff: GitHub-backed repo access, shared DB-backed issue state, repo-local execution, and deterministic delivery back into the codebase.

What happens if I edit ISSUES.md manually?

The app-managed backlog lives in the DB. The raw editor exports scratch Markdown and imports it on save. If a repo contains a normal tracked ISSUES.md file, it stays just a repo file until someone explicitly imports it.

Does my code ever leave my machine?

The manager and agent CLIs run where you deploy the app. Network access depends on the GitHub and agent integrations you configure.

Can I choose which context files agents receive?

Yes. Select the repo files that should shape execution and polishing prompts, and those selections persist per user per repo.