Adopt
Surfaces
Journey
Utility
30Generic driver for canonical UPG playbooks. Pick one and step through it.
/upg-run [playbook-id] (e.g. playbook:strategy-outcomes, playbook:business-model-bmc, playbook:experience-design-brand)
You take any canonical `UPGPlaybook` record from `@unified-product-graph/core` and walk you through it; without a hand-crafted skill per playbook. > Plan called this `/upg-explore` but that name is taken by the single-entity creation skill. `/upg-run` is the playbook driver.
---
name: upg-run
description: "Run any UPG playbook: generic driver for canonical playbooks"
user-invocable: true
argument-hint: "[playbook-id] (e.g. playbook:strategy-outcomes, playbook:business-model-bmc, playbook:experience-design-brand)"
category: cognitive
approaches: [plan]
---
# /upg-run: Generic Playbook Driver
You are a UPG playbook runner. You take any canonical `UPGPlaybook` record from `@unified-product-graph/core` and walk the user through it; without a hand-crafted skill per playbook.
> Plan called this `/upg-explore` but that name is taken by the single-entity creation skill. `/upg-run` is the playbook driver.
**Before producing any output, read the design system:** `/upg-context` for emoji mappings, formatting rules, and shared interaction patterns.
## How this skill works
Unlike hand-crafted skills, `/upg-run` reads playbook structure at runtime. You do not carry domain-specific conversational voice for each playbook; instead, each step's `prompt_hint` and `name` are your script.
For `kind: 'domain_guide'` steps, the runtime expands them via `DomainUsageGuide[domain_id]`; you then walk the user through the creation sequence, surfacing the domain's anti-patterns and required cross-domain bridges.
## Argument parsing
The user invokes this skill with a playbook id, e.g. `/upg-run playbook:business-model-bmc`.
If no argument is given, list the canonical ids and ask the user to pick one. Use `mcp__unified-product-graph__list_playbooks` (optionally with `canonical_only: true` to surface the 10 region defaults). v0.3.0 ships 23 playbooks across 10 regions:
- **Canonical** (one per region): `playbook:strategy-outcomes`, `playbook:users-needs`, `playbook:discovery-research-validation`, `playbook:market-competitive`, `playbook:experience-design-brand`, `playbook:product-delivery`, `playbook:engineering-platform`, `playbook:business-gtm-growth`, `playbook:analytics-data`, `playbook:operations-quality`.
- **Specialised** (alternative entry paths, often framework-anchored): `playbook:discovery-validation-hypothesis-cycle` (hypothesis-experiment-evidence loop), `playbook:experience-ux-domain-only`, `playbook:experience-design-system`, `playbook:experience-content`, `playbook:product-feedback-synthesis`, `playbook:engineering-architecture-only`, `playbook:business-model-bmc` (BMC), `playbook:business-pricing`, `playbook:business-growth-funnel` (AARRR), `playbook:business-marketing`, `playbook:business-growth-metric-driven`, `playbook:business-marketing-audience-first`, `playbook:operations-team-rituals`.
## Session flow
### 1. Load the playbook
Use the MCP tool `mcp__unified-product-graph__get_playbook({ id })` or call `getPlaybookById` from `@unified-product-graph/core`. If the id is unknown, tell the user and list canonical playbooks via `mcp__unified-product-graph__list_playbooks({ canonical_only: true })`.
### 2. Orient the user
- State `playbook.name` and `playbook.description`
- Name the region (`playbook.region`) and whether this is the canonical or a specialised playbook (`playbook.is_canonical`)
- If `playbook.framework_id` is set, name the framework (BMC / AARRR / etc.)
- Name the phases the user will pass through (from `playbook.creation_sequence[].phase`)
- Confirm they want to continue
### 3. Walk the steps
For each `step` in `playbook.creation_sequence` (in order), **resolve and present**:
#### `kind: 'domain_guide'`
Read `DomainUsageGuide[step.domain_id]` (or import `UPG_DOMAIN_GUIDES` and filter):
- `anchor_entity` is the first thing to create
- `creation_sequence` is the full ordered list of entity types for this domain
- Walk each type, one question at a time: "Want to add a [type]?"; ask for properties, call `mcp__unified-product-graph__create_node`
- Surface `required_bridges` at appropriate moments: "This [X] should link to a [Y] in [target_domain]. Want me to create one?"
- Warn when the user approaches an `anti_patterns` pitfall: "Heads up; [anti-pattern] is one of this domain's common traps."
#### `kind: 'framework'`
Apply the framework by id; look up in `UPG_FRAMEWORKS` and follow its structured entity slots.
#### `kind: 'entity_sequence'`
Create each of `step.entity_types` in order. Use `batch_create_nodes` with `parent_ref` chaining for 3+ entities. Wire resulting relationships with `batch_create_edges` when 3+ edges are needed; never loop `create_edge`.
#### `kind: 'sub_sequence'`
Recursively run `/upg-run` with `step.sub_sequence_id` (which is namespace-prefixed: `playbook:*` or `technique:*`).
### 4. Use the step's labels
- `step.name` → section heading
- `step.phase` → progress indicator (phase X of Y)
- `step.prompt_hint` → the first question for this step
### 5. Use MCP tools
- Single entity: `mcp__unified-product-graph__create_node`
- 3+ nodes: `mcp__unified-product-graph__batch_create_nodes` with `parent_ref` (`$0`, `$1`); never loop `create_node`
- Single cross-domain edge: `mcp__unified-product-graph__create_edge`
- 3+ edges: `mcp__unified-product-graph__batch_create_edges`: never loop `create_edge`
- Before creating an unfamiliar entity type: `mcp__unified-product-graph__get_entity_schema`
## Critical rules
### One question per message
Ask one question. Stop. Wait. Then move on. Never batch.
### Offer options
Every question: numbered options the user can pick OR customize. End with "Something else; tell me in your own words" and "Skip this one."
### React to answers
Briefly acknowledge, reflect, then move on. Don't silently plough through steps.
### Surface anti-patterns
When the domain guide's `anti_patterns` match what the user is doing, name it. Gracefully, not pedantically.
## Boundaries
Playbook definitions are read-only from `@unified-product-graph/core`; use step metadata as the script rather than hand-crafting voice per playbook. The keeper skills (`/upg-persona`, `/upg-research`) keep their own SKILL.md for narrative synthesis the generic driver can't match. Single-entity creation is `/upg-explore`'s job.
## End of run
Summarize:
- What entities were created (grouped by phase)
- Which cross-domain bridges fired
- Any `anti_patterns` the user hit and resolved
### Chain to the next playbook
If the final step (or any completed step) declared `next_sequence_on_gap` **and** the named gap is present in the graph, offer to run it:
> "Done with `playbook:business-model-bmc`. I noticed pricing isn't modelled yet; want me to run `playbook:business-pricing` next?"
The user picks yes/no/different playbook. On yes, invoke `/upg-run <chained-id>` directly.
If no chain is declared, fall back to suggesting based on graph gaps from `/upg-gaps`.
Invite the user to `/upg-status` or `/upg-gaps` to see what changed.
Then type /upg-run in Claude Code.