@forwardimpact/pathway 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/pathway",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Career progression web app and CLI for exploring roles and generating agent teams",
   "license": "Apache-2.0",
   "repository": {
@@ -40,8 +40,8 @@
     "./commands": "./src/commands/index.js"
   },
   "dependencies": {
-    "@forwardimpact/schema": "^0.8.0",
-    "@forwardimpact/model": "^1.0.0",
+    "@forwardimpact/schema": "^0.9.0",
+    "@forwardimpact/model": "^1.1.0",
     "mustache": "^4.2.0",
     "simple-icons": "^16.7.0",
     "yaml": "^2.3.4"

package/src/commands/agent.js

@@ -42,11 +42,17 @@ import {
   buildAgentIndex,
 } from "@forwardimpact/model";
 import { formatAgentProfile } from "../formatters/agent/profile.js";
-import { formatAgentSkill } from "../formatters/agent/skill.js";
+import {
+  formatAgentSkill,
+  formatInstallScript,
+  formatReference,
+} from "../formatters/agent/skill.js";
 import { formatError, formatSuccess } from "../lib/cli-output.js";
 import {
   loadAgentTemplate,
   loadSkillTemplate,
+  loadSkillInstallTemplate,
+  loadSkillReferenceTemplate,
 } from "../lib/template-loader.js";
 import { toolkitToPlainList } from "../formatters/toolkit/markdown.js";
 
@@ -263,25 +269,45 @@ async function writeProfile(profile, baseDir, template) {
 }
 
 /**
- * Write skill files
+ * Write skill files (SKILL.md, scripts/install.sh, references/REFERENCE.md)
  * @param {Array} skills - Generated skills
  * @param {string} baseDir - Base output directory
- * @param {string} template - Mustache template for skills
+ * @param {Object} templates - Templates object with skill, install, reference
  */
-async function writeSkills(skills, baseDir, template) {
+async function writeSkills(skills, baseDir, templates) {
+  let fileCount = 0;
   for (const skill of skills) {
-    const skillPath = join(
-      baseDir,
-      ".claude",
-      "skills",
-      skill.dirname,
-      "SKILL.md",
-    );
-    const skillContent = formatAgentSkill(skill, template);
+    const skillDir = join(baseDir, ".claude", "skills", skill.dirname);
+
+    // Write SKILL.md (always)
+    const skillPath = join(skillDir, "SKILL.md");
+    const skillContent = formatAgentSkill(skill, templates.skill);
     await ensureDir(skillPath);
     await writeFile(skillPath, skillContent, "utf-8");
     console.log(formatSuccess(`Created: ${skillPath}`));
+    fileCount++;
+
+    // Write scripts/install.sh (only when installScript exists)
+    if (skill.installScript) {
+      const installPath = join(skillDir, "scripts", "install.sh");
+      const installContent = formatInstallScript(skill, templates.install);
+      await ensureDir(installPath);
+      await writeFile(installPath, installContent, { mode: 0o755 });
+      console.log(formatSuccess(`Created: ${installPath}`));
+      fileCount++;
+    }
+
+    // Write references/REFERENCE.md (only when implementationReference exists)
+    if (skill.implementationReference) {
+      const refPath = join(skillDir, "references", "REFERENCE.md");
+      const refContent = formatReference(skill, templates.reference);
+      await ensureDir(refPath);
+      await writeFile(refPath, refContent, "utf-8");
+      console.log(formatSuccess(`Created: ${refPath}`));
+      fileCount++;
+    }
   }
+  return fileCount;
 }
 
 /**
@@ -428,7 +454,6 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
     agentBehaviours: agentData.behaviours,
     agentDiscipline,
     agentTrack,
-    capabilities: data.capabilities,
     stages: data.stages,
     agentIndex,
   };
@@ -535,6 +560,13 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
   // Load templates
   const agentTemplate = await loadAgentTemplate(dataDir);
   const skillTemplate = await loadSkillTemplate(dataDir);
+  const installTemplate = await loadSkillInstallTemplate(dataDir);
+  const referenceTemplate = await loadSkillReferenceTemplate(dataDir);
+  const skillTemplates = {
+    skill: skillTemplate,
+    install: installTemplate,
+    reference: referenceTemplate,
+  };
 
   // Output to console (default) or write to files (with --output)
   if (!options.output) {
@@ -548,7 +580,7 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
   for (const profile of profiles) {
     await writeProfile(profile, baseDir, agentTemplate);
   }
-  await writeSkills(skillFiles, baseDir, skillTemplate);
+  const fileCount = await writeSkills(skillFiles, baseDir, skillTemplates);
   await generateVSCodeSettings(baseDir, agentData.vscodeSettings);
   await generateDevcontainer(
     baseDir,
@@ -562,5 +594,5 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
   for (const profile of profiles) {
     console.log(`  - ${profile.frontmatter.name}`);
   }
-  console.log(`  Skills: ${skillFiles.length} files`);
+  console.log(`  Skills: ${fileCount} files`);
 }

package/src/components/code-display.js

@@ -1,7 +1,10 @@
 /**
  * Code Display Component
  *
- * Reusable read-only code block with copy buttons and syntax highlighting.
+ * Collapsible read-only code block with copy buttons and syntax highlighting.
+ * Wrapped in a <details>/<summary> element with the filename and copy buttons
+ * always visible in the summary. Content is lazy-rendered on first open.
+ *
  * Used for markdown content, agent profiles, skills, and code snippets.
  */
 
@@ -20,7 +23,9 @@ export function createCopyButton(content) {
   const btn = button(
     {
       className: "btn btn-sm copy-btn",
-      onClick: async () => {
+      onClick: async (e) => {
+        e.preventDefault();
+        e.stopPropagation();
         try {
           await navigator.clipboard.writeText(content);
           btn.textContent = "✓ Copied!";
@@ -52,7 +57,9 @@ function createCopyHtmlButton(html) {
   const btn = button(
     {
       className: "btn btn-sm btn-secondary copy-btn",
-      onClick: async () => {
+      onClick: async (e) => {
+        e.preventDefault();
+        e.stopPropagation();
         try {
           const blob = new Blob([html], { type: "text/html" });
           const clipboardItem = new ClipboardItem({ "text/html": blob });
@@ -78,27 +85,15 @@ function createCopyHtmlButton(html) {
 }
 
 /**
- * Create a code display component with syntax highlighting and copy button
+ * Create the code <pre> element with syntax highlighting
  * @param {Object} options
- * @param {string} options.content - The code content to display
- * @param {string} [options.language="markdown"] - Language for syntax highlighting
- * @param {string} [options.filename] - Optional filename to display in header
- * @param {string} [options.description] - Optional description text
- * @param {Function} [options.toHtml] - Function to convert content to HTML (enables "Copy as HTML" button)
- * @param {number} [options.minHeight] - Optional minimum height in pixels
- * @param {number} [options.maxHeight] - Optional maximum height in pixels
+ * @param {string} options.content - Code content
+ * @param {string} options.language - Language for highlighting
+ * @param {number} [options.minHeight] - Min height in pixels
+ * @param {number} [options.maxHeight] - Max height in pixels
  * @returns {HTMLElement}
  */
-export function createCodeDisplay({
-  content,
-  language = "markdown",
-  filename,
-  description,
-  toHtml,
-  minHeight,
-  maxHeight,
-}) {
-  // Create highlighted code block
+function createCodeBlock({ content, language, minHeight, maxHeight }) {
   const pre = document.createElement("pre");
   pre.className = "code-display";
   if (minHeight) pre.style.minHeight = `${minHeight}px`;
@@ -108,46 +103,111 @@ export function createCodeDisplay({
   }
 
   const code = document.createElement("code");
-  if (language) {
-    code.className = `language-${language}`;
-  }
+  if (language) code.className = `language-${language}`;
   code.textContent = content;
   pre.appendChild(code);
 
-  // Apply Prism highlighting if available and language specified
   if (language && typeof Prism !== "undefined") {
     Prism.highlightElement(code);
   }
 
-  // Build header content
-  const headerLeft = [];
+  return pre;
+}
+
+/**
+ * Create a collapsible code display component with syntax highlighting and copy buttons.
+ *
+ * Always rendered as a <details>/<summary> element. The filename and copy buttons
+ * appear in the summary (always visible). The code block is in the collapsible body
+ * and is lazy-rendered on first open.
+ *
+ * @param {Object} options
+ * @param {string} options.content - The code content to display
+ * @param {string} [options.language="markdown"] - Language for syntax highlighting
+ * @param {string} [options.filename] - Filename to display in summary
+ * @param {string} [options.description] - Optional description text shown in body
+ * @param {Function} [options.toHtml] - Function to convert content to HTML (enables "Copy as HTML" button)
+ * @param {number} [options.minHeight] - Optional minimum height in pixels
+ * @param {number} [options.maxHeight] - Optional maximum height in pixels
+ * @param {boolean} [options.open=false] - Whether the details element starts open
+ * @returns {HTMLDetailsElement}
+ */
+export function createCodeDisplay({
+  content,
+  language = "markdown",
+  filename,
+  description,
+  toHtml,
+  minHeight,
+  maxHeight,
+  open = false,
+}) {
+  const detailsEl = document.createElement("details");
+  detailsEl.className = "code-display-pane";
+  if (open) detailsEl.open = true;
+
+  // Build summary: filename (left) + copy buttons (right)
+  const summaryEl = document.createElement("summary");
+  summaryEl.className = "code-display-summary";
+
   if (filename) {
-    headerLeft.push(span({ className: "code-display-filename" }, filename));
-  }
-  if (description) {
-    headerLeft.push(p({ className: "text-muted" }, description));
+    summaryEl.appendChild(
+      span({ className: "code-display-filename" }, filename),
+    );
   }
 
-  // Build buttons
   const buttons = [createCopyButton(content)];
   if (toHtml) {
     buttons.push(createCopyHtmlButton(toHtml(content)));
   }
+  summaryEl.appendChild(div({ className: "button-group" }, ...buttons));
 
-  // Only show header if there's content for it
-  const hasHeader = headerLeft.length > 0 || buttons.length > 0;
-
-  return div(
-    { className: "code-display-container" },
-    hasHeader
-      ? div(
-          { className: "code-display-header" },
-          headerLeft.length > 0
-            ? div({ className: "code-display-info" }, ...headerLeft)
-            : null,
-          div({ className: "button-group" }, ...buttons),
-        )
-      : null,
-    pre,
-  );
+  detailsEl.appendChild(summaryEl);
+
+  // Lazy-render body on first open
+  let rendered = false;
+  const renderBody = () => {
+    if (rendered) return;
+    rendered = true;
+
+    const body = div({ className: "code-display-body" });
+
+    if (description) {
+      body.appendChild(p({ className: "text-muted" }, description));
+    }
+
+    body.appendChild(
+      createCodeBlock({ content, language, minHeight, maxHeight }),
+    );
+
+    detailsEl.appendChild(body);
+  };
+
+  if (open) {
+    renderBody();
+  } else {
+    detailsEl.addEventListener("toggle", () => {
+      if (detailsEl.open) renderBody();
+    });
+  }
+
+  return detailsEl;
+}
+
+/**
+ * Wire accordion behaviour on an array of <details> elements.
+ * Opening one pane closes all others.
+ *
+ * @param {HTMLDetailsElement[]} panes - Details elements to accordion
+ */
+export function accordionize(panes) {
+  for (const pane of panes) {
+    pane.addEventListener("toggle", () => {
+      if (pane.open) {
+        for (const other of panes) {
+          if (other !== pane) other.open = false;
+        }
+      }
+    });
+  }
 }

package/src/components/skill-file-viewer.js

@@ -0,0 +1,61 @@
+/**
+ * Skill File Viewer Component
+ *
+ * Vertically stacked collapsible panes for skill files: SKILL.md,
+ * scripts/install.sh, and references/REFERENCE.md.
+ * Reused across agent builder and skill detail pages.
+ *
+ * Each file is rendered as a collapsible code-display pane with
+ * accordion behaviour (only one open at a time).
+ */
+
+import { div } from "../lib/render.js";
+import { createCodeDisplay, accordionize } from "./code-display.js";
+
+/**
+ * @typedef {Object} SkillFile
+ * @property {string} filename - File path for code display header
+ * @property {string} content - File content
+ * @property {string} [language="markdown"] - Syntax highlighting language
+ */
+
+/**
+ * Create a stacked skill file viewer component
+ *
+ * Shows files as vertically stacked collapsible code-display panes.
+ * Only one pane is open at a time (accordion).
+ *
+ * @param {Object} options
+ * @param {SkillFile[]} options.files - Array of files to display
+ * @param {number} [options.maxHeight=300] - Maximum height for code displays
+ * @param {number} [options.openIndex=0] - Initially open pane index (-1 for all closed)
+ * @returns {HTMLElement}
+ */
+export function createSkillFileViewer({
+  files,
+  maxHeight = 300,
+  openIndex = 0,
+}) {
+  if (files.length === 0) return div();
+
+  const container = div({ className: "sfv" });
+  /** @type {HTMLDetailsElement[]} */
+  const panes = [];
+
+  for (let i = 0; i < files.length; i++) {
+    const pane = createCodeDisplay({
+      content: files[i].content,
+      filename: files[i].filename,
+      language: files[i].language || "markdown",
+      maxHeight,
+      open: i === openIndex,
+    });
+    pane.classList.add("sfv-pane");
+    panes.push(pane);
+    container.appendChild(pane);
+  }
+
+  accordionize(panes);
+
+  return container;
+}

package/src/css/bundles/app.css

@@ -26,6 +26,7 @@
 @import "../components/nav.css" layer(components);
 @import "../components/top-bar.css" layer(components);
 @import "../components/command-prompt.css" layer(components);
+@import "../components/skill-file-viewer.css" layer(components);
 
 /* Utilities */
 @import "../components/utilities.css" layer(utilities);

package/src/css/components/forms.css

@@ -103,31 +103,62 @@
     color: var(--color-primary);
   }
 
-  /* Code display - unified component for code/markdown with copy buttons */
-  .code-display-container {
-    display: flex;
-    flex-direction: column;
-    gap: var(--space-sm);
+  /* Code display - collapsible component for code/markdown with copy buttons */
+  .code-display-pane {
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-md);
+    background: var(--color-bg);
+    overflow: hidden;
   }
 
-  .code-display-header {
+  .code-display-summary {
     display: flex;
-    justify-content: space-between;
     align-items: center;
-    flex-wrap: wrap;
-    gap: var(--space-md);
+    gap: var(--space-sm);
+    padding: var(--space-sm) var(--space-md);
+    cursor: pointer;
+    list-style: none;
+    background: var(--color-surface);
+    border-bottom: 1px solid transparent;
   }
 
-  .code-display-info {
-    display: flex;
-    flex-direction: column;
-    gap: var(--space-xs);
+  .code-display-summary::-webkit-details-marker {
+    display: none;
+  }
+
+  .code-display-summary::before {
+    content: "▸";
+    font-size: var(--font-size-xs);
+    color: var(--color-text-muted);
+    flex-shrink: 0;
+  }
+
+  .code-display-pane[open] > .code-display-summary {
+    border-bottom-color: var(--color-border);
+  }
+
+  .code-display-pane[open] > .code-display-summary::before {
+    content: "▾";
+  }
+
+  .code-display-summary .code-display-filename {
     flex: 1;
-    min-width: 200px;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
   }
 
-  .code-display-info .text-muted {
-    margin: 0;
+  .code-display-summary .button-group {
+    flex-shrink: 0;
+  }
+
+  .code-display-body {
+    padding: var(--space-sm) var(--space-md) var(--space-md);
+  }
+
+  .code-display-body .text-muted {
+    margin: 0 0 var(--space-sm);
   }
 
   .code-display-filename {

package/src/css/components/skill-file-viewer.css

@@ -0,0 +1,18 @@
+/**
+ * Skill File Viewer
+ *
+ * Vertically stacked collapsible panes for viewing skill files
+ * (SKILL.md, install.sh, REFERENCE.md).
+ * Uses code-display-pane component with sfv-pane modifier.
+ */
+
+@layer components {
+  .sfv {
+    display: flex;
+    flex-direction: column;
+  }
+
+  .sfv-pane + .sfv-pane {
+    margin-top: var(--space-sm);
+  }
+}

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

@@ -106,7 +106,7 @@
     padding: var(--space-md);
   }
 
-  .agent-card-preview .code-display-container {
+  .agent-card-preview .code-display-pane {
     margin: 0;
   }
 
@@ -146,7 +146,7 @@
     padding: var(--space-sm) var(--space-md) var(--space-md);
   }
 
-  .skill-card-preview .code-display-container {
+  .skill-card-preview .code-display-pane {
     margin: 0;
   }
 
@@ -154,6 +154,17 @@
     max-height: 300px;
   }
 
+  /* Skill card file count badge */
+  .skill-card-badge {
+    font-size: var(--font-size-xs);
+    color: var(--color-text-muted);
+    background: var(--color-surface);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-sm);
+    padding: 0.1em 0.5em;
+    white-space: nowrap;
+  }
+
   .skills-list {
     display: flex;
     flex-direction: column;
@@ -167,59 +178,6 @@
     gap: var(--space-md);
   }
 
-  .role-agent-card {
-    border: 1px solid var(--color-border);
-    border-radius: var(--radius-md);
-    overflow: hidden;
-  }
-
-  .role-agent-card > summary {
-    cursor: pointer;
-    padding: var(--space-md);
-    background: var(--color-bg);
-    border-bottom: 1px solid transparent;
-    list-style: none;
-  }
-
-  .role-agent-card > summary::-webkit-details-marker {
-    display: none;
-  }
-
-  .role-agent-card[open] > summary {
-    border-bottom-color: var(--color-border);
-  }
-
-  .role-agent-header {
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
-  }
-
-  .role-name {
-    font-weight: var(--font-weight-semibold);
-    color: var(--color-text);
-  }
-
-  .role-filename {
-    font-family: var(--font-family-mono);
-    font-size: var(--font-size-xs);
-    color: var(--color-text-muted);
-  }
-
-  .role-agent-content {
-    padding: var(--space-md);
-  }
-
-  .role-description {
-    margin-bottom: var(--space-md);
-  }
-
-  .role-agent-actions {
-    display: flex;
-    gap: var(--space-sm);
-    margin-bottom: var(--space-sm);
-  }
-
   /* Stage agent preview */
   .stage-agent-preview .stage-header {
     display: flex;

package/src/formatters/agent/dom.js

@@ -5,17 +5,7 @@
  * Includes copy and download functionality.
  */
 
-import {
-  div,
-  h2,
-  h3,
-  p,
-  span,
-  button,
-  section,
-  details,
-  summary,
-} from "../../lib/render.js";
+import { div, h2, h3, p, span, button, section } from "../../lib/render.js";
 import { createCodeDisplay } from "../../components/code-display.js";
 import { formatAgentProfile } from "./profile.js";
 import { formatAgentSkill } from "./skill.js";
@@ -163,33 +153,13 @@ function createSkillCard(skill) {
  */
 function createRoleAgentCard(agent) {
   const content = formatAgentProfile(agent);
-  const roleName = agent.frontmatter.name.split("-").pop(); // Extract role suffix (plan, review)
 
-  return details(
-    { className: "role-agent-card" },
-    summary(
-      {},
-      div(
-        { className: "role-agent-header" },
-        span(
-          { className: "role-name" },
-          `${roleName.charAt(0).toUpperCase() + roleName.slice(1)} Agent`,
-        ),
-        span({ className: "role-filename" }, agent.filename),
-      ),
-    ),
-    div(
-      { className: "role-agent-content" },
-      p(
-        { className: "text-muted role-description" },
-        agent.frontmatter.description,
-      ),
-      createCodeDisplay({
-        content,
-        maxHeight: 400,
-      }),
-    ),
-  );
+  return createCodeDisplay({
+    content,
+    filename: agent.filename,
+    description: agent.frontmatter.description,
+    maxHeight: 400,
+  });
 }
 
 /**