# graph8 Lifecycle — PRDs (this repo)

This directory holds PRDs that describe infra, agent-os, MBM, tenant
configuration, and Kubernetes work. They follow the same schema as
[`graph8-com/g8/docs/prds/`](https://github.com/graph8-com/g8/tree/main/docs/prds)
— same frontmatter (11 fields), same body structure, same 5-gate
agent-readiness contract — but live here because the code they describe
lives here.

## When to write a PRD here vs in g8

| Touches | Goes in |
|---|---|
| `services/mbm/`, `services/platform-loader/`, `axon/` | `graph8-com/infra/docs/prds/` (this dir) |
| `tenants/graph8-eng/`, agent prompts, crons | `graph8-com/infra/docs/prds/` (this dir) |
| `k8s/`, `terraform/`, `scripts/`, `.github/workflows/` | `graph8-com/infra/docs/prds/` (this dir) |
| `npm/@graph8/*` packages (engineer-facing tooling) | `graph8-com/infra/docs/prds/` (this dir) |
| g8 monorepo Django / Celery / Next.js features | `graph8-com/g8/docs/prds/` |
| AI Inbox, Studio, Mashup, Voice, EDA, Signals | `graph8-com/g8/docs/prds/` |
| Anything touching graph8 product surface | `graph8-com/g8/docs/prds/` |

If a PRD spans both, file the parent here and a child PRD per touched
repo. Cross-link them in the `## Dependencies` section.

## Status transition rules

The mbm board has 5 columns ([live board](https://github.com/orgs/graph8-com/projects/42)). Items move between them under explicit rules:

```mermaid
graph LR
  G[GOALS] -->|strategy review| T[TODO]
  T -->|manual approval| AR[AGENT READY]
  AR -->|autopilot or planner picks up| IP[IN PROGRESS]
  IP -->|all AC checked| D[DONE]
  IP -.->|agent stuck → ping| T
```

| Transition | Triggered by | Gate |
|---|---|---|
| **GOALS → TODO** | Thomas or Shaharyar in a strategy review | Item is concrete enough to be one feature, not a permanent investment container |
| **TODO → AGENT READY** | Manual approval (admin flips PRD `status: draft` → `approved`) | All 5 agent-readiness gates pass — see below |
| **AGENT READY → IN PROGRESS** | [Engineer autopilot daemon](engineer-autopilot.md) on engineer's laptop OR planner agent dispatch | Item is assigned to engineer; autopilot picked it up; agent is running |
| **IN PROGRESS → DONE** | Acceptance criteria checklist completed | Every box ticked, evidence linked, MBM review + persona reviewers green |
| **IN PROGRESS → TODO** (ping path) | Agent gets stuck, retries exhausted, or hits unresolvable error | Human ack required; daemon posts Slack ping; item moves back to TODO with comment |

Per Shaharyar (2026-05-17 conversation): *"we should have agents that
move things from initiative to TODO after reviews of you, me, or
whoever; and from TODO after manual approval, we move them to AGENT
READY. And those AGENT READY automatically can run on MBM agent on
their local machine. All they have to do is just pick up tasks for the
day from AGENT READY."*

The pinging path matters: *"it would be a pinging system if human help
is needed somewhere suddenly in some agent... your help is needed on
these issues. Come look at it."* — Shaharyar, same conversation.

## Schema (identical to g8)

The `_template.md` here is copied verbatim from `g8/docs/prds/_template.md`.
A future CI check will pin them in sync; for now treat the g8 template
as canonical and sync this one when it changes.

**Frontmatter (11 fields, see `_template.md`):** `title`, `status`,
`author`, `assignee`, `created`, `approved`, `domains`, `issues`,
`complexity`, `gtm_score`, `analysis_date`.

**Required body sections** (13): GTM Automation Assessment · Problem
· Analysis Summary (Existing Code · Data Dependencies · Integration
Points · Competitive Context) · Technical Fit Review (System
Touchpoints · Reuse Plan · Extension-Before-Replacement · Architecture
Scorecard) · Requirements (API · UI · Data Model) · Acceptance Criteria
· Out of Scope · Dependencies.

**5 agent-readiness gates** (enforced by [`scripts/prd_workflow.py`](../../scripts/prd_workflow.py)
once PRD 4 lands):

1. `status` is `approved`, OR `status: draft` with non-null `assignee`.
2. All 11 frontmatter fields parse as valid YAML.
3. `## Acceptance Criteria` section exists with ≥3 checkbox items.
4. Title does NOT contain `human-only`.
5. `domains` array non-empty; at least one domain recognized in
   [`tenants/graph8-eng/domains-catalog.yaml`](../../tenants/graph8-eng/domains-catalog.yaml).

When all 5 gates pass on PR merge, the PRD pipeline workflow applies
the `agent-ready` label and dispatches the planner agent. Planner
spawns 4–10 GitHub issues, each routed to the right specialist agent
via the existing label dispatch.

## Active set — Lifecycle Phase 1

The 5 PRDs in this directory form one cohesive phase. See
[`ROADMAP.md`](ROADMAP.md) for status and sequencing.

```mermaid
graph LR
  P1[PRD 1<br/>Trace pipeline] --> P2[PRD 2<br/>Dashboards]
  P2 --> P3[PRD 3<br/>Review loop]
  P4[PRD 4<br/>PRD automation] --> P5[PRD 5<br/>Deploy loop]
  P5 --> P6[PRD 6<br/>Engineer autopilot]
  P1 -.signal.-> P3
  P1 -.signal.-> P6
```

PRDs 1 and 4 can start day 1 in parallel (no dependency). PRD 2 unlocks
PRD 3. PRD 5 leans on PRD 4 for `/check-prds` consistency. PRD 6
(engineer autopilot) depends on PRD 5's `mbm.spawn_agent` for the
cloud-dispatch path; can ship local-only sooner if PRD 5 slips.

## Related

- [`docs/lifecycle.html`](../lifecycle.html) — the system vision (master story).
- [`docs/prds.html`](../prds.html) — the 10-stage PRD lifecycle described as a flow.
- [`docs/assembly.html`](../assembly.html) — at-a-glance assembly-line view.
- [`docs/local.html`](../local.html) — engineer install kit (4 install paths).
- [`tenants/graph8-eng/agents/planner/prompt.md`](../../tenants/graph8-eng/agents/planner/prompt.md)
  — the planner agent that picks these up after approval.