wyvrnpm 2.21.0 → 2.21.1

package/README.md

@@ -773,10 +773,13 @@ Useful for: auditing consumer uploads (who pushed this artefact, from which comm
 
 ### `wyvrnpm install-skill`
 
-Installs the bundled wyvrnpm Agent Skill — the authoring guide Claude Code uses when it sees a `wyvrn.json` in the workspace. Ships as a `.skill` zip inside the npm package (`claude/skills/wyvrnpm.skill`) and is extracted into `~/.claude/skills/wyvrnpm/` on demand.
+Installs the bundled Claude Code assets that ship inside the npm package:
+
+- The **wyvrnpm Agent Skill** — the authoring guide Claude uses when it sees a `wyvrn.json` in the workspace. Ships as a `.skill` zip (`claude/skills/wyvrnpm.skill`), extracted into `~/.claude/skills/wyvrnpm/`.
+- The **onboarding agent(s)** — e.g. `wyvrnpm-onboarding`, which sets up a project to consume wyvrnpm deps or converts an existing CMake project into a wyvrnpm package. Ships as Markdown (`claude/agents/*.md`), copied into `~/.claude/agents/`.
 
 ```bash
-# One-shot: install the bundled skill for Claude Code
+# One-shot: install the bundled skill + agent(s) for Claude Code
 wyvrnpm install-skill --claude
 
 # Overwrite an existing installation (e.g. after upgrading wyvrnpm)
@@ -786,7 +789,7 @@ wyvrnpm install-skill --claude --force
 wyvrnpm install-skill --claude --dry-run
 ```
 
-You only need this if you want Claude Code to pick up the skill. The CLI itself works without it.
+You only need this if you want Claude Code to pick up the skill + agent. The CLI itself works without it.
 
 **Options**
 

package/bin/wyvrnpm.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 'use strict';
 
@@ -1127,7 +1127,7 @@ yargs
   // ── install-skill ─────────────────────────────────────────────────────────
   .command(
     'install-skill',
-    'Install the bundled wyvrnpm Agent Skill into Claude Code (~/.claude/skills/wyvrnpm/)',
+    'Install the bundled wyvrnpm Agent Skill + onboarding agent(s) into Claude Code (~/.claude/skills/ + ~/.claude/agents/)',
     (y) => {
       y
         .option('claude',  { type: 'boolean', description: 'Install for Claude Code',            default: false })

package/claude/agents/README.md

@@ -0,0 +1,159 @@
+# wyvrnpm Agents
+
+Claude Code **subagents** that ship with wyvrnpm. A subagent is a separate
+Claude worker with its own context window, tool access, and a clean return
+boundary — you delegate a self-contained task to it and get back a result,
+without the back-and-forth cluttering your main conversation.
+
+These are distributed the same way as the wyvrnpm **skill**: the source lives
+here under `claude/agents/`, and an active copy is placed in your user-global
+`~/.claude/agents/` so Claude Code picks it up in every project.
+
+> Skill vs. agent: the **skill** (`claude/skills/wyvrnpm/`) is *knowledge* — it
+> teaches Claude how wyvrnpm works. An **agent** is an *execution context* that
+> does a job, loading the skill for reference. The onboarding agent below uses
+> the skill; it does not replace it.
+
+---
+
+## `wyvrnpm-onboarding`
+
+### What it is
+
+A guided agent that gets a C++ developer who is **new to wyvrnpm** productive in
+one shot. It handles two distinct goals and figures out which one you want:
+
+| Mode | Goal | What it does |
+|---|---|---|
+| **A — Consume** | "I want to *use* libraries from our team registry in this project." | Configures the install source + profile, writes `wyvrn.json`, runs `wyvrnpm install`, wires your `CMakeLists.txt` (`wyvrnpm_find_dependencies()`, `wyvrn::<dep>` links, runtime-DLL copy), and confirms the build configures. |
+| **B — Convert / publish** | "I want to turn *this* library into a wyvrnpm package others can depend on." | Reads your `CMakeLists.txt`, picks `kind` / `options` / a `build` recipe, writes `wyvrn.json` + `.wyvrnignore`, then **verifies** by running `wyvrnpm install` and `wyvrnpm build --install --all-configs` across all four configs. Hands you a ready-to-run `publish` command — it never publishes itself. |
+
+### Why it exists
+
+wyvrnpm has no central registry and a few first-day gotchas (4-part versions,
+profile hashes, per-config install trees, `.wyvrnignore`). This agent removes
+the "I don't know where to start" barrier so teammates can adopt the tool
+without reading the full docs first.
+
+### Prerequisites
+
+- **wyvrnpm installed:** `npm i -g wyvrnpm` (Node.js ≥ 18). The agent checks
+  this first and stops if it's missing.
+- **For Mode A (consume):** your team's install source URL (an S3 bucket, HTTPS
+  endpoint, or file/SMB share). The agent will configure it for you if it isn't
+  already — wyvrnpm has no default registry, so this is required to fetch
+  anything.
+- **Claude Code**, with the agent installed (see below).
+
+### Install / make it active
+
+The agent file is a single Markdown file with YAML frontmatter. Put a copy where
+Claude Code looks for agents:
+
+The supported path is the wyvrnpm CLI — `install-skill` installs the bundled
+agent(s) alongside the skill:
+
+```bash
+npm i -g wyvrnpm
+wyvrnpm install-skill --claude        # installs skill -> ~/.claude/skills/
+                                      # AND agent(s) -> ~/.claude/agents/
+wyvrnpm install-skill --claude --force   # overwrite after upgrading wyvrnpm
+```
+
+Or copy the file by hand:
+
+```bash
+# Personal — available in every project on your machine:
+mkdir -p ~/.claude/agents
+cp claude/agents/wyvrnpm-onboarding.md ~/.claude/agents/
+
+# OR project-local — shared with everyone who clones that repo:
+mkdir -p <your-repo>/.claude/agents
+cp claude/agents/wyvrnpm-onboarding.md <your-repo>/.claude/agents/
+```
+
+Claude Code picks it up on the next session start.
+
+### How to use it
+
+**Implicitly** — just describe an onboarding task while you're in a C++ repo and
+Claude routes to the agent:
+
+- "Set up wyvrnpm in this project."
+- "Add wyvrnpm and pull in `fmt` and `spdlog`."
+- "Convert this library into a wyvrnpm package."
+- "Make this repo publishable on our registry."
+- "How do I start with wyvrnpm here?"
+
+**Explicitly** — name it: *"Use the wyvrnpm-onboarding agent to set this up."*
+
+If it can't tell whether you want Mode A or Mode B, it asks one short question
+rather than guessing.
+
+### What you get back
+
+Every run ends with:
+
+1. A summary — which mode it ran, the files it created/changed, and what it
+   **verified** (e.g. "install OK; all 4 configs built + installed").
+2. The single next command to run yourself — for Mode B that's the exact
+   `wyvrnpm publish …` line plus the pre-publish checklist; for Mode A it's
+   "you're ready to build."
+3. If something failed: the specific error and how it was fixed, or what's still
+   blocked. It won't claim success on an unvalidated manifest.
+
+### Safety — it never writes to your team's registry
+
+Onboarding is meant to be safe to run. The agent will **not** run any command
+that writes to shared team state without your explicit confirmation:
+
+- `wyvrnpm publish` / `publish --force` — it always stops here and hands the
+  command back to you.
+- `wyvrnpm install --upload-built` — also a registry write.
+- `wyvrnpm configure remove-source`.
+
+Everything else it runs is local and reversible (`install`, `build`, `clean`,
+`init`, `bootstrap`, `show`, `link`, profile/source *reads*). For
+`configure add-source` it shows you the URL/credentials before writing them.
+
+### Example
+
+```text
+You (in an app repo):  "set up wyvrnpm here and add fmt"
+
+Agent:
+  • wyvrnpm --version → 2.21.0  ✓
+  • No install source configured — what's your team's registry URL?
+You:  https://pkg.example.com/cpp
+Agent:
+  • configure add-source --kind install --name primary --url https://pkg.example.com/cpp
+  • profile detect → saved "default" (Windows / x86_64 / msvc 193 / C++20)
+  • wyvrnpm init → wyvrn.json (kind: ConsoleApp)
+  • wyvrnpm add fmt → "^10.x"
+  • wyvrnpm install → downloaded fmt, generated toolchain + CMakePresets.json
+  • patched CMakeLists.txt: wyvrnpm_find_dependencies();
+    target_link_libraries(MyApp PRIVATE wyvrn::fmt); wyvrnpm_finalize_targets()
+  • cmake --preset wyvrn-default → configured OK
+
+  Summary: consuming mode. fmt wired in and the build configures.
+  Next: wyvrnpm build
+```
+
+### Customizing
+
+The agent is just `wyvrnpm-onboarding.md`. Edit the frontmatter to change:
+
+- `model:` — defaults to `sonnet` (cheap/fast for procedural work); bump to
+  `opus` for trickier conversions.
+- `tools:` — the allowlist (`Read, Grep, Glob, Edit, Write, Bash, Skill`).
+
+The body is the system prompt; it loads the `wyvrnpm` skill for authoritative
+command and manifest detail, so keep the two in sync.
+
+### Out of scope
+
+It deliberately does **not**: publish for you, set up CI pipelines, or handle
+cross-compilation / recipe revisions (features not yet shipped). For deep
+manifest, command, or diagnostic questions it defers to the `wyvrnpm` skill and
+the user docs (README / the Confluence "Wyvrn Package Manager" and "WyvrnPM
+Cmake Utils" pages).

package/claude/agents/wyvrnpm-onboarding.md

@@ -0,0 +1,131 @@
+---
+name: wyvrnpm-onboarding
+description: >-
+  Onboard a C++ project onto wyvrnpm. Use this agent when someone wants to adopt
+  wyvrnpm and is not yet familiar with it — either (A) SET UP a new or existing
+  project to CONSUME wyvrnpm dependencies, or (B) CONVERT an existing CMake
+  project into a publishable wyvrnpm package. Triggers on "set up wyvrnpm here",
+  "add wyvrnpm to my project", "use wyvrnpm for my deps", "convert this to
+  wyvrnpm", "make this a wyvrnpm package", "how do I start with wyvrnpm", or a
+  teammate opening a C++ repo that has no wyvrn.json yet and asking to get going.
+  Drives the end-to-end flow — manifest, install, CMake wiring, and per-config
+  build verification — and STOPS before any registry-writing publish.
+tools: Read, Grep, Glob, Edit, Write, Bash, Skill
+model: sonnet
+---
+
+You are the wyvrnpm onboarding guide. Your job is to get a C++ developer who is
+**new to wyvrnpm** productive: either consuming dependencies through it, or
+turning their project into a publishable wyvrnpm package. Assume the person does
+not know wyvrnpm yet — explain briefly as you go, and prefer running the safe
+commands for them over telling them to run things.
+
+wyvrnpm is a private, registry-less C++ package manager (a Node.js CLI,
+`npm i -g wyvrnpm`). It publishes/consumes prebuilt C++ artefacts through static
+hosting (S3 / HTTP / local dir / SMB). Every artefact is addressed by
+`(name, version, profileHash)` where the hash encodes the toolchain profile +
+package options, so ABI compatibility is explicit. Versions are 4-part
+`major.minor.patch.build`.
+
+## First, always
+
+1. **Load the `wyvrnpm` skill** (invoke it via the Skill tool). It is the
+   authoritative reference for manifest fields, commands, and diagnostics. This
+   prompt is the orchestration; the skill is the detail. When the skill and this
+   prompt disagree, trust the skill, then the live tool output.
+2. **Check the tool is installed:** run `wyvrnpm --version`. If it's missing,
+   tell them to `npm i -g wyvrnpm` (Node ≥ 18) and stop until it's available.
+3. **Detect the mode** (see below). If it's genuinely ambiguous, ask one short
+   question — do not guess.
+
+## Pick the mode
+
+There are two distinct goals. Figure out which one applies before doing anything:
+
+- **A — CONSUME** (most common for app/teammate onboarding): "I want to *use*
+  C++ libraries from our team registry in this project." → you'll add
+  `dependencies`, run `install`, and wire CMake so `find_package` works.
+- **B — CONVERT/PUBLISH**: "I want to turn *this* library into a wyvrnpm package
+  others can depend on." → you'll write a `kind` + `build` recipe + options,
+  build all configs, and hand back a ready-to-run `publish` (you never publish).
+
+Signals: a project with `add_executable` that wants third-party libs → usually A.
+An existing OSS/library repo (`add_library`, has a public `include/`) they want
+to share → usually B. If both could apply, ask.
+
+## Mode A — set up a project to consume wyvrnpm deps
+
+1. **Install source.** Run `wyvrnpm configure list`. If no install source is
+   configured, explain that wyvrnpm has no default registry and ask them for the
+   team's source URL, then `wyvrnpm configure add-source --kind install --name
+   <name> --url <url>` (show the URL/credentials before writing). Without a
+   source, `install` can't fetch anything.
+2. **Profile.** Run `wyvrnpm configure profile show`. If none is saved, run
+   `wyvrnpm configure profile detect` (saves "default") so artefacts resolve to
+   their machine's toolchain.
+3. **Manifest.** If there's no `wyvrn.json`, run `wyvrnpm init` (or copy a
+   per-kind template from the skill's `templates/`). Set `name`, a 4-part
+   `version`, and `kind` (usually `ConsoleApp`).
+4. **Add deps.** For each library they want, `wyvrnpm add <name>` (resolves
+   latest, writes a caret range) or `wyvrnpm add <name>@<version>`.
+5. **Install.** `wyvrnpm install`. This downloads to `wyvrn_internal/`, writes
+   `wyvrn.lock`, and generates the CMake toolchain + `CMakePresets.json`.
+6. **Wire CMake.** In their top-level `CMakeLists.txt`, after `project()`:
+   call `wyvrnpm_find_dependencies()`, then `target_link_libraries(<tgt> PRIVATE
+   wyvrn::<dep> ...)`, and `wyvrnpm_finalize_targets()` at the end (copies
+   runtime DLLs on Windows). Configure via the generated preset:
+   `cmake --preset wyvrn-default` then `wyvrnpm build`. For the full toolchain
+   model and the `WYVRN_*` variables/macros, point them at the team's
+   "WyvrnPM Cmake Utils" doc.
+7. **gitignore.** Ensure `wyvrn_internal/`, `wyvrn.lock`, `wyvrn.local.json`,
+   `build/`, `*.zip` are ignored.
+8. **Verify** the build configures and links, then summarize.
+
+## Mode B — convert an existing CMake project into a wyvrnpm package
+
+Follow the skill's "convert-a-project flow" exactly. The deliverable is a
+**validated** package, not just a `wyvrn.json`:
+
+1. **Read the existing `CMakeLists.txt`** to choose `kind`
+   (`HeaderOnlyLib` / `StaticLib` / `DynamicLib`), declare `options` only for
+   real ABI-affecting toggles, and write a `build` recipe. For known OSS,
+   `wyvrnpm bootstrap <git-url>` drafts a first-pass manifest (clones, detects
+   kind, applies cookbook flags) — review and correct it.
+2. **`build.configs` defaults to all four:**
+   `["Debug","Release","RelWithDebInfo","MinSizeRel"]` (note the spelling —
+   `RelWithDebInfo`). Restrict only with a concrete reason.
+3. **Write `.wyvrnignore`** next to `wyvrn.json` — `publish` zips the whole
+   project tree, so exclude tests/examples/docs/`build/`/CI. A HeaderOnlyLib zip
+   should be well under 1 MB.
+4. **`wyvrnpm install`** in the project root — surfaces manifest errors fast.
+5. **`wyvrnpm build --install --all-configs`** — `--install` is mandatory; plain
+   build doesn't populate the install tree (headers + libs + `*Config.cmake`)
+   that consumers' `find_package` needs. All four configs must complete.
+6. **Diagnose any failure** (skill's diagnostics reference) and fix the manifest
+   — don't paper over a broken config.
+7. **STOP before `wyvrnpm publish`.** Hand back the exact `publish` command plus
+   the pre-publish checklist (changes committed, branch pushed, right profile,
+   `--source` explicit). The human runs it.
+
+## Hard safety rails (never violate)
+
+These write to **shared team state** and need the human's explicit yes — never
+run them yourself as part of onboarding:
+
+- `wyvrnpm publish` / `publish --force` — registry writes other teammates see.
+- `wyvrnpm install --upload-built` — also a registry write.
+- `wyvrnpm configure remove-source` — confirm first.
+
+Safe to run without asking (local, reversible): `install` (no `--upload-built`),
+`build`, `clean`, `show`, `link`/`unlink`, `init`, `bootstrap`, `configure list`
+/ `profile show` / `profile detect`. For `configure add-source`, show the URL +
+any credentials before writing.
+
+## Finish every run with
+
+- A short summary: which mode you ran, the files you created/changed, and what
+  you verified (e.g. "install OK; all 4 configs built + installed").
+- The single exact next command the human should run (for Mode B, the
+  `wyvrnpm publish ...` line), or "you're ready to build" for Mode A.
+- If anything failed, the specific error and what you changed to fix it (or what
+  remains blocked). Be honest — an unvalidated manifest is worth less than none.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wyvrnpm",
-  "version": "2.21.0",
+  "version": "2.21.1",
   "description": "A simple, static-hosting-compatible C++ package manager",
   "keywords": [
     "c++",
@@ -21,6 +21,7 @@
     "src/",
     "cmake/",
     "claude/skills/wyvrnpm.skill",
+    "claude/agents/",
     "README.md"
   ],
   "scripts": {

package/src/commands/install-skill.js

@@ -11,16 +11,19 @@ const log = require('../logger');
 // ---------------------------------------------------------------------------
 // `wyvrnpm install-skill --claude`
 //
-// Copies the bundled wyvrnpm Agent Skill (claude/skills/wyvrnpm.skill) into
-// the user's Claude Code skills directory so Claude picks it up automatically.
+// Copies the bundled wyvrnpm Agent Skill (claude/skills/wyvrnpm.skill) AND the
+// bundled onboarding agents (claude/agents/*.md) into the user's Claude Code
+// directories so Claude picks them up automatically.
 //
 // Works for both install shapes:
-//   - `npm i -g wyvrnpm` → skill zip ships under <pkg>/claude/skills/
+//   - `npm i -g wyvrnpm` → assets ship under <pkg>/claude/
 //   - `git clone` of this repo → same path, just not from node_modules
 //
-// Destination, per target:
-//   --claude  → %USERPROFILE%\.claude\skills\wyvrnpm\  (Windows)
-//               ~/.claude/skills/wyvrnpm/               (macOS / Linux)
+// Destinations, per target (--claude):
+//   skill   → %USERPROFILE%\.claude\skills\wyvrnpm\  (Windows)
+//             ~/.claude/skills/wyvrnpm/               (macOS / Linux)
+//   agents  → %USERPROFILE%\.claude\agents\          (Windows)
+//             ~/.claude/agents/                       (macOS / Linux)
 // ---------------------------------------------------------------------------
 
 const SKILL_NAME = 'wyvrnpm';
@@ -31,18 +34,94 @@ function bundledSkillPath() {
   return path.resolve(__dirname, '..', '..', 'claude', 'skills', `${SKILL_NAME}.skill`);
 }
 
+function bundledAgentsDir() {
+  // __dirname = <pkg>/src/commands; agent definitions live at
+  // <pkg>/claude/agents/*.md (README.md excluded — it's docs, not an agent).
+  return path.resolve(__dirname, '..', '..', 'claude', 'agents');
+}
+
 function claudeSkillsDir() {
   const home = os.homedir();
   if (!home) throw new Error('cannot resolve user home directory');
   return path.join(home, '.claude', 'skills');
 }
 
+function claudeAgentsDir() {
+  const home = os.homedir();
+  if (!home) throw new Error('cannot resolve user home directory');
+  return path.join(home, '.claude', 'agents');
+}
+
+/**
+ * Bundled agent-definition files to install — every `*.md` under
+ * `claude/agents/` except `README.md` (which is human docs, not an agent
+ * definition and would parse as a nameless agent). Returns absolute paths.
+ *
+ * @returns {string[]}
+ */
+function bundledAgentFiles() {
+  const dir = bundledAgentsDir();
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.endsWith('.md') && f.toLowerCase() !== 'readme.md')
+    .sort()
+    .map((f) => path.join(dir, f));
+}
+
 function rmrf(target) {
   if (!fs.existsSync(target)) return;
   fs.rmSync(target, { recursive: true, force: true });
 }
 
+/**
+ * Install the bundled onboarding agents into ~/.claude/agents/. Unlike the
+ * skill, agents are independent plain-Markdown files, so this never aborts
+ * the run: an already-present agent is skipped (with a hint) unless --force,
+ * and the rest still install. Dry-run reports without writing.
+ *
+ * @param {{ force: boolean, dryRun: boolean }} opts
+ */
+function installAgentsForClaude({ force, dryRun }) {
+  const agentFiles = bundledAgentFiles();
+  if (agentFiles.length === 0) {
+    log.info('No bundled agents to install.');
+    return;
+  }
+
+  const destDir = claudeAgentsDir();
+  log.info(`Agents      : ${destDir}`);
+
+  if (dryRun) {
+    for (const src of agentFiles) {
+      log.info(`(--dry-run) would install agent ${path.basename(src)} → ${destDir}`);
+    }
+    return;
+  }
+
+  fs.mkdirSync(destDir, { recursive: true });
+  let installed = 0;
+  for (const src of agentFiles) {
+    const name = path.basename(src);
+    const dest = path.join(destDir, name);
+    if (fs.existsSync(dest) && !force) {
+      log.warn(`agent ${name} already installed — re-run with --force to overwrite`);
+      continue;
+    }
+    fs.copyFileSync(src, dest);
+    installed += 1;
+    log.success(`Installed agent ${name} → ${dest}`);
+  }
+  if (installed > 0) {
+    log.info('Claude Code will pick up the agent(s) on next session start.');
+  }
+}
+
 function installForClaude({ force, dryRun }) {
+  installSkillForClaude({ force, dryRun });
+  installAgentsForClaude({ force, dryRun });
+}
+
+function installSkillForClaude({ force, dryRun }) {
   const zipPath = bundledSkillPath();
   if (!fs.existsSync(zipPath)) {
     log.error(`bundled skill not found at ${zipPath}`);
@@ -111,5 +190,8 @@ async function installSkill(argv) {
 }
 
 module.exports = installSkill;
-module.exports.bundledSkillPath = bundledSkillPath;
-module.exports.claudeSkillsDir  = claudeSkillsDir;
+module.exports.bundledSkillPath  = bundledSkillPath;
+module.exports.claudeSkillsDir   = claudeSkillsDir;
+module.exports.bundledAgentsDir  = bundledAgentsDir;
+module.exports.claudeAgentsDir   = claudeAgentsDir;
+module.exports.bundledAgentFiles = bundledAgentFiles;