@forwardimpact/pathway 0.3.0 → 0.4.0

package/app/lib/card-mappers.js

@@ -9,6 +9,23 @@ import { createBadge } from "../components/card.js";
 import { formatLevel } from "./render.js";
 import { getCapabilityEmoji } from "../model/levels.js";
 
+/**
+ * Create an external link element styled as a badge
+ * @param {string} text - Link text
+ * @param {string} url - External URL
+ * @returns {HTMLElement}
+ */
+function createExternalLink(text, url) {
+  const link = document.createElement("a");
+  link.href = url;
+  link.target = "_blank";
+  link.rel = "noopener noreferrer";
+  link.className = "badge badge-primary";
+  link.textContent = text;
+  link.addEventListener("click", (e) => e.stopPropagation()); // Don't trigger card click
+  return link;
+}
+
 /**
  * Map discipline to card config
  * @param {Object} discipline
@@ -155,24 +172,54 @@ export function jobToCardConfig(job) {
 }
 
 /**
- * Format capability for display
- * @param {string} capability
+ * Map tool to card config
+ * @param {Object} tool - Aggregated tool with usages
+ * @param {Array} capabilities - Capability entities for emoji lookup
+ * @returns {Object}
+ */
+export function toolToCardConfig(tool, capabilities) {
+  // Create skills list as card content
+  const skillsList = createSkillsList(tool.usages, capabilities);
+
+  return {
+    title: tool.name,
+    description: tool.description,
+    // Docs link in header badges (upper right)
+    badges: tool.url ? [createExternalLink("Docs →", tool.url)] : [],
+    content: skillsList,
+  };
+}
+
+/**
+ * Create an unordered list of skill links with capability emoji
+ * @param {Array} usages - Tool usage objects with skillId, skillName, capabilityId
+ * @param {Array} capabilities - Capability entities
+ * @returns {HTMLElement}
+ */
+function createSkillsList(usages, capabilities) {
+  const ul = document.createElement("ul");
+  ul.className = "tool-skills-list";
+
+  for (const usage of usages) {
+    const emoji = getCapabilityEmoji(capabilities, usage.capabilityId);
+    const li = document.createElement("li");
+    const link = document.createElement("a");
+    link.href = `#/skill/${usage.skillId}`;
+    link.textContent = `${emoji} ${usage.skillName}`;
+    li.appendChild(link);
+    ul.appendChild(li);
+  }
+
+  return ul;
+}
+
+/**
+ * Format capability for badge display (short, tag-like)
+ * @param {string} capabilityId
  * @param {Array} capabilities
  * @returns {string}
  */
-function formatCapability(capability, capabilities) {
-  const capabilityLabels = {
-    delivery: "Delivery",
-    scale: "Scale",
-    reliability: "Reliability",
-    data: "Data",
-    ai: "AI",
-    process: "Process",
-    business: "Business",
-    people: "People",
-    documentation: "Documentation",
-  };
-  const label = capabilityLabels[capability] || formatLevel(capability);
-  const emoji = getCapabilityEmoji(capabilities, capability);
-  return `${emoji} ${label}`;
+function formatCapability(capabilityId, capabilities) {
+  const emoji = getCapabilityEmoji(capabilities, capabilityId);
+  return `${emoji} ${capabilityId.toUpperCase()}`;
 }

package/app/lib/render.js

@@ -111,6 +111,10 @@ export const th = (attrs, ...children) =>
   createElement("th", attrs, ...children);
 export const td = (attrs, ...children) =>
   createElement("td", attrs, ...children);
+export const pre = (attrs, ...children) =>
+  createElement("pre", attrs, ...children);
+export const code = (attrs, ...children) =>
+  createElement("code", attrs, ...children);
 export const button = (attrs, ...children) =>
   createElement("button", attrs, ...children);
 export const input = (attrs) => createElement("input", attrs);

package/app/lib/yaml-loader.js

@@ -70,7 +70,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,
@@ -80,6 +88,9 @@ async function loadSkillsFromCapabilities(capabilitiesDir) {
           // Include isHumanOnly flag for agent filtering (defaults to false)
           ...(isHumanOnly && { isHumanOnly }),
           ...(agent && { agent }),
+          // Include implementation reference and tool references (shared by human and agent)
+          ...(implementationReference && { implementationReference }),
+          ...(toolReferences && { toolReferences }),
         });
       }
     }

package/app/main.js

@@ -26,6 +26,7 @@ import { renderTracksList, renderTrackDetail } from "./pages/track.js";
 import { renderGradesList, renderGradeDetail } from "./pages/grade.js";
 import { renderDriversList, renderDriverDetail } from "./pages/driver.js";
 import { renderStagesList, renderStageDetail } from "./pages/stage.js";
+import { renderToolsList } from "./pages/tool.js";
 import { renderJobBuilder } from "./pages/job-builder.js";
 import { renderJobDetail } from "./pages/job.js";
 import { renderInterviewPrep } from "./pages/interview-builder.js";
@@ -99,6 +100,9 @@ function setupRoutes() {
   router.on("/stage", renderStagesList);
   router.on("/stage/:id", renderStageDetail);
 
+  // Tool
+  router.on("/tool", renderToolsList);
+
   // Job builder
   router.on("/job-builder", renderJobBuilder);
   router.on("/job/:discipline/:grade/:track", renderJobDetail);

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,
   };
 }

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

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,

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 };
 }
 

package/app/pages/agent-builder.js

@@ -407,7 +407,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 +522,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" },

package/app/pages/landing.js

@@ -7,6 +7,7 @@ import { getState } from "../lib/state.js";
 import { createStatCard } from "../components/card.js";
 import { groupSkillsByCapability, getConceptEmoji } from "../model/levels.js";
 import { getStageEmoji } from "../formatters/stage/shared.js";
+import { aggregateTools } from "../formatters/tool/shared.js";
 
 /**
  * Create lifecycle flow visualization for landing page
@@ -43,6 +44,7 @@ export function renderLanding() {
   // Calculate stats using centralized capability ordering
   const skillsByCapability = groupSkillsByCapability(data.skills);
   const capabilityCount = Object.keys(skillsByCapability).length;
+  const tools = aggregateTools(data.skills);
 
   const page = div(
     { className: "landing-page" },
@@ -83,7 +85,7 @@ export function renderLanding() {
 
     // Stats grid
     div(
-      { className: "grid grid-6" },
+      { className: "grid grid-4" },
       createStatCard({
         value: data.disciplines.length,
         label: "Disciplines",
@@ -99,28 +101,41 @@ export function renderLanding() {
         label: "Tracks",
         href: "/track",
       }),
+      createStatCard({
+        value: data.behaviours.length,
+        label: "Behaviours",
+        href: "/behaviour",
+      }),
       createStatCard({
         value: data.skills.length,
         label: "Skills",
         href: "/skill",
       }),
       createStatCard({
-        value: data.behaviours.length,
-        label: "Behaviours",
-        href: "/behaviour",
+        value: data.drivers.length,
+        label: "Drivers",
+        href: "/driver",
       }),
       createStatCard({
         value: stages.length,
         label: "Stages",
         href: "/stage",
       }),
+      createStatCard({
+        value: tools.length,
+        label: "Tools",
+        href: "/tool",
+      }),
     ),
 
     // Lifecycle flow visualization
     stages.length > 0
       ? div(
           { className: "section section-detail" },
-          h2({ className: "section-title" }, "🔄 Engineering Lifecycle"),
+          h2(
+            { className: "section-title" },
+            `${getConceptEmoji(framework, "stage")} Engineering Lifecycle`,
+          ),
           p(
             { className: "text-muted", style: "margin-bottom: 1rem" },
             "The three stages of engineering work, from planning through review.",
@@ -134,7 +149,7 @@ export function renderLanding() {
       { className: "section section-detail" },
       h2({ className: "section-title" }, "Explore the Framework"),
       div(
-        { className: "grid grid-3" },
+        { className: "grid grid-4" },
         createQuickLinkCard(
           `${getConceptEmoji(framework, "discipline")} ${framework.entityDefinitions.discipline.title}`,
           `${data.disciplines.length} ${framework.entityDefinitions.discipline.title.toLowerCase()} — ${framework.entityDefinitions.discipline.description.trim().split("\n")[0]}`,
@@ -150,26 +165,31 @@ export function renderLanding() {
           `${data.tracks.length} ${framework.entityDefinitions.track.title.toLowerCase()} — ${framework.entityDefinitions.track.description.trim().split("\n")[0]}`,
           "/track",
         ),
-        createQuickLinkCard(
-          `${getConceptEmoji(framework, "skill")} ${framework.entityDefinitions.skill.title}`,
-          `${data.skills.length} ${framework.entityDefinitions.skill.title.toLowerCase()} across ${capabilityCount} capabilities — ${framework.entityDefinitions.skill.description.trim().split("\n")[0]}`,
-          "/skill",
-        ),
         createQuickLinkCard(
           `${getConceptEmoji(framework, "behaviour")} ${framework.entityDefinitions.behaviour.title}`,
           `${data.behaviours.length} ${framework.entityDefinitions.behaviour.title.toLowerCase()} — ${framework.entityDefinitions.behaviour.description.trim().split("\n")[0]}`,
           "/behaviour",
         ),
         createQuickLinkCard(
-          "🔄 Stages",
-          `${stages.length} stages — The engineering lifecycle from planning through review.`,
-          "/stage",
+          `${getConceptEmoji(framework, "skill")} ${framework.entityDefinitions.skill.title}`,
+          `${data.skills.length} ${framework.entityDefinitions.skill.title.toLowerCase()} across ${capabilityCount} capabilities — ${framework.entityDefinitions.skill.description.trim().split("\n")[0]}`,
+          "/skill",
         ),
         createQuickLinkCard(
           `${getConceptEmoji(framework, "driver")} ${framework.entityDefinitions.driver.title}`,
           `${data.drivers.length} ${framework.entityDefinitions.driver.title.toLowerCase()} — ${framework.entityDefinitions.driver.description.trim().split("\n")[0]}`,
           "/driver",
         ),
+        createQuickLinkCard(
+          `${getConceptEmoji(framework, "stage")} ${framework.entityDefinitions.stage.title}`,
+          `${stages.length} ${framework.entityDefinitions.stage.title.toLowerCase()} — ${framework.entityDefinitions.stage.description.trim().split("\n")[0]}`,
+          "/stage",
+        ),
+        createQuickLinkCard(
+          `${getConceptEmoji(framework, "tool")} ${framework.entityDefinitions.tool.title}`,
+          `${tools.length} ${framework.entityDefinitions.tool.title.toLowerCase()} — ${framework.entityDefinitions.tool.description.trim().split("\n")[0]}`,
+          "/tool",
+        ),
       ),
     ),
 

package/app/pages/self-assessment.js

@@ -82,7 +82,7 @@ function getWizardSteps(data) {
     if (skills && skills.length > 0) {
       steps.push({
         id: `skills-${capability}`,
-        name: formatCapability(capability),
+        name: formatCapability(capability, data.capabilities),
         icon: getCapabilityEmoji(data.capabilities, capability),
         type: "skills",
         capability: capability,
@@ -113,11 +113,13 @@ function getWizardSteps(data) {
 
 /**
  * Format capability name for display
- * @param {string} capability
+ * @param {string} capabilityId
+ * @param {Array} capabilities
  * @returns {string}
  */
-function formatCapability(capability) {
-  return capability.charAt(0).toUpperCase() + capability.slice(1);
+function formatCapability(capabilityId, capabilities) {
+  const capability = capabilities.find((c) => c.id === capabilityId);
+  return capability?.name || capabilityId;
 }
 
 /**
@@ -412,7 +414,7 @@ function renderSkillsStep(step, data) {
       h2(
         {},
         span({ className: "step-header-icon" }, step.icon),
-        ` ${formatCapability(capability)} Skills`,
+        ` ${formatCapability(capability, data.capabilities)} Skills`,
       ),
       span(
         { className: "step-progress" },

package/app/pages/skill.js

@@ -89,25 +89,13 @@ export function renderSkillDetail(params) {
 
 /**
  * Format capability for display
- * @param {string} capability
+ * @param {string} capabilityId
  * @param {Array} capabilities
  * @returns {string}
  */
-function formatCapability(capability, capabilities) {
-  const capabilityLabels = {
-    delivery: "Delivery",
-    scale: "Scale",
-    reliability: "Reliability",
-    data: "Data",
-    ai: "AI",
-    process: "Process",
-    business: "Business",
-    people: "People",
-    documentation: "Documentation",
-  };
-  const label =
-    capabilityLabels[capability] ||
-    capability.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
-  const emoji = getCapabilityEmoji(capabilities, capability);
+function formatCapability(capabilityId, capabilities) {
+  const capability = capabilities.find((c) => c.id === capabilityId);
+  const label = capability?.name || capabilityId;
+  const emoji = getCapabilityEmoji(capabilities, capabilityId);
   return `${emoji} ${label}`;
 }

package/app/pages/stage.js

@@ -7,6 +7,7 @@ import { getState } from "../lib/state.js";
 import { createCardList } from "../components/list.js";
 import { renderNotFound } from "../components/error-page.js";
 import { prepareStagesList, stageToDOM } from "../formatters/stage/index.js";
+import { getConceptEmoji } from "../model/levels.js";
 
 /**
  * Map stage to card configuration
@@ -15,7 +16,7 @@ import { prepareStagesList, stageToDOM } from "../formatters/stage/index.js";
  */
 function stageToCardConfig(stage) {
   return {
-    title: `${stage.emoji || "🔄"} ${stage.name}`,
+    title: `${stage.emoji} ${stage.name}`,
     description: stage.truncatedDescription,
     href: `/stage/${stage.id}`,
   };
@@ -28,14 +29,13 @@ function stageToCardConfig(stage) {
  */
 function createLifecycleFlow(stages) {
   const flowItems = stages.map((stage, index) => {
-    const emoji = stage.emoji || "🔄";
     const isLast = index === stages.length - 1;
 
     return div(
       { className: "lifecycle-flow-item" },
       a(
         { href: `#/stage/${stage.id}`, className: "lifecycle-stage" },
-        span({ className: "lifecycle-emoji" }, emoji),
+        span({ className: "lifecycle-emoji" }, stage.emoji),
         span({ className: "lifecycle-name" }, stage.name),
       ),
       !isLast ? span({ className: "lifecycle-arrow" }, "→") : null,
@@ -50,7 +50,9 @@ function createLifecycleFlow(stages) {
  */
 export function renderStagesList() {
   const { data } = getState();
+  const { framework } = data;
   const stages = data.stages || [];
+  const stageEmoji = getConceptEmoji(framework, "stage");
 
   // Transform data for list view
   const { items } = prepareStagesList(stages);
@@ -60,11 +62,13 @@ export function renderStagesList() {
     // Header
     div(
       { className: "page-header" },
-      h1({ className: "page-title" }, "🔄 Stages"),
+      h1(
+        { className: "page-title" },
+        `${stageEmoji} ${framework.entityDefinitions.stage.title}`,
+      ),
       p(
         { className: "page-description" },
-        "The engineering lifecycle stages. Each stage has specific tools, " +
-          "constraints, and handoffs to guide work from planning through review.",
+        framework.entityDefinitions.stage.description.trim().split("\n")[0],
       ),
     ),