PRDs

Auto-generated specs, one-click GitHub handoff.

A full-page markdown editor with debounced autosave, GFM preview with task lists, and a Send to GitHub button that creates an issue on the configured repo — duplicate sends blocked, URL persisted back.

What it is

The last step before a ticket lives in your tracker.

PRDs is the final, editable artifact in the PMOS pipeline. A PRD can arrive there two ways: auto-generated from an Aggregate suggestion (with competitor research baked in), or created manually from scratch. Either way, once you hit Send to GitHub, the spec becomes an issue and the URL is persisted back so the app can't double-send.

Flow

Four moves: open, edit, preview, send.

The editor autosaves on a debounce. Preview renders GitHub-flavored Markdown including task lists. Send creates the issue synchronously and blocks a second send with HTTP 409.

Open

GET /products/{id}/prds/{pid}

Title and markdown content are loaded into the editor. If this PRD originated from a suggestion, the link back is shown in the header.

Edit

PATCH /prds/{pid} (debounced)

Each keystroke schedules a PATCH after the debounce window. No save button — the subtle status indicator in the header is the source of truth.

Preview

Switch to the Preview tab to see the spec rendered as GFM: headings, tables, code, task lists. Matches what GitHub will show.

Send to GitHub

POST /products/{id}/github/issues

An issue is created using the per-product PAT. On success, the issue URL is persisted back on the suggestion; subsequent sends return 409.

Send to GitHub — contract

POST /api/products/{id}/github/issues

{
  "prd_id": "prd_abc123",
  "suggestion_id": "sug_xyz789",   // optional — when PRD came from Aggregate
  "labels": ["from-pmos"],          // optional
  "assignees": []                   // optional
}

→ 201  { "issue_url": "https://github.com/owner/repo/issues/42" }
→ 409  { "error": "already_sent", "issue_url": "…" }
→ 422  { "error": "github_repo not configured" }

Integration

One GitHub PAT per product, stored masked.

Each product can be wired to its own GitHub repo + fine-grained PAT with Issues: Read and write. The token is stored masked — reads show •••••••• plus the last 4 chars, and a github_token_set boolean. Update the token and the server rotates it without ever exposing the old value.

Field	Behavior
github_repo	URL or owner/repo. Normalized server-side to the owner/repo form.
github_token	Write-only in the API. Read responses return github_token_set: true/false.
issue_url	Persisted back on the suggestion so duplicate sends can 409.
labels	Optional; applied to the created issue at send time.

Highlights

Three details that matter.

Autosave you can trust

Debounced, with a visible status. Nothing is lost if you navigate away.

Real GFM preview

Task lists, tables, fenced code blocks — exactly what the GitHub issue will render.

No double-sends

A second Send is blocked with 409 and the existing URL; no orphan issues.

See PMOS end-to-end.

A 20-minute demo walks through Discover → Aggregate → PRD → GitHub issue, scoped to your product.

Get a demo Read the docs