@forwardimpact/pathway 0.3.0 → 0.5.0

package/app/model/agent.js

@@ -225,21 +225,13 @@ function buildWorkingStyleFromBehaviours(
   return sections.join("\n");
 }
 
-/**
- * Stage ID to display name and next stage mapping
- */
-const STAGE_INFO = {
-  plan: { name: "Plan", nextStage: "Code" },
-  code: { name: "Code", nextStage: "Review" },
-  review: { name: "Review", nextStage: "Complete" },
-};
-
 /**
  * Generate SKILL.md content from skill data
  * @param {Object} skillData - Skill with agent section containing stages
+ * @param {Array} stages - All stage entities
  * @returns {Object} Skill with frontmatter, title, stages array, reference, dirname
  */
-export function generateSkillMd(skillData) {
+export function generateSkillMd(skillData, stages) {
   const { agent, name } = skillData;
 
   if (!agent) {
@@ -250,17 +242,31 @@ export function generateSkillMd(skillData) {
     throw new Error(`Skill ${skillData.id} agent section missing stages`);
   }
 
+  // Build stage lookup map
+  const stageMap = new Map(stages.map((s) => [s.id, s]));
+
   // Transform stages object to array for template rendering
   const stagesArray = Object.entries(agent.stages).map(
     ([stageId, stageData]) => {
-      const info = STAGE_INFO[stageId] || {
-        name: stageId,
-        nextStage: "Next",
-      };
+      const stageEntity = stageMap.get(stageId);
+      const stageName = stageEntity?.name || stageId;
+
+      // Find next stage from handoffs
+      let nextStageName = "Complete";
+      if (stageEntity?.handoffs) {
+        const nextHandoff = stageEntity.handoffs.find(
+          (h) => h.targetStage !== stageId,
+        );
+        if (nextHandoff) {
+          const nextStage = stageMap.get(nextHandoff.targetStage);
+          nextStageName = nextStage?.name || nextHandoff.targetStage;
+        }
+      }
+
       return {
         stageId,
-        stageName: info.name,
-        nextStageName: info.nextStage,
+        stageName,
+        nextStageName,
         focus: stageData.focus,
         activities: stageData.activities || [],
         ready: stageData.ready || [],
@@ -277,11 +283,13 @@ export function generateSkillMd(skillData) {
   return {
     frontmatter: {
       name: agent.name,
-      description: agent.description.trim(),
+      description: agent.description,
+      useWhen: agent.useWhen || "",
     },
     title: name,
     stages: stagesArray,
-    reference: agent.reference ? agent.reference.trim() : "",
+    reference: skillData.implementationReference || "",
+    toolReferences: skillData.toolReferences || [],
     dirname: agent.name,
   };
 }
@@ -312,8 +320,11 @@ function estimateBodyDataLength(bodyData) {
   }
 
   // Array fields
-  if (bodyData.capabilities) {
-    length += bodyData.capabilities.join(", ").length;
+  if (bodyData.skillIndex) {
+    for (const skill of bodyData.skillIndex) {
+      length +=
+        skill.name.length + skill.dirname.length + skill.useWhen.length + 50;
+    }
   }
   if (bodyData.beforeMakingChanges) {
     for (const item of bodyData.beforeMakingChanges) {
@@ -483,6 +494,7 @@ function getChecklistStage(stageId) {
  * @param {Array} params.derivedSkills - Skills sorted by level
  * @param {Array} params.derivedBehaviours - Behaviours sorted by maturity
  * @param {Array} params.agentBehaviours - Agent behaviour definitions
+ * @param {Array} params.skills - All skill definitions (for agent section lookup)
  * @param {string} params.checklistMarkdown - Pre-formatted checklist markdown
  * @returns {Object} Structured profile body data
  */
@@ -495,6 +507,7 @@ function buildStageProfileBodyData({
   derivedSkills,
   derivedBehaviours,
   agentBehaviours,
+  skills,
   checklistMarkdown,
 }) {
   const name = `${humanDiscipline.specialization || humanDiscipline.name} - ${humanTrack.name}`;
@@ -524,8 +537,18 @@ function buildStageProfileBodyData({
     ? substituteTemplateVars(rawDelegation, humanDiscipline)
     : null;
 
-  // Primary capabilities from derived skills
-  const capabilities = derivedSkills.slice(0, 6).map((s) => s.skillName);
+  // Build skill index from derived skills with agent sections
+  const skillIndex = derivedSkills
+    .map((derived) => {
+      const skill = skills.find((s) => s.id === derived.skillId);
+      if (!skill?.agent) return null;
+      return {
+        name: derived.skillName,
+        dirname: skill.agent.name,
+        useWhen: skill.agent.useWhen?.trim() || "",
+      };
+    })
+    .filter(Boolean);
 
   // Operational Context - use track's roleContext (shared with human job descriptions)
   const operationalContext = humanTrack.roleContext.trim();
@@ -549,7 +572,7 @@ function buildStageProfileBodyData({
     stageDescription: stage.description,
     identity: identity.trim(),
     priority: priority ? priority.trim() : null,
-    capabilities,
+    skillIndex,
     beforeMakingChanges,
     delegation: delegation ? delegation.trim() : null,
     operationalContext,
@@ -711,6 +734,7 @@ export function generateStageAgentProfile({
     derivedSkills: agent.derivedSkills,
     derivedBehaviours: agent.derivedBehaviours,
     agentBehaviours,
+    skills,
     checklistMarkdown,
   });
 

package/app/model/checklist.js

@@ -72,7 +72,7 @@ export function deriveChecklist({
       capability: {
         id: capability.id,
         name: capability.name,
-        emoji: capability.emoji,
+        emojiIcon: capability.emojiIcon,
       },
       items: stageData.ready,
     });
@@ -94,7 +94,7 @@ export function formatChecklistMarkdown(checklist) {
   }
 
   const sections = checklist.map(({ skill, capability, items }) => {
-    const header = `**${capability.emoji} ${skill.name}**`;
+    const header = `**${capability.emojiIcon} ${skill.name}**`;
     const itemList = items.map((item) => `- [ ] ${item}`).join("\n");
     return `${header}\n\n${itemList}`;
   });

package/app/model/derivation.js

@@ -376,17 +376,17 @@ export function isValidJobCombination({
  * @returns {string} Generated job title
  */
 export function generateJobTitle(discipline, grade, track = null) {
-  const { roleTitle, specialization, isManagement } = discipline;
+  const { roleTitle, isManagement } = discipline;
   const { professionalTitle, managementTitle } = grade;
 
   // Management discipline (no track needed)
   if (isManagement && !track) {
-    return `${managementTitle}, ${specialization}`;
+    return `${managementTitle}, ${roleTitle}`;
   }
 
   // Management discipline with track
   if (isManagement && track) {
-    return `${managementTitle}, ${track.name}`;
+    return `${managementTitle}, ${roleTitle} – ${track.name}`;
   }
 
   // IC discipline with track
@@ -437,7 +437,7 @@ function generateJobId(discipline, grade, track = null) {
  * @param {import('./levels.js').SkillMatrixEntry[]} params.skillMatrix - Derived skill matrix for the job
  * @param {Object[]} params.capabilities - Capability definitions with responsibilities
  * @param {import('./levels.js').Discipline} params.discipline - The discipline (determines which responsibilities to use)
- * @returns {Array<{capability: string, capabilityName: string, emoji: string, responsibility: string, level: string}>}
+ * @returns {Array<{capability: string, capabilityName: string, emojiIcon: string, responsibility: string, level: string}>}
  */
 export function deriveResponsibilities({
   skillMatrix,
@@ -484,7 +484,7 @@ export function deriveResponsibilities({
       responsibilities.push({
         capability: capabilityId,
         capabilityName: capability.name,
-        emoji: capability.emoji || "💡",
+        emojiIcon: capability.emojiIcon || "💡",
         displayOrder: capability.displayOrder ?? 999,
         responsibility: responsibilityText,
         level,

package/app/model/levels.js

@@ -90,6 +90,7 @@ export const Capability = {
   RELIABILITY: "reliability",
   DATA: "data",
   AI: "ai",
+  ML: "ml",
   PROCESS: "process",
   BUSINESS: "business",
   PEOPLE: "people",
@@ -111,6 +112,7 @@ export const CAPABILITY_ORDER = [
   Capability.DELIVERY,
   Capability.DATA,
   Capability.AI,
+  Capability.ML,
   Capability.SCALE,
   Capability.RELIABILITY,
   Capability.PEOPLE,
@@ -218,7 +220,7 @@ export function getCapabilityOrder(capabilities) {
  */
 export function getCapabilityEmoji(capabilities, capabilityId) {
   const capability = getCapabilityById(capabilities, capabilityId);
-  return capability?.emoji || "💡";
+  return capability?.emojiIcon || "💡";
 }
 
 /**
@@ -595,5 +597,5 @@ export function behaviourMaturityMeetsRequirement(actual, required) {
  * @returns {string} The emoji for the concept or default "💡"
  */
 export function getConceptEmoji(framework, concept) {
-  return framework?.entityDefinitions?.[concept]?.emoji || "💡";
+  return framework?.entityDefinitions?.[concept]?.emojiIcon || "💡";
 }

package/app/model/loader.js

@@ -84,7 +84,15 @@ async function loadSkillsFromCapabilities(capabilitiesDir) {
 
     if (capability.skills && Array.isArray(capability.skills)) {
       for (const skill of capability.skills) {
-        const { id, name, isHumanOnly, human, agent } = skill;
+        const {
+          id,
+          name,
+          isHumanOnly,
+          human,
+          agent,
+          implementationReference,
+          toolReferences,
+        } = skill;
         allSkills.push({
           id,
           name,
@@ -95,6 +103,9 @@ async function loadSkillsFromCapabilities(capabilitiesDir) {
           ...(isHumanOnly && { isHumanOnly }),
           // Preserve agent section for agent generation
           ...(agent && { agent }),
+          // Include implementation reference and tool references (shared by human and agent)
+          ...(implementationReference && { implementationReference }),
+          ...(toolReferences && { toolReferences }),
         });
       }
     }

package/app/model/validation.js

@@ -241,17 +241,13 @@ function validateSkill(skill, index, requiredStageIds = []) {
       }
     }
 
-    // reference is optional but should be a string if present
-    if (
-      skill.agent.reference !== undefined &&
-      typeof skill.agent.reference !== "string"
-    ) {
+    // Error if old 'reference' field is still present (moved to skill.implementationReference)
+    if (skill.agent.reference !== undefined) {
       errors.push(
         createError(
-          "INVALID_VALUE",
-          "Skill agent reference must be a string",
+          "INVALID_FIELD",
+          "Skill agent 'reference' field is not supported. Use skill.implementationReference instead.",
           `${agentPath}.reference`,
-          skill.agent.reference,
         ),
       );
     }
@@ -295,6 +291,76 @@ function validateSkill(skill, index, requiredStageIds = []) {
     }
   }
 
+  // Validate implementationReference if present (optional string)
+  if (
+    skill.implementationReference !== undefined &&
+    typeof skill.implementationReference !== "string"
+  ) {
+    errors.push(
+      createError(
+        "INVALID_VALUE",
+        "Skill implementationReference must be a string",
+        `${path}.implementationReference`,
+        skill.implementationReference,
+      ),
+    );
+  }
+
+  // Validate toolReferences array if present
+  if (skill.toolReferences !== undefined) {
+    if (!Array.isArray(skill.toolReferences)) {
+      errors.push(
+        createError(
+          "INVALID_VALUE",
+          "Skill toolReferences must be an array",
+          `${path}.toolReferences`,
+          skill.toolReferences,
+        ),
+      );
+    } else {
+      skill.toolReferences.forEach((tool, i) => {
+        const toolPath = `${path}.toolReferences[${i}]`;
+        if (!tool.name) {
+          errors.push(
+            createError(
+              "MISSING_REQUIRED",
+              "Tool reference missing name",
+              `${toolPath}.name`,
+            ),
+          );
+        }
+        if (!tool.description) {
+          errors.push(
+            createError(
+              "MISSING_REQUIRED",
+              "Tool reference missing description",
+              `${toolPath}.description`,
+            ),
+          );
+        }
+        if (!tool.useWhen) {
+          errors.push(
+            createError(
+              "MISSING_REQUIRED",
+              "Tool reference missing useWhen",
+              `${toolPath}.useWhen`,
+            ),
+          );
+        }
+        if (tool.url !== undefined && typeof tool.url !== "string") {
+          errors.push(
+            createError(
+              "INVALID_VALUE",
+              "Tool reference url must be a string",
+              `${toolPath}.url`,
+              tool.url,
+            ),
+          );
+        }
+      });
+    }
+  }
+
   return { errors, warnings };
 }
 
@@ -1173,12 +1239,12 @@ function validateCapability(capability, index) {
       ),
     );
   }
-  if (!capability.emoji) {
+  if (!capability.emojiIcon) {
     warnings.push(
       createWarning(
         "MISSING_OPTIONAL",
-        "Capability missing emoji",
-        `${path}.emoji`,
+        "Capability missing emojiIcon",
+        `${path}.emojiIcon`,
       ),
     );
   }

package/app/pages/agent-builder.js

@@ -16,6 +16,8 @@ import {
   span,
   label,
   section,
+  select,
+  option,
 } from "../lib/render.js";
 import { getState } from "../lib/state.js";
 import { loadAgentDataBrowser } from "../lib/yaml-loader.js";
@@ -34,6 +36,7 @@ import { createReactive } from "../lib/reactive.js";
 import { getStageEmoji } from "../formatters/stage/shared.js";
 import { formatAgentProfile } from "../formatters/agent/profile.js";
 import { formatAgentSkill } from "../formatters/agent/skill.js";
+import { createCodeDisplay } from "../components/code-display.js";
 
 /** All stages option value */
 const ALL_STAGES_VALUE = "all";
@@ -101,9 +104,71 @@ export async function renderAgentBuilder() {
   const availableDisciplines = data.disciplines.filter((d) =>
     agentDisciplineIds.has(d.id),
   );
-  const availableTracks = data.tracks.filter((t) => agentTrackIds.has(t.id));
+  // All tracks with agent definitions (will be filtered per-discipline)
+  const allAgentTracks = data.tracks.filter((t) => agentTrackIds.has(t.id));
   const stages = data.stages || [];
 
+  /**
+   * Get tracks valid for a discipline that also have agent definitions
+   * @param {string} disciplineId - Discipline ID
+   * @returns {Array} - Valid tracks for the discipline
+   */
+  function getValidTracksForDiscipline(disciplineId) {
+    const discipline = data.disciplines.find((d) => d.id === disciplineId);
+    if (!discipline) return [];
+
+    const validTracks = discipline.validTracks ?? [];
+    // Filter to track IDs only (exclude null which means trackless)
+    const validTrackIds = validTracks.filter((t) => t !== null);
+
+    // Intersection: valid for discipline AND has agent definition
+    return allAgentTracks.filter((t) => validTrackIds.includes(t.id));
+  }
+
+  // Track select element - created once, options updated when discipline changes
+  const trackSelectEl = select(
+    { className: "form-select", id: "agent-track-select" },
+    option({ value: "", disabled: true, selected: true }, "Select a track..."),
+  );
+  trackSelectEl.disabled = true;
+
+  /**
+   * Update track select options based on selected discipline
+   * @param {string} disciplineId - Discipline ID
+   */
+  function updateTrackOptions(disciplineId) {
+    const validTracks = getValidTracksForDiscipline(disciplineId);
+
+    // Clear existing options
+    trackSelectEl.innerHTML = "";
+
+    if (validTracks.length === 0) {
+      trackSelectEl.appendChild(
+        option(
+          { value: "", disabled: true, selected: true },
+          "No tracks available for this discipline",
+        ),
+      );
+      trackSelectEl.disabled = true;
+      return;
+    }
+
+    // Add placeholder
+    trackSelectEl.appendChild(
+      option(
+        { value: "", disabled: true, selected: true },
+        "Select a track...",
+      ),
+    );
+
+    // Add available track options
+    validTracks.forEach((t) => {
+      trackSelectEl.appendChild(option({ value: t.id }, t.name));
+    });
+
+    trackSelectEl.disabled = false;
+  }
+
   // Build stage options with "All Stages" first
   const stageOptions = [
     { id: ALL_STAGES_VALUE, name: "All Stages" },
@@ -134,7 +199,7 @@ export async function renderAgentBuilder() {
   // Preview container - will be updated reactively
   const previewContainer = div(
     { className: "agent-preview" },
-    createEmptyState(availableDisciplines.length, availableTracks.length),
+    createEmptyState(availableDisciplines.length, allAgentTracks.length),
   );
 
   /**
@@ -156,7 +221,7 @@ export async function renderAgentBuilder() {
 
     if (!discipline) {
       previewContainer.appendChild(
-        createEmptyState(availableDisciplines.length, availableTracks.length),
+        createEmptyState(availableDisciplines.length, allAgentTracks.length),
       );
       return;
     }
@@ -251,7 +316,14 @@ export async function renderAgentBuilder() {
                 initialValue: selection.get().discipline,
                 placeholder: "Select a discipline...",
                 onChange: (value) => {
-                  selection.update((prev) => ({ ...prev, discipline: value }));
+                  // Update track options when discipline changes
+                  updateTrackOptions(value);
+                  // Reset track selection when discipline changes
+                  selection.update((prev) => ({
+                    ...prev,
+                    discipline: value,
+                    track: "",
+                  }));
                 },
                 getDisplayName: (d) => d.specialization || d.name,
               })
@@ -260,25 +332,32 @@ export async function renderAgentBuilder() {
                 "No disciplines have agent definitions.",
               ),
         ),
-        // Track selector
+        // Track selector (dynamically filtered by discipline)
         div(
           { className: "form-group" },
           label({ className: "form-label" }, "Track"),
-          availableTracks.length > 0
-            ? createSelectWithValue({
-                id: "agent-track-select",
-                items: availableTracks,
-                initialValue: selection.get().track,
-                placeholder: "Select a track...",
-                onChange: (value) => {
-                  selection.update((prev) => ({ ...prev, track: value }));
-                },
-                getDisplayName: (t) => t.name,
-              })
-            : p(
-                { className: "text-muted" },
-                "No tracks have agent definitions.",
-              ),
+          (() => {
+            // Wire up track select change handler
+            trackSelectEl.addEventListener("change", (e) => {
+              selection.update((prev) => ({ ...prev, track: e.target.value }));
+            });
+            // Initialize track options if discipline is pre-selected
+            const initialDiscipline = selection.get().discipline;
+            if (initialDiscipline) {
+              updateTrackOptions(initialDiscipline);
+              // Set initial track value if provided and valid
+              const initialTrack = selection.get().track;
+              const validTracks =
+                getValidTracksForDiscipline(initialDiscipline);
+              if (
+                initialTrack &&
+                validTracks.some((t) => t.id === initialTrack)
+              ) {
+                trackSelectEl.value = initialTrack;
+              }
+            }
+            return trackSelectEl;
+          })(),
         ),
         // Stage selector (dropdown with All Stages option)
         div(
@@ -407,7 +486,7 @@ function createAllStagesPreview(context) {
   const skillFiles = derivedSkills
     .map((derived) => skills.find((s) => s.id === derived.skillId))
     .filter((skill) => skill?.agent)
-    .map((skill) => generateSkillMd(skill));
+    .map((skill) => generateSkillMd(skill, stages));
 
   return div(
     { className: "agent-deployment" },
@@ -522,7 +601,7 @@ function createSingleStagePreview(context, stage) {
   const skillFiles = derivedSkills
     .map((d) => skills.find((s) => s.id === d.skillId))
     .filter((skill) => skill?.agent)
-    .map((skill) => generateSkillMd(skill));
+    .map((skill) => generateSkillMd(skill, stages));
 
   return div(
     { className: "agent-deployment" },
@@ -590,10 +669,15 @@ function createAgentCard(stage, profile, stages, agentTemplate, _derived) {
         span({ className: "agent-card-emoji" }, stageEmoji),
         h3({}, `${stage.name} Agent`),
       ),
-      createCopyButton(content),
     ),
-    p({ className: "agent-card-filename" }, profile.filename),
-    div({ className: "agent-card-preview" }, createCodePreview(content)),
+    div(
+      { className: "agent-card-preview" },
+      createCodeDisplay({
+        content,
+        filename: profile.filename,
+        maxHeight: 400,
+      }),
+    ),
   );
 
   return card;
@@ -614,57 +698,18 @@ function createSkillCard(skill, skillTemplate) {
     div(
       { className: "skill-card-header" },
       span({ className: "skill-card-name" }, skill.frontmatter.name),
-      createCopyButton(content),
     ),
-    p({ className: "skill-card-filename" }, filename),
-    div({ className: "skill-card-preview" }, createCodePreview(content)),
+    div(
+      { className: "skill-card-preview" },
+      createCodeDisplay({
+        content,
+        filename,
+        maxHeight: 300,
+      }),
+    ),
   );
 }
 
-/**
- * Create a code preview element
- * @param {string} content - Code content
- * @returns {HTMLElement}
- */
-function createCodePreview(content) {
-  const pre = document.createElement("pre");
-  pre.className = "code-block code-preview";
-
-  const code = document.createElement("code");
-  code.textContent = content;
-
-  pre.appendChild(code);
-  return pre;
-}
-
-/**
- * Create a copy button
- * @param {string} content - Content to copy
- * @returns {HTMLElement}
- */
-function createCopyButton(content) {
-  const btn = document.createElement("button");
-  btn.className = "btn btn-sm copy-btn";
-  btn.textContent = "📋 Copy";
-
-  btn.addEventListener("click", async () => {
-    try {
-      await navigator.clipboard.writeText(content);
-      btn.textContent = "✓ Copied";
-      setTimeout(() => {
-        btn.textContent = "📋 Copy";
-      }, 2000);
-    } catch {
-      btn.textContent = "Failed";
-      setTimeout(() => {
-        btn.textContent = "📋 Copy";
-      }, 2000);
-    }
-  });
-
-  return btn;
-}
-
 /**
  * Create download all button for all stages
  * @param {Array} stageAgents - Array of {stage, derived, profile}
@@ -860,11 +905,10 @@ function createCliHint(disciplineId, trackId, stageId) {
     { className: "agent-section cli-hint" },
     h2({}, "CLI Alternative"),
     p({}, "Generate this agent from the command line:"),
-    div(
-      { className: "cli-command" },
-      createCodePreview(command),
-      createCopyButton(command),
-    ),
+    createCodeDisplay({
+      content: command,
+      language: "bash",
+    }),
   );
 
   return container;