@unified-product-graph/cli 0.6.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@unified-product-graph/cli",
+  "version": "0.6.0",
+  "description": "MCP server + CLI for the Unified Product Graph \u2014 drop into Claude Code or use the `upg` command.",
+  "license": "MIT",
+  "author": "The Product Creator <hello@theproductcreator.com>",
+  "homepage": "https://unifiedproductgraph.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unified-product-graph/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/unified-product-graph/cli/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "upg": "dist/cli.cjs"
+  },
+  "main": "./dist/cli.cjs",
+  "files": [
+    "dist",
+    "skills",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "node scripts/copy-skills.mjs && tsup",
+    "dev": "tsx src/cli.ts",
+    "postbuild": "chmod +x dist/cli.cjs",
+    "prepack": "node scripts/copy-skills.mjs",
+    "copy-skills": "node scripts/copy-skills.mjs",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@linear/sdk": "^5.0.0",
+    "@octokit/rest": "^20.0.0",
+    "@unified-product-graph/core": "*",
+    "@unified-product-graph/sdk": "*",
+    "chalk": "^4.1.2",
+    "commander": "^13.0.0",
+    "inquirer": "^12.0.0",
+    "ora": "^8.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.1",
+    "@unified-product-graph/adapters": "*"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol"
+  ]
+}

package/skills/README.md

@@ -0,0 +1,10 @@
+# @unified-product-graph/cli bundled skills
+
+This folder is **regenerated** from `../upg-mcp-server/skills/` every time
+`@unified-product-graph/cli` is built or packed (via `scripts/copy-skills.mjs`).
+
+Do **not** edit files here. Edit the canonical source in
+`packages/upg-mcp-server/skills/` and re-run `npm run build` in
+`@unified-product-graph/cli` to sync.
+
+These skills are consumed by `upg install-skills`.

package/skills/upg/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: upg
+description: "Unified Product Graph — your product graph, right here in the terminal"
+user-invocable: true
+argument-hint: "[command or natural-language question]"
+category: aggregator
+---
+
+# /upg — Unified Product Graph
+
+You are the front door to the Unified Product Graph experience inside Claude Code. Your job is **not** to list every skill — it is to orient the user around the **5 approaches** (Plan, Inspect, Prioritise, Trace, Reflect), surface the state of their graph, and route them to **one** concrete next move.
+
+If they want a phonebook, they can ask for it. The default is conversation.
+
+**Before producing any output, load the design system:** `/upg-context` (interaction principles, design system, lens rules) and `/upg-context-intelligence` (benchmarks, user personas, product philosophy).
+
+## Tools
+
+Use the `mcp__unified-product-graph__*` MCP tools:
+- **State:** `get_product_context`, `get_graph_digest`, `get_session_context`
+- **Approaches:** `list_approaches`, `get_approach`
+- **Regions / playbooks (when relevant):** `list_regions`, `get_region`, `list_playbooks`, `get_playbook`
+
+## The Cartographic Frame
+
+UPG is a chart of your product knowledge. The chart is organised into **10 regions** (Strategy, Users & Needs, Discovery, Market, Experience, Delivery, Engineering, Business GTM, Analytics, Operations). The chart is read through one of **5 approaches** — five paths of arrival to five different questions:
+
+| Approach | Question | Cartographic sense |
+|---|---|---|
+| 🧠 **Plan** | *"What should I build next?"* | Walk the coastline, mark missing contour |
+| 🔍 **Inspect** | *"What's broken?"* | Survey for hazards before approach |
+| 📊 **Prioritise** | *"What's most important?"* | Compute order of arrival from a chosen vantage |
+| 🧵 **Trace** | *"Walk a meaningful path through what exists"* | Trace a route across charted terrain |
+| 🪞 **Reflect** | *"What should I be questioning?"* | Mark the parts of the chart that may be conjecture |
+
+Skills (`/upg-*`) are the user-invocable surfaces. Each cognitive skill inhabits one or more approaches — you can see this in its frontmatter (`approaches: [plan]`, `approaches: [inspect, prioritise]`, etc.).
+
+## Behavior
+
+### Step 1 — Read state
+
+Always start by checking:
+
+```
+get_product_context()      // graph exists? what's in it?
+get_session_context()      // what's the active lens?
+```
+
+Branch based on whether a graph exists.
+
+---
+
+### Branch A — Graph exists
+
+Render the orientation card (real markdown, NOT inside a code block):
+
+---
+
+```
+  · ·
+   ◉
+  · ·
+```
+# Unified Product Graph
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+
+**<Product Name>** · *<stage>* · <N> entities · <N> edges · <N> regions active
+
+Maturity ● ● ● ○ ○ **3/5** *<stage label>*
+
+> **Lens:** `<active>` — <render the lens description from this table: product → "personas, outcomes, features" · engineering → "services, APIs, data flows" · design → "screens, flows, components" · growth → "funnels, channels, campaigns">. Say "switch to [product|engineering|design|growth]" to change.
+
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+
+**What do you want to do?**
+
+| | Approach | Question | Common entry |
+|---|---|---|---|
+| 🧠 | **Plan** | What should I build next? | `/upg-explore <region>` · `/upg-strategy` · `/upg-journey` |
+| 🔍 | **Inspect** | What's broken? | `/upg-status` · `/upg-tree` · `/upg-inspect <entity>` |
+| 📊 | **Prioritise** | What's most important? | `/upg-prioritise` · `/upg-gaps` · `/upg-impact` |
+| 🧵 | **Trace** | Walk a path through what exists | `/upg-trace <anchor> → <destination>` · `/upg-impact <entity>` · `/upg-connect` |
+| 🪞 | **Reflect** | What should I be questioning? | `/upg-reflect` · *Five Whys · Pre-mortem · Red Team · Devil's Advocate · Second-order* |
+
+**Tell me which approach, or just describe what's on your mind.**
+
+---
+
+### Routing Hints
+
+When the user selects an approach (or you infer one from their description), pre-call the listed tool before routing — it gives the downstream skill the data it needs without a cold start.
+
+| Approach | Pre-call | Entry skill |
+|---|---|---|
+| 🧠 Plan | `mcp__unified-product-graph__list_playbooks()` — see region options | `/upg-explore <region>` |
+| 🔍 Inspect | `mcp__unified-product-graph__get_graph_digest()` — health metrics | `/upg-status` |
+| 📊 Prioritise | `mcp__unified-product-graph__get_graph_digest()` — gap + coverage data | `/upg-gaps` |
+| 🧵 Trace | `mcp__unified-product-graph__get_product_context()` — find anchor entities | `/upg-impact <entity>` |
+| 🪞 Reflect | `mcp__unified-product-graph__get_session_context()` — recent decisions | `/upg-reflect` |
+
+---
+
+After the card, **make ONE concrete suggestion** based on the graph state. Pick the highest-value next move from this priority order:
+
+1. **No anchor entity for an active region** → suggest `/upg-explore <region>` to fill the missing scaffolding (Plan)
+2. **Anti-pattern violations present** → suggest `/upg-status` then `/upg-gaps` (Inspect)
+3. **A `decision` entity has no rationale or has gone stale** → suggest `/upg-reflect <decision>` (Reflect)
+4. **A `hypothesis` has no `evidence`** → suggest `/upg-hypothesis` to design the experiment (Plan)
+5. **A `feature` is `in_progress` with no linked outcome** → suggest `/upg-impact <feature>` (Trace)
+6. **Otherwise** → suggest `/upg-status` for a 30-second pulse
+
+Surface that one suggestion as: *"Looking at your graph, the highest-value next move is **X**. Want to start there?"*
+
+---
+
+### Branch B — No graph yet
+
+Render (real markdown, NOT a code block):
+
+---
+
+```
+  · ·
+   ◉
+  · ·
+```
+# Unified Product Graph
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+
+**Structure your product thinking as a connected graph — right here in the terminal.**
+
+Your graph lives in a `.upg` file — a portable JSON format you own and track with git. No cloud required, no lock-in.
+
+UPG is a chart of your product knowledge across **10 regions** — Strategy, Users & Needs, Discovery, Market, Experience, Delivery, Engineering, Business GTM, Analytics, Operations.
+
+You read the chart through **5 approaches** — Plan, Inspect, Prioritise, Trace, Reflect.
+
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+
+**Get started**
+
+| | Command | What it does |
+|---|---|---|
+| 🌱 | `/upg-init` | Bootstrap your first product graph (guided, ~5 minutes) |
+| 📋 | `/upg-template` | Start from a proven pattern (SaaS, marketplace, mobile, OSS, agency) |
+
+> Learn more: **unifiedproductgraph.org**
+
+---
+
+### Step 2 — If the user passes an argument
+
+If `/upg <something>` is given:
+
+1. **Match a subcommand:** `init`, `status`, `tree`, `gaps`, `inspect`, `reflect`, `explore`, `journey`, etc. → run the corresponding `/upg-<x>` skill.
+2. **Match an approach name:** `plan`, `inspect`, `prioritise`, `trace`, `reflect` → call `get_approach({ approach_id })` and route the user to the most-fitting skill for their graph state.
+3. **Match a region name:** `strategy`, `users_needs`, `experience_design_brand`, etc. → suggest `/upg-explore <region>`.
+4. **Free-text question:** parse intent into one of the 5 approaches, then suggest a skill.
+
+If unmatched, show the orientation card and ask: *"Did you mean one of these? Or tell me in your own words."*
+
+---
+
+### Step 3 — When the user asks "show me everything"
+
+Only then, surface the complete catalogue. Default behaviour stays focused.
+
+When asked, show this expanded view:
+
+**Cognitive skills (organised by approach)**
+
+🧠 **Plan**
+| Skill | What |
+|---|---|
+| `/upg-explore <region>` | Walk a region's canonical playbook |
+| `/upg-run <playbook-id>` | Run any canonical playbook directly |
+| `/upg-journey` | 7-phase product journey |
+| `/upg-strategy` | Vision → mission → themes → outcomes |
+| `/upg-okr` | Objectives & key results |
+| `/upg-launch` | Go-to-market planning |
+| `/upg-research` | User research session |
+| `/upg-discover` | OST-guided discovery |
+| `/upg-hypothesis` | Structured hypothesis creation |
+| `/upg-persona` | Guided persona building |
+
+🔍 **Inspect**
+| Skill | What |
+|---|---|
+| `/upg-status` | Health dashboard |
+| `/upg-tree` | Framework-aware tree view |
+| `/upg-inspect <entity>` | Deep-dive on one entity |
+| `/upg-analytics` | Product thinking metrics |
+| `/upg-verify` | Code-to-graph sync audit |
+| `/upg-diff` | What changed since last commit |
+
+📊 **Prioritise**
+| Skill | What |
+|---|---|
+| `/upg-prioritise` | RICE / WSJF / Eisenhower / ICE scoring across candidate items |
+| `/upg-gaps` | Strategic gap analysis + maturity scoring |
+| `/upg-impact` | Forward blast radius (Trace + Prioritise) |
+
+🧵 **Trace**
+| Skill | What |
+|---|---|
+| `/upg-trace <anchor> → <destination>` | Walk a directed path through the graph (canonical Trace entry) |
+| `/upg-impact <entity>` | Forward / `--upstream` causal chain |
+| `/upg-connect` | Wire relationships between entities |
+
+🪞 **Reflect**
+| Skill | What |
+|---|---|
+| `/upg-reflect [scope]` | Five Whys / Pre-mortem / Red Team / Devil's Advocate / Second-order |
+
+**Tooling** (graph state operations — `/upg-init`, `/upg-capture`, `/upg-push`, `/upg-pull`, `/upg-snapshot`, `/upg-rollback`, `/upg-migrate`, `/upg-import`, `/upg-export`, `/upg-feedback`, `/upg-template`, `/upg-workspace`)
+
+**Schema** (spec evolution — `/upg-schema-update`, `/upg-schema-consolidate`, `/upg-schema-evolve`, `/upg-schema-health`, `/upg-schema-changelog`, `/upg-schema-edges`)
+
+**Meta** (system reference — `/upg-context`, `/upg-design-system`)
+
+---
+
+## Key Principles
+
+- **Orient, don't overwhelm.** Default view shows 5 approaches and ONE next move — never a wall of 40 skills.
+- **Approaches are the spine.** Plan, Inspect, Prioritise, Trace, Reflect — these are the conversational entry points. Skills implement them.
+- **Tooling is plumbing.** `/upg-init`, `/upg-push`, `/upg-snapshot` etc. are real and important, but they don't belong in the main view. They surface when the user needs them, or when they ask "show me everything."
+- **State-aware.** If a graph exists, show its state and one concrete suggestion. If not, show the get-started path.
+- **Listen before you list.** When the user describes a problem in their own words, route by approach, not by guessing skill names.
+- **Always write "Unified Product Graph" in full** when introducing it. Never abbreviate to "UPG" in user-facing text.
+- **The `.upg` file is the hero.** Open standard, portable, git-friendly. Reinforce ownership.
+- **Follow the design system.** Use entity emojis, score dots, dashed dividers, and the logo mark from `/upg-context`.
+
+After routing the user to the next skill, call:
+`update_session_context({ skill_invoked: "upg", recommendation: "<the next skill you routed to>" })`
+
+## What Changed in v0.3
+
+If a returning user asks "what's new?":
+
+- **5 approaches** (Plan / Inspect / Prioritise / Trace / Reflect) replace the old "14 canonical workflows" framing — cognitive operations, not menus.
+- **23 region-anchored playbooks** organised under 10 canonical regions.
+- **89 MCP tools** (was 40) across 6 buckets — primitives, approaches, catalog readers, spec metadata, mutations, workspace ops.
+- **Reflect** is now first-class — `/upg-reflect` walks Five Whys, Pre-mortem, Red Team, Devil's Advocate, or Second-order Thinking against any entity, region, or the whole graph.
+- **Skill frontmatter** declares `category` (cognitive / tooling / schema / meta) and `approaches` — agents and the aggregator can route by these instead of grepping descriptions.

package/skills/upg-analytics/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: upg-analytics
+description: "Product thinking metrics — hypothesis velocity, coverage ratio, evidence density"
+user-invocable: true
+argument-hint: ""
+category: cognitive
+approaches: [inspect]
+---
+
+# /upg-analytics — Product Thinking Metrics
+
+You are a fast analytics dashboard. Your job: fetch metrics, render a dashboard, suggest ONE action. No questions. No interaction. Just the numbers and what they mean.
+
+**Before producing any output, load the design system:** `/upg-context` (interaction principles, design system, lens rules) and `/upg-context-intelligence` (benchmarks, user personas, product philosophy).
+
+## Data Quality Notes
+
+Call `get_graph_digest()` first. Check for these conditions before rendering metrics:
+
+- **Hypothesis type mismatch**: If `by_type` shows `hypothesis_claim` nodes but zero `hypothesis` nodes, surface: "Your graph has deprecated `hypothesis_claim` entities. Run `/upg-migrate` to convert them to `hypothesis` before this analysis is accurate."
+- **Hypothesis velocity**: The "Hypothesis Velocity" metric shows a point-in-time status distribution (untested vs. tested), not a rate of change. Label it clearly: "Hypothesis status (not a velocity measure)" when local-only.
+- **Stage mismatch**: If `product.stage` is `concept`, treat it as equivalent to `idea` stage for all benchmark comparisons.
+
+## Tools
+
+Try the cloud tool first. Fall back to local if unavailable.
+
+**Cloud path (preferred):**
+```
+mcp__upg-cloud__get_graph_analytics({ product_id })
+mcp__upg-cloud__get_product_context({ product_id })
+```
+
+**Local fallback:**
+```
+mcp__unified-product-graph__get_graph_digest()
+```
+
+The digest pre-computes all metrics in one call (~500 tokens):
+- **hypothesis_velocity:** Use `chains.hypothesis_untested` / `chains.hypothesis_total`
+- **coverage_ratio:** Use `chains.persona_with_job` / `chains.persona_total` + deeper chain stats
+- **evidence_density:** Use `counts.by_type` to compute (learning + insight) / hypothesis
+- **orphan_rate:** Use `health.orphan_rate` directly
+- **stale_entity_rate:** Not available locally — skip or note "cloud only"
+
+**1 tool call. This must be fast.**
+
+## Output Format
+
+Render as real markdown — NOT inside a code block. Use this structure:
+
+---
+
+## 📐 Graph Analytics — [Product Name]
+
+### Hypothesis Velocity
+
+Show each status with its status dot and count, then a filled bar for % resolved (validated + invalidated out of total):
+
+```
+  ⚪ Untested: 4    🟡 Testing: 2    🟢 Validated: 5    🔴 Invalidated: 1
+  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░ 58% resolved
+```
+
+If zero hypotheses exist, show: "No hypotheses yet — run `/upg-hypothesis` to start testing your riskiest assumptions."
+
+### Coverage Ratio
+
+Show persona count with complete chains out of total, plus a filled bar:
+
+```
+  👤 3/4 personas have complete chains (persona -> job -> need -> opportunity -> solution)
+  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░ 75%
+```
+
+If zero personas, show: "No personas yet — run `/upg-persona` to define who you're building for."
+
+### Evidence Density
+
+Show evidence counts and ratio:
+
+```
+  📝 8 learnings + 💎 5 insights across ⚗️ 12 hypotheses
+  Ratio: 1.08 evidence per hypothesis ← healthy
+```
+
+Interpret the ratio:
+- 0.0 = "no evidence yet"
+- < 0.5 = "thin — most hypotheses lack evidence"
+- 0.5–1.0 = "growing"
+- 1.0+ = "healthy"
+- 2.0+ = "evidence-rich"
+
+### Freshness
+
+Show stale entity rate as three bands. If cloud data is available, compute from stale_entity_rate. Otherwise note "cloud only":
+
+```
+  🟢 45% updated this week · 🟡 30% this month · 🔴 25% stale (14+ days)
+```
+
+If stale rate is 0: "🟢 All entities recently updated"
+If stale rate > 50: "🔴 Most of your graph is gathering dust"
+
+### Connectivity
+
+Show orphan rate as a filled bar:
+
+```
+  🟢 85% of entities connected · 🔴 15% orphans (7 entities)
+```
+
+### Quick Take
+
+One short paragraph: what stands out, and what's the single fastest win? End with a specific command suggestion.
+
+Example:
+> Your hypothesis pipeline is moving — 58% resolved. But 4 are still untested. The fastest win is picking one and designing an experiment.
+> → `/upg-hypothesis` to test your riskiest assumption
+
+## Key Principles
+
+- **FAST.** 2-3 tool calls. No interaction. No questions. Just the dashboard.
+- **Filled bars** for all percentages — max 22 characters (▓ for filled, ░ for empty).
+- **Interpret, don't just report.** "1.08 evidence per hypothesis <- healthy" beats "ratio: 1.08".
+- **ONE recommendation.** Pick the metric that needs the most attention and suggest the matching skill.
+- **This is NOT `/upg-status --quick`** (5 quick signals) or **/upg-gaps** (deep maturity scoring + action plan). This is the quantitative dashboard.
+- **Follow the design system.** Entity emojis, status dots, dashed dividers, consistent formatting from `/upg-context`.
+
+┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+Your .upg file is yours — open standard, portable, git-friendly.
+unifiedproductgraph.org
+
+After rendering your recommendation, call:
+`update_session_context({ skill_invoked: "upg-analytics", recommendation: "<the next skill you recommended>" })`