---
requiresProjectContext: true
---

# Playbook: Plan → PRD

You are {{agent_name}}, the {{agent_role}} on the {{project_name}} project.
TEAM ROOT: {{team_root}}

## Your Task

A user has provided a plan. Analyze it against the codebase and produce a structured PRD that the minions engine will automatically pick up and dispatch as implementation work.

## The Plan

{{plan_content}}

## Instructions

{{#project_skills_block}}
{{project_skills_block}}

{{/project_skills_block}}
1. **Read the plan carefully** — understand the goals, scope, and requirements
   - If the plan declares `Project: <name>` (including `**Project:** <name>`), the engine has resolved `{{project_name}}` from that declaration. Preserve `{{project_name}}` for the top-level `project`, default item `project`, filename, and implementation framing; do not let contextual mentions of another product or repository override it.
2. **Check for an existing PRD** — if the engine provides `existing_prd_json` below, a PRD already exists for this plan. See "Reusing an Existing PRD" section for how to preserve item IDs and done statuses. If no existing PRD is provided, this is a fresh run — all items start as `"missing"`.
3. **Explore the codebase** at `{{project_path}}` — understand the existing structure to write accurate descriptions and acceptance criteria. Do NOT use observations about existing PRs or partial work to set item statuses — status is determined only by existing PRD items (step 2), not codebase state
4. **Break the plan into discrete, implementable items** — each should be a single PR's worth of work, with enough detail for another agent to implement it directly
5. **Estimate complexity** — `small` (< 1 file), `medium` (2-5 files), `large` (6+ files or cross-cutting)
6. **Order by dependency** — items that others depend on come first
7. **Use unique item IDs** — generate a short uuid for each item (e.g. `P-a3f9b2c1`). Do not use sequential `P001`/`P002` — IDs must be globally unique across all PRDs to avoid collisions. **If reusing an existing PRD, keep all existing IDs — only generate new UUIDs for genuinely new items.**
8. **Identify open questions** — flag anything ambiguous in the plan that needs user input

## Output

Write the PRD to: `{{team_root}}/prd/{{prd_filename}}`

**Use the exact filename above.** The engine pre-generates a unique filename to avoid collisions with existing or archived PRDs; renaming it will detach the PRD from the plan.

This file is NOT checked into the repo. The engine reads it on every tick and dispatches implementation work automatically.

```json
{
  "version": "plan-{{date}}",
  "project": "{{project_name}}",
  "source_plan": "{{plan_file}}",
  "generated_by": "{{agent_id}}",
  "generated_at": "{{date}}",
  "plan_summary": "Short title (max ~80 chars, shown in dashboard tiles)",
  "status": "awaiting-approval",
  "requires_approval": true,
  "branch_strategy": "shared-branch|parallel",
  "feature_branch": "user/<loginname>/PL-<short-kebab-slug>",
  "missing_features": [
    {
      "id": "P-<uuid>",
      "name": "Short feature name",
      "description": "What needs to be built and why",
      "project": "{{project_name}}",
      "status": "missing",
      "type": "implement",
      "estimated_complexity": "small|medium|large",
      "priority": "high|medium|low",
      "depends_on": [],
      "acceptance_criteria": [
        "Criterion 1",
        "Criterion 2"
      ]
    }
  ],
  "open_questions": [
    "Question about ambiguity in the plan"
  ]
}
```

### Per-item `type` field (REQUIRED when the plan declares it)

Set `type` on each `missing_features[i]` to the work-item type the engine should dispatch. If the plan markdown declares a type for an item (e.g. `**Type:** explore`, `Type: docs`, `Type: fix`), you MUST carry it into the structured `type` field — the materializer reads this field as the source of truth.

Accepted values:

- `implement` — default; build a new feature (produces a PR)
- `implement:large` — same as implement but routed through the decompose flow (use only when the plan explicitly asks for it; large `estimated_complexity` alone does NOT require this — the engine auto-escalates on the default path)
- `fix` — bug fix (produces a PR)
- `review` — code review of an existing PR (no PR produced)
- `verify` — end-to-end verification of a completed plan (no PR by default)
- `explore` — read-only research / audit; writes findings as notes
- `ask` — read-only Q&A; writes findings as notes
- `test` — author or repair tests (produces a PR)
- `docs` — documentation-only change (produces a PR against minions repo)
- `setup` — bootstrap / configure infrastructure inside the project worktree (no PR)
- `decompose` — engine-internal; do not emit from plan-to-prd

Rules:

- If you omit `type`, the materializer defaults to `implement` (with `large` complexity auto-escalating to `implement:large`).
- Do not invent new type values — anything not in the list above falls back to `implement`.
- For prose-only plans that say e.g. `**Type:** explore` in an item's description, the engine has a fallback regex that will extract the type from a leading `Type: <label>` line, but the structured field is preferred and is checked first.

## Branch Strategy

Choose one of the following strategies based on how the items relate to each other:

- **`shared-branch`** — All items share a single feature branch. Agents work sequentially, respecting `depends_on` order. One PR is created at the end with all changes. **Use this when items build on each other** (most common for feature plans).
- **`parallel`** — Each item gets its own branch and PR. Items are dispatched independently. **Use this when items are fully independent** and can be reviewed/merged separately.

{{branch_strategy_hint}}

When using `shared-branch`:
- Generate a `feature_branch` name using the canonical convention: `user/<loginname>/PL-<short-kebab-description>` (≤ 120 chars, lowercase). `<loginname>` is the human operator's platform login (e.g. `yemi33` on GitHub) — never an AI agent persona. See `shared-rules.md` → "Branch Naming Convention".
- Use `depends_on` to express the ordering — items execute in dependency order
- Each item should be able to build on the prior items' work

When using `parallel`:
- Omit `feature_branch` (the engine derives per-item branches as `user/<loginname>/<wi-id>-<slug>`)
- `depends_on` is still respected but items can dispatch concurrently if no deps

Rules for items:
- IDs must be `P-<uuid>` format (e.g. `P-a3f9b2c1`) — globally unique, never sequential
- **`status` is `"missing"` for new items** — do not set `done`, `complete`, `implemented`, or any other value based on codebase observations. The only exception is when reusing an existing PRD (see below) — items already `"done"` in the existing PRD carry forward as `"done"`. Pre-setting any other status on new items causes them to be silently skipped by the engine.
- **Do NOT include a "verify" or "test" or "integration test" item** — the engine automatically creates a verify task when all PRD items are done. Adding one manually creates a duplicate that blocks plan completion.
- **`project` field is required** — set it to the project name where the code changes go (e.g., `"OfficeAgent"`, `"office-bohemia"`). If the plan declares a single project, every item should use `{{project_name}}`; contextual mentions of another repo/product should not override it. Cross-repo plans should route each item to the correct project. The engine materializes items into that project's work queue.
  - **Cross-repo plans:** the canonical signal that this is a cross-repo plan-to-prd dispatch is `{{target_projects}}` being non-empty — the engine extracts it from the plan markdown's `**Projects:** …` header (or `<!-- minions:targetProjects=… -->` marker) and injects the comma-separated list. When set, `{{project_name}}` is unset (no single owning repo). Set each item's `project` to the actual repo from `{{target_projects}}` where its code changes belong, and omit the top-level `"project"` field (or set it to `""`). Example:
    ```json
    "missing_features": [
      { "id": "P-aaa1", "name": "API endpoint", "project": "backend-service", ... },
      { "id": "P-bbb2", "name": "UI client",    "project": "web-dashboard",   ... }
    ]
    ```
    The engine routes each item to that project's `work-items.json`. The verify task at plan completion picks the project with the most completed items and runs cross-repo verification from there. See the **Cross-repo plans** section below for the full output contract when `{{target_projects}}` is set.
- `depends_on` lists IDs of items that must be done first
- Keep descriptions actionable — name the files, functions, patterns, or integration points the implementing agent should touch whenever the plan makes them clear
- Include `acceptance_criteria` so reviewers know when it's done
- Aim for 5-25 items depending on plan scope. If more than 25, group related work

{{#target_projects}}
## Cross-repo plans

This dispatch is rendering against a **cross-repo plan** — the engine extracted the list `{{target_projects}}` from the plan's `**Projects:**` header (P-c1f87a92) and injected it here. There is no single owning project for the PRD as a whole; every item ships into one of the listed repos.

Apply these rules on top of (and where they conflict, instead of) the single-project guidance above:

1. **Omit the top-level `"project"` field** on the PRD JSON — or set it to `""`. The PRD is not anchored to a single project. The dashboard reads `i.projects[]` per item (P-e8d49105) to render the cross-repo rollup; the top-level `project` only makes sense when the whole plan lives in one repo.
2. **Every `missing_features` item MUST have an explicit `project`** chosen from `{{target_projects}}`. Do NOT leave `project` unset, do NOT fall back to `{{project_name}}` (it is unset for cross-repo dispatches), and do NOT invent a project not in the list — the engine routes each item to that project's `work-items.json` and an item with an unrecognized project will not materialize. Example:
   ```json
   "missing_features": [
     { "id": "P-aaa1", "name": "API endpoint", "project": "<first project from {{target_projects}}>", ... },
     { "id": "P-bbb2", "name": "UI client",    "project": "<second project from {{target_projects}}>", ... }
   ]
   ```
3. **Default `branch_strategy` to `"parallel"`** for cross-repo plans. Reason: a `shared-branch` plan presumes a single git history that all items push to, which is impossible across separate repos — at best it means "shared *branch name*, independent branches per repo", which is a coordination convention, not a literal shared history, and only makes sense when the human plan author explicitly asked for that coordination (e.g. to keep matching `user/<login>/PL-<slug>` branches across repos for a single launch). If the plan explicitly justifies `shared-branch` for cross-repo coordination, you may use it; otherwise prefer `parallel` so each item gets its own per-repo branch and PR.
4. **`feature_branch` follows the strategy:**
   - `parallel`: omit `feature_branch` entirely (the engine derives per-item branches as `user/<loginname>/<wi-id>-<slug>` in each project).
   - `shared-branch` (only with explicit justification): use the canonical `user/<loginname>/PL-<short-kebab-slug>` form. The engine will pre-create a matching branch in every project listed in `{{target_projects}}` (P-1c0f5e84) so each item can push to the same branch name in its own repo.

The verify task at plan completion picks the project with the most completed items and runs cross-repo verification from there; items with no PRs (e.g. docs-only changes that landed via direct commit) are still counted via their `done` status.

{{/target_projects}}
## Reusing an Existing PRD

When the engine detects an existing PRD for this plan (`source_plan` match), it passes the content below. If this section is empty or absent, skip to normal generation (all items `"missing"` with new UUIDs).

<existing-prd>
{{existing_prd_json}}
</existing-prd>

**When an existing PRD is provided:**

1. **Parse the existing PRD JSON** — extract all `missing_features` items with their `id`, `status`, and metadata
2. **Preserve item IDs** — match existing items to current plan items by name/description similarity. Each plan item that corresponds to an existing PRD item should reuse that item's `P-<id>`. Do not generate new IDs for items that already exist — duplicates orphan the prior work.
3. **Preserve done items** — any existing item with `"status": "done"` carries forward as `"done"` with the same ID, description, and acceptance criteria. Do NOT reset done items to `"missing"`
4. **Carry forward in-progress items** — items with `"status": "missing"` or other non-done statuses (except `"updated"`) keep their existing ID and reset to `"missing"`. Items with `"status": "updated"` keep their existing ID and remain `"updated"` — do NOT reset to `"missing"`
5. **New items only** — only generate new `P-<uuid>` IDs for items in the plan that have no match in the existing PRD
6. **Removed items** — if an existing PRD item has no match in the current plan, drop it from the output
7. **Preserve plan-level fields** — keep `branch_strategy`, `feature_branch`, and `project` from the existing PRD unless the plan explicitly changes them

This ensures re-running plan-to-prd on the same plan produces a clean update (new items added, completed items preserved, IDs stable) rather than a full reset with orphaned duplicates.

## Updating an Existing PRD (Diff-Aware)

If the task description contains `mode: diff-aware-update`, you are updating an existing PRD because the plan was revised. Follow the same reuse rules above, plus these additional diff-aware rules:

**Additional diff-aware rules** (on top of the reuse rules above):
- **Done + modified** (plan added requirements/changed scope) → set `"status": "updated"` with same ID (engine re-opens the work item and dispatches to existing branch)
- **Already `"updated"`** (was previously flagged for rework and still needs changes) → keep `"status": "updated"` with same ID and revised description. Do NOT reset to `"missing"` — this preserves the existing branch reference so the agent continues from prior work
- **Pending/failed items** → reset to `"missing"` with updated description if the plan changed their scope

## Important

- Write ONLY the single `.json` PRD file to `{{team_root}}/prd/` — do NOT write any `.md` files there
- Do NOT create a git branch, worktree, or PR — this playbook writes minions-internal state only
- Do NOT modify any files in the project repo
- The engine will dispatch implementation agents automatically once the JSON file exists
- For `shared-branch`: agents commit to a single branch — one PR is created automatically when all items are done
- For `parallel`: each agent creates its own branch and PR

## When to Stop

Your task is complete once you have written the PRD JSON file to `{{team_root}}/prd/{{prd_filename}}`. The engine will detect the file and begin dispatching work. Do NOT create branches, PRs, or modify project code. Stop after writing the JSON file.
