Merge pull request #127 from ai-agent-assembly/v0.0.1/AAASM-3007/docs/release_coordination_sop

[AAASM-3007] 📝 (sdk-only-release): Add release-coordination SOP for agent-assembly cycles

Author: Chisanan232

.claude/skills/sdk-only-release/EXAMPLES.md

@@ -67,3 +67,62 @@ confirms `0.0.1a9.post1` is the latest.
 on `repository_dispatch` (AAASM-2868), and this run was a
 `workflow_dispatch`. If a documentation refresh is needed it must be
 dispatched separately against the docs pipeline.
+
+---
+
+## Two cases — when to use this skill
+
+The `sdk-only-release` skill's [SKILL.md SOP](SKILL.md#release-coordination-sop--when-agent-assembly-is-also-releasing) defines two release shapes. The worked example above (`0.0.1a9.post1`) is a **Case B** scenario — SDK-only release with the bundled `aasm` binary already published from the previous coordinated cycle. The walkthrough below shows the **Case A** coordinated cycle.
+
+## Case A — coordinated cycle (wait for agent-assembly)
+
+Worked example for the SOP. **Scenario**: operator wants to publish `agent-assembly==0.0.1b3` **alongside** agent-assembly `v0.0.1-beta.3` — both carry the same content cycle. The SOP requires the SDK dispatch to wait for the upstream tag + the auto-bump PR.
+
+**1. Verify the agent-assembly tag exists and `release.yml` finished green.**
+
+```bash
+$ gh release view v0.0.1-beta.3 --repo ai-agent-assembly/agent-assembly \
+    --json tagName,publishedAt
+{"tagName":"v0.0.1-beta.3","publishedAt":"2026-..."}
+
+$ gh run list --repo ai-agent-assembly/agent-assembly --workflow release.yml \
+    --branch v0.0.1-beta.3 --limit 1 --json conclusion,name
+[{"name":"Release","conclusion":"success"}]
+```
+
+If the release is missing or the run is still in progress, STOP — do not dispatch the SDK release yet.
+
+**2. Verify the `bot/aa-ffi-pin-v0.0.1-beta.3` PR opened on this repo.**
+
+```bash
+$ gh pr list --repo ai-agent-assembly/python-sdk --head bot/aa-ffi-pin-v0.0.1-beta.3 \
+    --json number,title,mergedAt
+[{"number":NNN,"title":"🤖 (aa-ffi-python): Bump aa-core/aa-proto/aa-sdk-client pin to v0.0.1-beta.3","mergedAt":null}]
+```
+
+If no PR is listed, the upstream `update-python-sdk-ffi-pin` job (AAASM-2883) hasn't run yet. Wait, then re-probe.
+
+**3. Review + merge the auto-bump PR.** The PR moves all three shared `git-SHA` pins (`aa-core`, `aa-proto`, `aa-sdk-client`) in `native/aa-ffi-python/Cargo.toml` to the new agent-assembly tag commit (and regenerates `Cargo.lock`). The single-SHA invariant from ADR 0002 / AAASM-2559 is preserved.
+
+**4. ONLY NOW dispatch `release-python.yml`.** Same mechanics as the `0.0.1a9.post1` example above — `dry-run=true` first, then `dry-run=false`. Use `binary_source_tag=v0.0.1-beta.3` (NOT the previous tag) so the wheels bundle the new `aasm-*.tar.gz` assets, and `pypi_version=0.0.1b3` (the PEP 440 form of the agent-assembly tag).
+
+```bash
+gh workflow run release-python.yml \
+  --repo ai-agent-assembly/python-sdk \
+  --ref master \
+  -f pypi_version=0.0.1b3 \
+  -f binary_source_tag=v0.0.1-beta.3 \
+  -f dry-run=true
+```
+
+**5. Verify on the registry** (same probes as the `0.0.1a9.post1` example: `pip index versions agent-assembly` confirms `0.0.1b3` is the latest; downloading a wheel and inspecting the bundled `aasm` binary should match the new agent-assembly Release artifacts).
+
+### Anti-example — what happens if you skip steps 1-3
+
+This is the 2026-06-15 foot-gun the SOP prevents:
+
+- **02:22 UTC** — operator dispatched `release-python.yml` with `pypi_version=0.0.1b2` while agent-assembly's latest release was still `v0.0.1-beta.1`. `binary_source_tag` resolved to that previous tag. `dry-run` defaulted to false. **PyPI accepted the publish**, bundling wheels with the previous agent-assembly content.
+- **09:36 UTC** — agent-assembly's actual `v0.0.1-beta.2` tag cut (commit `0aa9c945`, AAASM-3004) → `notify-downstream` fired the coordinated republish. `release-python.yml` tried to re-publish `0.0.1b2` with the new content carrying the AAASM-3000 IPC fix. **PyPI 400'd** with `File already exists ('agent_assembly-0.0.1b2-cp312-cp312-macosx_10_12_x86_64.whl'). See https://pypi.org/help/#file-name-reuse`.
+- **Net**: `agent-assembly==0.0.1b2` on PyPI carries the OLD content (no AAASM-3000 fix). The file-name slot is permanently burnt — PyPI explicitly disallows file-name reuse even after yank (see the linked help page). The fix had to ship under a different SDK version cut later.
+
+The verification probes in steps 1-3 above make this impossible to repeat: any of them failing forces the operator to stop and resolve before dispatch.

.claude/skills/sdk-only-release/SKILL.md

@@ -36,6 +36,34 @@ release path, not an emergency one.
   That is a `binary_source_tag` change — decide which axis is actually changing
   before invoking.
 
+## Release-coordination SOP — when agent-assembly is ALSO releasing
+
+This is the canonical ordering rule operators MUST follow whenever `agent-assembly` is cutting a release in the same version cycle as this SDK. Codified after the 2026-06-15 incident (AAASM-3007).
+
+### Case A — agent-assembly is ALSO releasing this version cycle
+
+The SDK release MUST wait. Required order:
+
+1. Cut the `agent-assembly` tag (e.g. `v0.0.1-beta.3`) and wait for its `Release` workflow to complete (build → publish → `notify-downstream`).
+2. Wait for the auto-bump PR (`bot/aa-ffi-pin-<tag>`) to open on this repo (AAASM-2883 for node/python; AAASM-3006 extends the same fan-out to go-sdk).
+3. Review + merge the auto-bump PR. This brings `master` in line with the `aa-sdk-client` SHA carried by the new agent-assembly tag.
+4. ONLY THEN cut the SDK tag (matching version) — by tag-push OR `workflow_dispatch` — to fire this skill.
+
+Do NOT pre-publish the SDK tag against the previous agent-assembly content. Doing so:
+
+- Burns the version slot on the registry (npm / PyPI refuse re-publish).
+- Means users installing that SDK version get content that does NOT carry the agent-assembly fix they expect.
+
+### Case B — SDK-only release (no agent-assembly cut in this cycle)
+
+This skill may be triggered freely via `workflow_dispatch`. No coordination required, because the existing `aa-sdk-client` SHA pin on `master` is already what we want to ship.
+
+### Why this SOP exists (the 2026-06-15 incident)
+
+On 2026-06-15 02:21 UTC, `@agent-assembly/sdk@0.0.1-beta.2` was published to npm via `workflow_dispatch` while `agent-assembly`'s latest release was still `v0.0.1-beta.1` (pre-AAASM-3000 IPC fix). The bundle on npm at version `0.0.1-beta.2` therefore does NOT carry the AAASM-3000 fix that users would reasonably expect from that version label. Same incident on PyPI at 02:22 UTC.
+
+The fix is operator discipline (this SOP), not a workflow-code restriction — `workflow_dispatch` is kept open for legitimate Case B releases.
+
 ## How to use
 
 Invoke `release-python.yml` via `workflow_dispatch` against `master`, three