@forwardimpact/pathway 0.25.21 → 0.25.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/pathway",
-  "version": "0.25.21",
+  "version": "0.25.22",
   "description": "Career progression web app and CLI for exploring roles and generating agent teams",
   "license": "Apache-2.0",
   "repository": {

package/src/commands/agent.js

@@ -32,11 +32,11 @@ import {
   deriveReferenceLevel,
   deriveAgentSkills,
   generateSkillMarkdown,
-  deriveToolkit,
   getDisciplineAbbreviation,
   toKebabCase,
   interpolateTeamInstructions,
-} from "@forwardimpact/libskill";
+} from "@forwardimpact/libskill/agent";
+import { deriveToolkit } from "@forwardimpact/libskill/toolkit";
 import { formatAgentProfile } from "../formatters/agent/profile.js";
 import { formatError, formatSuccess } from "../lib/cli-output.js";
 import { toolkitToPlainList } from "../formatters/toolkit/markdown.js";
@@ -94,7 +94,7 @@ function showAgentSummary(data, agentData, skillsWithAgent) {
  * @param {Object} agentData - Agent-specific data
  * @returns {Array<{discipline: Object, track: Object, humanDiscipline: Object, humanTrack: Object}>}
  */
-function findValidCombinations(data, agentData) {
+export function findValidCombinations(data, agentData) {
   const pairs = [];
   for (const discipline of agentData.disciplines) {
     for (const track of agentData.tracks) {
@@ -237,10 +237,10 @@ function resolveAgentEntities(data, agentData, disciplineId, trackId) {
  * @param {Object} humanDiscipline
  */
 function printTeamInstructions(agentTrack, humanDiscipline) {
-  const teamInstructions = interpolateTeamInstructions(
+  const teamInstructions = interpolateTeamInstructions({
     agentTrack,
     humanDiscipline,
-  );
+  });
   if (teamInstructions) {
     console.log("# Team Instructions (CLAUDE.md)\n");
     console.log(teamInstructions.trim());
@@ -287,10 +287,10 @@ async function handleSingleStage({
     return;
   }
 
-  const teamInstructions = interpolateTeamInstructions(
+  const teamInstructions = interpolateTeamInstructions({
     agentTrack,
     humanDiscipline,
-  );
+  });
   await writeTeamInstructions(teamInstructions, baseDir);
   await writeProfile(profile, baseDir, agentTemplate);
   await generateClaudeCodeSettings(baseDir, agentData.claudeCodeSettings);
@@ -331,7 +331,9 @@ async function handleAllStages({
   const skillFiles = derivedSkills
     .map((derived) => skillsWithAgent.find((s) => s.id === derived.skillId))
     .filter((skill) => skill?.agent)
-    .map((skill) => generateSkillMarkdown(skill, data.stages));
+    .map((skill) =>
+      generateSkillMarkdown({ skillData: skill, stages: data.stages }),
+    );
 
   for (const profile of profiles) {
     const errors = validateAgentProfile(profile);
@@ -373,10 +375,10 @@ async function handleAllStages({
     return;
   }
 
-  const teamInstructions = interpolateTeamInstructions(
+  const teamInstructions = interpolateTeamInstructions({
     agentTrack,
     humanDiscipline,
-  );
+  });
   await writeTeamInstructions(teamInstructions, baseDir);
   for (const profile of profiles) {
     await writeProfile(profile, baseDir, agentTemplate);

package/src/commands/build-bundle.js

@@ -0,0 +1,88 @@
+/**
+ * Bundle generation for Pathway distribution.
+ *
+ * Emits `bundle.tar.gz` and `install.sh` alongside the static site so
+ * engineers can install `@forwardimpact/pathway` globally via
+ * `curl -fsSL <site>/install.sh | bash`. Invoked from build.js when
+ * `framework.distribution.siteUrl` is configured.
+ */
+
+import { cp, mkdir, rm, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import { execFileSync } from "child_process";
+import Mustache from "mustache";
+
+/**
+ * Generate distribution bundle (bundle.tar.gz + install.sh)
+ * @param {Object} params
+ * @param {string} params.outputDir - Build output directory
+ * @param {string} params.dataDir - Source data directory
+ * @param {string} params.siteUrl - Base URL for the published site
+ * @param {Object} params.framework - Framework configuration
+ * @param {string} params.version - Pathway package version
+ * @param {string} params.templatesDir - Absolute path to pathway/templates
+ */
+export async function generateBundle({
+  outputDir,
+  dataDir,
+  siteUrl,
+  framework,
+  version,
+  templatesDir,
+}) {
+  console.log("📦 Generating distribution bundle...");
+
+  const frameworkTitle = framework.title || "Engineering Pathway";
+
+  // 1. Create temporary bundle directory
+  const bundleDir = join(outputDir, "_bundle");
+  await mkdir(bundleDir, { recursive: true });
+
+  // 2. Generate minimal package.json for the bundle
+  const bundlePkg = {
+    name: "fit-pathway-local",
+    version: version,
+    private: true,
+    dependencies: {
+      "@forwardimpact/pathway": `^${version}`,
+    },
+  };
+  await writeFile(
+    join(bundleDir, "package.json"),
+    JSON.stringify(bundlePkg, null, 2) + "\n",
+  );
+  console.log(`   ✓ package.json (pathway ^${version})`);
+
+  // 3. Copy data files into bundle
+  await cp(dataDir, join(bundleDir, "data"), {
+    recursive: true,
+    dereference: true,
+  });
+  console.log("   ✓ data/");
+
+  // 4. Create tar.gz from the bundle directory
+  execFileSync("tar", [
+    "-czf",
+    join(outputDir, "bundle.tar.gz"),
+    "-C",
+    outputDir,
+    "_bundle",
+  ]);
+  console.log("   ✓ bundle.tar.gz");
+
+  // 5. Clean up temporary bundle directory
+  await rm(bundleDir, { recursive: true });
+
+  // 6. Render install.sh from template
+  const templatePath = join(templatesDir, "install.template.sh");
+  const template = await readFile(templatePath, "utf8");
+  const installScript = Mustache.render(template, {
+    siteUrl: siteUrl.replace(/\/$/, ""),
+    version,
+    frameworkTitle,
+  });
+  await writeFile(join(outputDir, "install.sh"), installScript, {
+    mode: 0o755,
+  });
+  console.log("   ✓ install.sh");
+}

package/src/commands/build-packs.js

@@ -0,0 +1,392 @@
+/**
+ * Pack generation for Pathway distribution.
+ *
+ * Emits one pre-built agent/skill pack per valid discipline/track combination
+ * and two discovery manifests (`.well-known/agent-skills/index.json` for
+ * `npx skills` and `apm.yml` for Microsoft APM). See
+ * specs/320-pathway-ecosystem-distribution for context.
+ *
+ * Invoked from build.js after the distribution bundle has been generated.
+ */
+
+import { mkdir, rm, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import { execFileSync } from "child_process";
+import { createHash } from "crypto";
+
+import { createDataLoader } from "@forwardimpact/map/loader";
+import { createTemplateLoader } from "@forwardimpact/libtemplate";
+import {
+  generateStageAgentProfile,
+  deriveReferenceLevel,
+  deriveAgentSkills,
+  generateSkillMarkdown,
+  interpolateTeamInstructions,
+  getDisciplineAbbreviation,
+  toKebabCase,
+} from "@forwardimpact/libskill/agent";
+
+import { formatAgentProfile } from "../formatters/agent/profile.js";
+import {
+  formatAgentSkill,
+  formatInstallScript,
+  formatReference,
+} from "../formatters/agent/skill.js";
+import { findValidCombinations } from "./agent.js";
+
+/**
+ * Slugify a string for use as a package name.
+ * @param {string} text
+ * @returns {string}
+ */
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Stringify a JSON value with object keys sorted recursively.
+ * Produces deterministic output for digest stability.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function stringifySorted(value) {
+  const seen = new WeakSet();
+  const sort = (v) => {
+    if (v === null || typeof v !== "object") return v;
+    if (seen.has(v)) throw new Error("Cannot stringify circular structure");
+    seen.add(v);
+    if (Array.isArray(v)) return v.map(sort);
+    const out = {};
+    for (const key of Object.keys(v).sort()) out[key] = sort(v[key]);
+    return out;
+  };
+  return JSON.stringify(sort(value), null, 2) + "\n";
+}
+
+/**
+ * Escape a YAML scalar double-quoted value.
+ * @param {string} text
+ * @returns {string}
+ */
+function yamlQuote(text) {
+  return `"${String(text).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * Write a single pack's files to disk under the staging directory.
+ * Calls the formatters directly (silent, no console output).
+ * @param {Object} params
+ * @returns {Promise<void>}
+ */
+async function writePackFiles({
+  packDir,
+  profiles,
+  skillFiles,
+  teamInstructions,
+  agentTemplate,
+  skillTemplates,
+  claudeCodeSettings,
+}) {
+  const claudeDir = join(packDir, ".claude");
+  const agentsDir = join(claudeDir, "agents");
+  const skillsDir = join(claudeDir, "skills");
+
+  await mkdir(agentsDir, { recursive: true });
+  await mkdir(skillsDir, { recursive: true });
+
+  for (const profile of profiles) {
+    const profilePath = join(agentsDir, profile.filename);
+    await writeFile(
+      profilePath,
+      formatAgentProfile(profile, agentTemplate),
+      "utf-8",
+    );
+  }
+
+  for (const skill of skillFiles) {
+    const skillDir = join(skillsDir, skill.dirname);
+    await mkdir(skillDir, { recursive: true });
+
+    await writeFile(
+      join(skillDir, "SKILL.md"),
+      formatAgentSkill(skill, skillTemplates.skill),
+      "utf-8",
+    );
+
+    if (skill.installScript) {
+      const scriptsDir = join(skillDir, "scripts");
+      await mkdir(scriptsDir, { recursive: true });
+      await writeFile(
+        join(scriptsDir, "install.sh"),
+        formatInstallScript(skill, skillTemplates.install),
+        { mode: 0o755 },
+      );
+    }
+
+    if (skill.implementationReference) {
+      const refsDir = join(skillDir, "references");
+      await mkdir(refsDir, { recursive: true });
+      await writeFile(
+        join(refsDir, "REFERENCE.md"),
+        formatReference(skill, skillTemplates.reference),
+        "utf-8",
+      );
+    }
+  }
+
+  if (teamInstructions) {
+    await writeFile(
+      join(claudeDir, "CLAUDE.md"),
+      teamInstructions.trim() + "\n",
+      "utf-8",
+    );
+  }
+
+  // Claude Code settings — matches the CLI path's generateClaudeCodeSettings
+  // output format (no merge with existing files since the staging dir starts
+  // empty).
+  const settings = { ...(claudeCodeSettings || {}) };
+  await writeFile(
+    join(claudeDir, "settings.json"),
+    JSON.stringify(settings, null, 2) + "\n",
+    "utf-8",
+  );
+}
+
+/**
+ * Derive profiles, skills, and team instructions for a single combination.
+ * @param {Object} params
+ * @returns {{profiles: Array, skillFiles: Array, teamInstructions: string|null}}
+ */
+function derivePackContent({
+  discipline,
+  track,
+  humanDiscipline,
+  humanTrack,
+  data,
+  agentData,
+  skillsWithAgent,
+  level,
+}) {
+  const stageParams = {
+    discipline: humanDiscipline,
+    track: humanTrack,
+    level,
+    skills: skillsWithAgent,
+    behaviours: data.behaviours,
+    agentBehaviours: agentData.behaviours,
+    agentDiscipline: discipline,
+    agentTrack: track,
+    stages: data.stages,
+  };
+
+  const profiles = data.stages.map((stage) =>
+    generateStageAgentProfile({ ...stageParams, stage }),
+  );
+
+  const derivedSkills = deriveAgentSkills({
+    discipline: humanDiscipline,
+    track: humanTrack,
+    level,
+    skills: skillsWithAgent,
+  });
+
+  const skillFiles = derivedSkills
+    .map((derived) => skillsWithAgent.find((s) => s.id === derived.skillId))
+    .filter((skill) => skill?.agent)
+    .map((skill) =>
+      generateSkillMarkdown({ skillData: skill, stages: data.stages }),
+    );
+
+  const teamInstructions = interpolateTeamInstructions({
+    agentTrack: track,
+    humanDiscipline,
+  });
+
+  return { profiles, skillFiles, teamInstructions };
+}
+
+/**
+ * Archive a staged pack directory as a deterministic tar.gz and return its
+ * sha256 digest.
+ * @param {string} packDir - Staging directory containing the pack files
+ * @param {string} archivePath - Destination path for the tar.gz
+ * @returns {Promise<string>} sha256 digest string (e.g. "sha256:abc...")
+ */
+async function archivePack(packDir, archivePath) {
+  execFileSync("tar", [
+    "-czf",
+    archivePath,
+    "--sort=name",
+    "--mtime=1970-01-01",
+    "--owner=0",
+    "--group=0",
+    "--numeric-owner",
+    "-C",
+    packDir,
+    ".",
+  ]);
+
+  const bytes = await readFile(archivePath);
+  return "sha256:" + createHash("sha256").update(bytes).digest("hex");
+}
+
+/**
+ * Write the `npx skills` discovery manifest.
+ * @param {string} outputDir
+ * @param {Array<{name: string, description: string, url: string, digest: string}>} packs
+ * @param {string} version
+ */
+async function writeSkillsManifest(outputDir, packs, version) {
+  const wellKnownDir = join(outputDir, ".well-known", "agent-skills");
+  await mkdir(wellKnownDir, { recursive: true });
+  const manifest = {
+    $schema: "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+    skills: packs.map((pack) => ({
+      description: pack.description,
+      digest: pack.digest,
+      name: pack.name,
+      type: "archive",
+      url: pack.url,
+      version,
+    })),
+  };
+  await writeFile(
+    join(wellKnownDir, "index.json"),
+    stringifySorted(manifest),
+    "utf-8",
+  );
+}
+
+/**
+ * Write the Microsoft APM manifest at the site root.
+ * @param {string} outputDir
+ * @param {Array<{name: string, description: string, url: string, digest: string}>} packs
+ * @param {string} version
+ * @param {string} frameworkTitle
+ */
+async function writeApmManifest(outputDir, packs, version, frameworkTitle) {
+  const lines = [
+    `name: ${slugify(frameworkTitle)}`,
+    `version: ${version}`,
+    `description: ${yamlQuote(`${frameworkTitle} agent teams for Claude Code`)}`,
+    "",
+    "skills:",
+  ];
+  for (const pack of packs) {
+    lines.push(`  - name: ${pack.name}`);
+    lines.push(`    description: ${yamlQuote(pack.description)}`);
+    lines.push(`    version: ${version}`);
+    lines.push(`    url: ${yamlQuote(pack.url)}`);
+    lines.push(`    digest: ${yamlQuote(pack.digest)}`);
+  }
+  lines.push("");
+  await writeFile(join(outputDir, "apm.yml"), lines.join("\n"), "utf-8");
+}
+
+/**
+ * Generate pre-built agent/skill packs for installation through ecosystem
+ * tools like `npx skills` and Microsoft APM. One pack per valid
+ * discipline/track combination.
+ *
+ * @param {Object} params
+ * @param {string} params.outputDir - Build output directory
+ * @param {string} params.dataDir - Source data directory
+ * @param {string} params.siteUrl - Base URL for the published site
+ * @param {Object} params.framework - Framework configuration
+ * @param {string} params.version - Pathway package version
+ * @param {string} params.templatesDir - Absolute path to pathway/templates
+ */
+export async function generatePacks({
+  outputDir,
+  dataDir,
+  siteUrl,
+  framework,
+  version,
+  templatesDir,
+}) {
+  console.log("📦 Generating agent/skill packs...");
+
+  const normalizedSiteUrl = siteUrl.replace(/\/$/, "");
+  const frameworkTitle = framework.title || "Engineering Pathway";
+
+  const loader = createDataLoader();
+  const templateLoader = createTemplateLoader(templatesDir);
+
+  const data = await loader.loadAllData(dataDir);
+  const agentData = await loader.loadAgentData(dataDir);
+  const skillsWithAgent = await loader.loadSkillsWithAgentData(dataDir);
+
+  const level = deriveReferenceLevel(data.levels);
+
+  const agentTemplate = templateLoader.load("agent.template.md", dataDir);
+  const skillTemplates = {
+    skill: templateLoader.load("skill.template.md", dataDir),
+    install: templateLoader.load("skill-install.template.sh", dataDir),
+    reference: templateLoader.load("skill-reference.template.md", dataDir),
+  };
+
+  const stagingDir = join(outputDir, "_packs");
+  const packsDir = join(outputDir, "packs");
+  await mkdir(stagingDir, { recursive: true });
+  await mkdir(packsDir, { recursive: true });
+
+  const combinations = findValidCombinations(data, agentData);
+  if (combinations.length === 0) {
+    console.log("   (no valid discipline/track combinations — skipping)");
+    await rm(stagingDir, { recursive: true, force: true });
+    return;
+  }
+
+  const packs = [];
+
+  for (const combination of combinations) {
+    const { discipline, track, humanDiscipline, humanTrack } = combination;
+    const abbrev = getDisciplineAbbreviation(discipline.id);
+    const agentName = `${abbrev}-${toKebabCase(track.id)}`;
+    const specName = humanDiscipline.specialization || humanDiscipline.name;
+    const description = `${specName} (${humanTrack.name}) — agent team`;
+
+    const { profiles, skillFiles, teamInstructions } = derivePackContent({
+      ...combination,
+      data,
+      agentData,
+      skillsWithAgent,
+      level,
+    });
+
+    const packDir = join(stagingDir, agentName);
+    await writePackFiles({
+      packDir,
+      profiles,
+      skillFiles,
+      teamInstructions,
+      agentTemplate,
+      skillTemplates,
+      claudeCodeSettings: agentData.claudeCodeSettings,
+    });
+
+    const archivePath = join(packsDir, `${agentName}.tar.gz`);
+    const digest = await archivePack(packDir, archivePath);
+
+    packs.push({
+      name: agentName,
+      description,
+      url: `${normalizedSiteUrl}/packs/${agentName}.tar.gz`,
+      digest,
+    });
+
+    console.log(`   ✓ packs/${agentName}.tar.gz`);
+  }
+
+  await rm(stagingDir, { recursive: true, force: true });
+
+  await writeSkillsManifest(outputDir, packs, version);
+  console.log("   ✓ .well-known/agent-skills/index.json");
+
+  await writeApmManifest(outputDir, packs, version, frameworkTitle);
+  console.log("   ✓ apm.yml");
+}

package/src/commands/build.js

@@ -3,26 +3,20 @@
  *
  * Generates a static site from the Engineering Pathway data.
  * Copies all necessary files (HTML, JS, CSS) and data to an output directory.
- * Optionally generates a distribution bundle (bundle.tar.gz + install.sh)
- * for local installs by individual engineers.
+ * Optionally delegates to build-bundle and build-packs to produce the
+ * distribution surfaces (bundle.tar.gz + install.sh for the curl|bash flow,
+ * and agent/skill packs for ecosystem tools like `npx skills` and APM) when
+ * `framework.distribution.siteUrl` is configured.
  */
 
-import {
-  cp,
-  mkdir,
-  rm,
-  access,
-  realpath,
-  readFile,
-  writeFile,
-} from "fs/promises";
+import { cp, mkdir, rm, access, realpath, writeFile } from "fs/promises";
 import { readFileSync } from "fs";
 import { join, dirname, relative, resolve } from "path";
 import { fileURLToPath } from "url";
-import { execFileSync } from "child_process";
-import Mustache from "mustache";
 import { createIndexGenerator } from "@forwardimpact/map/index-generator";
 import { createDataLoader } from "@forwardimpact/map/loader";
+import { generateBundle } from "./build-bundle.js";
+import { generatePacks } from "./build-packs.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -201,10 +195,26 @@ ${framework.emojiIcon} Generating ${framework.title} static site...
   );
   console.log(`   ✓ version.json (${version})`);
 
-  // Generate distribution bundle if siteUrl is configured
+  // Generate distribution surfaces if siteUrl is configured
   const siteUrl = options.url || framework.distribution?.siteUrl;
   if (siteUrl) {
-    await generateBundle({ outputDir, dataDir, siteUrl, framework });
+    const templatesDir = join(appDir, "..", "templates");
+    await generateBundle({
+      outputDir,
+      dataDir,
+      siteUrl,
+      framework,
+      version,
+      templatesDir,
+    });
+    await generatePacks({
+      outputDir,
+      dataDir,
+      siteUrl,
+      framework,
+      version,
+      templatesDir,
+    });
   }
 
   // Show summary
@@ -212,7 +222,7 @@ ${framework.emojiIcon} Generating ${framework.title} static site...
 ✅ Site generated successfully!
 
 Output: ${outputDir}
-${siteUrl ? `\nDistribution:\n  ${outputDir}/bundle.tar.gz\n  ${outputDir}/install.sh\n` : ""}
+${siteUrl ? `\nDistribution:\n  ${outputDir}/bundle.tar.gz\n  ${outputDir}/install.sh\n  ${outputDir}/packs/ (agent/skill packs)\n  ${outputDir}/.well-known/agent-skills/index.json\n  ${outputDir}/apm.yml\n` : ""}
 To serve locally:
   cd ${relative(process.cwd(), outputDir) || "."}
   bunx serve .
@@ -228,70 +238,3 @@ function getPathwayVersion() {
   const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
   return pkg.version;
 }
-
-/**
- * Generate distribution bundle (bundle.tar.gz + install.sh)
- * @param {Object} params
- * @param {string} params.outputDir - Build output directory
- * @param {string} params.dataDir - Source data directory
- * @param {string} params.siteUrl - Base URL for the published site
- * @param {Object} params.framework - Framework configuration
- */
-async function generateBundle({ outputDir, dataDir, siteUrl, framework }) {
-  console.log("📦 Generating distribution bundle...");
-
-  const version = getPathwayVersion();
-  const frameworkTitle = framework.title || "Engineering Pathway";
-
-  // 1. Create temporary bundle directory
-  const bundleDir = join(outputDir, "_bundle");
-  await mkdir(bundleDir, { recursive: true });
-
-  // 2. Generate minimal package.json for the bundle
-  const bundlePkg = {
-    name: "fit-pathway-local",
-    version: version,
-    private: true,
-    dependencies: {
-      "@forwardimpact/pathway": `^${version}`,
-    },
-  };
-  await writeFile(
-    join(bundleDir, "package.json"),
-    JSON.stringify(bundlePkg, null, 2) + "\n",
-  );
-  console.log(`   ✓ package.json (pathway ^${version})`);
-
-  // 3. Copy data files into bundle
-  await cp(dataDir, join(bundleDir, "data"), {
-    recursive: true,
-    dereference: true,
-  });
-  console.log("   ✓ data/");
-
-  // 4. Create tar.gz from the bundle directory
-  execFileSync("tar", [
-    "-czf",
-    join(outputDir, "bundle.tar.gz"),
-    "-C",
-    outputDir,
-    "_bundle",
-  ]);
-  console.log("   ✓ bundle.tar.gz");
-
-  // 5. Clean up temporary bundle directory
-  await rm(bundleDir, { recursive: true });
-
-  // 6. Render install.sh from template
-  const templatePath = join(appDir, "..", "templates", "install.template.sh");
-  const template = await readFile(templatePath, "utf8");
-  const installScript = Mustache.render(template, {
-    siteUrl: siteUrl.replace(/\/$/, ""),
-    version,
-    frameworkTitle,
-  });
-  await writeFile(join(outputDir, "install.sh"), installScript, {
-    mode: 0o755,
-  });
-  console.log("   ✓ install.sh");
-}

package/src/commands/job.js

@@ -44,7 +44,11 @@ function formatJob(view, _options, entities, jobTemplate) {
  */
 function printJobList(filteredJobs) {
   for (const job of filteredJobs) {
-    const title = generateJobTitle(job.discipline, job.level, job.track);
+    const title = generateJobTitle({
+      discipline: job.discipline,
+      level: job.level,
+      track: job.track,
+    });
     if (job.track) {
       console.log(
         `${job.discipline.id} ${job.level.id} ${job.track.id}, ${title}`,

package/src/commands/skill.js

@@ -79,7 +79,7 @@ async function formatAgentDetail(skill, stages, templateLoader, dataDir) {
   }
 
   const template = templateLoader.load("skill.template.md", dataDir);
-  const skillMd = generateSkillMarkdown(skill, stages);
+  const skillMd = generateSkillMarkdown({ skillData: skill, stages });
   const output = formatAgentSkill(skillMd, template);
   console.log(output);
 }

package/src/css/pages/agent-builder.css

@@ -33,6 +33,54 @@
     gap: var(--space-xl);
   }
 
+  /* Install section — ecosystem-tool install commands shown between the
+     dropdowns and the preview cards. Uses the same surface treatment as
+     the form so the two blocks read as a matched pair. */
+  .agent-install-section {
+    background: var(--color-surface);
+    border-radius: var(--radius-lg);
+    padding: var(--space-xl);
+    box-shadow: var(--shadow-md);
+    margin-bottom: var(--space-xl);
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-lg);
+  }
+
+  .agent-install-header h2 {
+    margin: 0 0 var(--space-sm) 0;
+  }
+
+  .agent-install-description {
+    margin: 0;
+  }
+
+  .agent-install-commands {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-md);
+  }
+
+  .agent-install-command {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-xs);
+  }
+
+  .agent-install-command-label {
+    margin: 0;
+    font-size: var(--font-size-sm);
+    font-weight: 600;
+    color: var(--color-text-secondary);
+  }
+
+  /* Allow the command prompts inside the install section to grow beyond the
+     600px center-aligned default used on the landing hero. */
+  .agent-install-command .command-prompt {
+    max-width: none;
+    margin: 0;
+  }
+
   /* Agent section — spacing container, no surface */
   .agent-section {
     margin-bottom: var(--space-lg);

package/src/formatters/interview/shared.js

@@ -14,7 +14,9 @@ import {
   deriveDecompositionInterview,
   deriveStakeholderInterview,
 } from "@forwardimpact/libskill/interview";
-import { getOrCreateJob } from "@forwardimpact/libskill/job-cache";
+import { createJobCache } from "@forwardimpact/libskill/job-cache";
+
+const jobCache = createJobCache();
 
 /**
  * Interview type configurations
@@ -140,7 +142,7 @@ export function prepareInterviewDetail({
 }) {
   if (!discipline || !level) return null;
 
-  const job = getOrCreateJob({
+  const job = jobCache.getOrCreate({
     discipline,
     level,
     track,
@@ -275,7 +277,7 @@ export function prepareInterviewBuilderPreview({
     };
   }
 
-  const title = generateJobTitle(discipline, level, track);
+  const title = generateJobTitle({ discipline, level, track });
   const totalSkills = getDisciplineSkillIds(discipline).length;
 
   return {
@@ -320,7 +322,7 @@ export function prepareAllInterviews({
   // Track is optional (null = generalist)
   if (!discipline || !level) return null;
 
-  const job = getOrCreateJob({
+  const job = jobCache.getOrCreate({
     discipline,
     level,
     track,

package/src/formatters/progress/shared.js

@@ -13,7 +13,9 @@ import {
   analyzeCustomProgression,
   getNextLevel,
 } from "@forwardimpact/libskill/progression";
-import { getOrCreateJob } from "@forwardimpact/libskill/job-cache";
+import { createJobCache } from "@forwardimpact/libskill/job-cache";
+
+const jobCache = createJobCache();
 
 /**
  * Get the next level for progression
@@ -22,20 +24,7 @@ import { getOrCreateJob } from "@forwardimpact/libskill/job-cache";
  * @returns {Object|null}
  */
 export function getDefaultTargetLevel(currentLevel, levels) {
-  return getNextLevel(currentLevel, levels);
-}
-
-/**
- * Check if a job combination is valid
- * @param {Object} params
- * @param {Object} params.discipline
- * @param {Object} params.level
- * @param {Object} params.track
- * @param {Array} [params.levels] - All levels for validation
- * @returns {boolean}
- */
-export function isValidCombination({ discipline, level, track, levels }) {
-  return isValidJobCombination({ discipline, level, track, levels });
+  return getNextLevel({ level: currentLevel, levels });
 }
 
 /**
@@ -69,7 +58,7 @@ export function prepareCurrentJob({
 }) {
   if (!discipline || !level) return null;
 
-  const job = getOrCreateJob({
+  const job = jobCache.getOrCreate({
     discipline,
     level,
     track,
@@ -148,8 +137,8 @@ export function prepareCareerProgressPreview({
     };
   }
 
-  const title = generateJobTitle(discipline, level, track);
-  const nextLevel = getNextLevel(level, levels);
+  const title = generateJobTitle({ discipline, level, track });
+  const nextLevel = getNextLevel({ level, levels });
 
   // Find other valid tracks for comparison (exclude current track if any)
   const validTracks = tracks.filter(
@@ -209,7 +198,7 @@ export function prepareProgressDetail({
   if (!fromDiscipline || !fromLevel) return null;
   if (!toDiscipline || !toLevel) return null;
 
-  const fromJob = getOrCreateJob({
+  const fromJob = jobCache.getOrCreate({
     discipline: fromDiscipline,
     level: fromLevel,
     track: fromTrack,
@@ -218,7 +207,7 @@ export function prepareProgressDetail({
     capabilities,
   });
 
-  const toJob = getOrCreateJob({
+  const toJob = jobCache.getOrCreate({
     discipline: toDiscipline,
     level: toLevel,
     track: toTrack,

package/src/formatters/skill/shared.js

@@ -95,11 +95,18 @@ export function prepareSkillDetail(
   if (!skill) return null;
 
   const relatedDisciplines = disciplines
-    .filter((d) => getSkillTypeForDiscipline(d, skill.id) !== null)
+    .filter(
+      (d) =>
+        getSkillTypeForDiscipline({ discipline: d, skillId: skill.id }) !==
+        null,
+    )
     .map((d) => ({
       id: d.id,
       name: d.specialization || d.name,
-      skillType: getSkillTypeForDiscipline(d, skill.id),
+      skillType: getSkillTypeForDiscipline({
+        discipline: d,
+        skillId: skill.id,
+      }),
     }));
 
   const relatedTracks = tracks

package/src/formatters/track/shared.js

@@ -88,7 +88,10 @@ export function prepareTrackDetail(track, { skills, behaviours }) {
   const skillModifiers = track.skillModifiers
     ? Object.entries(track.skillModifiers).map(([key, modifier]) => {
         if (isCapability(key)) {
-          const capabilitySkills = getSkillsByCapability(skills, key);
+          const capabilitySkills = getSkillsByCapability({
+            skills,
+            capability: key,
+          });
           return {
             id: key,
             name: key.charAt(0).toUpperCase() + key.slice(1),

package/src/pages/agent-builder-install.js

@@ -0,0 +1,117 @@
+/**
+ * Agent builder install section
+ *
+ * Surfaces the ecosystem-tool install commands (Microsoft APM and
+ * `npx skills`) for the currently selected discipline/track pack. The packs
+ * themselves are emitted by `fit-pathway build` when
+ * `framework.distribution.siteUrl` is configured — see spec 320 and
+ * `products/pathway/src/commands/build-packs.js`. The pack name derivation
+ * here must stay in sync with that generator so the command points at an
+ * archive that actually exists on the deployed site.
+ */
+
+import { code, div, h2, p, section } from "../lib/render.js";
+import {
+  getDisciplineAbbreviation,
+  toKebabCase,
+} from "@forwardimpact/libskill/agent";
+import { createCommandPrompt } from "../components/command-prompt.js";
+
+/** Stable id for the install section heading (for aria-labelledby). */
+const INSTALL_HEADING_ID = "agent-builder-install-heading";
+
+/**
+ * Derive the pack archive name for a discipline/track combination.
+ * Must match `build-packs.js` → `${abbrev}-${toKebabCase(track.id)}`.
+ * @param {{id: string}} discipline
+ * @param {{id: string}} track
+ * @returns {string}
+ */
+export function getPackName(discipline, track) {
+  return `${getDisciplineAbbreviation(discipline.id)}-${toKebabCase(track.id)}`;
+}
+
+/**
+ * Normalize a site URL by stripping a trailing slash. Matches the
+ * normalization applied by `generatePacks` so the displayed URL lines up
+ * with the manifest entries.
+ * @param {string} siteUrl
+ * @returns {string}
+ */
+function normalizeSiteUrl(siteUrl) {
+  return siteUrl.replace(/\/$/, "");
+}
+
+/**
+ * Build the `apm install` command for a specific pack archive. Targets the
+ * direct archive URL (rather than a registry-style shorthand) because it is
+ * the most durable path through APM's evolving resolution logic and matches
+ * the URL listed in the generated `apm.yml` manifest.
+ * @param {string} siteUrl
+ * @param {string} packName
+ * @returns {string}
+ */
+export function getApmInstallCommand(siteUrl, packName) {
+  return `apm install ${normalizeSiteUrl(siteUrl)}/packs/${packName}.tar.gz`;
+}
+
+/**
+ * Build the `npx skills add` command that discovers the published pack
+ * registry at `<siteUrl>/.well-known/agent-skills/index.json`.
+ * @param {string} siteUrl
+ * @returns {string}
+ */
+export function getSkillsAddCommand(siteUrl) {
+  return `npx skills add ${normalizeSiteUrl(siteUrl)}`;
+}
+
+/**
+ * Render the install section for the selected agent combination. Returns
+ * `null` when no site URL is configured (no packs have been published, so
+ * there is nothing meaningful to install) so the caller can skip rendering.
+ * @param {Object} params
+ * @param {{id: string}} params.discipline - Selected human discipline
+ * @param {{id: string}} params.track - Selected human track
+ * @param {string|undefined} params.siteUrl - Framework distribution site URL
+ * @returns {HTMLElement|null}
+ */
+export function createInstallSection({ discipline, track, siteUrl }) {
+  if (!siteUrl) return null;
+
+  const packName = getPackName(discipline, track);
+  const apmCommand = getApmInstallCommand(siteUrl, packName);
+  const skillsCommand = getSkillsAddCommand(siteUrl);
+
+  return section(
+    {
+      className: "agent-install-section",
+      "aria-labelledby": INSTALL_HEADING_ID,
+    },
+    div(
+      { className: "agent-install-header" },
+      h2({ id: INSTALL_HEADING_ID }, "📦 Install This Agent Team"),
+      p(
+        { className: "text-muted agent-install-description" },
+        "Install the pre-built pack for this discipline × track combination " +
+          "directly through an ecosystem package manager. The pack contains " +
+          "the same stage agents, skills, team instructions, and Claude Code " +
+          "settings shown below — installed into your project's ",
+        code({}, ".claude/"),
+        " directory.",
+      ),
+    ),
+    div(
+      { className: "agent-install-commands" },
+      div(
+        { className: "agent-install-command" },
+        p({ className: "agent-install-command-label" }, "Microsoft APM"),
+        createCommandPrompt(apmCommand),
+      ),
+      div(
+        { className: "agent-install-command" },
+        p({ className: "agent-install-command-label" }, "npx skills"),
+        createCommandPrompt(skillsCommand),
+      ),
+    ),
+  );
+}

package/src/pages/agent-builder-preview.js

@@ -10,8 +10,8 @@ import {
   deriveStageAgent,
   generateSkillMarkdown,
   deriveAgentSkills,
-  deriveToolkit,
-} from "@forwardimpact/libskill";
+} from "@forwardimpact/libskill/agent";
+import { deriveToolkit } from "@forwardimpact/libskill/toolkit";
 import { getStageEmoji } from "../formatters/stage/shared.js";
 import { formatAgentProfile } from "../formatters/agent/profile.js";
 import {
@@ -115,7 +115,7 @@ function deriveSkillData(context) {
   const skillFiles = derivedSkills
     .map((d) => skills.find((s) => s.id === d.skillId))
     .filter((skill) => skill?.agent)
-    .map((skill) => generateSkillMarkdown(skill, stages));
+    .map((skill) => generateSkillMarkdown({ skillData: skill, stages }));
 
   const toolkit = deriveToolkit({
     skillMatrix: derivedSkills,

package/src/pages/agent-builder.js

@@ -18,7 +18,7 @@ import {
 } from "../lib/render.js";
 import { getState } from "../lib/state.js";
 import { loadAgentDataBrowser } from "../lib/yaml-loader.js";
-import { deriveReferenceLevel } from "@forwardimpact/libskill";
+import { deriveReferenceLevel } from "@forwardimpact/libskill/agent";
 import {
   createSelectWithValue,
   createDisciplineSelect,
@@ -30,6 +30,7 @@ import {
   createSingleStagePreview,
   createHelpSection,
 } from "./agent-builder-preview.js";
+import { createInstallSection } from "./agent-builder-install.js";
 
 /** All stages option value */
 const ALL_STAGES_VALUE = "all";
@@ -79,6 +80,7 @@ async function getTemplates() {
  */
 export async function renderAgentBuilder() {
   const { data } = getState();
+  const siteUrl = data.framework?.distribution?.siteUrl;
 
   // Show loading state
   render(
@@ -260,8 +262,27 @@ export async function renderAgentBuilder() {
       templates,
     };
 
+    // Install section (ecosystem-tool install commands) — appears above the
+    // preview cards so the install action is visible before users scroll
+    // through the generated files. Only rendered when the framework has a
+    // published distribution site URL, since the packs only exist at that
+    // URL after a `fit-pathway build`. Must come after the stage-validity
+    // guard below so an invalid stage id (e.g. from a stale bookmark) does
+    // not pair the install card with a "Stage not found" error.
+    function appendInstallSection() {
+      const installSection = createInstallSection({
+        discipline: humanDiscipline,
+        track: humanTrack,
+        siteUrl,
+      });
+      if (installSection) {
+        previewContainer.appendChild(installSection);
+      }
+    }
+
     // Generate preview based on stage selection
     if (stage === ALL_STAGES_VALUE) {
+      appendInstallSection();
       previewContainer.appendChild(createAllStagesPreview(context));
     } else {
       const stageObj = stages.find((s) => s.id === stage);
@@ -274,6 +295,7 @@ export async function renderAgentBuilder() {
         );
         return;
       }
+      appendInstallSection();
       previewContainer.appendChild(createSingleStagePreview(context, stageObj));
     }
   }

package/src/pages/progress.js

@@ -16,8 +16,8 @@ import {
   prepareCurrentJob,
   prepareCustomProgression,
   getDefaultTargetLevel,
-  isValidCombination,
 } from "../formatters/progress/shared.js";
+import { isValidJobCombination } from "@forwardimpact/libskill/derivation";
 import { buildComparisonResult } from "./progress-comparison.js";
 
 /**
@@ -188,7 +188,7 @@ function createComparisonSelectorsSection({
     for (const level of data.levels) {
       // Check trackless combination
       if (
-        isValidCombination({ discipline: selectedDisc, level, track: null })
+        isValidJobCombination({ discipline: selectedDisc, level, track: null })
       ) {
         if (!validLevels.find((g) => g.id === level.id)) {
           validLevels.push(level);
@@ -197,7 +197,7 @@ function createComparisonSelectorsSection({
       }
       // Check each track combination
       for (const track of data.tracks) {
-        if (isValidCombination({ discipline: selectedDisc, level, track })) {
+        if (isValidJobCombination({ discipline: selectedDisc, level, track })) {
           if (!validLevels.find((g) => g.id === level.id)) {
             validLevels.push(level);
           }

package/src/pages/skill.js

@@ -11,7 +11,7 @@ import { prepareSkillsList } from "../formatters/skill/shared.js";
 import { skillToDOM } from "../formatters/skill/dom.js";
 import { skillToCardConfig } from "../lib/card-mappers.js";
 import { getCapabilityEmoji, getConceptEmoji } from "@forwardimpact/map/levels";
-import { generateSkillMarkdown } from "@forwardimpact/libskill";
+import { generateSkillMarkdown } from "@forwardimpact/libskill/agent";
 import { formatAgentSkill } from "../formatters/agent/skill.js";
 
 /** @type {string|null} Cached skill template */
@@ -101,7 +101,10 @@ export async function renderSkillDetail(params) {
   let agentSkillContent;
   if (skill.agent) {
     const template = await getSkillTemplate();
-    const skillData = generateSkillMarkdown(skill, data.stages);
+    const skillData = generateSkillMarkdown({
+      skillData: skill,
+      stages: data.stages,
+    });
     agentSkillContent = formatAgentSkill(skillData, template);
   }
 

package/src/lib/job-cache.js

@@ -1,89 +0,0 @@
-/**
- * Job Cache
- *
- * Centralized caching for generated job definitions.
- * Provides consistent key generation and get-or-create pattern.
- */
-
-import { deriveJob } from "@forwardimpact/libskill/derivation";
-
-/** @type {Map<string, Object>} */
-const cache = new Map();
-
-/**
- * Build a consistent cache key from job parameters
- * @param {string} disciplineId
- * @param {string} levelId
- * @param {string} [trackId] - Optional track ID
- * @returns {string}
- */
-export function buildJobKey(disciplineId, levelId, trackId = null) {
-  if (trackId) {
-    return `${disciplineId}_${levelId}_${trackId}`;
-  }
-  return `${disciplineId}_${levelId}`;
-}
-
-/**
- * Get or create a cached job definition
- * @param {Object} params
- * @param {Object} params.discipline
- * @param {Object} params.level
- * @param {Object} [params.track] - Optional track
- * @param {Array} params.skills
- * @param {Array} params.behaviours
- * @param {Array} [params.capabilities]
- * @returns {Object|null}
- */
-export function getOrCreateJob({
-  discipline,
-  level,
-  track = null,
-  skills,
-  behaviours,
-  capabilities,
-}) {
-  const key = buildJobKey(discipline.id, level.id, track?.id);
-
-  if (!cache.has(key)) {
-    const job = deriveJob({
-      discipline,
-      level,
-      track,
-      skills,
-      behaviours,
-      capabilities,
-    });
-    if (job) {
-      cache.set(key, job);
-    }
-    return job;
-  }
-
-  return cache.get(key);
-}
-
-/**
- * Clear all cached jobs
- */
-export function clearCache() {
-  cache.clear();
-}
-
-/**
- * Invalidate a specific job from the cache
- * @param {string} disciplineId
- * @param {string} levelId
- * @param {string} [trackId] - Optional track ID
- */
-export function invalidateCachedJob(disciplineId, levelId, trackId = null) {
-  cache.delete(buildJobKey(disciplineId, levelId, trackId));
-}
-
-/**
- * Get the number of cached jobs (for testing/debugging)
- * @returns {number}
- */
-export function getCachedJobCount() {
-  return cache.size;
-}