@forwardimpact/pathway 0.24.0 → 0.25.1

package/src/formatters/agent/profile.js

@@ -1,8 +1,8 @@
 /**
  * Agent Profile Formatter
  *
- * Formats agent profile data into .agent.md file content
- * following the GitHub Copilot Custom Agents specification.
+ * Formats agent profile data into .md file content
+ * following the Claude Code agent specification.
  *
  * Uses Mustache templates for flexible output formatting.
  * Templates are loaded from data/ directory with fallback to templates/ directory.
@@ -11,10 +11,7 @@
 import Mustache from "mustache";
 
 import { trimValue, trimRequired, trimFields } from "../shared.js";
-import {
-  flattenToLine,
-  preprocessArrayFrontmatter,
-} from "../template-preprocess.js";
+import { flattenToLine } from "../template-preprocess.js";
 
 /**
  * @typedef {Object} WorkingStyleEntry
@@ -29,8 +26,8 @@ import {
  * @param {Object} params.frontmatter - YAML frontmatter data
  * @param {string} params.frontmatter.name - Agent name
  * @param {string} params.frontmatter.description - Agent description
- * @param {boolean} params.frontmatter.infer - Whether to auto-select
- * @param {Array} [params.frontmatter.handoffs] - Handoff definitions
+ * @param {string} params.frontmatter.model - Claude Code model (sonnet, opus, haiku)
+ * @param {string[]} params.frontmatter.skills - Skill dirnames for auto-loading
  * @param {Object} params.bodyData - Structured body data
  * @param {string} params.bodyData.title - Agent title
  * @param {string} params.bodyData.stageDescription - Stage description text
@@ -43,41 +40,51 @@ import {
  * @param {string} params.bodyData.roleContext - Role context text
  * @param {WorkingStyleEntry[]} params.bodyData.workingStyles - Working style entries
  * @param {string[]} params.bodyData.constraints - List of constraints
- * @param {Array<{id: string, name: string, description: string}>} [params.bodyData.agentIndex] - List of all available agents
- * @param {boolean} [params.bodyData.hasAgentIndex] - Whether agent index is available
+ * @param {Array<{targetStageName: string, summaryInstruction: string, entryCriteria: string[]}>} params.bodyData.stageTransitions - Stage transition definitions
  * @returns {Object} Data object ready for Mustache template
  */
 function prepareAgentProfileData({ frontmatter, bodyData }) {
-  // Preprocess handoffs - flatten prompt field for front matter compatibility
-  const preprocessedHandoffs = preprocessArrayFrontmatter(
-    frontmatter.handoffs,
-    ["prompt"],
+  const stageConstraints = (bodyData.stageConstraints || []).map((c) =>
+    trimRequired(c),
+  );
+  const disciplineConstraints = (bodyData.disciplineConstraints || []).map(
+    (c) => trimRequired(c),
+  );
+  const trackConstraints = (bodyData.trackConstraints || []).map((c) =>
+    trimRequired(c),
+  );
+  const returnFormat = (bodyData.returnFormat || []).map((r) =>
+    trimRequired(r),
   );
-  // Then trim as before
-  const handoffs = trimFields(preprocessedHandoffs, { prompt: "required" });
-
-  const constraints = (bodyData.constraints || []).map((c) => trimRequired(c));
   const skillIndex = trimFields(bodyData.skillIndex, {
     name: "required",
     dirname: "required",
     useWhen: "required",
   });
-  const agentIndex = trimFields(bodyData.agentIndex, {
-    id: "required",
-    name: "required",
-    description: "required",
-  });
   const workingStyles = trimFields(bodyData.workingStyles, {
     title: "required",
     content: "required",
   });
 
+  // Prepare stage transitions for body rendering
+  const stageTransitions = (bodyData.stageTransitions || []).map((t) => ({
+    targetStageName: t.targetStageName,
+    summaryInstruction: trimValue(t.summaryInstruction),
+    entryCriteria: (t.entryCriteria || []).map((c) => trimRequired(c)),
+    hasEntryCriteria: (t.entryCriteria || []).length > 0,
+  }));
+
+  const hasConstraints =
+    stageConstraints.length > 0 ||
+    disciplineConstraints.length > 0 ||
+    trackConstraints.length > 0;
+
   return {
-    // Frontmatter - flatten description for single-line front matter
+    // Frontmatter
     name: frontmatter.name,
     description: flattenToLine(frontmatter.description),
-    infer: frontmatter.infer,
-    handoffs,
+    model: frontmatter.model,
+    skills: frontmatter.skills,
 
     // Body data - trim all string fields
     title: bodyData.title,
@@ -92,22 +99,28 @@ function prepareAgentProfileData({ frontmatter, bodyData }) {
     roleContext: trimValue(bodyData.roleContext),
     workingStyles,
     hasWorkingStyles: workingStyles.length > 0,
-    constraints,
-    hasConstraints: constraints.length > 0,
-    agentIndex,
-    hasAgentIndex: agentIndex.length > 0,
+    stageConstraints,
+    disciplineConstraints,
+    trackConstraints,
+    hasStageConstraints: stageConstraints.length > 0,
+    hasDisciplineOrTrackConstraints:
+      disciplineConstraints.length > 0 || trackConstraints.length > 0,
+    hasConstraints,
+    returnFormat,
+    hasReturnFormat: returnFormat.length > 0,
+    stageTransitions,
+    hasStageTransitions: stageTransitions.length > 0,
   };
 }
 
 /**
- * Format agent profile as .agent.md file content using Mustache template
+ * Format agent profile as .md file content using Mustache template
  * @param {Object} profile - Profile with frontmatter and bodyData
  * @param {Object} profile.frontmatter - YAML frontmatter data
  * @param {string} profile.frontmatter.name - Agent name
  * @param {string} profile.frontmatter.description - Agent description
- * @param {string[]} profile.frontmatter.tools - Available tools
- * @param {boolean} profile.frontmatter.infer - Whether to auto-select
- * @param {Array} [profile.frontmatter.handoffs] - Handoff definitions
+ * @param {string} profile.frontmatter.model - Claude Code model
+ * @param {string[]} profile.frontmatter.skills - Skill dirnames
  * @param {Object} profile.bodyData - Structured body data
  * @param {string} profile.bodyData.title - Agent title (e.g. "Software Engineering - Platform - Plan Agent")
  * @param {string} profile.bodyData.stageDescription - Stage description text
@@ -117,8 +130,9 @@ function prepareAgentProfileData({ frontmatter, bodyData }) {
  * @param {string} profile.bodyData.roleContext - Role context text
  * @param {WorkingStyleEntry[]} profile.bodyData.workingStyles - Working style entries
  * @param {string[]} profile.bodyData.constraints - List of constraints
+ * @param {Array} profile.bodyData.stageTransitions - Stage transitions for body section
  * @param {string} template - Mustache template string
- * @returns {string} Complete .agent.md file content
+ * @returns {string} Complete .md file content
  */
 export function formatAgentProfile({ frontmatter, bodyData }, template) {
   const data = prepareAgentProfileData({ frontmatter, bodyData });

package/src/formatters/job/dom.js

@@ -2,7 +2,7 @@
  * Job formatting for DOM/web output
  */
 
-import { div, h1, h2, p, a, span, section } from "../../lib/render.js";
+import { div, h1, h2, a, section } from "../../lib/render.js";
 import { createBackLink } from "../../components/nav.js";
 import {
   createDetailSection,
@@ -117,7 +117,9 @@ export function jobToDOM(view, options = {}) {
 
           createDetailSection({
             title: "Skill Matrix",
-            content: createSkillMatrix(view.skillMatrix),
+            content: createSkillMatrix(view.skillMatrix, {
+              capabilityOrder: view.capabilityOrder,
+            }),
           }),
 
           // Toolkit (after skill matrix)
@@ -127,21 +129,6 @@ export function jobToDOM(view, options = {}) {
                 content: createToolkitTable(view.toolkit),
               })
             : null,
-
-          // Driver coverage
-          view.driverCoverage.length > 0
-            ? createDetailSection({
-                title: "Driver Coverage",
-                content: div(
-                  {},
-                  p(
-                    { className: "text-muted", style: "margin-bottom: 1rem" },
-                    "How well this job aligns with organizational outcome drivers.",
-                  ),
-                  createDriverCoverageDisplay(view.driverCoverage),
-                ),
-              })
-            : null,
         )
       : null,
 
@@ -164,48 +151,6 @@ export function jobToDOM(view, options = {}) {
   );
 }
 
-/**
- * Create driver coverage display
- */
-function createDriverCoverageDisplay(coverage) {
-  const items = coverage.map((c) => {
-    const percentage = Math.round(c.coverage * 100);
-
-    return div(
-      { className: "driver-coverage-item" },
-      div(
-        { className: "driver-coverage-header" },
-        a(
-          {
-            href: `#/driver/${c.id}`,
-            className: "driver-coverage-name",
-          },
-          c.name,
-        ),
-        span({ className: "driver-coverage-score" }, `${percentage}%`),
-      ),
-      div(
-        { className: "progress-bar" },
-        div({
-          className: "progress-bar-fill",
-          style: `width: ${percentage}%; background: ${getScoreColor(c.coverage)}`,
-        }),
-      ),
-    );
-  });
-
-  return div({ className: "driver-coverage" }, ...items);
-}
-
-/**
- * Get color based on score
- */
-function getScoreColor(score) {
-  if (score >= 0.8) return "#10b981"; // Green
-  if (score >= 0.5) return "#f59e0b"; // Yellow
-  return "#ef4444"; // Red
-}
-
 /**
  * Create the job description section with copy button
  * @param {Object} params
@@ -243,6 +188,7 @@ export function createJobDescriptionSection({
         "Copy this markdown-formatted job description for use in job postings, documentation, or sharing.",
       toHtml: markdownToHtml,
       minHeight: 450,
+      open: true,
     }),
   );
 }

package/src/handout.html

@@ -8,7 +8,7 @@
     <script type="importmap">
       {
         "imports": {
-          "mustache": "https://esm.sh/mustache@4.2.0",
+          "mustache": "/vendor/mustache.mjs",
           "@forwardimpact/map": "/map/lib/index.js",
           "@forwardimpact/map/levels": "/map/lib/levels.js",
           "@forwardimpact/map/loader": "/map/lib/loader.js",

package/src/index.html

@@ -15,12 +15,18 @@
       href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism.min.css"
     />
     <link rel="stylesheet" href="css/bundles/app.css" />
-    <script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js"></script>
-    <script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-markdown.min.js"></script>
+    <script
+      src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js"
+      defer
+    ></script>
+    <script
+      src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-markdown.min.js"
+      defer
+    ></script>
     <script type="importmap">
       {
         "imports": {
-          "mustache": "https://esm.sh/mustache@4.2.0",
+          "mustache": "/vendor/mustache.mjs",
           "@forwardimpact/map": "/map/lib/index.js",
           "@forwardimpact/map/levels": "/map/lib/levels.js",
           "@forwardimpact/map/loader": "/map/lib/loader.js",

package/src/lib/radar.js

@@ -2,6 +2,20 @@
  * Radar chart visualization using SVG
  */
 
+/**
+ * Escape HTML special characters to prevent XSS
+ * @param {string} text
+ * @returns {string}
+ */
+function escapeHtml(text) {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+}
+
 /**
  * @typedef {Object} RadarDataPoint
  * @property {string} label - Label for this axis
@@ -393,9 +407,9 @@ export class RadarChart {
     const y = event.clientY - rect.top;
 
     this.tooltip.innerHTML = `
-      <strong>${data.label}</strong><br>
+      <strong>${escapeHtml(data.label)}</strong><br>
       Value: ${data.value}/${data.maxValue}
-      ${data.description ? `<br><small>${data.description}</small>` : ""}
+      ${data.description ? `<br><small>${escapeHtml(data.description)}</small>` : ""}
     `;
 
     this.tooltip.style.left = `${x + 10}px`;
@@ -815,9 +829,9 @@ export class ComparisonRadarChart {
     const typeLabel = type === "current" ? "Current" : "Target";
 
     this.tooltip.innerHTML = `
-      <strong>${data.label}</strong><br>
+      <strong>${escapeHtml(data.label)}</strong><br>
       ${typeLabel}: ${data.value}/${data.maxValue}
-      ${data.description ? `<br><small>${data.description}</small>` : ""}
+      ${data.description ? `<br><small>${escapeHtml(data.description)}</small>` : ""}
     `;
 
     this.tooltip.style.left = `${x + 10}px`;
@@ -844,7 +858,7 @@ export class ComparisonRadarChart {
           : "<span style='color: #94a3b8'>No change</span>";
 
     this.tooltip.innerHTML = `
-      <strong>${currentData.label}</strong><br>
+      <strong>${escapeHtml(currentData.label)}</strong><br>
       Current: ${currentData.value}/${currentData.maxValue}<br>
       Target: ${targetData.value}/${targetData.maxValue}<br>
       ${diffText}

package/src/lib/yaml-loader.js

@@ -287,27 +287,15 @@ export async function loadAllData(dataDir = "./data") {
  * @returns {Promise<Object>}
  */
 export async function loadAgentDataBrowser(dataDir = "./data") {
-  const [
-    disciplines,
-    tracks,
-    behaviours,
-    vscodeSettings,
-    devcontainer,
-    copilotSetupSteps,
-  ] = await Promise.all([
-    loadDisciplinesFromDir(`${dataDir}/disciplines`),
-    loadTracksFromDir(`${dataDir}/tracks`),
-    loadBehavioursFromDir(`${dataDir}/behaviours`),
-    tryLoadYamlFile(`${dataDir}/repository/vscode-settings.yaml`).then(
-      (r) => r ?? tryLoadYamlFile(`${dataDir}/vscode-settings.yaml`),
-    ),
-    tryLoadYamlFile(`${dataDir}/repository/devcontainer.yaml`).then(
-      (r) => r ?? tryLoadYamlFile(`${dataDir}/devcontainer.yaml`),
-    ),
-    tryLoadYamlFile(`${dataDir}/repository/copilot-setup-steps.yaml`).then(
-      (r) => r ?? tryLoadYamlFile(`${dataDir}/copilot-setup-steps.yaml`),
-    ),
-  ]);
+  const [disciplines, tracks, behaviours, claudeCodeSettings] =
+    await Promise.all([
+      loadDisciplinesFromDir(`${dataDir}/disciplines`),
+      loadTracksFromDir(`${dataDir}/tracks`),
+      loadBehavioursFromDir(`${dataDir}/behaviours`),
+      tryLoadYamlFile(`${dataDir}/repository/claude-code-settings.yaml`).then(
+        (r) => r ?? tryLoadYamlFile(`${dataDir}/claude-code-settings.yaml`),
+      ),
+    ]);
 
   return {
     disciplines: disciplines
@@ -319,8 +307,6 @@ export async function loadAgentDataBrowser(dataDir = "./data") {
     behaviours: behaviours
       .filter((b) => b.agent)
       .map((b) => ({ id: b.id, ...b.agent })),
-    vscodeSettings: vscodeSettings || {},
-    devcontainer: devcontainer || {},
-    copilotSetupSteps: copilotSetupSteps || null,
+    claudeCodeSettings: claudeCodeSettings || {},
   };
 }

package/src/pages/agent-builder.js

@@ -28,7 +28,6 @@ import {
   deriveAgentSkills,
   deriveReferenceLevel,
   deriveToolkit,
-  buildAgentIndex,
 } from "@forwardimpact/libskill";
 import {
   createSelectWithValue,
@@ -259,15 +258,6 @@ export async function renderAgentBuilder() {
     // Get reference level for derivation
     const level = deriveReferenceLevel(data.levels);
 
-    // Build agent index for all valid combinations
-    const agentIndex = buildAgentIndex({
-      disciplines: data.disciplines,
-      tracks: data.tracks,
-      stages,
-      agentDisciplines: agentData.disciplines,
-      agentTracks: agentData.tracks,
-    });
-
     // Build context for generation
     const context = {
       humanDiscipline,
@@ -279,10 +269,8 @@ export async function renderAgentBuilder() {
       skills: data.skills,
       behaviours: data.behaviours,
       agentBehaviours: agentData.behaviours,
-      vscodeSettings: agentData.vscodeSettings,
-      devcontainer: agentData.devcontainer,
+      claudeCodeSettings: agentData.claudeCodeSettings,
       templates,
-      agentIndex,
     };
 
     // Generate preview based on stage selection
@@ -316,7 +304,7 @@ export async function renderAgentBuilder() {
       p(
         { className: "page-description" },
         "Generate coding agent teams from discipline × track × stage combinations. " +
-          "Export complete agent profiles and skill files for GitHub Copilot.",
+          "Export complete agent profiles and skill files for Claude Code.",
       ),
     ),
 
@@ -456,10 +444,8 @@ function createAllStagesPreview(context) {
     skills,
     behaviours,
     agentBehaviours,
-    vscodeSettings,
-    devcontainer,
+    claudeCodeSettings,
     templates,
-    agentIndex,
   } = context;
 
   // Generate all stage agents
@@ -474,7 +460,6 @@ function createAllStagesPreview(context) {
       agentBehaviours,
       agentDiscipline,
       agentTrack,
-      stages,
     });
 
     const profile = generateStageAgentProfile({
@@ -488,7 +473,6 @@ function createAllStagesPreview(context) {
       agentDiscipline,
       agentTrack,
       stages,
-      agentIndex,
     });
 
     return { stage, derived, profile };
@@ -521,8 +505,7 @@ function createAllStagesPreview(context) {
     createDownloadAllButton(
       stageAgents,
       skillFiles,
-      vscodeSettings,
-      devcontainer,
+      claudeCodeSettings,
       context,
     ),
 
@@ -532,7 +515,7 @@ function createAllStagesPreview(context) {
       h2({}, `Agents (${stageAgents.length})`),
       p(
         { className: "text-muted" },
-        "Stage-specific agents with appropriate tools, constraints, and handoffs.",
+        "Stage-specific agents with skills, constraints, and stage transitions.",
       ),
       div(
         { className: "agent-cards-grid" },
@@ -598,11 +581,9 @@ function createSingleStagePreview(context, stage) {
     skills,
     behaviours,
     agentBehaviours,
-    vscodeSettings,
-    devcontainer,
+    claudeCodeSettings,
     stages,
     templates,
-    agentIndex,
   } = context;
 
   const profile = generateStageAgentProfile({
@@ -616,7 +597,6 @@ function createSingleStagePreview(context, stage) {
     agentDiscipline,
     agentTrack,
     stages,
-    agentIndex,
   });
 
   // Get skills for this stage (using full derived skills)
@@ -645,8 +625,7 @@ function createSingleStagePreview(context, stage) {
     createDownloadSingleButton(
       profile,
       skillFiles,
-      vscodeSettings,
-      devcontainer,
+      claudeCodeSettings,
       templates,
     ),
 
@@ -756,16 +735,14 @@ function buildSkillFileCard(skill, templates) {
  * Create download all button for all stages
  * @param {Array} stageAgents - Array of {stage, derived, profile}
  * @param {Array} skillFiles - Array of skill file objects
- * @param {Object} vscodeSettings - VS Code settings
- * @param {Object} devcontainer - Devcontainer config
+ * @param {Object} claudeCodeSettings - Claude Code settings
  * @param {Object} context - Context with discipline/track info and templates
  * @returns {HTMLElement}
  */
 function createDownloadAllButton(
   stageAgents,
   skillFiles,
-  vscodeSettings,
-  devcontainer,
+  claudeCodeSettings,
   context,
 ) {
   const { humanDiscipline, humanTrack, templates } = context;
@@ -783,10 +760,10 @@ function createDownloadAllButton(
       const JSZip = await importJSZip();
       const zip = new JSZip();
 
-      // Add all stage agent profiles
+      // Add all stage agent profiles to .claude/agents/
       for (const { profile } of stageAgents) {
         const content = formatAgentProfile(profile, templates.agent);
-        zip.file(`.github/agents/${profile.filename}`, content);
+        zip.file(`.claude/agents/${profile.filename}`, content);
       }
 
       // Add skills (SKILL.md + optional install script + optional reference)
@@ -812,27 +789,11 @@ function createDownloadAllButton(
         }
       }
 
-      // Add VS Code settings
-      if (Object.keys(vscodeSettings).length > 0) {
-        zip.file(
-          ".vscode/settings.json",
-          JSON.stringify(vscodeSettings, null, 2) + "\n",
-        );
-      }
-
-      // Add devcontainer.json with VS Code settings embedded
-      if (devcontainer && Object.keys(devcontainer).length > 0) {
-        const devcontainerJson = {
-          ...devcontainer,
-          customizations: {
-            vscode: {
-              settings: vscodeSettings,
-            },
-          },
-        };
+      // Add Claude Code settings
+      if (Object.keys(claudeCodeSettings).length > 0) {
         zip.file(
-          ".devcontainer/devcontainer.json",
-          JSON.stringify(devcontainerJson, null, 2) + "\n",
+          ".claude/settings.json",
+          JSON.stringify(claudeCodeSettings, null, 2) + "\n",
         );
       }
 
@@ -861,16 +822,14 @@ function createDownloadAllButton(
  * Create download button for single stage
  * @param {Object} profile - Agent profile
  * @param {Array} skillFiles - Skill files
- * @param {Object} vscodeSettings - VS Code settings
- * @param {Object} devcontainer - Devcontainer config
+ * @param {Object} claudeCodeSettings - Claude Code settings
  * @param {{agent: string, skill: string}} templates - Mustache templates
  * @returns {HTMLElement}
  */
 function createDownloadSingleButton(
   profile,
   skillFiles,
-  vscodeSettings,
-  devcontainer,
+  claudeCodeSettings,
   templates,
 ) {
   const btn = document.createElement("button");
@@ -885,9 +844,9 @@ function createDownloadSingleButton(
       const JSZip = await importJSZip();
       const zip = new JSZip();
 
-      // Add profile
+      // Add profile to .claude/agents/
       const content = formatAgentProfile(profile, templates.agent);
-      zip.file(`.github/agents/${profile.filename}`, content);
+      zip.file(`.claude/agents/${profile.filename}`, content);
 
       // Add skills (SKILL.md + optional install script + optional reference)
       for (const skill of skillFiles) {
@@ -912,27 +871,11 @@ function createDownloadSingleButton(
         }
       }
 
-      // Add VS Code settings
-      if (Object.keys(vscodeSettings).length > 0) {
-        zip.file(
-          ".vscode/settings.json",
-          JSON.stringify(vscodeSettings, null, 2) + "\n",
-        );
-      }
-
-      // Add devcontainer.json with VS Code settings embedded
-      if (devcontainer && Object.keys(devcontainer).length > 0) {
-        const devcontainerJson = {
-          ...devcontainer,
-          customizations: {
-            vscode: {
-              settings: vscodeSettings,
-            },
-          },
-        };
+      // Add Claude Code settings
+      if (Object.keys(claudeCodeSettings).length > 0) {
         zip.file(
-          ".devcontainer/devcontainer.json",
-          JSON.stringify(devcontainerJson, null, 2) + "\n",
+          ".claude/settings.json",
+          JSON.stringify(claudeCodeSettings, null, 2) + "\n",
         );
       }
 
@@ -982,7 +925,7 @@ function createHelpSection() {
         p(
           {},
           "Agents are generated for each stage: Plan (research), Code (implement), and Review (verify). " +
-            "Each stage has specific tools, constraints, and handoffs.",
+            "Each stage has specific skills, constraints, and stage transitions.",
         ),
       ),
       div(
@@ -990,8 +933,8 @@ function createHelpSection() {
         div({ className: "detail-item-label" }, "Agent Profiles"),
         p(
           {},
-          "The .agent.md files contain the agent's identity, capabilities, and constraints. " +
-            "Place them in .github/agents/ to register with GitHub Copilot.",
+          "The .md files contain the agent's identity, skills, and constraints. " +
+            "Place them in .claude/agents/ for Claude Code to discover.",
         ),
       ),
       div(

package/src/pages/landing.js

@@ -299,7 +299,7 @@ export function renderLanding() {
           p(
             {},
             "Generate coding agent team configurations from discipline × track combinations " +
-              "for GitHub Copilot custom agents.",
+              "for Claude Code agents.",
           ),
           div(
             { className: "page-actions", style: "justify-content: center" },