@mediadatafusion/pi-workflow-suite 0.0.1

package/scripts/bootstrap-project.sh

@@ -0,0 +1,220 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+APPLY=0
+ALLOW_HOME=0
+CREATE_WORKFLOW_SETTINGS=1
+CREATE_APPEND_SYSTEM=1
+UPDATE_GITIGNORE=1
+PACKAGE_SOURCE=""
+PRESET=""
+WORKFLOW_THEME=""
+TARGET=""
+
+usage() {
+  cat <<'USAGE'
+Usage: ./scripts/bootstrap-project.sh <project-dir> [options]
+
+Dry-run by default. Creates a project Workflow Suite scaffold only with --apply.
+Does not modify the live ~/.pi/agent runtime.
+
+Options:
+  --apply                         Write files. Default is dry-run.
+  --allow-home                    Allow targeting $HOME explicitly.
+  --no-workflow-settings          Do not create .pi/workflow-settings.json.
+  --no-append-system              Do not create .pi/APPEND_SYSTEM.md.
+  --no-gitignore                  Do not append project .gitignore runtime exclusions.
+  --package-source <source>       Also create .pi/settings.json with a Pi package reference.
+                                  Example after publish: npm:@mediadatafusion/pi-workflow-suite
+  --preset <name>                 Set presets.activePreset in copied workflow settings.
+  --workflow-theme <name>         Set ui.workflowTheme in copied workflow settings.
+  -h, --help                      Show help.
+
+Current behavior note:
+  Workflow Suite settings are global/project scoped, not session-local. Project
+  .pi/workflow-settings.json affects sessions launched under that project scope.
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --apply) APPLY=1; shift ;;
+    --allow-home) ALLOW_HOME=1; shift ;;
+    --no-workflow-settings) CREATE_WORKFLOW_SETTINGS=0; shift ;;
+    --no-append-system) CREATE_APPEND_SYSTEM=0; shift ;;
+    --no-gitignore) UPDATE_GITIGNORE=0; shift ;;
+    --package-source)
+      [[ $# -ge 2 ]] || { printf 'ERROR: --package-source needs a value\n' >&2; exit 2; }
+      PACKAGE_SOURCE="$2"; shift 2 ;;
+    --preset)
+      [[ $# -ge 2 ]] || { printf 'ERROR: --preset needs a value\n' >&2; exit 2; }
+      PRESET="$2"; shift 2 ;;
+    --workflow-theme)
+      [[ $# -ge 2 ]] || { printf 'ERROR: --workflow-theme needs a value\n' >&2; exit 2; }
+      WORKFLOW_THEME="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    --*) printf 'ERROR: unknown option: %s\n' "$1" >&2; usage >&2; exit 2 ;;
+    *)
+      if [[ -n "$TARGET" ]]; then
+        printf 'ERROR: multiple project directories provided: %s and %s\n' "$TARGET" "$1" >&2
+        exit 2
+      fi
+      TARGET="$1"; shift ;;
+  esac
+done
+
+if [[ -z "$TARGET" ]]; then
+  usage >&2
+  exit 2
+fi
+
+if [[ ! -d "$TARGET" ]]; then
+  printf 'ERROR: project directory does not exist: %s\n' "$TARGET" >&2
+  exit 2
+fi
+
+TARGET="$(cd "$TARGET" && pwd -P)"
+HOME_REAL="$(cd "$HOME" && pwd -P)"
+if [[ "$TARGET" == "$HOME_REAL" && "$ALLOW_HOME" -ne 1 ]]; then
+  printf 'ERROR: refusing to target HOME without --allow-home: %s\n' "$TARGET" >&2
+  printf 'This avoids confusing home-directory project settings with global ~/.pi/agent state.\n' >&2
+  exit 2
+fi
+
+PI_DIR="$TARGET/.pi"
+WORKFLOW_FILE="$PI_DIR/workflow-settings.json"
+APPEND_SYSTEM_FILE="$PI_DIR/APPEND_SYSTEM.md"
+PROJECT_SETTINGS_FILE="$PI_DIR/settings.json"
+GITIGNORE_FILE="$TARGET/.gitignore"
+EXAMPLE_WORKFLOW="$REPO_DIR/config/workflow-settings.example.json"
+
+printf 'Pi Workflow Suite project bootstrap\n'
+printf 'Mode: %s\n' "$([[ "$APPLY" -eq 1 ]] && printf apply || printf dry-run)"
+printf 'Project: %s\n' "$TARGET"
+printf '\n'
+printf 'Current scope behavior:\n'
+printf '  Pi core project settings: exact cwd .pi/settings.json\n'
+printf '  Workflow Suite project settings: nearest upward .pi/workflow-settings.json\n'
+printf '  Workflow Suite settings are not session-local today.\n'
+printf '\n'
+
+planned=0
+
+plan_line() {
+  printf '%s\n' "$1"
+  planned=1
+}
+
+if [[ "$CREATE_WORKFLOW_SETTINGS" -eq 1 ]]; then
+  if [[ -e "$WORKFLOW_FILE" ]]; then
+    printf 'exists, skip: %s\n' "$WORKFLOW_FILE"
+  else
+    plan_line "create: $WORKFLOW_FILE"
+  fi
+fi
+
+if [[ "$CREATE_APPEND_SYSTEM" -eq 1 ]]; then
+  if [[ -e "$APPEND_SYSTEM_FILE" ]]; then
+    printf 'exists, skip: %s\n' "$APPEND_SYSTEM_FILE"
+  else
+    plan_line "create: $APPEND_SYSTEM_FILE"
+  fi
+fi
+
+if [[ "$UPDATE_GITIGNORE" -eq 1 ]]; then
+  plan_line "ensure runtime exclusions in: $GITIGNORE_FILE"
+fi
+
+if [[ -n "$PACKAGE_SOURCE" ]]; then
+  if [[ -e "$PROJECT_SETTINGS_FILE" ]]; then
+    printf 'exists, skip package reference: %s\n' "$PROJECT_SETTINGS_FILE"
+    printf '  Review and edit existing project Pi settings manually if needed.\n'
+  else
+    plan_line "create package reference: $PROJECT_SETTINGS_FILE -> $PACKAGE_SOURCE"
+  fi
+fi
+
+if [[ "$planned" -eq 0 ]]; then
+  printf 'No changes needed.\n'
+fi
+
+if [[ "$APPLY" -ne 1 ]]; then
+  printf '\nDry run only. Re-run with --apply to write files.\n'
+  exit 0
+fi
+
+mkdir -p "$PI_DIR"
+
+if [[ "$CREATE_WORKFLOW_SETTINGS" -eq 1 && ! -e "$WORKFLOW_FILE" ]]; then
+  if [[ ! -f "$EXAMPLE_WORKFLOW" ]]; then
+    printf 'ERROR: missing example workflow settings: %s\n' "$EXAMPLE_WORKFLOW" >&2
+    exit 1
+  fi
+  cp "$EXAMPLE_WORKFLOW" "$WORKFLOW_FILE"
+  if [[ -n "$PRESET" || -n "$WORKFLOW_THEME" ]]; then
+    node - "$WORKFLOW_FILE" "$PRESET" "$WORKFLOW_THEME" <<'NODE'
+const fs = require('fs');
+const file = process.argv[2];
+const preset = process.argv[3];
+const workflowTheme = process.argv[4];
+const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+if (preset) {
+  data.presets = data.presets || {};
+  data.presets.activePreset = preset;
+}
+if (workflowTheme) {
+  data.ui = data.ui || {};
+  data.ui.workflowTheme = workflowTheme;
+}
+fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n');
+NODE
+  fi
+  printf 'created: %s\n' "$WORKFLOW_FILE"
+fi
+
+if [[ "$CREATE_APPEND_SYSTEM" -eq 1 && ! -e "$APPEND_SYSTEM_FILE" ]]; then
+  cat > "$APPEND_SYSTEM_FILE" <<'EOF'
+# Project Workflow Guidance
+
+This project may use Pi Workflow Suite for approval-gated planning, execution, validation, and mission workflows.
+
+- Prefer `/p <task>` for scoped implementation work.
+- Use `/workflow-settings scope` to verify whether project workflow settings are active.
+- Treat project `AGENTS.md` as the main source of project rules and commands.
+- Do not assume Workflow Suite settings are session-local; project `.pi/workflow-settings.json` applies to sessions launched under this project scope.
+EOF
+  printf 'created: %s\n' "$APPEND_SYSTEM_FILE"
+fi
+
+if [[ "$UPDATE_GITIGNORE" -eq 1 ]]; then
+  touch "$GITIGNORE_FILE"
+  if ! grep -qF '# Pi Workflow Suite runtime state' "$GITIGNORE_FILE"; then
+    cat >> "$GITIGNORE_FILE" <<'EOF'
+
+# Pi Workflow Suite runtime state
+.pi/sessions/
+.pi/workflows/
+.pi/npm/
+.pi/git/
+.pi/*.tmp-*
+EOF
+    printf 'updated: %s\n' "$GITIGNORE_FILE"
+  else
+    printf 'already has Pi Workflow Suite runtime block: %s\n' "$GITIGNORE_FILE"
+  fi
+fi
+
+if [[ -n "$PACKAGE_SOURCE" && ! -e "$PROJECT_SETTINGS_FILE" ]]; then
+  node - "$PROJECT_SETTINGS_FILE" "$PACKAGE_SOURCE" <<'NODE'
+const fs = require('fs');
+const file = process.argv[2];
+const source = process.argv[3];
+const data = { packages: [source] };
+fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n');
+NODE
+  printf 'created: %s\n' "$PROJECT_SETTINGS_FILE"
+fi
+
+printf '\nBootstrap complete. Verify with:\n'
+printf '  %s/scripts/audit-settings.sh %s\n' "$REPO_DIR" "$TARGET"

package/scripts/install-to-live.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+LIVE_DIR="${PI_AGENT_DIR:-$HOME/.pi/agent}"
+
+printf 'Installing from repo mirror into live Pi runtime ~/.pi/agent.\n'
+printf 'Repo mirror: %s\n' "$REPO_DIR"
+printf 'Live runtime: %s\n' "$LIVE_DIR"
+printf 'A live backup will be created before installing files.\n'
+
+"$REPO_DIR/scripts/backup-live.sh"
+
+is_forbidden_path() {
+  local rel="$1"
+  case "$rel" in
+    auth.json|settings.json|workflow-settings.json|active.json|workflows/*|missions/*|plans/*|sessions/*|logs/*|*.log|*.backup.*|*.broken.*|.env|.env.*|.factory/*|.cursor/*|*.DS_Store|*.tmp)
+      return 0
+      ;;
+  esac
+  return 1
+}
+
+validate_source_file() {
+  local file="$1"
+  case "$file" in
+    *.json) python3 -m json.tool "$file" >/dev/null ;;
+    *.ts|*.md|*.sh) test -s "$file" ;;
+    *) test -f "$file" ;;
+  esac
+}
+
+atomic_install_file() {
+  local rel="$1"
+  if is_forbidden_path "$rel"; then
+    printf 'refusing forbidden install path: %s\n' "$rel" >&2
+    exit 1
+  fi
+  local src="$REPO_DIR/$rel"
+  local dst="$LIVE_DIR/$rel"
+  if [[ ! -f "$src" ]]; then
+    printf 'missing repo file: %s\n' "$src" >&2
+    exit 1
+  fi
+  validate_source_file "$src"
+  mkdir -p "$(dirname "$dst")"
+  local tmp="$dst.tmp-$$-$(date +%s%N)"
+  install -m 0644 "$src" "$tmp"
+  validate_source_file "$tmp"
+  mv -f "$tmp" "$dst"
+  printf 'installed atomically: %s -> %s\n' "$src" "$dst"
+}
+
+install_dir() {
+  local rel="$1"
+  local src_root="$REPO_DIR/$rel"
+  if [[ ! -d "$src_root" ]]; then
+    printf 'skipping missing optional repo directory: %s\n' "$src_root"
+    return 0
+  fi
+  if find "$src_root" -type l | grep -q .; then
+    printf 'refusing to install symlinks from repo directory: %s\n' "$src_root" >&2
+    exit 1
+  fi
+  while IFS= read -r -d '' file; do
+    local sub="${file#$REPO_DIR/}"
+    if is_forbidden_path "$sub"; then
+      continue
+    fi
+    atomic_install_file "$sub"
+  done < <(find "$src_root" -type f \
+    ! -name '.DS_Store' \
+    ! -name '*.log' \
+    ! -name '*.tmp' \
+    ! -name '*.backup.*' \
+    ! -name '*.broken.*' \
+    -print0)
+}
+
+atomic_install_file "package.json"
+atomic_install_file "package-lock.json"
+install_dir "extensions"
+install_dir "agents"
+install_dir "skills"
+install_dir "config"
+
+printf 'install complete; auth, settings, and workflow state were not touched\n'

package/scripts/quarantine-live-junk.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+LIVE_DIR="${PI_AGENT_DIR:-$HOME/.pi/agent}"
+BACKUP_BASE="${PI_BACKUP_DIR:-$HOME/.pi/agent-emergency-backups}"
+TS="$(date +%Y%m%d-%H%M%S)"
+DEST="$BACKUP_BASE/live-junk-quarantine-$TS"
+APPLY=0
+
+if [[ "${1:-}" == "--apply" ]]; then
+  APPLY=1
+elif [[ "${1:-}" == "" ]]; then
+  APPLY=0
+else
+  printf 'usage: %s [--apply]\n' "$0" >&2
+  exit 2
+fi
+
+printf 'Pi Workflow Suite live junk quarantine\n'
+printf 'Live runtime: %s\n' "$LIVE_DIR"
+printf 'Quarantine destination: %s\n' "$DEST"
+if [[ "$APPLY" -eq 0 ]]; then
+  printf 'Mode: dry run. Re-run with --apply to move files.\n'
+else
+  printf 'Mode: apply. Files will be moved, not deleted.\n'
+  mkdir -p "$DEST"
+fi
+
+move_rel() {
+  local rel="$1"
+  local src="$LIVE_DIR/$rel"
+  local dst="$DEST/$rel"
+  [[ -e "$src" ]] || return 0
+  if [[ "$APPLY" -eq 0 ]]; then
+    printf 'would quarantine: %s\n' "$rel"
+    return 0
+  fi
+  mkdir -p "$(dirname "$dst")"
+  mv "$src" "$dst"
+  printf 'quarantined: %s\n' "$rel"
+}
+
+# Stale Git metadata in the live runtime is not required by Pi and should not be
+# mixed with auth, settings, sessions, or workflow state.
+move_rel ".git"
+
+# Only move backup/broken/log/Finder debris. Do not move current auth/settings,
+# current workflow state, session JSONL files, mission files, or plan files.
+while IFS= read -r -d '' path; do
+  rel="${path#$LIVE_DIR/}"
+  case "$rel" in
+    auth.json|settings.json|workflow-settings.json|sessions/*.jsonl|workflows/missions/*|workflows/plans/*)
+      continue
+      ;;
+  esac
+  move_rel "$rel"
+done < <(find "$LIVE_DIR" -maxdepth 3 \( -name '*.backup.*' -o -name '*.broken.*' -o -name '.DS_Store' -o -name '*.log' \) -print0 2>/dev/null)
+
+# Known stale/development directories from earlier manual repair flows. These are
+# quarantined whole only when present. Review the dry-run output first.
+for rel in recovery-snapshots extensions-disabled prompts.disabled docs; do
+  move_rel "$rel"
+done
+
+if [[ "$APPLY" -eq 0 ]]; then
+  printf 'Dry run complete; no files moved.\n'
+else
+  printf 'Quarantine complete: %s\n' "$DEST"
+fi

package/scripts/verify-live.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+LIVE_DIR="${PI_AGENT_DIR:-$HOME/.pi/agent}"
+printf 'This verifies the local live Pi runtime. GitHub Actions cannot perform this check.\n'
+printf 'Live runtime: %s\n' "$LIVE_DIR"
+missing=0
+warning=0
+
+require_file() {
+  local rel="$1"
+  if [[ -f "$LIVE_DIR/$rel" ]]; then
+    printf 'found: %s\n' "$LIVE_DIR/$rel"
+  else
+    printf 'missing: %s\n' "$LIVE_DIR/$rel" >&2
+    missing=1
+  fi
+}
+
+warn_path() {
+  local rel="$1"
+  local message="$2"
+  if [[ -e "$LIVE_DIR/$rel" ]]; then
+    printf 'warning: %s (%s)\n' "$message" "$LIVE_DIR/$rel" >&2
+    warning=1
+  fi
+}
+
+warn_stale_files() {
+  local stale
+  stale="$(find "$LIVE_DIR" -maxdepth 3 \( -name '*.backup.*' -o -name '*.broken.*' -o -name '.DS_Store' -o -name '*.log' \) -print 2>/dev/null | sort || true)"
+  if [[ -n "$stale" ]]; then
+    printf 'warning: stale/noisy files found in live runtime; run scripts/audit-live.sh for details\n' >&2
+    warning=1
+  fi
+}
+
+warn_unexpected_loadable_extensions() {
+  local expected actual unexpected
+  expected="$(cat <<'TEXT'
+extensions/subagent/index.ts
+extensions/workflow-model-router.ts
+extensions/workflow-modes.ts
+extensions/workflow-state.ts
+extensions/workflow-summary.ts
+extensions/workflow-tool-guard.ts
+TEXT
+)"
+  actual="$(
+    {
+      find "$LIVE_DIR/extensions" -maxdepth 1 \( -name '*.ts' -o -name '*.js' \) -type f -print 2>/dev/null || true
+      find "$LIVE_DIR/extensions" -mindepth 2 -maxdepth 2 \( -name 'index.ts' -o -name 'index.js' \) -type f -print 2>/dev/null || true
+    } | sed "s#^$LIVE_DIR/##" | sort
+  )"
+  unexpected="$(comm -13 <(printf '%s\n' "$expected" | sort) <(printf '%s\n' "$actual" | sort) || true)"
+  if [[ -n "$unexpected" ]]; then
+    printf 'warning: unexpected loadable extension candidates found:\n%s\n' "$unexpected" >&2
+    warning=1
+  fi
+}
+
+require_file "extensions/workflow-modes.ts"
+require_file "extensions/workflow-state.ts"
+require_file "extensions/workflow-summary.ts"
+require_file "extensions/workflow-tool-guard.ts"
+require_file "extensions/workflow-model-router.ts"
+require_file "extensions/subagent/index.ts"
+require_file "extensions/subagent/agents.ts"
+
+require_file "agents/codebase-research.md"
+require_file "agents/general-worker.md"
+require_file "agents/implementation-planning.md"
+require_file "agents/quality-validation.md"
+require_file "agents/workflow-orchestrator.md"
+
+require_file "skills/codebase-discovery/SKILL.md"
+require_file "skills/find-skills/SKILL.md"
+require_file "skills/git-safe-summary/SKILL.md"
+require_file "skills/implementation-planning/SKILL.md"
+require_file "skills/project-rules-audit/SKILL.md"
+require_file "skills/safe-execution/SKILL.md"
+require_file "skills/validation-review/SKILL.md"
+
+require_file "config/prompts/execute-approved-plan.md"
+require_file "config/prompts/validate-approved-plan.md"
+require_file "config/prompts/workflow-plan-prompt.md"
+require_file "config/prompts/workflow-summary.md"
+require_file "config/prompts/workflow-repair.md"
+require_file "config/prompts/mission-plan.md"
+require_file "config/prompts/mission-run.md"
+require_file "config/prompts/mission-repair.md"
+require_file "config/prompts/mission-checkpoint.md"
+require_file "config/prompts/mission-final-validation.md"
+
+require_file "config/workflow-settings.example.json"
+
+warn_path ".git" "top-level .git should not be inside the live Pi runtime"
+warn_path "recovery-snapshots" "stale recovery snapshot directory should be quarantined outside active runtime"
+warn_path "extensions-disabled" "disabled extension directory should be reviewed/quarantined outside active runtime"
+warn_path "prompts.disabled" "disabled prompt directory should be reviewed/quarantined outside active runtime"
+warn_path "docs" "repo docs should not be mixed into active live runtime unless intentionally used"
+warn_stale_files
+warn_unexpected_loadable_extensions
+
+if [[ "$missing" -ne 0 ]]; then
+  exit 1
+fi
+
+if [[ "$warning" -ne 0 ]]; then
+  printf 'live runtime warnings detected; required files are present, but cleanup/audit is recommended\n' >&2
+fi
+
+printf '\nRunning basic Pi load check: pi --help\n'
+pi --help >/dev/null
+printf 'basic load check passed\n'
+
+cat <<'TEXT'
+
+Manual runtime tests still required:
+- pi
+- /workflow status
+- /workflow settings Show Current Settings
+- /p
+- /p <task>
+- approval action
+
+Note: pi --help is only a basic load check, not full workflow verification.
+TEXT

package/skills/codebase-discovery/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: codebase-discovery
+description: Inspect project structure, frameworks, package managers, entry points, configs, and architecture before implementation planning. Use when planning requires understanding an unfamiliar codebase.
+---
+
+# Codebase Discovery
+
+Use read-only inspection only. Identify package manager, framework, entry points, key configs, tests, build scripts, and relevant existing patterns. Summarize findings before proposing changes.
+
+Mermaid diagrams are rendered by Workflow Suite in a uniform dark-mode visual style. For user-facing workflows, export/share paths, request lifecycles, architecture, data flow, multi-step sequences, state transitions, dependencies, validation flow, or implementation phases, include a meaningful Mermaid diagram plus concise prose unless the user requested prose only or the response is trivial. Use concise labels and the right diagram type; do not hardcode random style/classDef/light-theme overrides unless the user explicitly asks.
+## Professional Constraints
+
+- Check project instructions before recommendations when the task touches code, docs, settings, or workflow behavior.
+- Keep scope bounded to the user request and approved workflow phase.
+- Do not print secrets, credentials, tokens, auth/session values, private runtime state, or `.env` contents.
+- Avoid destructive commands, deploys, pushes, resets, cleans, database mutations, and dependency installs unless explicitly approved outside this workflow.
+- Prefer concise, evidence-based output with exact files or commands reviewed.
+## Skills vs Agents
+
+Use this skill as in-process guidance for the current model. Use a sub-agent only when the task benefits from an isolated context window, parallel read-only research, forced preflight, or independent validation. Do not use both this skill and a same-purpose agent for the same narrow job unless the workflow or user explicitly requires it.

package/skills/find-skills/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+
+For workflow/tooling explanations with user-facing flows, request lifecycles, architecture, data flow, or multi-step sequences, include a meaningful Mermaid diagram plus concise prose unless the user requested prose only or the response is trivial. Workflow Suite renders diagrams in a uniform dark-mode visual style; use concise labels and do not hardcode random light styling unless explicitly requested.
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Check the Leaderboard First
+
+Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
+
+For example, top skills for web development include:
+- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
+- `anthropics/skills` — Frontend design, document processing (100K+ installs)
+
+### Step 3: Search for Skills
+
+If the leaderboard doesn't cover the user's need, run the find command:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+### Step 4: Verify Quality Before Recommending
+
+**Do not recommend a skill based solely on search results.** Always verify:
+
+1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
+2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
+3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
+
+### Step 5: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install count and source
+3. The install command they can run
+4. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+(185K installs)
+
+To install it:
+npx skills add vercel-labs/agent-skills@react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
+```
+
+### Step 6: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```
+## Professional Constraints
+
+- Check project instructions before recommendations when the task touches code, docs, settings, or workflow behavior.
+- Keep scope bounded to the user request and approved workflow phase.
+- Do not print secrets, credentials, tokens, auth/session values, private runtime state, or `.env` contents.
+- Avoid destructive commands, deploys, pushes, resets, cleans, database mutations, and dependency installs unless explicitly approved outside this workflow.
+- Prefer concise, evidence-based output with exact files or commands reviewed.
+## Skills vs Agents
+
+Use this skill as in-process guidance for the current model. Use a sub-agent only when the task benefits from an isolated context window, parallel read-only research, forced preflight, or independent validation. Do not use both this skill and a same-purpose agent for the same narrow job unless the workflow or user explicitly requires it.