# Product Grid Context > Use when working in or around a Product Grid Management project and you need project, node, image, or graph context through the pgm CLI. This skill helps agents query context from a running Product Grid server without scraping the UI. - Skill: `byronwall/product-grid-context` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add byronwall/product-grid-context` - Raw SKILL.md: https://api.skillmd.com/api/skills/byronwall/product-grid-context/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: byronwall (https://skillmd.com/u/byronwall) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/byronwall/product-grid-context --- # Product Grid Context Use the `pgm` CLI to inspect and update Product Grid projects before changing code or answering project-specific questions. ## URL Fast Path If the user provides a Product Grid URL with `project=...` and `node=...`, do not start with broad discovery. Resolve the issue context directly: ```bash pgm issue view '' --json ``` If `pgm issue view` is not available, use the IDs from the URL: ```bash pgm node view --project --with-context --compact --json ``` After implementation, prefer a compact status update: ```bash pgm node resolve --project --status implemented --note "What changed." --json ``` ## Install Install the CLI from npm when `pgm` is not already available: ```bash npm install -g @byronwallrus/product-grid-cli ``` Install this skill for Codex globally: ```bash pgm skill install --agent codex --global ``` Install this skill into the current project: ```bash pgm skill install --agent codex ``` Inspect the bundled skill: ```bash pgm skill path pgm skill print ``` ## First Checks Check whether `pgm` is configured: ```bash pgm auth status --json pgm project current --json ``` If no project is linked, list projects: ```bash pgm project list --json ``` When the user identifies a project, link it: ```bash pgm project link ``` If the user asks to start a new product grid, create and link a project: ```bash pgm project create "Product Site" --link --json ``` Use `projectId` or `project.id` from the JSON response in subsequent commands. After selecting a project, inspect the compact schema early so you know the available statuses, node types, and metadata fields: ```bash pgm project schema --json ``` ## Gather Context Start small. Do not begin by dumping the full project into context. Recommended first pass: ```bash pgm project schema --json pgm node list --roots --compact --preset tree --json pgm node list --status planned --type task --with-ancestors --preset status --json pgm node list --search "checkout" --preset compact --json ``` Use `--with-ancestors` when a node title is terse; it returns the root-to-leaf path without pulling every node's full body. When a specific node looks relevant, pull the inherited context projection: ```bash pgm node view --with-context --compact --json ``` For implementation handoff or deeper work, export only that node context: ```bash pgm node export-context --output ./tmp/node-context.md ``` When you need a parent node plus all descendant context, metadata, and image files in one local bundle, export a context pack: ```bash pgm node context-pack --output ./tmp/context-pack --json ``` Use filters before expanding context: ```bash pgm node list --status working --with-ancestors --preset status --json pgm node list --type task --search "layout" --with-context --compact --json pgm node list --status blocked --preset status --json pgm node list --type page --preset compact --json ``` Avoid `pgm project view --json` as a default first step. It returns the full graph, all links, metadata, context, and images, which can be very large and usually wastes context. Use it only when you explicitly need the complete project record. Use `pgm project export-markdown` when another process needs broad project context, but prefer node context exports for ordinary implementation work. ## Hierarchical Node Context Product Grid hierarchy carries requirements. Parent nodes often contain the product area, constraints, and shared intent; leaf nodes may intentionally be short. Prefer commands that preserve this hierarchy: ```bash pgm node list --with-ancestors --preset status --json pgm node list --with-context --compact --json pgm node view --with-context --compact --json pgm node export-context --output ./tmp/node-context.md pgm node context-pack --output ./tmp/context-pack --json ``` When reading node context, respect provenance: - Use `path` / `titlePath` to understand the node's product area. - Treat parent metadata/context/images as inherited requirements, not as text owned by the leaf node. - Check `inheritedContext.hasDirectContext`, `hasInheritedContext`, and `missingContext` before deciding whether to implement or ask for clarification. - If `missingContext` is true, inspect nearby siblings with `pgm node list --search ... --with-ancestors --json` instead of falling back to full project JSON. ## Create Context Nodes From Markdown Use `node import-markdown` when the user wants a markdown document, LLM-generated brief, or research note captured in the product grid. Create one context node: ```bash pgm node import-markdown --file ./brief.md --title "Product Brief" --json ``` Split markdown headings into a parent-child node hierarchy: ```bash pgm node import-markdown --file ./brief.md --title "Product Brief" --split-headings --max-heading-depth 2 --json ``` The JSON response includes: - `import.rootNodeId` - `import.createdNodeIds` - `import.createdNodeCount` - `nodes` - `links` Use those returned IDs directly in the next step instead of re-discovering them by search. Add metadata at import time when useful: ```bash pgm node import-markdown --file ./brief.md --title "Product Brief" --metadata-json '{"purpose":"Imported source context"}' --json ``` ## Create And Update Product Nodes Use `node create` for normal product structure nodes such as pages, regions, components, states, and implementation themes. ```bash pgm node create --title "Checkout" --type page --parent --json pgm node create --title "Payment Form" --type component --parent --context-file ./payment-form.md --metadata-json '{"purpose":"Collects payment details"}' --json ``` Use the returned `nodeId` or `node.id` immediately in later commands. Update existing nodes when the agent learns more: ```bash pgm node update --title "Checkout" --status working --type page --json pgm node complete --note "Implemented the requested change." --json pgm node context set --file ./context.md --json pgm node metadata set purpose "Checkout entry point" --json pgm node metadata unset purpose --json pgm node move --parent --json pgm node move --root --json ``` ## Attach Images To Nodes Use `image add` when the agent creates screenshots or local image artifacts, such as Playwright screenshots, and needs to attach them to specific nodes. ```bash pgm image add ./screenshots/home-desktop.png ./screenshots/home-mobile.png --json pgm image list --json pgm image remove --json ``` The JSON response includes the stored image IDs and URLs. Prefer attaching screenshots to the most specific matching node. ## Export Project Markdown Use `project export-markdown` only before broad edits or when another LLM process needs compact whole-project context. For scoped work, prefer `node export-context`. ```bash pgm project export-markdown --output ./project-context.md pgm node export-context --output ./node-context.md pgm node context-pack --output ./context-pack-dir --json ``` ## Rules - Prefer `--json` for parsing. - Prefer targeted list/search/context commands over `pgm project view --json`. - Do not scrape the browser UI when `pgm` can provide the data. - Do not mutate project data unless the user explicitly asks. - Before creating nodes or adding images, inspect the project and choose the target project/node deliberately. - After `project create`, keep using the returned `projectId`; if `--link` was passed, the CLI is already linked to it. - After `node create`, keep using the returned `nodeId`. - After `node import-markdown`, keep using the returned node IDs. - After `image add`, keep using the returned image IDs/URLs. - If `pgm` cannot reach the server, ask whether the Product Grid server is running. - The default local server is `http://localhost:3000`. - Use `--server ` when the project is not on the default server. - Use `--project ` when no project is linked. ## Useful Commands ```bash pgm project list --json pgm project create "Product Site" --link --json pgm project link pgm project schema --project --json pgm node list --project --json pgm node list --project --roots --compact --json pgm node view --project --with-context --json pgm node create --project --title "Checkout" --type page --json pgm node update --project --status working --json pgm node complete --project --note "Implemented the requested change." --json pgm node context set --project --file ./context.md --json pgm node metadata set purpose "Purpose text" --project --json pgm node move --project --parent --json pgm node import-markdown --project --file ./brief.md --title "Brief" --split-headings --json pgm image add ./screenshot.png --project --json pgm image list --project --json pgm image remove --project --json pgm node list --project --search "checkout" --with-ancestors --json pgm node export-context --project --output ./node-context.md pgm project export-markdown --project --output ./project-context.md ```