Playbooks

Playbooks are standard operating procedures (SOPs) for PVM. Use calls.md for payload shape and required fields.

Surface availability (explicit)

• API Gateway: Available.
• Direct Lambda: Not offered.
• CLI: Available (g3n pvm ..., API Gateway).
• MCP: Available.

Playbook: Build a product model (suppliers → taxonomy → style → variant)

Goal: Create the supplier and taxonomy foundation, then model a style and its variants.

Why this sequence:

• Styles require supplier primaries and taxonomy references.
• Variants inherit constraints from the style/OGM and must be created after the style exists.

Preconditions

• Valid orgcode and a USM session/API key with PVM roles.
• Supplier identities (vendor/manufacturer) ready.

SOP (happy path)

1. Create suppliers (POST /vendor, POST /manufacturer).
   • Reason: styles require vendor + manufacturer coverage.
2. Create taxonomy (POST /division, /department, /category, /season).
   • Reason: styles require a non-doomed category.
3. Create brand (POST /brand) and link to suppliers (POST /brand/link/add).
   • Reason: brand coverage must match supplier links when brand_id is set.
4. Set brand primaries (POST /brand/link/set_primary) if the brand will be active.
   • Reason: active brands require primary supplier links.
5. Create options and groups (POST /option_group, POST /option).
   • Reason: variants reference option selections by group/option code.
6. Create OGM (POST /ogm) or clone (POST /ogm/clone) for revisions.
   • Reason: the option matrix defines valid variant signatures.
7. Create style (POST /style) in inactive status.
   • Reason: style anchors variants and supplier coverage; edits are inactive-only.
8. Create variants (POST /variant) with selections and optional identifiers/aliases.
   • Reason: variants are the sellable units.
9. Add identifiers/barcodes (POST /identifier/add, POST /barcode/add, POST /barcode/set_primary).
   • Reason: downstream systems resolve by code/identifier/barcode.
10. Activate records (POST /style/status, POST /variant/status, supplier status).

• Reason: active status is required for publish and downstream use.

Outputs

• Active style + variants with supplier, taxonomy, and identifier coverage.
• Ready for publishing (PMC) and operational use (SCM/ICS/PPM).

Failure modes / remediation

• expected-revision-required / conflict: re-read record and retry with current revision.
• code-generation-exhausted: adjust code_pattern or provide explicit codes.
• invalid-transition: ensure parent records are active before activating children.

Cross-service relationships

• OFM: org association and roles (anti-enumeration).
• PMC: publishes PVM variants into channel-specific products.
• SCM/ICS/PPM: consume variant identifiers and status.

Playbook: OGM change + variant refresh

Goal: Update the option matrix while keeping variant integrity.

Why this sequence:

• OGM revisions are immutable; changes require a new revision.
• Variants become stale when the style’s OGM rev changes.

Preconditions

• Existing style + variants.
• New option group/option changes are ready.

SOP (happy path)

1. Clone OGM (POST /ogm/clone) or create a new OGM.
   • Reason: updates are applied to a new revision.
2. Set style OGM (POST /style/ogm/set).
   • Reason: ties the style to the new matrix and marks variants stale.
3. List stale variants (GET /variant/stale/list).
   • Reason: identify variants that need recreation.
4. Recreate variants (POST /variant/recreate) on the new matrix rev.
   • Reason: ensures signatures and selections match the new OGM.
5. Verify variants (GET /variant/get, /variant/list).
   • Reason: confirm all variants are current and active.

Outputs

• Updated style OGM rev with refreshed variants.

Failure modes / remediation

• invalid-state: ensure OGM and options are active before switching.
• Stale variants remain: re-run variant/recreate for any misses.

Cross-service relationships

• PMC: republish if OGM changes affect sellable variants.