@forwardimpact/pathway 0.1.0 → 0.2.0

package/app/formatters/track/shared.js

@@ -8,43 +8,12 @@ import { isCapability, getSkillsByCapability } from "../../model/modifiers.js";
 import { truncate } from "../shared.js";
 
 /**
- * Sort tracks by type: professional tracks first, then management tracks.
- * Within each type, preserves original order.
+ * Sort tracks alphabetically by name.
  * @param {Array} tracks - Raw track entities
  * @returns {Array} Sorted tracks array
  */
-export function sortTracksByType(tracks) {
-  return [...tracks].sort((a, b) => {
-    const aFlags = getTrackTypeFlags(a);
-    const bFlags = getTrackTypeFlags(b);
-
-    // Professional tracks come first
-    if (aFlags.isProfessional && !bFlags.isProfessional) return -1;
-    if (!aFlags.isProfessional && bFlags.isProfessional) return 1;
-
-    // Preserve original order within same type
-    return 0;
-  });
-}
-
-/**
- * Determine track type flags from track data.
- *
- * Logic: Only one flag needs to be explicitly set to true; the other defaults to false.
- * - If isManagement: true → management track (isProfessional = false)
- * - If isProfessional: true (or neither set) → professional track (isManagement = false)
- *
- * @param {Object} track
- * @param {boolean} [track.isProfessional] - Whether this is a professional/IC track
- * @param {boolean} [track.isManagement] - Whether this is a management track
- * @returns {{isProfessional: boolean, isManagement: boolean}}
- */
-export function getTrackTypeFlags(track) {
-  // Management takes precedence if explicitly set to true
-  const isManagement = track.isManagement === true;
-  // Professional is true if management is not true (default behavior)
-  const isProfessional = !isManagement && track.isProfessional !== false;
-  return { isProfessional, isManagement };
+export function sortTracksByName(tracks) {
+  return [...tracks].sort((a, b) => a.name.localeCompare(b.name));
 }
 
 /**
@@ -53,8 +22,6 @@ export function getTrackTypeFlags(track) {
  * @property {string} name
  * @property {string} description
  * @property {string} truncatedDescription
- * @property {boolean} isProfessional
- * @property {boolean} isManagement
  */
 
 /**
@@ -64,16 +31,13 @@ export function getTrackTypeFlags(track) {
  * @returns {{ items: TrackListItem[] }}
  */
 export function prepareTracksList(tracks, descriptionLimit = 120) {
-  const sortedTracks = sortTracksByType(tracks);
+  const sortedTracks = sortTracksByName(tracks);
   const items = sortedTracks.map((track) => {
-    const { isProfessional, isManagement } = getTrackTypeFlags(track);
     return {
       id: track.id,
       name: track.name,
       description: track.description,
       truncatedDescription: truncate(track.description, descriptionLimit),
-      isProfessional,
-      isManagement,
     };
   });
 
@@ -101,11 +65,8 @@ export function prepareTracksList(tracks, descriptionLimit = 120) {
  * @property {string} id
  * @property {string} name
  * @property {string} description
- * @property {boolean} isProfessional
- * @property {boolean} isManagement
  * @property {SkillModifierRow[]} skillModifiers
  * @property {BehaviourModifierRow[]} behaviourModifiers
- * @property {Array<{id: string, name: string}>} validDisciplines
  */
 
 /**
@@ -114,14 +75,12 @@ export function prepareTracksList(tracks, descriptionLimit = 120) {
  * @param {Object} context - Additional context
  * @param {Array} context.skills - All skills
  * @param {Array} context.behaviours - All behaviours
- * @param {Array} context.disciplines - All disciplines
+ * @param {Array} context.disciplines - All disciplines (unused but kept for API compatibility)
  * @returns {TrackDetailView|null}
  */
-export function prepareTrackDetail(track, { skills, behaviours, disciplines }) {
+export function prepareTrackDetail(track, { skills, behaviours }) {
   if (!track) return null;
 
-  const { isProfessional, isManagement } = getTrackTypeFlags(track);
-
   // Build skill modifiers
   const skillModifiers = track.skillModifiers
     ? Object.entries(track.skillModifiers).map(([key, modifier]) => {
@@ -160,22 +119,11 @@ export function prepareTrackDetail(track, { skills, behaviours, disciplines }) {
       )
     : [];
 
-  // Get valid disciplines
-  const validDisciplines = track.validDisciplines
-    ? track.validDisciplines
-        .map((id) => disciplines.find((d) => d.id === id))
-        .filter(Boolean)
-        .map((d) => ({ id: d.id, name: d.specialization || d.name }))
-    : [];
-
   return {
     id: track.id,
     name: track.name,
     description: track.description,
-    isProfessional,
-    isManagement,
     skillModifiers,
     behaviourModifiers,
-    validDisciplines,
   };
 }

package/app/handout-main.js

@@ -36,7 +36,7 @@ import {
   gradeToDOM,
   trackToDOM,
 } from "./formatters/index.js";
-import { sortTracksByType } from "./formatters/track/shared.js";
+import { sortTracksByName } from "./formatters/track/shared.js";
 
 /**
  * Create a chapter cover page
@@ -271,6 +271,17 @@ function renderBehaviourHandout(data) {
   renderHandout(content);
 }
 
+/**
+ * Sort disciplines by type (professional first, then management)
+ * @param {Array} disciplines - Raw discipline entities
+ * @returns {Array} - Sorted disciplines
+ */
+function sortDisciplinesByType(disciplines) {
+  const professional = disciplines.filter((d) => !d.isManagement);
+  const management = disciplines.filter((d) => d.isManagement);
+  return [...professional, ...management];
+}
+
 /**
  * Render all job component slides (disciplines, grades, tracks)
  * @param {Object} data
@@ -278,7 +289,10 @@ function renderBehaviourHandout(data) {
 function renderJobHandout(data) {
   const { framework } = data;
 
-  const disciplineSlides = data.disciplines.map((discipline) => {
+  // Sort disciplines by type: professional first, then management
+  const sortedDisciplines = sortDisciplinesByType(data.disciplines);
+
+  const disciplineSlides = sortedDisciplines.map((discipline) => {
     return disciplineToDOM(discipline, {
       skills: data.skills,
       behaviours: data.behaviours,
@@ -295,7 +309,7 @@ function renderJobHandout(data) {
     });
   });
 
-  const trackSlides = sortTracksByType(data.tracks).map((track) => {
+  const trackSlides = sortTracksByName(data.tracks).map((track) => {
     return trackToDOM(track, {
       skills: data.skills,
       behaviours: data.behaviours,
@@ -314,21 +328,21 @@ function renderJobHandout(data) {
     }),
     ...disciplineSlides,
 
-    // Tracks chapter
-    createChapterCover({
-      emoji: getConceptEmoji(framework, "track"),
-      title: framework.entityDefinitions.track.title,
-      description: framework.entityDefinitions.track.description,
-    }),
-    ...trackSlides,
-
-    // Grades chapter
+    // Grades chapter (moved before Tracks)
     createChapterCover({
       emoji: getConceptEmoji(framework, "grade"),
       title: framework.entityDefinitions.grade.title,
       description: framework.entityDefinitions.grade.description,
     }),
     ...gradeSlides,
+
+    // Tracks chapter (moved after Grades)
+    createChapterCover({
+      emoji: getConceptEmoji(framework, "track"),
+      title: framework.entityDefinitions.track.title,
+      description: framework.entityDefinitions.track.description,
+    }),
+    ...trackSlides,
   );
 
   renderHandout(content);

package/app/index.html

@@ -5,6 +5,13 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Engineering Pathway</title>
     <link rel="stylesheet" href="css/bundles/app.css" />
+    <script type="importmap">
+      {
+        "imports": {
+          "mustache": "https://esm.sh/mustache@4.2.0"
+        }
+      }
+    </script>
   </head>
   <body>
     <div id="app">
@@ -51,6 +58,10 @@
 
       <footer id="app-footer">
         <p>Engineering Pathway</p>
+        <nav class="footer-links">
+          <a href="slides.html">Slides</a>
+          <a href="handout.html">Handouts</a>
+        </nav>
       </footer>
     </div>
 

package/app/lib/card-mappers.js

@@ -15,10 +15,18 @@ import { getCapabilityEmoji } from "../model/levels.js";
  * @returns {Object}
  */
 export function disciplineToCardConfig(discipline) {
+  const badges = [];
+  if (discipline.isProfessional) {
+    badges.push(createBadge("Professional", "secondary"));
+  }
+  if (discipline.isManagement) {
+    badges.push(createBadge("Management", "primary"));
+  }
   return {
     title: discipline.name,
     description: discipline.truncatedDescription,
     href: `/discipline/${discipline.id}`,
+    badges,
     meta: [
       createBadge(`${discipline.coreSkillsCount} core`, "primary"),
       createBadge(
@@ -118,19 +126,11 @@ export function gradeToCardConfig(grade) {
  * @returns {Object}
  */
 export function trackToCardConfig(track) {
-  const badges = [];
-  if (track.isProfessional) {
-    badges.push(createBadge("Professional", "secondary"));
-  }
-  if (track.isManagement) {
-    badges.push(createBadge("Management", "default"));
-  }
-
   return {
     title: track.name,
     description: track.truncatedDescription,
     href: `/track/${track.id}`,
-    meta: badges,
+    meta: [],
   };
 }
 
@@ -140,12 +140,17 @@ export function trackToCardConfig(track) {
  * @returns {Object}
  */
 export function jobToCardConfig(job) {
+  const href = job.track
+    ? `/job/${job.discipline.id}/${job.grade.id}/${job.track.id}`
+    : `/job/${job.discipline.id}/${job.grade.id}`;
   return {
     title: job.title,
-    description: `${job.discipline.specialization || job.discipline.name} at ${job.grade.professionalTitle} level on ${job.track.name} track`,
-    href: `/job/${job.discipline.id}/${job.track.id}/${job.grade.id}`,
+    description: job.track
+      ? `${job.discipline.specialization || job.discipline.name} at ${job.grade.professionalTitle} level on ${job.track.name} track`
+      : `${job.discipline.specialization || job.discipline.name} at ${job.grade.professionalTitle} level`,
+    href,
     badges: [createBadge(job.grade.id, "default")],
-    meta: [createBadge(job.track.name, "secondary")],
+    meta: job.track ? [createBadge(job.track.name, "secondary")] : [],
   };
 }
 

package/app/lib/job-cache.js

@@ -13,12 +13,15 @@ const cache = new Map();
 /**
  * Create a consistent cache key from job parameters
  * @param {string} disciplineId
- * @param {string} trackId
  * @param {string} gradeId
+ * @param {string} [trackId] - Optional track ID
  * @returns {string}
  */
-export function makeJobKey(disciplineId, trackId, gradeId) {
-  return `${disciplineId}_${trackId}_${gradeId}`;
+export function makeJobKey(disciplineId, gradeId, trackId = null) {
+  if (trackId) {
+    return `${disciplineId}_${gradeId}_${trackId}`;
+  }
+  return `${disciplineId}_${gradeId}`;
 }
 
 /**
@@ -26,7 +29,7 @@ export function makeJobKey(disciplineId, trackId, gradeId) {
  * @param {Object} params
  * @param {Object} params.discipline
  * @param {Object} params.grade
- * @param {Object} params.track
+ * @param {Object} [params.track] - Optional track
  * @param {Array} params.skills
  * @param {Array} params.behaviours
  * @param {Array} [params.capabilities]
@@ -35,12 +38,12 @@ export function makeJobKey(disciplineId, trackId, gradeId) {
 export function getOrCreateJob({
   discipline,
   grade,
-  track,
+  track = null,
   skills,
   behaviours,
   capabilities,
 }) {
-  const key = makeJobKey(discipline.id, track.id, grade.id);
+  const key = makeJobKey(discipline.id, grade.id, track?.id);
 
   if (!cache.has(key)) {
     const job = deriveJob({
@@ -70,11 +73,11 @@ export function clearJobCache() {
 /**
  * Invalidate a specific job from the cache
  * @param {string} disciplineId
- * @param {string} trackId
  * @param {string} gradeId
+ * @param {string} [trackId] - Optional track ID
  */
-export function invalidateJob(disciplineId, trackId, gradeId) {
-  cache.delete(makeJobKey(disciplineId, trackId, gradeId));
+export function invalidateJob(disciplineId, gradeId, trackId = null) {
+  cache.delete(makeJobKey(disciplineId, gradeId, trackId));
 }
 
 /**

package/app/lib/template-loader.js

@@ -0,0 +1,66 @@
+/**
+ * Template Loader
+ *
+ * Loads Mustache templates from the data directory with fallback to the
+ * top-level templates directory. This allows users to customize agent
+ * and skill templates by placing them in their data directory.
+ *
+ * Resolution order:
+ * 1. {dataDir}/templates/{name} (user customization)
+ * 2. {codebaseDir}/templates/{name} (fallback)
+ */
+
+import { readFile } from "fs/promises";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { existsSync } from "fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CODEBASE_TEMPLATES_DIR = join(__dirname, "..", "..", "templates");
+
+/**
+ * Load a template file with fallback to codebase templates
+ * @param {string} templateName - Template filename (e.g., 'agent.template.md')
+ * @param {string} dataDir - Path to data directory
+ * @returns {Promise<string>} Template content
+ * @throws {Error} If template not found in either location
+ */
+export async function loadTemplate(templateName, dataDir) {
+  // Build list of paths to try
+  const paths = [];
+  if (dataDir) {
+    paths.push(join(dataDir, "templates", templateName));
+  }
+  paths.push(join(CODEBASE_TEMPLATES_DIR, templateName));
+
+  // Try each path in order
+  for (const path of paths) {
+    if (existsSync(path)) {
+      return await readFile(path, "utf-8");
+    }
+  }
+
+  // Not found
+  throw new Error(
+    `Template '${templateName}' not found. Checked:\n` +
+      paths.map((p) => `  - ${p}`).join("\n"),
+  );
+}
+
+/**
+ * Load agent profile template
+ * @param {string} dataDir - Path to data directory
+ * @returns {Promise<string>} Agent template content
+ */
+export async function loadAgentTemplate(dataDir) {
+  return loadTemplate("agent.template.md", dataDir);
+}
+
+/**
+ * Load agent skill template
+ * @param {string} dataDir - Path to data directory
+ * @returns {Promise<string>} Skill template content
+ */
+export async function loadSkillTemplate(dataDir) {
+  return loadTemplate("skill.template.md", dataDir);
+}

package/app/lib/yaml-loader.js

@@ -103,6 +103,11 @@ async function loadDisciplinesFromDir(disciplinesDir) {
       const {
         specialization,
         roleTitle,
+        // Track constraints
+        isProfessional,
+        isManagement,
+        validTracks,
+        minGrade,
         // Shared content - now at root level
         description,
         // Structural properties (derivation inputs)
@@ -118,6 +123,11 @@ async function loadDisciplinesFromDir(disciplinesDir) {
         id,
         specialization,
         roleTitle,
+        // Track constraints
+        isProfessional,
+        isManagement,
+        validTracks,
+        minGrade,
         // Shared content at top level
         description,
         // Structural properties
@@ -152,12 +162,10 @@ async function loadTracksFromDir(tracksDir) {
         description,
         roleContext,
         // Structural properties (derivation inputs)
-        isProfessional,
-        isManagement,
         skillModifiers,
         behaviourModifiers,
         matchingWeights,
-        validDisciplines,
+        minGrade,
         // Agent section (no human section anymore for tracks)
         agent,
       } = content;
@@ -168,12 +176,10 @@ async function loadTracksFromDir(tracksDir) {
         description,
         roleContext,
         // Structural properties
-        isProfessional,
-        isManagement,
         skillModifiers,
         behaviourModifiers,
         matchingWeights,
-        validDisciplines,
+        minGrade,
         ...(agent && { agent }),
       };
     }),
@@ -301,14 +307,23 @@ export async function loadAllData(dataDir = "./data") {
  * Load agent-specific data for browser-based agent generation
  * Uses co-located files where agent sections are embedded in entity files
  * @param {string} [dataDir='./data'] - Path to data directory
- * @returns {Promise<Object>} Agent data including disciplines, tracks, behaviours, vscodeSettings
+ * @returns {Promise<Object>} Agent data including disciplines, tracks, behaviours, vscodeSettings, devcontainer, copilotSetupSteps
  */
 export async function loadAgentDataBrowser(dataDir = "./data") {
-  const [disciplines, tracks, behaviours, vscodeSettings] = await Promise.all([
+  const [
+    disciplines,
+    tracks,
+    behaviours,
+    vscodeSettings,
+    devcontainer,
+    copilotSetupSteps,
+  ] = await Promise.all([
     loadDisciplinesFromDir(`${dataDir}/disciplines`),
     loadTracksFromDir(`${dataDir}/tracks`),
     loadBehavioursFromDir(`${dataDir}/behaviours`),
     tryLoadYamlFile(`${dataDir}/vscode-settings.yaml`),
+    tryLoadYamlFile(`${dataDir}/devcontainer.yaml`),
+    tryLoadYamlFile(`${dataDir}/copilot-setup-steps.yaml`),
   ]);
 
   // Extract agent sections from co-located files
@@ -323,5 +338,7 @@ export async function loadAgentDataBrowser(dataDir = "./data") {
       .filter((b) => b.agent)
       .map((b) => ({ id: b.id, ...b.agent })),
     vscodeSettings: vscodeSettings || {},
+    devcontainer: devcontainer || {},
+    copilotSetupSteps: copilotSetupSteps || null,
   };
 }

package/app/main.js

@@ -101,15 +101,18 @@ function setupRoutes() {
 
   // Job builder
   router.on("/job-builder", renderJobBuilder);
-  router.on("/job/:discipline/:track/:grade", renderJobDetail);
+  router.on("/job/:discipline/:grade/:track", renderJobDetail);
+  router.on("/job/:discipline/:grade", renderJobDetail);
 
   // Interview prep
   router.on("/interview-prep", renderInterviewPrep);
-  router.on("/interview/:discipline/:track/:grade", renderInterviewDetail);
+  router.on("/interview/:discipline/:grade/:track", renderInterviewDetail);
+  router.on("/interview/:discipline/:grade", renderInterviewDetail);
 
   // Career progress
   router.on("/career-progress", renderCareerProgress);
-  router.on("/progress/:discipline/:track/:grade", renderProgressDetail);
+  router.on("/progress/:discipline/:grade/:track", renderProgressDetail);
+  router.on("/progress/:discipline/:grade", renderProgressDetail);
 
   // Self-assessment
   router.on("/self-assessment", renderSelfAssessment);
@@ -117,8 +120,9 @@ function setupRoutes() {
 
   // Agent builder
   router.on("/agent-builder", renderAgentBuilder);
-  router.on("/agent/:discipline/:track", renderAgentBuilder);
   router.on("/agent/:discipline/:track/:stage", renderAgentBuilder);
+  router.on("/agent/:discipline/:track", renderAgentBuilder);
+  router.on("/agent/:discipline", renderAgentBuilder);
 }
 
 /**