Planning format for human and AI teams

One plan for humans and agents.

The need

PMs, TPMs, engineers, and AI agents need the same readable view of intent, priority, blockers, and definition of done. ISSUES.md keeps that plan in standard Markdown so it travels with the repo and stays useful in any editor. Launch the hosted editor to sign in with GitHub, choose a repository, and operate its .mprlab/ISSUES.md from the browser.

Launch editor Read RFC Copy template Read format
PMs TPMs Engineers AI agents Automation

The Gap

Mixed human and AI teams break down when planning lives in prompts, chats, and tracker views that cannot travel with the work. The missing layer is a durable plan everyone can read and reuse.

Prompt Drift

Ad hoc prompts lose the original scope, constraints, and acceptance criteria after the run starts.

No Next View

Teams need to see what is ready, blocked, dependent, or already done before asking agents to act.

Context Loss

Useful details get split across tickets, comments, docs, PRs, and chat threads instead of staying with the issue.

Weak Handoff

PM intent, TPM sequencing, engineering evidence, and agent instructions need one shared shape.

Thin Audit

Without a readable plan, it is hard to explain what the agent was asked to do and why it was safe to proceed.

Tool Lock-in

Execution context should move between humans, agents, repos, and automation without depending on one tracker.

Planning

ISSUES.md turns a backlog into a shared planning surface: intent, sequencing, readiness, and evidence are visible to the humans and agents doing the work.

PM

Intent

Capture the outcome, priority, and acceptance criteria so the work is more than a task title.

TPM

Sequence

Make dependencies, blocked states, and readiness visible so everyone can see what should happen next.

ENG

Definition

Keep repro steps, contracts, commands, and verification notes close enough for implementation and review.

Execution

Once the plan is explicit, humans and agents can work from the same contract: choose the next issue, carry context, execute, validate, and publish.

1. Pick next Status, priority, and dependencies make ready work visible without another planning meeting.
2. Carry context Acceptance criteria, repro steps, blocked reasons, and decisions stay attached to the issue body.
3. Run agent AI agents get structured Markdown with stable IDs and enough surrounding text to reason about the work.
4. Validate The same issue can name the checks, commands, and expected result that define done.

Anatomy

The file stays normal Markdown; the issue line carries the planning and execution semantics.

1. Title

Start with a Markdown title, usually # ISSUES. Add ordinary prose before the first section when the repo has local workflow rules. 

# ISSUES

Working backlog for this repository.

2. Sections

Issues are grouped under fixed ## headings. This is normal Markdown structure with agreed category names. 

## BugFixes
## Improvements
## Maintenance
## Features
## Planning

3. Issue Line

Each issue starts as a Markdown list item. The semantic extension is the compact prefix: status, ID, optional priority, and optional dependencies. 

- [ ] [B042] (P1) {I007} Short title

4. Body

Add acceptance criteria, repro steps, owners, verification commands, and decisions as normal indented Markdown below the issue. 

- [ ] [I012] Add import preview
  Acceptance criteria:
  1. Preview shows open, blocked, and closed totals.
  2. Failed import does not mutate issue state.

5. Blocked

A blocked issue uses [!] and must include a short body line that starts with Blocked:. 

- [!] [B042] (P0) Restore checkout after timeout
  Blocked: waiting on processor replay logs.

Issue Line

A readable Markdown list item becomes a portable contract for planning and execution. 

- [ ] [B042] (P1) {I007,F010} Fix session restore after reload
- Markdown list item marker.
[ ] Status marker. Use [ ], [!], or [x].
[B042] Required external ID. The leading letter must match the section.
(P1) Optional priority from P0 through P2.
{I007,F010} Optional comma-separated dependency IDs.
Fix session restore after reload Required short title.

Adopt It

Use it where planning has to work for people, agents, and delivery systems.

1. Put plans in a file Use one ISSUES.md per repo or product surface so the shared plan is easy to find.
2. Write for handoff Include outcomes, acceptance criteria, repro steps, and decisions in normal Markdown below the issue.
3. Mark state plainly Use status, priority, dependency IDs, and Blocked: lines so state is visible in text.
4. Feed agents Give AI agents the same structured Markdown that PMs, TPMs, and engineers can inspect directly.

Examples

Use these as patterns for planning work that can move into execution.

Intent

## Features
- [ ] [F024] (P1) Add saved workspace filters
  Outcome: returning users can reopen the product and see the same filtered issue view.

  Acceptance criteria:
  1. Filters restore after refresh.
  2. Clearing filters updates the saved state.

Blocked

## Improvements
- [!] [I018] (P1) {F024} Add workspace filter telemetry
  Blocked: analytics event names need final approval from Data Platform.

  Dependency owner: Data Platform.

Repro

## BugFixes
- [ ] [B105] (P0) Fix refresh restoring stale issue filters
  Reproduce:
  1. Set Status = blocked.
  2. Refresh the browser.
  3. Observe the previous default filter state.

  Expected: the visible filter state matches the URL and saved state.

Validate

## Maintenance
- [ ] [M410] (P2) Document release verification
  Add the release checklist to README.md.

  Acceptance criteria:
  1. The checklist names the exact make target.
  2. The release tag format is shown.

  ```bash
  timeout -k 350s -s SIGKILL 350s make ci
  ```

Template

Start with this shape. Keep the examples that match your operating model and delete the rest. 

# ISSUES

Working backlog for this repository.

## BugFixes
- [ ] [B001] (P0) Fix checkout timeout after payment authorization
  Reproduce:
  1. Submit payment with a slow processor response.
  2. Wait for frontend timeout.
  3. Observe that the order is not recoverable from checkout.

## Improvements
- [ ] [I001] (P1) Add checkout retry telemetry
  Outcome: support and engineering can distinguish customer retry, processor retry, and duplicate submit states.

## Maintenance
### Recurring
- [ ] [M001R] (P2) Backlog housekeeping
  1. Remove stale resolved issues.
  2. Merge duplicate requests.
  3. Confirm blocked issues still have current owners.

## Features
- [ ] [F001] (P1) {B001,I001} Add guided checkout recovery
  Acceptance criteria:
  1. Customer can resume from the failed payment state.
  2. Duplicate charges are not created.

## Planning
*do not implement yet*
- [ ] [P001] (P2) Evaluate enterprise tracker import options