@forwardimpact/pathway 0.4.0 → 0.5.0

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(
@@ -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;

package/app/pages/landing.js

@@ -53,7 +53,7 @@ export function renderLanding() {
       { className: "landing-hero" },
       div(
         { className: "hero-title-wrapper" },
-        h1({}, `${framework.emoji} ${framework.title}`),
+        h1({}, `${framework.emojiIcon} ${framework.title}`),
         span({ className: "brand-tag brand-tag-hero" }, framework.tag),
       ),
       p({}, framework.description.trim()),

package/app/pages/stage.js

@@ -11,12 +11,12 @@ import { getConceptEmoji } from "../model/levels.js";
 
 /**
  * Map stage to card configuration
- * @param {Object} stage - Prepared stage item (includes emoji)
+ * @param {Object} stage - Prepared stage item (includes emojiIcon)
  * @returns {Object} Card configuration
  */
 function stageToCardConfig(stage) {
   return {
-    title: `${stage.emoji} ${stage.name}`,
+    title: `${stage.emojiIcon} ${stage.name}`,
     description: stage.truncatedDescription,
     href: `/stage/${stage.id}`,
   };
@@ -24,7 +24,7 @@ function stageToCardConfig(stage) {
 
 /**
  * Create lifecycle flow visualization
- * @param {Array} stages - Array of stage items (each includes emoji)
+ * @param {Array} stages - Array of stage items (each includes emojiIcon)
  * @returns {HTMLElement}
  */
 function createLifecycleFlow(stages) {
@@ -35,7 +35,7 @@ function createLifecycleFlow(stages) {
       { className: "lifecycle-flow-item" },
       a(
         { href: `#/stage/${stage.id}`, className: "lifecycle-stage" },
-        span({ className: "lifecycle-emoji" }, stage.emoji),
+        span({ className: "lifecycle-emoji" }, stage.emojiIcon),
         span({ className: "lifecycle-name" }, stage.name),
       ),
       !isLast ? span({ className: "lifecycle-arrow" }, "→") : null,

package/app/slide-main.js

@@ -346,7 +346,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/slides/chapter.js

@@ -20,37 +20,37 @@ export function renderChapterSlide({ render, data, params }) {
   const chapterConfig = {
     driver: {
       title: framework.entityDefinitions.driver.title,
-      emoji: framework.entityDefinitions.driver.emoji,
+      emojiIcon: framework.entityDefinitions.driver.emojiIcon,
       description: framework.entityDefinitions.driver.description,
     },
     skill: {
       title: framework.entityDefinitions.skill.title,
-      emoji: framework.entityDefinitions.skill.emoji,
+      emojiIcon: framework.entityDefinitions.skill.emojiIcon,
       description: framework.entityDefinitions.skill.description,
     },
     behaviour: {
       title: framework.entityDefinitions.behaviour.title,
-      emoji: framework.entityDefinitions.behaviour.emoji,
+      emojiIcon: framework.entityDefinitions.behaviour.emojiIcon,
       description: framework.entityDefinitions.behaviour.description,
     },
     discipline: {
       title: framework.entityDefinitions.discipline.title,
-      emoji: framework.entityDefinitions.discipline.emoji,
+      emojiIcon: framework.entityDefinitions.discipline.emojiIcon,
       description: framework.entityDefinitions.discipline.description,
     },
     grade: {
       title: framework.entityDefinitions.grade.title,
-      emoji: framework.entityDefinitions.grade.emoji,
+      emojiIcon: framework.entityDefinitions.grade.emojiIcon,
       description: framework.entityDefinitions.grade.description,
     },
     track: {
       title: framework.entityDefinitions.track.title,
-      emoji: framework.entityDefinitions.track.emoji,
+      emojiIcon: framework.entityDefinitions.track.emojiIcon,
       description: framework.entityDefinitions.track.description,
     },
     job: {
       title: framework.entityDefinitions.job.title,
-      emoji: framework.entityDefinitions.job.emoji,
+      emojiIcon: framework.entityDefinitions.job.emojiIcon,
       description: framework.entityDefinitions.job.description,
     },
   };
@@ -72,7 +72,7 @@ export function renderChapterSlide({ render, data, params }) {
     { className: "slide chapter-cover" },
     h1(
       { className: "chapter-title" },
-      config.emoji ? `${config.emoji} ` : "",
+      config.emojiIcon ? `${config.emojiIcon} ` : "",
       span({ className: "gradient-text" }, config.title),
     ),
     p({ className: "chapter-description" }, config.description.trim()),

package/app/slides/index.js

@@ -22,7 +22,7 @@ export function renderSlideIndex({ render, data }) {
       { className: "page-header" },
       heading1(
         { className: "page-title" },
-        `${framework.emoji} ${framework.title}`,
+        `${framework.emojiIcon} ${framework.title}`,
       ),
       p(
         { className: "page-description" },

package/app/slides/overview.js

@@ -63,14 +63,14 @@ export function renderOverviewSlide({ render, data, params }) {
   const chapterConfig = {
     driver: {
       title: framework.entityDefinitions.driver.title,
-      emoji: framework.entityDefinitions.driver.emoji,
+      emojiIcon: framework.entityDefinitions.driver.emojiIcon,
       description: framework.entityDefinitions.driver.description,
       entities: prepareDriversList(data.drivers).items,
       mapper: driverToCardConfig,
     },
     skill: {
       title: framework.entityDefinitions.skill.title,
-      emoji: framework.entityDefinitions.skill.emoji,
+      emojiIcon: framework.entityDefinitions.skill.emojiIcon,
       description: framework.entityDefinitions.skill.description,
       entities: Object.values(
         prepareSkillsList(data.skills, data.capabilities).groups,
@@ -79,14 +79,14 @@ export function renderOverviewSlide({ render, data, params }) {
     },
     behaviour: {
       title: framework.entityDefinitions.behaviour.title,
-      emoji: framework.entityDefinitions.behaviour.emoji,
+      emojiIcon: framework.entityDefinitions.behaviour.emojiIcon,
       description: framework.entityDefinitions.behaviour.description,
       entities: prepareBehavioursList(data.behaviours).items,
       mapper: behaviourToCardConfig,
     },
     discipline: {
       title: framework.entityDefinitions.discipline.title,
-      emoji: framework.entityDefinitions.discipline.emoji,
+      emojiIcon: framework.entityDefinitions.discipline.emojiIcon,
       description: framework.entityDefinitions.discipline.description,
       groups: prepareDisciplinesList(data.disciplines).groups,
       mapper: disciplineToCardConfig,
@@ -94,21 +94,21 @@ export function renderOverviewSlide({ render, data, params }) {
     },
     grade: {
       title: framework.entityDefinitions.grade.title,
-      emoji: framework.entityDefinitions.grade.emoji,
+      emojiIcon: framework.entityDefinitions.grade.emojiIcon,
       description: framework.entityDefinitions.grade.description,
       entities: prepareGradesList(data.grades).items,
       mapper: gradeToCardConfig,
     },
     track: {
       title: framework.entityDefinitions.track.title,
-      emoji: framework.entityDefinitions.track.emoji,
+      emojiIcon: framework.entityDefinitions.track.emojiIcon,
       description: framework.entityDefinitions.track.description,
       entities: prepareTracksList(data.tracks).items,
       mapper: trackToCardConfig,
     },
     job: {
       title: framework.entityDefinitions.job.title,
-      emoji: framework.entityDefinitions.job.emoji,
+      emojiIcon: framework.entityDefinitions.job.emojiIcon,
       description: framework.entityDefinitions.job.description,
       entities: generateAllJobs({
         disciplines: data.disciplines,
@@ -150,7 +150,7 @@ export function renderOverviewSlide({ render, data, params }) {
       { className: "overview-header" },
       h1(
         { className: "overview-title" },
-        config.emoji ? `${config.emoji} ` : "",
+        config.emojiIcon ? `${config.emojiIcon} ` : "",
         span({ className: "gradient-text" }, config.title),
       ),
       p({ className: "overview-description" }, config.description.trim()),

package/app/slides/skill.js

@@ -35,6 +35,7 @@ export function renderSkillSlide({ render, data, params }) {
       drivers: data.drivers,
       capabilities: data.capabilities,
       showBackLink: false,
+      showToolsAndPatterns: false,
     }),
   );
 }

package/examples/capabilities/business.yaml

@@ -1,7 +1,7 @@
 # yaml-language-server: $schema=https://schema.forwardimpact.team/json/capability.schema.json
 
 name: Business
-emoji: 💼
+emojiIcon: 💼
 displayOrder: 8
 description: |
   Understanding and driving business value.

package/examples/capabilities/delivery.yaml

@@ -1,7 +1,7 @@
 # yaml-language-server: $schema=https://schema.forwardimpact.team/json/capability.schema.json
 
 name: Delivery
-emoji: 🚀
+emojiIcon: 🚀
 displayOrder: 1
 description: |
   Building and shipping solutions that solve real problems.
@@ -271,6 +271,7 @@ skills:
     toolReferences:
       - name: Terraform
         url: https://developer.hashicorp.com/terraform/docs
+        simpleIcon: terraform
         description: Infrastructure as code tool
         useWhen: Provisioning and managing cloud infrastructure
       - name: CloudFormation
@@ -279,6 +280,7 @@ skills:
         useWhen: Managing AWS infrastructure as code
       - name: Docker
         url: https://docs.docker.com/
+        simpleIcon: docker
         description: Container platform
         useWhen: Containerizing applications or managing container environments
     implementationReference: |

package/examples/capabilities/people.yaml

@@ -1,7 +1,7 @@
 # yaml-language-server: $schema=https://schema.forwardimpact.team/json/capability.schema.json
 
 name: People
-emoji: 👥
+emojiIcon: 👥
 displayOrder: 6
 description: |
   Growing individuals and building effective teams.

package/examples/capabilities/reliability.yaml

@@ -1,7 +1,7 @@
 # yaml-language-server: $schema=https://schema.forwardimpact.team/json/capability.schema.json
 
 name: Reliability
-emoji: 🛡️
+emojiIcon: 🛡️
 displayOrder: 5
 description: |
   Ensuring systems are dependable, secure, and observable.
@@ -158,10 +158,12 @@ skills:
     toolReferences:
       - name: Terraform
         url: https://developer.hashicorp.com/terraform/docs
+        simpleIcon: terraform
         description: Infrastructure as code tool
         useWhen: Provisioning and managing cloud infrastructure
       - name: Docker
         url: https://docs.docker.com/
+        simpleIcon: docker
         description: Container platform
         useWhen: Containerizing applications or managing container environments
     implementationReference: |

package/examples/capabilities/scale.yaml

@@ -1,7 +1,7 @@
 # yaml-language-server: $schema=https://schema.forwardimpact.team/json/capability.schema.json
 
 name: Scale
-emoji: 📐
+emojiIcon: 📐
 displayOrder: 4
 description: |
   Building systems that grow gracefully.

package/examples/framework.yaml

@@ -1,7 +1,7 @@
 # yaml-language-server: $schema=https://schema.forwardimpact.team/json/framework.schema.json
 
 title: Engineering Pathway
-emoji: "🧭"
+emojiIcon: "🧭"
 tag: "#AcmeCorp"
 description: |
   A unified framework for human and AI collaboration in engineering. Define roles, track skills and behaviours, build career paths, and generate AI coding agents—all from the same coherent foundation. The pathway aligns human capabilities with AI assistance, enabling productive teams in the AI era.
@@ -10,60 +10,60 @@ description: |
 entityDefinitions:
   driver:
     title: Drivers
-    emoji: "🎯"
+    emojiIcon: "🎯"
     description: |
       Organizational outcomes that productive teams achieve. Drivers link skills and behaviours to business value, helping teams understand how their capabilities contribute to organizational success.
 
   skill:
     title: Skills
-    emoji: "💡"
+    emojiIcon: "💡"
     description: |
       Capabilities required to perform work effectively. Skills are organized by capability and measured across five levels from Awareness to Expert. They form the foundation of technical and professional competence.
 
   behaviour:
     title: Behaviours
-    emoji: "🧠"
+    emojiIcon: "🧠"
     description: |
       Mindsets and ways of working that underpin effective application of skills. Behaviours are measured across five maturity levels from Emerging to Exemplifying. They describe how engineers approach their work, collaborate with others, and drive outcomes.
 
   discipline:
     title: Disciplines
-    emoji: "🔧"
+    emojiIcon: "🔧"
     description: |
       Engineering specializations that define T-shaped skill profiles. Each discipline specifies primary skills for deep expertise, secondary skills for supporting capabilities, and broad skills for general awareness. Disciplines answer the question: "What kind of engineer are you?"
 
   grade:
     title: Grades
-    emoji: "📊"
+    emojiIcon: "📊"
     description: |
       Career levels that define expectations for skill proficiency, behaviour maturity, and scope of impact. Grades provide a clear progression path from entry-level to distinguished leadership roles, with defined expectations at each stage.
 
   track:
     title: Tracks
-    emoji: "🛤️"
+    emojiIcon: "🛤️"
     description: |
       Work contexts that modify skill and behaviour expectations based on the nature of the role. Tracks answer the question: "Where and how do you work?" They apply modifiers to adjust expectations for different working environments and responsibilities.
 
   job:
     title: Jobs
-    emoji: "📋"
+    emojiIcon: "📋"
     description: |
       Complete role specifications that combine discipline, track, and grade into actionable job definitions with skill matrices, behaviour profiles, and derived responsibilities. Jobs represent the practical application of the framework to define concrete engineering positions.
 
   agent:
     title: Agents
-    emoji: "🤖"
+    emojiIcon: "🤖"
     description: |
       AI coding agent configurations generated from the same disciplines, tracks, and skills that define human roles. Agent profiles and skills follow the GitHub Copilot specification, ensuring AI assistants understand context, constraints, and working styles aligned with human engineering expectations.
 
   stage:
     title: Stages
-    emoji: "🔄"
+    emojiIcon: "🔄"
     description: |
       Defined phases of the engineering lifecycle that structure work from planning through delivery and review. Stages provide context for AI agents and define entry criteria, exit criteria, and appropriate handoffs between phases.
 
   tool:
     title: Tools
-    emoji: "🔧"
+    emojiIcon: "🔧"
     description: |
       Recommended tools and utilities referenced by skills for effective engineering workflows. Tools are linked to specific skills with guidance on when and how to use them, surfacing best practices directly in skill definitions.