Document Flex tagging, tag push order, and track-builds behavior.

Align the workspace rule, README, and release guide generator with current go.py and track_builds.py behavior.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: y3rsh

.cursor/rules/robot-stack.mdc

@@ -21,7 +21,7 @@ The system supports internal and external release channels. This tool helps enfo
 
 | Path | Repos synced | App repo (tagging) | Version scheme |
 |---|---|---|---|
-| **Flex** | `opentrons`, `oe-core`, `ot3-firmware` | `opentrons` | Semver with `v` prefix (e.g. `v8.5.0`, `v8.5.0-alpha.6`) |
+| **Flex** | `opentrons`, `oe-core`, `ot3-firmware` | `opentrons` | Per-repo prefixes (see Flex semver below) |
 | **OT-2** | `opentrons-ot2`, `buildroot` | `opentrons-ot2` | Calendar semver (see below) |
 
 `robot-stack-infra` is always cloned and pulled for both paths as a reference repo, but is not included in release tables or tagging.
@@ -68,6 +68,58 @@ External alpha/beta use semver prerelease numbering on a fixed base: `v26.6.0-al
 
 External tags use a `v` prefix; internal tags use `internal@`.
 
+### Flex semver tagging
+
+Flex uses **different tag prefixes per repo**. In `just go`, Flex prompts for **Stability: stable/unstable** (not OT-2's alpha/beta/stable). `unstable` means alpha builds.
+
+| Repo | Internal | External |
+|---|---|---|
+| `opentrons` (app) | `ot3@X.Y.Z`, alpha `ot3@X.Y.Z-alpha.N` | `vX.Y.Z`, alpha `vX.Y.Z-alpha.N` |
+| `oe-core` (robot OS) | `internal@X.Y.Z`, alpha `internal@X.Y.Z-alpha.N` | `v0.X.Y` (independent line; patch bump from latest merged tag) |
+| `ot3-firmware` | `internal@vN` integer counter | `vN` integer counter |
+
+Tag suggestion rules in `automation/go.py`:
+
+- **App (`opentrons`):** base `X.Y.Z` comes from the prompted release version. Stable: `ot3@X.Y.Z` if missing, else patch bump. Alpha: increment `ot3@X.Y.Z-alpha.N` from branch tags.
+- **Robot OS (`oe-core`, internal):** base `X.Y.Z` comes from the same prompted version (not from the newest oe-core tag alone). Alpha `N` is **coordinated with the app**: `go` reads the next `ot3@X.Y.Z-alpha.N` from `opentrons` and reuses that `N` for `internal@X.Y.Z-alpha.N`. Stable: `internal@X.Y.Z` if missing, else patch bump.
+- **Firmware (`ot3-firmware`):** next integer above the highest merged channel tag (`internal@vN` or `vN`).
+
+### Tag push order
+
+Push annotated tags in this order. Dependent stack repos first, app monorepo last.
+
+| Path | Order |
+|---|---|
+| **Flex** | 1. `ot3-firmware` (if needed), 2. `oe-core` (if needed), 3. `opentrons` (app, always last) |
+| **OT-2** | 1. `buildroot` (if needed), 2. `opentrons-ot2` (app, always last) |
+
+`go` prints this order at the end of a release run.
+
+### Track release builds (`just track-builds`)
+
+After pushing the **app** tag, run `just track-builds --path flex|ot2 --tag <app-tag> --wait` (or without `--wait` for a one-shot lookup). `go` prints this command with `--wait` by default.
+
+`automation/track_builds.py` locates GitHub Actions runs for:
+
+1. **App** workflow on the monorepo (`App test, build, and deploy`)
+2. **Kickoff** cross-repo dispatch (`Start OT-2 build` or `Start Flex build`)
+3. **Robot OS** build in `buildroot` (OT-2) or `oe-core` (Flex)
+
+The Rich table also lists matching **key jobs** (deploy, desktop builds, dispatch spawn, robot image build). The **Slack copy block** includes only two links:
+
+```
+OT-2 release `internal@26.5.2801`
+
+- app: https://github.com/Opentrons/opentrons-ot2/actions/runs/...
+- ot2: https://github.com/Opentrons/buildroot/actions/runs/...
+```
+
+(Flex uses `- flex:` instead of `- ot2:`.)
+
+**`--wait` behavior:** poll every 15 seconds (default) until App, Kickoff, and Robot OS workflow runs all appear, up to 900 seconds (default). The poll loop only checks for workflow runs (not jobs). After all three runs exist, the script fetches key jobs with retries for transient GitHub 404s on the jobs API. Exit code `2` if any top-level run is still missing.
+
+Tag prefix inference when `--path` is omitted: `internal@` → OT-2, `ot3@` → Flex, otherwise Flex.
+
 ## Development Standards
 
 ### Language & Version

README.md

@@ -16,20 +16,53 @@ Instead of make, use [just](https://github.com/casey/just). The VS Code justfile
   - `uv run just fix`
 - sync repos and inspect release state
   - `uv run just go`
+- find GitHub Actions runs after pushing an app tag
+  - `uv run just track-builds --path ot2 --tag internal@26.5.2801 --wait`
 
 ## Release Paths
 
 `just go` runs `automation/go.py`, an interactive release helper. It supports two robot paths; **Flex is the default**.
 
 | Path | Repos | App repo | Version scheme |
 |---|---|---|---|
-| **Flex** | `opentrons`, `oe-core`, `ot3-firmware` | `opentrons` | Semver (`v8.5.0`, alpha tags like `v8.5.0-alpha.6`) |
+| **Flex** | `opentrons`, `oe-core`, `ot3-firmware` | `opentrons` | Per-repo prefixes (`ot3@`, `internal@`, `v`; see below) |
 | **OT-2** | `opentrons-ot2`, `buildroot` | `opentrons-ot2` | Calendar semver (internal + external; see below) |
 
 `robot-stack-infra` is always cloned and pulled for both paths as a reference repo. It is not included in release tables or tagging.
 
 Each repo uses isolation branches named `chore_release-<version>` during a release cycle.
 
+### Tag push order
+
+Push annotated tags in this order. Stack repos first, app monorepo last.
+
+| Path | Order |
+|---|---|
+| **Flex** | `ot3-firmware` (if needed) → `oe-core` (if needed) → `opentrons` (app, always last) |
+| **OT-2** | `buildroot` (if needed) → `opentrons-ot2` (app, always last) |
+
+### Flex semver
+
+Flex repos use different tag prefixes. In `just go`, Flex uses **stable/unstable** stability (unstable = alpha).
+
+| Repo | Internal | External |
+|---|---|---|
+| `opentrons` | `ot3@X.Y.Z`, alpha `ot3@X.Y.Z-alpha.N` | `vX.Y.Z`, alpha `vX.Y.Z-alpha.N` |
+| `oe-core` | `internal@X.Y.Z`, alpha `internal@X.Y.Z-alpha.N` | `v0.X.Y` (independent line) |
+| `ot3-firmware` | `internal@vN` | `vN` |
+
+For internal alpha builds, `go` coordinates oe-core alpha numbers with the next `ot3@X.Y.Z-alpha.N` on `opentrons`. Internal oe-core and app stable tags use the prompted base version; if that exact tag already exists on the branch, `go` suggests a patch bump.
+
+### Track release builds
+
+After pushing the app tag, locate CI with `just track-builds`:
+
+```bash
+just track-builds --path ot2 --tag internal@26.5.2801 --wait
+```
+
+The script finds app, kickoff, and robot OS workflow runs and prints a Rich table plus a Slack copy block with two links (`app` and `ot2` or `flex`). With `--wait`, it polls every 15 seconds until all three workflow runs appear (default timeout 15 minutes).
+
 ## OT-2 calendar semver
 
 OT-2 uses semver-shaped versions so electron-updater and robot update checks work. **Internal and external channels use different patch schemes.** Within a channel, the app and robot OS share the same version string.

automation/release_guides.py

@@ -199,6 +199,55 @@ def _tag_need_section() -> str:
     """
 
 
+def _tag_push_order_section(robot: str) -> str:
+    """Explain annotated tag push order for one robot path."""
+    if robot == "flex":
+        rows = """
+        <tr><td>1</td><td><code>ot3-firmware</code></td><td>Firmware, if a new tag is needed</td></tr>
+        <tr><td>2</td><td><code>oe-core</code></td><td>Robot OS, if a new tag is needed</td></tr>
+        <tr><td>3</td><td><code>opentrons</code></td><td>App monorepo, always last</td></tr>"""
+        path_label = "Flex"
+    else:
+        rows = """
+        <tr><td>1</td><td><code>buildroot</code></td><td>Robot OS, if a new tag is needed</td></tr>
+        <tr><td>2</td><td><code>opentrons-ot2</code></td><td>App monorepo, always last</td></tr>"""
+        path_label = "OT-2"
+    return f"""
+    <h2>Tag push order</h2>
+    <p>Push annotated tags in this order. Dependent stack repos first, app monorepo last.
+    <code>just go</code> prints this reminder at the end of a release run.</p>
+    <table>
+      <thead><tr><th>Step</th><th>Repo</th><th>Notes</th></tr></thead>
+      <tbody>{rows}</tbody>
+    </table>
+    <p>{path_label} stack repos only get a new tag when their release branch tip is ahead of the
+    latest channel tag on that branch.</p>
+    """
+
+
+def _track_builds_section(robot: str, example_tag: str, slack_robot_label: str) -> str:
+    """Explain just track-builds for one robot path."""
+    path_flag = html.escape(robot)
+    tag = html.escape(example_tag)
+    slack_label = html.escape(slack_robot_label)
+    return f"""
+    <h2>Track release builds</h2>
+    <p>After pushing the app tag, run:</p>
+    <pre>just track-builds --path {path_flag} --tag {tag} --wait</pre>
+    <p><code>automation/track_builds.py</code> locates GitHub Actions runs for the app workflow,
+    the cross-repo kickoff workflow, and the robot OS build in
+    <code>{'buildroot' if robot == 'ot2' else 'oe-core'}</code>.</p>
+    <p>The Rich output includes a full table (including key jobs). The Slack copy block is shorter:</p>
+    <pre>{'OT-2' if robot == 'ot2' else 'Flex'} release `{tag}`
+
+- app: &lt;app workflow run URL&gt;
+- {slack_label}: &lt;robot OS workflow run URL&gt;</pre>
+    <p><strong><code>--wait</code></strong> polls every 15 seconds until app, kickoff, and robot OS
+    workflow runs all appear (default timeout 15 minutes). It avoids calling the jobs API during
+    polling, then retries job lookups if GitHub briefly returns 404 for a new run.</p>
+    """
+
+
 def _yaml_links(channel_host: str) -> str:
     """Render electron-updater YAML links for a host."""
     items = []
@@ -256,6 +305,10 @@ def render_flex_external() -> str:
     <p>When a new tag is needed, <code>go</code> takes the highest <code>vN</code> number merged
     into the branch and suggests <code>v(N+1)</code>.</p>
 
+    {_tag_push_order_section("flex")}
+
+    {_track_builds_section("flex", "v9.1.0", "flex")}
+
     <h2>Where to find published releases</h2>
     <p>External Flex artifacts live on <code>{html.escape(FLEX_EXTERNAL.app_host)}</code>.</p>
     <table>
@@ -320,22 +373,33 @@ def render_flex_internal() -> str:
     <h2>How the next tag is chosen</h2>
     <h3>App (<code>opentrons</code>)</h3>
     <ul>
-      <li><strong>Stable:</strong> <code>ot3@X.Y.Z</code> if not already on the branch.</li>
-      <li><strong>Alpha (unstable):</strong> increment <code>ot3@X.Y.Z-alpha.N</code> from existing tags on the branch.</li>
+      <li><strong>Stable:</strong> <code>ot3@X.Y.Z</code> if not already on the branch; otherwise patch bump
+      (e.g. <code>ot3@8.5.0</code> → <code>ot3@8.5.1</code>).</li>
+      <li><strong>Alpha (unstable):</strong> increment <code>ot3@X.Y.Z-alpha.N</code> from existing tags on the branch
+      (first alpha is <code>ot3@8.5.0-alpha.0</code>).</li>
     </ul>
 
     <h3>Robot OS (<code>oe-core</code>)</h3>
     <p>Internal tags use the <code>internal@</code> prefix without a leading <code>v</code>.
-    The base version (e.g. <code>3.0.0</code>) comes from the newest <code>internal@</code> tag on the branch.</p>
+    The base <code>X.Y.Z</code> comes from the same version you enter at the <code>just go</code> prompt
+    (not from the newest oe-core tag alone).</p>
     <ul>
-      <li><strong>Alpha (unstable):</strong> <code>internal@3.0.0-alpha.N</code>, increment <code>N</code>.</li>
-      <li><strong>Stable:</strong> <code>internal@3.0.0</code>, or patch bump if that exact tag already exists.</li>
+      <li><strong>Alpha (unstable):</strong> <code>internal@X.Y.Z-alpha.N</code>. The alpha number
+      <code>N</code> is coordinated with the app: <code>go</code> reads the next
+      <code>ot3@X.Y.Z-alpha.N</code> from <code>opentrons</code> and reuses that <code>N</code>
+      for oe-core.</li>
+      <li><strong>Stable:</strong> <code>internal@X.Y.Z</code> if that exact tag is not on the branch;
+      otherwise patch bump (e.g. <code>internal@8.5.0</code> → <code>internal@8.5.1</code>).</li>
     </ul>
 
     <h3>Firmware (<code>ot3-firmware</code>)</h3>
     <p>Internal tags look like <code>internal@v26</code>, <code>internal@v27</code>.
     When needed, <code>go</code> suggests one higher than the max merged tag number.</p>
 
+    {_tag_push_order_section("flex")}
+
+    {_track_builds_section("flex", "ot3@8.5.0-alpha.0", "flex")}
+
     <h2>Where to find published releases</h2>
     <p>Internal Flex artifacts live on <code>{html.escape(FLEX_INTERNAL.app_host)}</code>.</p>
     <table>
@@ -358,8 +422,8 @@ def render_flex_internal() -> str:
       <table>
         <thead><tr><th>Stability</th><th>App tag example</th><th>oe-core example</th></tr></thead>
         <tbody>
-          <tr><td>Stable internal</td><td><code>ot3@8.5.0</code> (uncommon)</td><td><code>internal@3.0.0</code></td></tr>
-          <tr><td>Alpha</td><td><code>ot3@8.5.0-alpha.0</code></td><td><code>internal@3.0.0-alpha.0</code></td></tr>
+          <tr><td>Stable internal</td><td><code>ot3@8.5.0</code></td><td><code>internal@8.5.0</code> (same prompted base)</td></tr>
+          <tr><td>Alpha</td><td><code>ot3@8.5.0-alpha.0</code></td><td><code>internal@8.5.0-alpha.0</code> (same <code>N</code> as app)</td></tr>
           <tr><td>Beta</td><td><code>ot3@8.5.0-beta.0</code> (manual)</td><td><code>internal@3.0.0-beta.0</code> (manual)</td></tr>
         </tbody>
       </table>
@@ -419,6 +483,10 @@ def render_ot2_external() -> str:
     <p><code>buildroot</code> uses the same next-tag logic and should receive the matching tag when its
     branch has commits since the latest channel tag.</p>
 
+    {_tag_push_order_section("ot2")}
+
+    {_track_builds_section("ot2", "v26.6.0", "ot2")}
+
     <h2>Where to find published releases</h2>
     <p>External OT-2 artifacts live on <code>{html.escape(OT2_EXTERNAL.app_host)}</code>.</p>
     <table>
@@ -508,6 +576,10 @@ def render_ot2_internal() -> str:
     <p>Examples: <code>internal@26.5.2601-alpha</code>, <code>internal@26.5.2602-alpha</code>.</p>
     <p><code>buildroot</code> receives the matching tag when its branch is ahead of the latest internal tag.</p>
 
+    {_tag_push_order_section("ot2")}
+
+    {_track_builds_section("ot2", "internal@26.5.2601", "ot2")}
+
     <h2>Where to find published releases</h2>
     <p>Internal OT-2 artifacts live on <code>{html.escape(OT2_INTERNAL.app_host)}</code>.</p>
     <table>