@pbhamri/quartermaster-mcp 0.3.0 → 0.4.0

package/bin/server.js

@@ -138,7 +138,7 @@ Seeded by quartermaster-mcp · profile **${profile.displayName}**.
 - Score every artefact against the **TRANSFORMATIVE** PM behaviors (AI-driven innovation, outcome-centric, shared leverage, decision velocity).
 - Close every response with a 2-line Transformative prompt-sharpening tip.
 
-## CXE pillars (Hayete, 2026-05-29)
+## CXE pillars (EVP Security, FY26)
 1. CXE = core priority
 2. Customers get value fast (TTV)
 3. Operate with confidence
@@ -300,6 +300,163 @@ function emitPr({ repoPath, profileId, branch = null, title = null, body = null,
 }
 
 
+// ---- Onboarding surface (since v0.4.0) ----
+// First-time peer experience: welcome, personalize, skills tour. Designed
+// after real customer feedback (a peer PM installed v0.3.1 and got 12
+// tools with no guide, no personalization). All three tools return
+// markdown the AI client renders inline; no auto-fill, no credentials
+// inherited from the package author.
+
+const QM_HOME = path.join(os.homedir(), ".quartermaster");
+const QM_CONNECT_DB = process.env.QM_CONNECT_DB || path.join(QM_HOME, "connect-db.json");
+
+function qmWelcome() {
+  const hasConnectDb = fs.existsSync(QM_CONNECT_DB);
+  const profiles = listProfiles();
+  return {
+    server: "quartermaster-mcp",
+    version: PKG.version,
+    welcome: "Welcome to Quartermaster MCP — a PM paved-path bundle for Microsoft PMs.",
+    what_this_is: "12 MCP tools that scaffold a PM operating model: Purview product profiles, /npf and /cxe prompts, NPF assessment, BATON-style frameworks, and read-only access to your repo content.",
+    next_three_steps: hasConnectDb ? [
+      `1. Run \`qm_personalize\` to refresh your Connect tracker if needed (current: ${QM_CONNECT_DB}).`,
+      "2. Run `qm_skills_for_pm` to see the daily-use catalog for product roadmap + strategy.",
+      "3. Run `qm_seed_repo` to scaffold a target repo with the Quartermaster kit.",
+    ] : [
+      "1. Run `qm_personalize` — answers 5 questions, writes YOUR connect-db (uses ~/.quartermaster/connect-db.json by default; override via QM_CONNECT_DB env var). The package author's data is never used.",
+      `2. Run \`qm_apply_profile\` with one of the ${profiles.length} profiles: ${profiles.map(p => p.id).join(", ")}.`,
+      "3. Run `qm_skills_for_pm` to see the daily-use catalog for product roadmap + strategy.",
+    ],
+    privacy_note: "Quartermaster ships templates only. Your Connect data, GitHub/Kusto/ADO credentials, and personal NPF history live on YOUR machine and are never committed to the package. The author's environment is not leaked to your install.",
+    troubleshooting: {
+      "Tools not visible after install": "Restart your MCP client (Copilot CLI: /restart; Claude Desktop: Cmd-Q + relaunch).",
+      "qm_personalize asks me questions but I want to skip": "Answer 'skip' to any question; you can re-run later. The template is also at <package>/resources/connect-db.template.json — copy and edit by hand.",
+      "I want to see what files this server can read": "Call repo_overview — it returns the repo_root and exclusion list.",
+    },
+    docs: "https://www.npmjs.com/package/@pbhamri/quartermaster-mcp",
+  };
+}
+
+function qmPersonalize(args = {}) {
+  // Two modes: (1) returns a Q&A flow for the AI client to walk through;
+  // (2) if the client passes answers, generates the connect-db file from
+  // the template at resources/connect-db.template.json. NEVER inherits
+  // the package author's data.
+  const tplPath = path.join(RES, "connect-db.template.json");
+  if (!fs.existsSync(tplPath)) {
+    return { error: "Template not found", expected: tplPath };
+  }
+  const template = readJson(tplPath);
+
+  // Mode 1: no answers yet — return the question flow.
+  if (!args.answers) {
+    return {
+      mode: "interview",
+      target_path: QM_CONNECT_DB,
+      target_exists: fs.existsSync(QM_CONNECT_DB),
+      override_with_env: "Set QM_CONNECT_DB env var to use a different path.",
+      questions: [
+        { id: "owner_role", q: "What's your role + product? (e.g. 'PM, Microsoft Intune Endpoint Management')", required: true },
+        { id: "level", q: "What's your IC level? (L62 / L63 / L64 / L65 / L67) — drives /npf calibration", required: true },
+        { id: "fy_period", q: "Current FY period? (e.g. 'FY26 H1')", required: true },
+        { id: "goal_titles", q: "Your top 3-5 Connect goal titles (one per line). I'll scaffold them as drafts you can fill in baselines + targets later.", required: true },
+        { id: "active_directive", q: "Top active directive from your manager / GPM (one line, free-form)", required: false },
+      ],
+      instructions_for_ai_client: "Ask the user the questions above one at a time. When all answers collected, call qm_personalize again with answers={...} keyed by question id. The user — not the AI — answers each question.",
+      will_write_to: QM_CONNECT_DB,
+      will_overwrite: fs.existsSync(QM_CONNECT_DB) ? "YES — backup recommended before proceeding" : "NO — new file",
+    };
+  }
+
+  // Mode 2: answers provided — write the personalized connect-db.
+  const a = args.answers;
+  const personalized = {
+    ...template,
+    meta: {
+      owner_role: a.owner_role || template.meta.owner_role,
+      level: a.level || template.meta.level,
+      fy_period: a.fy_period || template.meta.fy_period,
+      last_updated: new Date().toISOString().split("T")[0],
+    },
+    goals: (a.goal_titles ? a.goal_titles.split("\n") : [])
+      .map((t, i) => ({ id: i + 1, title: t.trim(), status: "draft", smart: false, baseline: null, target: null, due: null }))
+      .filter(g => g.title),
+    directives: a.active_directive ? [{ id: "d1", title: a.active_directive, status: "active" }] : [],
+  };
+  // Backup existing if present
+  if (fs.existsSync(QM_CONNECT_DB)) {
+    const backup = QM_CONNECT_DB.replace(/\.json$/, `.backup-${Date.now()}.json`);
+    fs.copyFileSync(QM_CONNECT_DB, backup);
+    personalized._backup_of_previous = backup;
+  }
+  fs.mkdirSync(path.dirname(QM_CONNECT_DB), { recursive: true });
+  fs.writeFileSync(QM_CONNECT_DB, JSON.stringify(personalized, null, 2));
+  emit("qm.personalize", { level: a.level, goal_count: personalized.goals.length });
+  return {
+    mode: "written",
+    path: QM_CONNECT_DB,
+    summary: `Wrote ${personalized.goals.length} draft goals + ${personalized.directives.length} directive at level ${personalized.meta.level}.`,
+    next_step: "Run /npf in your Copilot CLI / Chat to get your first NPF assessment calibrated to " + (personalized.meta.level || "your level") + ".",
+  };
+}
+
+function qmSkillsForPm() {
+  // Curated catalog: 12 MCP tools mapped to PM daily-use cases.
+  // Optimised for product roadmap + strategy work.
+  return {
+    title: "Quartermaster — daily PM skills for roadmap + strategy",
+    intro: "12 tools, organised by PM workflow. Each tool name in backticks is callable as `<tool_name>` from your MCP client.",
+    workflows: [
+      {
+        scenario: "Monday — Weekly self-assessment + planning",
+        tools: [
+          { name: "/npf (prompt)", use: "30-second NPF score + biggest gap + next-move recommendation. Calibrated to your IC level." },
+          { name: "qm_telemetry", use: "Read paved-path adoption events from the last 7 days; see whose installs landed." },
+          { name: "repo_recent_sessions", use: "Read your cross-model session log to recall what shipped last week without re-explaining." },
+        ],
+      },
+      {
+        scenario: "Tuesday-Thursday — PRD authoring + roadmap shaping",
+        tools: [
+          { name: "qm_seed_repo", use: "Scaffold a new repo with the IGRM-style PRD format, /cxe + /npf prompts, command-center seed. Idempotent." },
+          { name: "qm_apply_profile", use: "Lock in your product profile (DLM / Insider Risk / eDiscovery / Records / Compliance / Billing) so every PRD inherits your KPIs + directives." },
+          { name: "qm_audit_repo", use: "Score any repo /6 against PM-readiness (AGENTS.md, copilot-instructions, profile, /npf, /cxe, verify.ps1). Fast peer review." },
+          { name: "/cxe (prompt)", use: "Audit a PRD or work item against the 4 CXE pillars (Priority / TTV / Confidence / Support)." },
+        ],
+      },
+      {
+        scenario: "Friday — Strategy + leadership prep",
+        tools: [
+          { name: "repo_overview / repo_list_dir / repo_read_file / repo_search", use: "Pull artefacts into context for an exec readout without copy-pasting. Read-only, secrets denied at server." },
+          { name: "qm_emit_pr", use: "Seed a repo with a profile AND open a labeled PR via gh CLI — closes the loop on cross-team commitments in one call." },
+        ],
+      },
+      {
+        scenario: "Onboarding + sharing with peer PMs",
+        tools: [
+          { name: "qm_welcome", use: "First-run guide. Surface this to any new peer." },
+          { name: "qm_personalize", use: "Walk a peer through 5 questions, write THEIR connect-db. Their data, their machine, never the package author's." },
+          { name: "qm_install_prompts", use: "Drop /npf + /cxe into a peer's ~/.github/prompts so the prompts work in Copilot Chat (IDE) too." },
+          { name: "qm_skills_for_pm", use: "This catalog. Run any time you forget what's available." },
+        ],
+      },
+    ],
+    daily_loop: [
+      "1. Mon 09:00 — `/npf` for the week's score + gap.",
+      "2. Tue-Thu — `qm_seed_repo` / `qm_apply_profile` / `/cxe` while authoring PRDs.",
+      "3. Fri PM — `repo_search` + `repo_read_file` to assemble Friday's exec readout.",
+      "4. Monthly — `qm_telemetry` to check who's actually adopting your paved paths (Reach signal for next /npf).",
+    ],
+    not_in_scope: [
+      "Real-time customer feedback ingestion — pair with WorkIQ MCP for that.",
+      "ADO work-item bulk operations — pair with Azure DevOps MCP.",
+      "Kusto KPI pulls — pair with the Kusto MCP server.",
+      "All three above have profile templates in resources/mcp-servers/ — paste into your MCP config, fill the {{PLACEHOLDERS}} with your own org/project/cluster.",
+    ],
+  };
+}
+
+
 // ---- Repo-read surface (since v0.3.0) ----
 // Lets a peer's MCP client read files in the repo where the server runs.
 // Default REPO_ROOT = cwd at launch (overridable via QM_REPO_ROOT env).
@@ -403,7 +560,7 @@ function repoRecentSessions({ limit = 10 } = {}) {
 
 // ---------------- MCP wiring ----------------
 const server = new Server(
-  { name: "quartermaster-mcp", version: "0.1.0" },
+  { name: "quartermaster-mcp", version: PKG.version },
   { capabilities: { tools: {}, resources: {} } }
 );
 
@@ -433,6 +590,13 @@ const TOOLS = [
       title: { type:"string" }, body: { type:"string" },
       base: { type:"string", default:"main" }, draft: { type:"boolean", default:false }
     } } },
+  // ---- v0.4.0 onboarding surface ----
+  { name: "qm_welcome", description: "First-run welcome + 3-step onboarding guide. Surface this to any new peer who installed quartermaster-mcp. No args.",
+    inputSchema: { type: "object", properties: {} } },
+  { name: "qm_personalize", description: "Interactive setup. Returns a Q&A flow (mode='interview') for the AI client to walk the user through, OR if answers provided, writes a personalized connect-db at ~/.quartermaster/connect-db.json (override with QM_CONNECT_DB env var). Never inherits the package author's data.",
+    inputSchema: { type: "object", properties: { answers: { type: "object", description: "Key-value of question ids to user answers. Returned by interview mode." } } } },
+  { name: "qm_skills_for_pm", description: "Curated catalog of the Quartermaster tools mapped to PM daily-use workflows (Monday self-assess, midweek PRDs + roadmap, Friday strategy prep, onboarding + sharing).",
+    inputSchema: { type: "object", properties: {} } },
   // ---- v0.3.0 read-only repo surface ----
   { name: "repo_overview", description: "Returns server metadata: repo_root, framework_count (if a competitive-intel-agent/frameworks dir exists), exclusion rules. No args.",
     inputSchema: { type: "object", properties: {} } },
@@ -460,6 +624,9 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       case "qm_apply_profile":   result = await timed("qm.apply_profile",   { profileId: args.profileId }, async () => applyProfile(args)); break;
       case "qm_telemetry":       result = readTelemetry(args); break;
       case "qm_emit_pr":         result = await timed("qm.emit_pr",         { profileId: args.profileId }, async () => emitPr(args)); break;
+      case "qm_welcome":           result = qmWelcome(); break;
+      case "qm_personalize":       result = qmPersonalize(args); break;
+      case "qm_skills_for_pm":     result = qmSkillsForPm(); break;
       case "repo_overview":         result = repoOverview(); break;
       case "repo_list_dir":         result = repoListDir(args); break;
       case "repo_read_file":        result = repoReadFile(args); break;
@@ -490,3 +657,4 @@ server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
 
 await server.connect(new StdioServerTransport());
 process.stderr.write(`quartermaster-mcp v${PKG.version} ready (stdio)\n`);
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pbhamri/quartermaster-mcp",
-  "version": "0.3.0",
-  "description": "MCP server that seeds any repo with the Quartermaster PM kit AND exposes a read-only repo surface (repo_overview, repo_list_dir, repo_read_file, repo_search, repo_recent_sessions). One-command share with any MS PM peer: npx -y @pbhamri/quartermaster-mcp",
+  "version": "0.4.0",
+  "description": "MCP server that seeds any repo with the Quartermaster PM kit + provides read-only repo access + first-run onboarding (qm_welcome, qm_personalize, qm_skills_for_pm). Personalised per peer; never inherits the package author's Connect/credentials/personal data. One-command share with any MS PM peer: npx -y @pbhamri/quartermaster-mcp",
   "type": "module",
   "bin": {
     "quartermaster-mcp": "bin/server.js"

package/resources/connect-db.template.json

@@ -0,0 +1,54 @@
+{
+  "_template_for": "Quartermaster MCP — Connect goal tracker template",
+  "_instructions": "Replace TODO placeholders with your own goals/KPIs. Never commit your filled copy back to a public repo.",
+  "schemaVersion": 1,
+  "meta": {
+    "owner_role": "TODO: e.g. PM, Microsoft Purview DLM",
+    "level": "TODO: e.g. L62 / L63 / L64 / L65",
+    "fy_period": "TODO: e.g. FY26 H1",
+    "last_updated": "TODO: ISO date"
+  },
+  "goals": [
+    { "id": 1, "title": "TODO: Customer outcome you own E2E", "status": "draft", "smart": false, "baseline": null, "target": null, "due": null },
+    { "id": 2, "title": "TODO: Adoption / funnel KPI", "status": "draft", "smart": false, "baseline": null, "target": null, "due": null },
+    { "id": 3, "title": "TODO: AI-leverage / paved-path goal", "status": "draft", "smart": false, "baseline": null, "target": null, "due": null },
+    { "id": 4, "title": "TODO: Cross-functional collaboration / mentor goal", "status": "draft", "smart": false, "baseline": null, "target": null, "due": null },
+    { "id": 5, "title": "TODO: Personal growth / level-up goal", "status": "draft", "smart": false, "baseline": null, "target": null, "due": null }
+  ],
+  "kpis": {
+    "_examples": "Replace these with KPIs from your team's OKR doc. Each KPI has baseline + target + cadence.",
+    "kpi_1": { "name": "TODO", "baseline": null, "target": null, "cadence": "weekly" }
+  },
+  "directives": [
+    { "id": "d1", "title": "TODO: Active directive from your manager / GPM", "status": "active" }
+  ],
+  "todos": [],
+  "cxePillars": {
+    "_anchor": "EVP Security CXE pillars (FY26)",
+    "priority": { "evidence": [], "lagging_metric": null },
+    "ttv": { "evidence": [], "lagging_metric": null },
+    "confidence": { "evidence": [], "lagging_metric": null },
+    "support": { "evidence": [], "lagging_metric": null }
+  },
+  "npfHistory": [],
+  "cadenceSchedule": {
+    "weekly_self_assess": "Mon 09:00 local",
+    "monthly_exec_readout": "Last Friday of month",
+    "quarterly_connect_review": "Mid-quarter + close-quarter"
+  },
+  "mcpHealth": {
+    "_purpose": "Track which MCP surfaces you have configured. Quartermaster fills this when you accept the qm_install_mcp prompts.",
+    "ado": { "configured": false },
+    "kusto": { "configured": false },
+    "workiq": { "configured": false },
+    "playwright": { "configured": false }
+  },
+  "quickLinks": {
+    "_examples": "Replace with your team's actual links",
+    "team_okr_doc": "TODO",
+    "release_calendar": "TODO",
+    "exec_review_deck": "TODO"
+  },
+  "notes": [],
+  "recentReports": []
+}

package/resources/prompts/cxe.prompt.md

@@ -1,7 +1,7 @@
 ---
-description: One-word trigger — audit any PRD, work-item, or shipped surface against Hayete's 4 CXE pillars (CXE-first / Value-fast / Confidence / Support-when-it-matters).
+description: One-word trigger — audit any PRD, work-item, or shipped surface against EVP Security CXE pillars (CXE-first / Value-fast / Confidence / Support-when-it-matters).
 ---
-# /cxe — Hayete CXE pillar audit
+# /cxe — EVP Security CXE pillar audit
 
 When the user types `/cxe` (alone, or `/cxe <id-or-path>`), run a 4-pillar audit.
 
@@ -10,7 +10,7 @@ When the user types `/cxe` (alone, or `/cxe <id-or-path>`), run a 4-pillar audit
 - If `<id>`: audit that PRD id.
 - If `<path>`: audit the file at that path (PRD .md / .docx / .html or ADO work-item .json export).
 
-## Pillars (verbatim from Hayete, 2026-05-29)
+## Pillars (verbatim from EVP Security, FY26)
 
 | # | Pillar | The lens |
 |---|---|---|
@@ -48,9 +48,10 @@ Biggest gap:      <one sentence>
 Next move:        <one specific edit + owner + by-when>
 ```
 
-Then close with the standard 3-block (Transformative tip / Hayete AMA / NPF Reach Expansion) — the **Hayete AMA line must now reference whichever pillar the audit found weakest**, so the rubric drives the close, not generic alignment.
+Then close with the standard 3-block (Transformative tip / EVP Security AMA / NPF Reach Expansion) — the **EVP Security AMA line must now reference whichever pillar the audit found weakest**, so the rubric drives the close, not generic alignment.
 
 ## Notes
 - This is candid, not flattering. A 3/8 is a real signal that the artefact needs a CXE rewrite, not a re-edit.
 - TTV (P2) cannot be scored 2 without a *measured* baseline number — "TTV is fast" doesn't count.
 - Support (P4) must be **in-product**. A docs link is P4=1, not P4=2.
+

package/resources/prompts/npf.prompt.md

@@ -1,5 +1,5 @@
 ---
-description: One-word trigger — assess current NPF (Net Productivity Factor) performance from connect-db.json + recent CI reports, score against L3 Transformative band, and recommend the single highest-leverage next move.
+description: One-word trigger — assess current NPF (Net Productivity Factor) performance, calibrated to your IC level (default L64 — Senior PM IC4). Reads connect-db.json + recent CI reports, scores against L3 Transformative band AND the band-specific expectation table, and recommends the single highest-leverage next move.
 ---
 # /npf — Net Productivity Factor assessment
 
@@ -7,39 +7,47 @@ When the user types `/npf` (or just "npf"), run this assessment.
 
 ## Steps
 
-1. Read `C:\Users\pbhamri\Documents\Connect\db\connect-db.json` → extract `npfHistory[]`, `kpis`, `goals`, `directives`, `todos`.
-2. Compute:
+1. **Locate connect-db.** Order of preference:
+   - Env var `QM_CONNECT_DB` if set, OR
+   - `~/.quartermaster/connect-db.json` (default for new installs), OR
+   - `~/Documents/Connect/db/connect-db.json` (legacy location).
+
+   If none exist: tell the user to run `qm_personalize` (Quartermaster MCP tool) to scaffold one, then re-run /npf.
+
+2. From connect-db, extract `npfHistory[]`, `kpis`, `goals`, `directives`, `todos`.
+3. Compute:
    - **Current NPF**: latest `npfHistory[].index` + band
    - **Week-over-week delta**: latest − snapshot from 7 days ago
    - **Trend**: rising / flat / falling
-   - **L3 band proof**: count of evidence in last 7 days (skills shipped, §7 rules, frameworks added, paved-path artefacts, ADO/PR telemetry-tagged work)
-3. Score against the four TRANSFORMATIVE behaviors (each 0–25, total /100):
-   - **Leverage** — shared assets built (skills, agents, paved paths, templates)
-   - **Reach** — peers / workloads who can reuse this week's output
+   - **L3 band proof**: count of evidence in last 7 days (skills shipped, paved-path artefacts, npm packages published, ADO/PR telemetry-tagged work)
+4. Score against the four TRANSFORMATIVE behaviors **AND apply the IC-band calibration table** (default L64: NPF 65-80, mentor footprint 1-3 peers, all 4 CXE pillars with lagging metric, telemetry-confirmed reach not just outreach):
+   - **Leverage** — shared assets (skills, agents, paved paths, npm packages)
+   - **Reach** — peers / workloads with telemetry-confirmed adoption (use paved-path-events.jsonl as ground truth)
    - **Cycle-time collapse** — weeks→days or days→minutes proof
    - **Outcome focus** — customer/business metric movement vs activity counts
-4. Identify the **single biggest NPF leak** (KPI stuck at 0 / blocker on a directive / overdue todo / no real NPF capture).
-5. Recommend **one move** that would lift NPF by ≥5 points before the next refresh.
+5. Identify the **single biggest NPF leak** and recommend **one move** that would lift NPF by ≥5 points before the next refresh.
 
 ## Output format
 
 ```
-NPF: <score>/100 · <band> · <trend arrow> <delta> wk/wk
+NPF (calibrated to L<band>): <score>/100 · <band-name> · <trend arrow> <delta> wk/wk
 
-Behavior          Score   Evidence
-Leverage          xx/25   <1-line proof>
-Reach             xx/25   <1-line proof>
-Cycle-time        xx/25   <1-line proof>
-Outcome focus     xx/25   <1-line proof>
+Dimension          IC-band read   Mechanical  Evidence
+Leverage           A/B/C/D        xx/100      <1-line proof>
+Reach              A/B/C/D        xx/100      <1-line proof>
+Cycle-time         A/B/C/D        xx/100      <1-line proof>
+Outcome focus      A/B/C/D        xx/100      <1-line proof>
 
-Biggest leak:     <one sentence>
-Next move (≥+5):  <one specific action with owner + by-when>
+Calibration verdict: <A-/B/B-/C+/C/D> (<one sentence summary>)
+Biggest gap to bar:  <one sentence>
+Next move (≥+5 NPF): <one specific action with owner + by-when>
 ```
 
-Then close with the standard 3-block (Transformative tip / Hayete AMA / NPF Reach Expansion).
+Then close with the standard 3-block (Transformative tip · AMA Alignment · NPF Reach Expansion).
 
-## Notes
+## Rules
 
-- The carried-forward NPF (note contains "auto-carried") is a placeholder, not a real score — call it out and *overwrite* it as part of this assessment by editing `connect-db.json` directly with your real computed score.
-- Never score above 80 without at least one shipped artefact a *peer PM has actually consumed* (proof of reach, not just availability).
+- The carried-forward NPF (note contains "auto-carried") is a placeholder, not a real score — call it out and **overwrite** it with the real computed score.
+- Never score above the band-ceiling on Reach or Mentor footprint without telemetry-confirmed peer adoption (≥1 entry in `~/.copilot/metrics/paved-path-events.jsonl` from a non-self machine). Outreach ≠ adoption.
+- Refer to people by role/designation, never by name.
 - This is a self-assessment for the user's growth — be candid, not flattering.