promptgraph-mcp 2.9.61 → 2.9.62

package/README.md

@@ -128,6 +128,24 @@ Your **skill files** stay wherever you put them (the platform skills dir or any
 
 ---
 
+## Skill orchestration — `pg` → `pg-chain`
+
+`pg setup` installs two router skills:
+
+- **`pg`** — single lookup: search → read → execute one skill for a task.
+- **`pg-chain`** — orchestrator: wraps `pg` in a controlled loop for **multi-step** tasks. The model runs a skill, reassesses, finds the next skill, runs it, and repeats **until the goal is met** — following explicit skill chains (`pg_callees`) and discovering new ones (`pg_search`) as needs emerge.
+
+`pg-chain` has hard stop conditions so it can't loop forever: goal met, max 7 skills per chain, a repeat-guard (never re-run the same skill on the same sub-task), and a no-progress guard. It keeps a visible `Goal / Done / Now / Left` ledger so the chain is auditable.
+
+```
+"Add a feature flag, make sure nothing broke, and write the commit."
+  → feature-flag ✓ → safe-verify ✓ → commit-message ✓  (3 skills chained)
+```
+
+Use `pg` for one-step tasks, `pg-chain` when a request clearly spans several skills.
+
+---
+
 ## OpenCode — `/pg` slash commands
 
 After `pg setup opencode`, two slash commands are available inside OpenCode:

package/commands/setup.js

@@ -1,5 +1,39 @@
 import { colors, success, error, info, section } from '../cli.js';
 import chalk from 'chalk';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// Install the bundled router skills (pg, pg-chain) so a fresh install actually
+// has the orchestration capability — not just docs that reference it.
+// Copies into skillsDir (indexed → discoverable via pg_search on every platform)
+// and, on Claude platforms, into ~/.claude/commands (so /pg & /pg-chain slash
+// commands work). Never overwrites a user-edited copy.
+function installRouterSkills(skillsDir, platformId) {
+  const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const srcDir = path.join(pkgRoot, 'skills');
+  if (!fs.existsSync(srcDir)) return;
+  const files = fs.readdirSync(srcDir).filter(f => f.endsWith('.md'));
+
+  const targets = [path.join(skillsDir, '_promptgraph')];
+  if (platformId === 'claude-code' || platformId === 'claude-desktop') {
+    targets.push(path.join(os.homedir(), '.claude', 'commands'));
+  }
+
+  let installed = 0;
+  for (const dir of targets) {
+    fs.mkdirSync(dir, { recursive: true });
+    for (const f of files) {
+      const dest = path.join(dir, f);
+      // Don't clobber a copy the user has customized; refresh only if missing/identical-origin.
+      if (fs.existsSync(dest)) continue;
+      fs.copyFileSync(path.join(srcDir, f), dest);
+      installed++;
+    }
+  }
+  if (installed) success(`Installed router skills (${files.map(f => f.replace('.md', '')).join(', ')})`);
+}
 
 export default async function handler(args, bin) {
   const { detectPlatforms, PLATFORMS } = await import('../platform.js');
@@ -43,6 +77,9 @@ export default async function handler(args, bin) {
   success(`Skills directory: ${chalk.white(skillsDir)}`);
   info(chalk.gray('  Marketplace installs and pg import will save here'));
 
+  // 2b. Install bundled router skills (pg + pg-chain orchestrator)
+  try { installRouterSkills(skillsDir, platformId); } catch (e) { info(chalk.gray(`  (router skills skipped: ${e.message})`)); }
+
   // 3. Reindex
   console.log(chalk.gray('\n  Indexing skills...\n'));
   await indexAll();

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "promptgraph-mcp",
-  "version": "2.9.61",
+  "version": "2.9.62",
   "files": [
     "*.js",
     "commands/",
     "src/",
+    "skills/",
     "README.md",
     ".claude-plugin/",
     ".mcp.json"

package/skills/pg-chain.md

@@ -0,0 +1,94 @@
+---
+name: pg-chain
+description: Skill orchestrator — chains skills in a loop (search → execute → reassess → next) until the whole task is done
+---
+
+# PromptGraph Chain Orchestrator
+
+Use this when a request needs **more than one skill** to finish — a multi-step task
+where you execute one skill, then discover you need another, and another, until the
+goal is met. Builds on the `pg` router (single lookup) by wrapping it in a controlled loop.
+
+## The loop
+
+```
+1. PLAN      → restate the goal in one sentence + list the obvious sub-tasks.
+2. SELECT    → take the next unfinished sub-task.
+3. FIND      → pg_search(<sub-task in English keywords>).
+                 score ≥ 0.60 → use the skill   |   score < 0.60 → handle directly (no skill).
+4. CHAIN?    → pg_callees(<skill id>) — does this skill explicitly call others?
+                 If yes, those are the next chain links (follow them before re-searching).
+5. EXECUTE   → Read the skill file at `path` (MANDATORY), then run its instructions fully.
+6. REASSESS  → Is the GOAL complete?
+                 • Done            → STOP, summarize what was chained.
+                 • Gap remains     → name the next sub-task, go to step 2.
+                 • Stuck/no skill  → handle directly, or report the blocker and STOP.
+```
+
+## Stop conditions (hard — never skip)
+
+The loop **must** terminate. Stop when ANY of these is true:
+
+- **Goal met** — the original request is fully satisfied (state it explicitly).
+- **Max 7 skill executions** in one chain. If you hit 7, stop and report progress + what's left.
+- **No progress** — if a sub-task's skill ran but the goal didn't move closer, do NOT
+  re-run the same skill. Mark it tried, pick a different approach or stop.
+- **Repeat guard** — keep a list of executed skill ids. Never execute the same skill id
+  twice for the same sub-task. Re-running a skill on identical input is a loop, not progress.
+- **No match + can't proceed** — if `pg_search` < 0.60 and you can't handle it directly, stop and ask the user.
+
+## State to track out loud
+
+Keep a short visible ledger so the chain is auditable:
+
+```
+Goal: <one sentence>
+Done: [skill-a ✓, skill-b ✓]
+Now:  <current sub-task> → <skill being used>
+Left: <remaining sub-tasks, or "none">
+```
+
+Update it after every EXECUTE step. This is what prevents silent infinite loops.
+
+## Two ways skills connect
+
+1. **Explicit chain** — a skill's file references another skill (e.g. `/run-tests`).
+   `pg_callees` surfaces these. Follow declared chains first — the author intended them.
+2. **Emergent need** — mid-task you realize you need something new. `pg_search` for it.
+   This is where the orchestrator earns its keep.
+
+Prefer explicit chains (deterministic) over emergent search (discovered) when both apply.
+
+## Worked example
+
+```
+User: "Add a feature flag, then make sure nothing broke and write the commit."
+
+Goal: ship a feature flag safely with a commit.
+Done: []
+Now:  add a feature flag → pg_search("add feature flag toggle config")
+      → feature-flag (0.81) → Read → execute.   Done: [feature-flag ✓]
+Reassess: code changed but untested.
+Now:  verify nothing broke → pg_search("run tests verify no regression")
+      → safe-verify (0.78) → Read → execute.    Done: [feature-flag ✓, safe-verify ✓]
+Reassess: tests green, change not committed.
+Now:  write commit → pg_search("write git commit message")
+      → commit-message (0.91) → Read → execute.  Done: [..., commit-message ✓]
+Reassess: GOAL MET → STOP.
+
+Summary: chained feature-flag → safe-verify → commit-message (3 skills).
+```
+
+## When NOT to chain
+
+- Single-skill tasks → just use `pg` (this orchestrator is overhead for one step).
+- Pure-knowledge questions with no skill match → answer directly.
+- If two sub-tasks are independent, you may do them in either order — don't invent
+  false dependencies.
+
+## Honesty rules
+
+- A skill running ≠ the sub-task being done. Verify the **outcome**, then advance.
+- If no skill fits a step, say so and handle it directly — do not force a low-score skill
+  just to keep the chain going.
+- Report the final chain (which skills, in what order) so the user can audit it.

package/skills/pg.md

@@ -0,0 +1,88 @@
+---
+name: pg
+description: PromptGraph router — finds and loads the right skill for any task
+---
+
+# PromptGraph Router
+
+You have access to a semantic skill index via the `promptgraph` MCP server tools.
+
+## Step-by-step for every task
+
+1. **Translate** the user's request to English keywords (if needed)
+2. **Call `pg_search`** with those keywords
+3. **Evaluate results:**
+   - score ≥ 0.75 → use it, high confidence
+   - score 0.60–0.74 → use it, but stay alert if instructions feel off-topic
+   - score < 0.60 → skip, handle the task directly
+4. **Read the skill file** at the returned `path` using the Read tool — **MANDATORY. Do NOT skip this step even if the task seems obvious. Saying "using skill X" and then doing the task from memory is a protocol violation.**
+5. **Execute** the skill's instructions fully
+
+## Score thresholds
+
+| Score | Action |
+|---|---|
+| ≥ 0.75 | Use skill, high confidence |
+| 0.60–0.74 | Use skill, verify relevance |
+| < 0.60 | Handle directly, no skill |
+
+## Search query tips
+
+- Write in English — the embedding model is English-only
+- Use task-oriented phrases: "refactor without breaking tests", "debug memory leak", "write commit message"
+- If first search returns low scores, try a shorter or more specific query
+
+## Available MCP tools
+
+| Tool | When to use |
+|---|---|
+| `pg_search` | Find a skill by task description — **always start here** |
+| `pg_context` | Get full details + callers/callees for a known skill id |
+| `pg_callers` | Which skills reference this one (dependency check) |
+| `pg_callees` | Which skills this one calls (before executing a chain) |
+| `pg_impact` | What breaks if a skill changes |
+| `pg_list` | List all indexed skills (use when unsure what's available) |
+| `pg_top_rated` | Best-rated skills by success/fail ratio |
+| `pg_marketplace_browse` | Browse community registry |
+| `pg_marketplace_install` | Install by code (`pg-xxxxxx`), id, or name |
+| `pg_bundle_install` | Install a skill bundle |
+
+## Skill sources indexed
+
+- `~/.claude/commands/` — local command skills
+- `~/.claude/skills-store/` — personal skills
+- `~/.claude/skills-store/github/alirezarezvani-claude-skills` — 330+ engineering, product, marketing, compliance skills
+- `~/.claude/skills-store/github/trailofbits-skills` — security research and audit skills
+- `~/.claude/skills-store/github/OthmanAdi-planning-with-files` — project planning skills
+- `~/.claude/skills-store/marketplace/` — installed community skills
+
+## Examples
+
+```
+User: "отрефактори этот модуль без багов"
+→ pg_search("safe refactor without breaking tests")
+→ returns safe-refactor (score: 0.82) → Read → execute
+
+User: "напиши commit message"
+→ pg_search("write git commit message")
+→ returns commit-message (score: 0.91) → Read → execute
+
+User: "аудит безопасности кода"
+→ pg_search("security audit vulnerability scan")
+→ returns audit (score: 0.80) → Read → execute
+
+User: "спланируй проект"
+→ pg_search("project planning breakdown tasks")
+→ returns planning skill → Read → execute
+```
+
+## If no skill matches (score < 0.60)
+
+Handle the task directly with your own knowledge. Do not force a low-score skill.
+
+## Multi-step tasks → use `pg-chain`
+
+This router loads **one** skill. If the task needs several skills in sequence
+(execute one → discover you need another → continue until done), switch to the
+**`pg-chain`** orchestrator skill — it wraps this lookup in a controlled loop with
+hard stop conditions. `pg` = single lookup; `pg-chain` = chained execution.