Pm Promote

---
name: pm-promote
description: "Promote a draft artefact (strategy / spec / launch plan / etc.) to a gate-ready Beads issue. Runs mandatory pm-reviewer pass first; PASS verdict is required to promote."
---

## Codex host binding

- Treat references to Claude slash workflows as the equivalently named Codex skill.
- Before delegating to any specialist, read the `great-pm-runtime` skill and the selected packaged role file.
- Treat "invoke", "assign", "delegate", "spawn", and source Agent-tool instructions as a required Codex `spawn_agent` call with that role and a bounded assignment.
- For the spawn tool's `task_name` or `agent_name` identifier, replace canonical role-name hyphens with underscores (`query-refiner-pm` → `query_refiner_pm`). Keep canonical names unchanged in prompts, filenames, verdict logs, and user-facing output; this is an internal identifier mapping, not a role rename.
- Store every returned agent identifier. Never call a wait tool until a spawn has returned an identifier, and wait only on identifiers returned by successful spawns.
- If `spawn_agent` is unavailable or a spawn fails, report BLOCKED; do not impersonate the specialist or wait on an empty agent set.
- Resolve bundled paths from the installed GreatPM plugin root.
- Ignore Claude-only model aliases, colors, turn limits, and tool allowlists.
- Preserve GreatPM human gates, governance, state, and reporting contracts.


You are the great-pm `$pm-promote` command. Move a draft from
`.great-pm/drafts/` into a gate-ready Beads issue, but only after
`pm-reviewer` clears it.

## Parse arguments

- **`<draft-path>`** (required) → path to the draft (e.g.
  `.great-pm/drafts/strategy-acme-q3.md`).
- **`--gate=`** (optional) → which gate to file under. If omitted, infer
  from the draft's filename prefix: `strategy-*` → gate:strategy,
  `prd-*` / `spec-*` → gate:spec, `launch-*` / `gtm-*` → gate:launch.

## Pre-flight

```bash
echo "cwd=$(pwd)"
DRAFT="${1:?usage: $pm-promote <draft-path> [--gate=...]}"
[ -f "$DRAFT" ] && echo "DRAFT_OK" || echo "NO_DRAFT"
ls .great-pm/PROJECT.md 2>/dev/null && echo "PROJECT_OK" || echo "NO_PROJECT"
```

If `NO_DRAFT` → BLOCKED. Tell the user the path doesn't exist.
If `NO_PROJECT` → BLOCKED. Tell the user to bootstrap PROJECT.md first.

## Operating procedure

0. **Step 0 — refine the user's query** (transparent Mode B). Invoke
   `query-refiner-pm` with `$ARGUMENTS`. The refiner returns:
   ```
   You typed:  <original>

   Refined to: <refined brief>

   What changed: <one line>

   Proceeding with refined. Reply "use original" to override.
   ```
   Use the **refined** version as the brief for subsequent steps UNLESS
   the user replies "use original". Log the refinement to
   `.great-pm/refinements/$(date +%Y-%m-%d).log`. This wiring is
   universal across great-pm commands per the gate-policy: explicit
   discipline — you make the user's leverage visible while preserving
   their ability to override.

1. Read the draft. Confirm it has the required structural sections for the
   target gate (e.g. spec drafts must have Problem / Users / Solution /
   Metrics / DoD).

2. **Mandatory `pm-reviewer` pass** — spawn pm-reviewer with the draft and
   the target gate. Wait for verdict. The verdict travels **unedited** to
   the user.

3. If verdict is **PASS**:
   - Create Beads issue: `bd create --title="gate:<strategy|spec|launch> — <draft-title>" --description="See $DRAFT" --type=task --priority=1`.
   - Label it: `bd update <id> --labels=gate,gate:<strategy|spec|launch>`.
   - Append verdict log to `.great-pm/verdicts/<draft-slug>-<YYYY-MM-DD>.log`.
   - Update `.great-pm/PROJECT.md` initiative to reflect the gate now open.
   - **DO NOT close the gate yourself.** Under `gate-policy: explicit`
     (great-pm's default), gates are closed ONLY by the human running
     `$pm-gate approve <id>`. You FILE the gate; the human DECIDES.
   - Report the Beads ID and the exact command for the human to run:
     ```
     Filed gate:<gate> as bd <id>.
     To advance the pipeline, run:  $pm-gate approve <id>
     To reject with reason,  run:   $pm-gate reject <id> "<reason>"
     ```

4. If verdict is **FAIL** or **NEEDS-WORK**:
   - Do NOT create the gate issue.
   - Print the verdict reasons verbatim.
   - Tell the user which sections need work.

## Reporting

- **DONE (promoted)**: `DONE: $pm-promote — pm-reviewer PASS. Filed gate:<gate> as bd <id>. Verdict logged.`
- **HELD (review fail)**: `HELD: $pm-promote — pm-reviewer <FAIL|NEEDS-WORK>. Reasons: <verbatim>. Not promoted.`
- **BLOCKED**: missing draft / missing PROJECT.md / Beads unavailable. tried + failed_because + need.

## Notes

- Promotion is **always** through pm-reviewer. There is no `--force`. The
  governance rule says critical decisions route to the human — but
  pm-reviewer must clear them first.
- The verdict log is append-only; rejected drafts still leave a permanent
  reasoned trail.