@forwardimpact/pathway 0.3.0 → 0.5.0

package/app/formatters/skill/dom.js

@@ -18,8 +18,10 @@ import {
 } from "../../lib/render.js";
 import { createBackLink } from "../../components/nav.js";
 import { createLevelCell } from "../../components/detail.js";
+import { createCodeDisplay } from "../../components/code-display.js";
+import { createToolIcon } from "../../lib/card-mappers.js";
 import { SKILL_LEVEL_ORDER } from "../../model/levels.js";
-import { prepareSkillDetail, formatCapability } from "./shared.js";
+import { prepareSkillDetail } from "./shared.js";
 import { createJsonLdScript, skillToJsonLd } from "../json-ld.js";
 
 /**
@@ -31,11 +33,19 @@ import { createJsonLdScript, skillToJsonLd } from "../json-ld.js";
  * @param {Array} context.drivers - All drivers
  * @param {Array} context.capabilities - Capability entities
  * @param {boolean} [context.showBackLink=true] - Whether to show back navigation link
+ * @param {boolean} [context.showToolsAndPatterns=true] - Whether to show recommended tools and implementation patterns
  * @returns {HTMLElement}
  */
 export function skillToDOM(
   skill,
-  { disciplines, tracks, drivers, capabilities, showBackLink = true } = {},
+  {
+    disciplines,
+    tracks,
+    drivers,
+    capabilities,
+    showBackLink = true,
+    showToolsAndPatterns = true,
+  } = {},
 ) {
   const view = prepareSkillDetail(skill, {
     disciplines,
@@ -61,7 +71,7 @@ export function skillToDOM(
         { className: "page-meta" },
         span(
           { className: "badge badge-default" },
-          formatCapability(view.capability),
+          `${view.capabilityEmoji} ${view.capability.toUpperCase()}`,
         ),
         view.isHumanOnly
           ? span(
@@ -167,5 +177,62 @@ export function skillToDOM(
           ),
         )
       : null,
+
+    // Recommended Tools
+    showToolsAndPatterns && view.toolReferences.length > 0
+      ? div(
+          { className: "detail-section" },
+          heading2({ className: "section-title" }, "Recommended Tools"),
+          table(
+            { className: "tools-table" },
+            thead({}, tr({}, th({}, "Tool"), th({}, "Use When"))),
+            tbody(
+              {},
+              ...view.toolReferences.map((tool) =>
+                tr(
+                  {},
+                  td(
+                    { className: "tool-name-cell" },
+                    tool.simpleIcon
+                      ? createToolIcon(tool.simpleIcon, tool.name)
+                      : null,
+                    tool.url
+                      ? a(
+                          {
+                            href: tool.url,
+                            target: "_blank",
+                            rel: "noopener noreferrer",
+                          },
+                          tool.name,
+                        )
+                      : tool.name,
+                  ),
+                  td({}, tool.useWhen),
+                ),
+              ),
+            ),
+          ),
+          showBackLink
+            ? p(
+                { className: "see-all-link" },
+                a({ href: "#/tool" }, "See all tools →"),
+              )
+            : null,
+        )
+      : null,
+
+    // Implementation Reference
+    showToolsAndPatterns && view.implementationReference
+      ? div(
+          { className: "detail-section" },
+          heading2({ className: "section-title" }, "Implementation Patterns"),
+          createCodeDisplay({
+            content: view.implementationReference,
+            description:
+              "Project-specific implementation guidance for this skill.",
+            minHeight: 450,
+          }),
+        )
+      : null,
   );
 }

package/app/formatters/skill/markdown.js

@@ -105,5 +105,23 @@ export function skillToMarkdown(
     lines.push("");
   }
 
+  // Recommended tools
+  if (view.toolReferences.length > 0) {
+    lines.push("## Recommended Tools", "");
+    const toolRows = view.toolReferences.map((tool) => [
+      tool.url ? `[${tool.name}](${tool.url})` : tool.name,
+      tool.useWhen,
+    ]);
+    lines.push(tableToMarkdown(["Tool", "Use When"], toolRows));
+    lines.push("");
+  }
+
+  // Implementation reference
+  if (view.implementationReference) {
+    lines.push("## Implementation Patterns", "");
+    lines.push(view.implementationReference);
+    lines.push("");
+  }
+
   return lines.join("\n");
 }

package/app/formatters/skill/shared.js

@@ -13,12 +13,12 @@ import { truncate } from "../shared.js";
 
 /**
  * Format capability name for display
- * @param {string} capability
+ * @param {string} capabilityName - The capability name to display
  * @returns {string}
  */
-export function formatCapability(capability) {
-  if (!capability) return "";
-  return capability.charAt(0).toUpperCase() + capability.slice(1);
+export function formatCapability(capabilityName) {
+  if (!capabilityName) return "";
+  return capabilityName;
 }
 
 /**
@@ -66,12 +66,15 @@ export function prepareSkillsList(
  * @property {string} name
  * @property {string} description
  * @property {string} capability
+ * @property {string} capabilityName
  * @property {boolean} isHumanOnly
  * @property {string} capabilityEmoji
  * @property {Object<string, string>} levelDescriptions
  * @property {Array<{id: string, name: string, skillType: string}>} relatedDisciplines
  * @property {Array<{id: string, name: string, modifier: number}>} relatedTracks
  * @property {Array<{id: string, name: string}>} relatedDrivers
+ * @property {Array<{name: string, url?: string, description: string, useWhen: string}>} toolReferences
+ * @property {string|null} implementationReference
  */
 
 /**
@@ -110,16 +113,23 @@ export function prepareSkillDetail(
     .filter((d) => d.contributingSkills?.includes(skill.id))
     .map((d) => ({ id: d.id, name: d.name }));
 
+  const capabilityEntity = capabilities.find((c) => c.id === skill.capability);
+
   return {
     id: skill.id,
     name: skill.name,
     description: skill.description,
     capability: skill.capability,
+    capabilityName: capabilityEntity?.name || skill.capability,
     isHumanOnly: skill.isHumanOnly || false,
     capabilityEmoji: getCapabilityEmoji(capabilities, skill.capability),
     levelDescriptions: skill.levelDescriptions,
     relatedDisciplines,
     relatedTracks,
     relatedDrivers,
+    toolReferences: (skill.toolReferences || [])
+      .slice()
+      .sort((a, b) => a.name.localeCompare(b.name)),
+    implementationReference: skill.implementationReference || null,
   };
 }

package/app/formatters/stage/microdata.js

@@ -32,7 +32,7 @@ export function stageListToMicrodata(stages) {
           ? `→ ${stage.handoffs.map((h) => h.target).join(", ")}`
           : "";
       return `${openTag("article", { itemtype: "Stage", itemid: `#${stage.id}` })}
-${prop("h2", "name", `${stage.emoji || ""} ${stage.name}`)}
+${prop("h2", "name", `${stage.emojiIcon} ${stage.name}`)}
 ${prop("p", "description", stage.truncatedDescription)}
 ${handoffText ? `<p>Handoffs: ${handoffText}</p>` : ""}
 </article>`;
@@ -100,7 +100,7 @@ ${prop("p", "prompt", h.prompt)}
 ${openTag("article", { itemtype: "Stage", itemid: `#${view.id}` })}
 ${prop("h1", "name", view.name)}
 ${metaTag("id", view.id)}
-${stage.emoji ? metaTag("emoji", stage.emoji) : ""}
+${stage.emojiIcon ? metaTag("emojiIcon", stage.emojiIcon) : ""}
 ${prop("p", "description", view.description)}
 ${sections.join("\n")}
 </article>

package/app/formatters/stage/shared.js

@@ -10,7 +10,7 @@ import { truncate } from "../shared.js";
  * @typedef {Object} StageListItem
  * @property {string} id
  * @property {string} name
- * @property {string} emoji
+ * @property {string} emojiIcon
  * @property {string} description
  * @property {string} truncatedDescription
  * @property {Array<{target: string, label: string}>} handoffs
@@ -27,7 +27,7 @@ export function prepareStagesList(stages, descriptionLimit = 150) {
     return {
       id: stage.id,
       name: stage.name,
-      emoji: stage.emoji,
+      emojiIcon: stage.emojiIcon,
       description: stage.description,
       truncatedDescription: truncate(stage.description, descriptionLimit),
       handoffs: (stage.handoffs || []).map((h) => ({
@@ -80,5 +80,5 @@ export function prepareStageDetail(stage) {
  */
 export function getStageEmoji(stages, stageId) {
   const stage = stages.find((s) => s.id === stageId);
-  return stage?.emoji || "🔄";
+  return stage?.emojiIcon;
 }

package/app/formatters/tool/shared.js

@@ -0,0 +1,78 @@
+/**
+ * Tool presentation helpers
+ *
+ * Shared utilities for formatting tool data across DOM and CLI outputs.
+ */
+
+/**
+ * @typedef {Object} ToolUsage
+ * @property {string} skillId
+ * @property {string} skillName
+ * @property {string} capabilityId
+ * @property {string} useWhen
+ */
+
+/**
+ * @typedef {Object} AggregatedTool
+ * @property {string} name
+ * @property {string} [url]
+ * @property {string} [simpleIcon]
+ * @property {string} description
+ * @property {ToolUsage[]} usages
+ */
+
+/**
+ * Aggregate tools from all skills, deduplicating by name
+ * @param {Array} skills - All skills with toolReferences
+ * @returns {AggregatedTool[]}
+ */
+export function aggregateTools(skills) {
+  const toolMap = new Map();
+
+  for (const skill of skills) {
+    if (!skill.toolReferences) continue;
+
+    for (const tool of skill.toolReferences) {
+      const usage = {
+        skillId: skill.id,
+        skillName: skill.name,
+        capabilityId: skill.capability,
+        useWhen: tool.useWhen,
+      };
+
+      const existing = toolMap.get(tool.name);
+      if (existing) {
+        existing.usages.push(usage);
+        // Prefer simpleIcon from first occurrence that has one
+        if (!existing.simpleIcon && tool.simpleIcon) {
+          existing.simpleIcon = tool.simpleIcon;
+        }
+      } else {
+        toolMap.set(tool.name, {
+          name: tool.name,
+          url: tool.url,
+          simpleIcon: tool.simpleIcon,
+          description: tool.description,
+          usages: [usage],
+        });
+      }
+    }
+  }
+
+  return Array.from(toolMap.values()).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  );
+}
+
+/**
+ * Prepare tools list view data
+ * @param {Array} skills - All skills
+ * @returns {{ tools: AggregatedTool[], totalCount: number }}
+ */
+export function prepareToolsList(skills) {
+  const tools = aggregateTools(skills);
+  return {
+    tools,
+    totalCount: tools.length,
+  };
+}

package/app/handout-main.js

@@ -41,17 +41,17 @@ import { sortTracksByName } from "./formatters/track/shared.js";
 /**
  * Create a chapter cover page
  * @param {Object} params
- * @param {string} params.emoji - Chapter emoji
+ * @param {string} params.emojiIcon - Chapter emoji
  * @param {string} params.title - Chapter title
  * @param {string} params.description - Chapter description
  * @returns {HTMLElement}
  */
-function createChapterCover({ emoji, title, description }) {
+function createChapterCover({ emojiIcon, title, description }) {
   return div(
     { className: "chapter-cover" },
     h1(
       { className: "chapter-title" },
-      emoji,
+      emojiIcon,
       " ",
       span({ className: "gradient-text" }, title),
     ),
@@ -111,7 +111,7 @@ function renderIndex(data) {
       { className: "page-header" },
       heading1(
         { className: "page-title" },
-        `${framework.emoji} ${framework.title} Handouts`,
+        `${framework.emojiIcon} ${framework.title} Handouts`,
       ),
       p(
         { className: "page-description" },
@@ -135,25 +135,25 @@ function renderIndex(data) {
             `${getConceptEmoji(framework, "job")} ${framework.entityDefinitions.job.title}`,
           ),
           " - ",
-          `${data.disciplines.length} disciplines, ${data.tracks.length} tracks, ${data.grades.length} grades`,
+          `${data.disciplines.length} disciplines, ${data.grades.length} grades, ${data.tracks.length} tracks`,
         ),
         li(
           {},
           a(
-            { href: "#/skill" },
-            `${getConceptEmoji(framework, "skill")} ${framework.entityDefinitions.skill.title}`,
+            { href: "#/behaviour" },
+            `${getConceptEmoji(framework, "behaviour")} ${framework.entityDefinitions.behaviour.title}`,
           ),
           " - ",
-          `${data.skills.length} skill definitions`,
+          `${data.behaviours.length} behaviour definitions`,
         ),
         li(
           {},
           a(
-            { href: "#/behaviour" },
-            `${getConceptEmoji(framework, "behaviour")} ${framework.entityDefinitions.behaviour.title}`,
+            { href: "#/skill" },
+            `${getConceptEmoji(framework, "skill")} ${framework.entityDefinitions.skill.title}`,
           ),
           " - ",
-          `${data.behaviours.length} behaviour definitions`,
+          `${data.skills.length} skill definitions`,
         ),
         li(
           {},
@@ -190,7 +190,7 @@ function renderDriverHandout(data) {
   const content = div(
     {},
     createChapterCover({
-      emoji: getConceptEmoji(framework, "driver"),
+      emojiIcon: getConceptEmoji(framework, "driver"),
       title: framework.entityDefinitions.driver.title,
       description: framework.entityDefinitions.driver.description,
     }),
@@ -227,13 +227,14 @@ function renderSkillHandout(data) {
       drivers: data.drivers,
       capabilities: data.capabilities,
       showBackLink: false,
+      showToolsAndPatterns: false,
     });
   });
 
   const content = div(
     {},
     createChapterCover({
-      emoji: getConceptEmoji(framework, "skill"),
+      emojiIcon: getConceptEmoji(framework, "skill"),
       title: framework.entityDefinitions.skill.title,
       description: framework.entityDefinitions.skill.description,
     }),
@@ -261,7 +262,7 @@ function renderBehaviourHandout(data) {
   const content = div(
     {},
     createChapterCover({
-      emoji: getConceptEmoji(framework, "behaviour"),
+      emojiIcon: getConceptEmoji(framework, "behaviour"),
       title: framework.entityDefinitions.behaviour.title,
       description: framework.entityDefinitions.behaviour.description,
     }),
@@ -322,7 +323,7 @@ function renderJobHandout(data) {
     {},
     // Disciplines chapter
     createChapterCover({
-      emoji: getConceptEmoji(framework, "discipline"),
+      emojiIcon: getConceptEmoji(framework, "discipline"),
       title: framework.entityDefinitions.discipline.title,
       description: framework.entityDefinitions.discipline.description,
     }),
@@ -330,7 +331,7 @@ function renderJobHandout(data) {
 
     // Grades chapter (moved before Tracks)
     createChapterCover({
-      emoji: getConceptEmoji(framework, "grade"),
+      emojiIcon: getConceptEmoji(framework, "grade"),
       title: framework.entityDefinitions.grade.title,
       description: framework.entityDefinitions.grade.description,
     }),
@@ -338,7 +339,7 @@ function renderJobHandout(data) {
 
     // Tracks chapter (moved after Grades)
     createChapterCover({
-      emoji: getConceptEmoji(framework, "track"),
+      emojiIcon: getConceptEmoji(framework, "track"),
       title: framework.entityDefinitions.track.title,
       description: framework.entityDefinitions.track.description,
     }),
@@ -393,7 +394,7 @@ function populateBrandHeader(framework) {
   header.appendChild(
     a(
       { className: "brand-title", href: "#/" },
-      `${framework.emoji} ${framework.title}`,
+      `${framework.emojiIcon} ${framework.title}`,
     ),
   );
   header.appendChild(span({ className: "brand-tag" }, framework.tag));

package/app/index.html

@@ -4,7 +4,19 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Engineering Pathway</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&display=swap"
+      rel="stylesheet"
+    />
+    <link
+      rel="stylesheet"
+      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 type="importmap">
       {
         "imports": {
@@ -31,12 +43,13 @@
         </button>
         <ul class="nav-links" id="nav-links">
           <li><a href="#/discipline">Disciplines</a></li>
-          <li><a href="#/track">Tracks</a></li>
           <li><a href="#/grade">Grades</a></li>
-          <li><a href="#/skill">Skills</a></li>
+          <li><a href="#/track">Tracks</a></li>
           <li><a href="#/behaviour">Behaviours</a></li>
-          <li><a href="#/stage">Stages</a></li>
+          <li><a href="#/skill">Skills</a></li>
           <li><a href="#/driver">Drivers</a></li>
+          <li><a href="#/stage">Stages</a></li>
+          <li><a href="#/tool">Tools</a></li>
           <li><a href="#/job-builder" class="nav-cta">Build a Job</a></li>
           <li><a href="#/agent-builder" class="nav-cta">Build an Agent</a></li>
           <li><a href="#/interview-prep" class="nav-cta">Interview Prep</a></li>

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,81 @@ 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);
+
+  // Create icon element if available
+  const icon = tool.simpleIcon
+    ? createToolIcon(tool.simpleIcon, tool.name)
+    : null;
+
+  return {
+    title: tool.name,
+    description: tool.description,
+    // Docs link in header badges (upper right)
+    badges: tool.url ? [createExternalLink("Docs →", tool.url)] : [],
+    content: skillsList,
+    icon,
+  };
+}
+
+/**
+ * Create a tool icon element using Simple Icons CDN
+ * @param {string} slug - Simple Icons slug (e.g., 'terraform', 'docker')
+ * @param {string} name - Tool name for alt text
+ * @returns {HTMLElement}
+ */
+export function createToolIcon(slug, name) {
+  const img = document.createElement("img");
+  // Use black color for consistent monochrome appearance
+  img.src = `https://cdn.simpleicons.org/${slug}/000000`;
+  img.alt = `${name} icon`;
+  img.className = "tool-icon";
+  img.width = 28;
+  img.height = 28;
+  // Gracefully handle missing icons
+  img.onerror = () => {
+    img.style.display = "none";
+  };
+  return img;
+}
+
+/**
+ * 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);