@forwardimpact/pathway 0.1.0 → 0.3.0

package/app/components/builder.js

@@ -12,10 +12,15 @@ import {
   button,
   label,
   section,
+  select,
+  option,
 } from "../lib/render.js";
 import { getState } from "../lib/state.js";
 import { createBadge } from "./card.js";
-import { createSelectWithValue } from "../lib/form-controls.js";
+import {
+  createSelectWithValue,
+  createDisciplineSelect,
+} from "../lib/form-controls.js";
 import { createReactive } from "../lib/reactive.js";
 
 /**
@@ -89,9 +94,70 @@ export function createBuilder({
     buttonText,
   );
 
+  // Track select element - created once, options updated when discipline changes
+  const trackSelectEl = select(
+    { className: "form-select", id: "track-select" },
+    option({ value: "" }, "Generalist"),
+  );
+  // Initially disabled until discipline is selected
+  trackSelectEl.disabled = true;
+
+  /**
+   * Check if a discipline allows trackless (generalist) jobs
+   * @param {Object|null} disciplineObj
+   * @returns {boolean}
+   */
+  function allowsTrackless(disciplineObj) {
+    if (!disciplineObj) return false;
+    const validTracks = disciplineObj.validTracks ?? [];
+    // Empty array = trackless only (legacy), or null in array = trackless allowed
+    return validTracks.length === 0 || validTracks.includes(null);
+  }
+
+  /**
+   * Get available tracks for a discipline (excludes null entries)
+   * @param {Object|null} disciplineObj
+   * @returns {Array}
+   */
+  function getAvailableTracks(disciplineObj) {
+    if (!disciplineObj) return [];
+    const validTracks = disciplineObj.validTracks ?? [];
+    if (validTracks.length === 0) return [];
+    // Filter to actual track IDs (exclude null which means "trackless")
+    const trackIds = validTracks.filter((t) => t !== null);
+    return data.tracks.filter((t) => trackIds.includes(t.id));
+  }
+
+  /**
+   * Update track select options based on selected discipline
+   * @param {string} disciplineId
+   */
+  function updateTrackOptions(disciplineId) {
+    const disciplineObj = data.disciplines.find((d) => d.id === disciplineId);
+    const availableTracks = getAvailableTracks(disciplineObj);
+    const canBeTrackless = allowsTrackless(disciplineObj);
+
+    // Clear existing options
+    trackSelectEl.innerHTML = "";
+
+    // Add generalist option if trackless is allowed
+    if (canBeTrackless) {
+      trackSelectEl.appendChild(option({ value: "" }, "Generalist"));
+    }
+
+    // Add available track options
+    availableTracks.forEach((t) => {
+      trackSelectEl.appendChild(option({ value: t.id }, t.name));
+    });
+
+    // Disable if no options (neither trackless nor tracks)
+    trackSelectEl.disabled = !canBeTrackless && availableTracks.length === 0;
+  }
+
   // Subscribe to selection changes - all updates happen here
   selection.subscribe(({ discipline, track, grade }) => {
-    if (!discipline || !track || !grade) {
+    // Track is now optional - only discipline and grade are required
+    if (!discipline || !grade) {
       previewContainer.innerHTML = "";
       previewContainer.appendChild(
         p({ className: "text-muted" }, emptyPreviewText),
@@ -101,10 +167,10 @@ export function createBuilder({
     }
 
     const disciplineObj = data.disciplines.find((d) => d.id === discipline);
-    const trackObj = data.tracks.find((t) => t.id === track);
+    const trackObj = track ? data.tracks.find((t) => t.id === track) : null;
     const gradeObj = data.grades.find((g) => g.id === grade);
 
-    if (!disciplineObj || !trackObj || !gradeObj) {
+    if (!disciplineObj || !gradeObj) {
       previewContainer.innerHTML = "";
       previewContainer.appendChild(
         p({ className: "text-muted" }, "Invalid selection. Please try again."),
@@ -146,37 +212,29 @@ export function createBuilder({
       h2({}, formTitle),
       div(
         { className: "auto-grid-sm gap-lg" },
-        // Discipline selector
+        // Discipline selector (first)
         div(
           { className: "form-group" },
           label({ className: "form-label" }, labels.discipline || "Discipline"),
-          createSelectWithValue({
+          createDisciplineSelect({
             id: "discipline-select",
-            items: data.disciplines,
+            disciplines: data.disciplines,
             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,
           }),
         ),
-        // Track selector
-        div(
-          { className: "form-group" },
-          label({ className: "form-label" }, labels.track || "Track"),
-          createSelectWithValue({
-            id: "track-select",
-            items: data.tracks,
-            initialValue: selection.get().track,
-            placeholder: "Select a track...",
-            onChange: (value) => {
-              selection.update((prev) => ({ ...prev, track: value }));
-            },
-            getDisplayName: (t) => t.name,
-          }),
-        ),
-        // Grade selector
+        // Grade selector (second)
         div(
           { className: "form-group" },
           label({ className: "form-label" }, labels.grade || "Grade"),
@@ -191,6 +249,31 @@ export function createBuilder({
             getDisplayName: (g) => g.id,
           }),
         ),
+        // Track selector (third, optional)
+        div(
+          { className: "form-group" },
+          label(
+            { className: "form-label" },
+            labels.track || "Track (optional)",
+          ),
+          (() => {
+            // 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
+              const initialTrack = selection.get().track;
+              if (initialTrack) {
+                trackSelectEl.value = initialTrack;
+              }
+            }
+            return trackSelectEl;
+          })(),
+        ),
       ),
       previewContainer,
       div({ className: "page-actions" }, actionButton),
@@ -289,6 +372,15 @@ export function createProgressPreview(preview, selection) {
 
   const { discipline, grade, track } = selection;
 
+  // Build badges array - track is optional
+  const badges = [
+    createBadge(discipline.specialization, "discipline"),
+    createBadge(grade.id, "grade"),
+  ];
+  if (track) {
+    badges.push(createBadge(track.name, "track"));
+  }
+
   return div(
     { className: "job-preview-content" },
     div(
@@ -296,12 +388,7 @@ export function createProgressPreview(preview, selection) {
       div({ className: "preview-label" }, "Current Role"),
       div({ className: "preview-title" }, preview.title),
     ),
-    div(
-      { className: "preview-badges" },
-      createBadge(discipline.specialization, "discipline"),
-      createBadge(grade.id, "grade"),
-      createBadge(track.name, "track"),
-    ),
+    div({ className: "preview-badges" }, ...badges),
     div(
       { className: "preview-section", style: "margin-top: 1rem" },
       div({ className: "preview-label" }, "Progression Paths Available"),

package/app/css/components/surfaces.css

@@ -240,4 +240,20 @@
   #app-footer p {
     margin: 0 0 var(--space-sm) 0;
   }
+
+  .footer-links {
+    display: flex;
+    gap: var(--space-md);
+    justify-content: center;
+  }
+
+  .footer-links a {
+    color: var(--color-text-muted);
+    text-decoration: none;
+  }
+
+  .footer-links a:hover {
+    color: var(--color-primary);
+    text-decoration: underline;
+  }
 }

package/app/formatters/agent/profile.js

@@ -3,131 +3,46 @@
  *
  * Formats agent profile data into .agent.md file content
  * following the GitHub Copilot Custom Agents specification.
+ *
+ * Uses Mustache templates for flexible output formatting.
+ * Templates are loaded from data/ directory with fallback to templates/ directory.
  */
 
-/**
- * Format YAML frontmatter value
- * @param {any} value - Value to format
- * @returns {string} Formatted value
- */
-function formatYamlValue(value) {
-  if (Array.isArray(value)) {
-    return JSON.stringify(value);
-  }
-  if (typeof value === "boolean") {
-    return String(value);
-  }
-  if (typeof value === "string") {
-    // Quote strings that contain special characters or newlines
-    if (value.includes("\n") || value.includes(":") || value.includes("#")) {
-      return `"${value.replace(/"/g, '\\"')}"`;
-    }
-    return value;
-  }
-  return String(value);
-}
-
-/**
- * Format handoffs array as YAML
- * @param {Array} handoffs - Array of handoff objects
- * @returns {string[]} YAML lines for handoffs
- */
-function formatHandoffs(handoffs) {
-  const lines = ["handoffs:"];
-  for (const handoff of handoffs) {
-    lines.push(`  - label: ${formatYamlValue(handoff.label)}`);
-    if (handoff.agent) {
-      lines.push(`    agent: ${formatYamlValue(handoff.agent)}`);
-    }
-
-    // Format prompt as single-line string, replacing newlines with spaces
-    const singleLinePrompt = handoff.prompt
-      .replace(/\n\n+/g, " ")
-      .replace(/\n/g, " ")
-      .replace(/\s+/g, " ")
-      .trim();
-    lines.push(`    prompt: ${formatYamlValue(singleLinePrompt)}`);
-
-    if (handoff.send !== undefined) {
-      lines.push(`    send: ${formatYamlValue(handoff.send)}`);
-    }
-  }
-  return lines;
-}
+import Mustache from "mustache";
 
 /**
- * Format agent profile as .agent.md file content
- * @param {Object} profile - Profile with frontmatter and body
+ * Format agent profile as .agent.md file content using Mustache template
+ * @param {Object} profile - Profile with frontmatter and bodyData
  * @param {Object} profile.frontmatter - YAML frontmatter data
  * @param {string} profile.frontmatter.name - Agent name
  * @param {string} profile.frontmatter.description - Agent description
  * @param {string[]} profile.frontmatter.tools - Available tools
  * @param {boolean} profile.frontmatter.infer - Whether to auto-select
  * @param {Array} [profile.frontmatter.handoffs] - Handoff definitions
- * @param {string} profile.body - Markdown body content
+ * @param {Object} profile.bodyData - Structured body data
+ * @param {string} profile.bodyData.title - Agent title (e.g. "Software Engineering - Platform - Plan Agent")
+ * @param {string} profile.bodyData.stageDescription - Stage description text
+ * @param {string} profile.bodyData.identity - Core identity text
+ * @param {string} [profile.bodyData.priority] - Priority/philosophy statement (optional)
+ * @param {string[]} profile.bodyData.capabilities - List of capability names
+ * @param {Array<{index: number, text: string}>} profile.bodyData.beforeMakingChanges - Numbered steps
+ * @param {string} [profile.bodyData.delegation] - Delegation guidance (optional)
+ * @param {string} profile.bodyData.operationalContext - Operational context text
+ * @param {string} profile.bodyData.workingStyle - Working style markdown section
+ * @param {string} [profile.bodyData.beforeHandoff] - Before handoff checklist markdown (optional)
+ * @param {string[]} profile.bodyData.constraints - List of constraints
+ * @param {string} template - Mustache template string
  * @returns {string} Complete .agent.md file content
  */
-export function formatAgentProfile({ frontmatter, body }) {
-  const lines = ["---"];
-
-  // Name (optional but recommended)
-  if (frontmatter.name) {
-    lines.push(`name: ${formatYamlValue(frontmatter.name)}`);
-  }
-
-  // Description (required)
-  lines.push(`description: ${formatYamlValue(frontmatter.description)}`);
-
-  // Tools (optional, defaults to all)
-  if (frontmatter.tools && frontmatter.tools.length > 0) {
-    lines.push(`tools: ${formatYamlValue(frontmatter.tools)}`);
-  }
-
-  // Infer (optional)
-  if (frontmatter.infer !== undefined) {
-    lines.push(`infer: ${formatYamlValue(frontmatter.infer)}`);
-  }
-
-  // Handoffs (optional)
-  if (frontmatter.handoffs && frontmatter.handoffs.length > 0) {
-    lines.push(...formatHandoffs(frontmatter.handoffs));
-  }
-
-  lines.push("---");
-  lines.push("");
-  lines.push(body);
-
-  return lines.join("\n");
-}
-
-/**
- * Format agent profile for CLI output (markdown)
- * @param {Object} profile - Profile with frontmatter and body
- * @returns {string} Markdown formatted for CLI display
- */
-export function formatAgentProfileForCli({ frontmatter, body }) {
-  const lines = [];
-
-  lines.push(`# Agent Profile: ${frontmatter.name}`);
-  lines.push("");
-  lines.push(`**Description:** ${frontmatter.description}`);
-  lines.push("");
-  lines.push(`**Tools:** ${frontmatter.tools.join(", ")}`);
-  lines.push(`**Infer:** ${frontmatter.infer}`);
-
-  if (frontmatter.handoffs && frontmatter.handoffs.length > 0) {
-    lines.push("");
-    lines.push("**Handoffs:**");
-    for (const handoff of frontmatter.handoffs) {
-      const target = handoff.agent ? ` → ${handoff.agent}` : " (self)";
-      lines.push(`  - ${handoff.label}${target}`);
-    }
-  }
-
-  lines.push("");
-  lines.push("---");
-  lines.push("");
-  lines.push(body);
-
-  return lines.join("\n");
+export function formatAgentProfile({ frontmatter, bodyData }, template) {
+  const data = {
+    // Frontmatter
+    name: frontmatter.name,
+    description: frontmatter.description,
+    infer: frontmatter.infer,
+    handoffs: frontmatter.handoffs || [],
+    // Body data
+    ...bodyData,
+  };
+  return Mustache.render(template, data);
 }

package/app/formatters/agent/skill.js

@@ -3,56 +3,35 @@
  *
  * Formats agent skill data into SKILL.md file content
  * following the Agent Skills Standard specification.
+ *
+ * Uses Mustache templates for flexible output formatting.
+ * Templates are loaded from data/ directory with fallback to templates/ directory.
  */
 
+import Mustache from "mustache";
+
 /**
- * Format agent skill as SKILL.md file content
- * @param {Object} skill - Skill with frontmatter and body
+ * Format agent skill as SKILL.md file content using Mustache template
+ * @param {Object} skill - Skill with frontmatter, title, stages, reference
  * @param {Object} skill.frontmatter - YAML frontmatter data
  * @param {string} skill.frontmatter.name - Skill name (required)
  * @param {string} skill.frontmatter.description - Skill description (required)
- * @param {string} skill.body - Markdown body content
+ * @param {string} skill.title - Human-readable skill title for heading
+ * @param {Array} skill.stages - Array of stage objects with stageName, focus, activities, ready
+ * @param {string} skill.reference - Reference content (markdown)
+ * @param {string} template - Mustache template string
  * @returns {string} Complete SKILL.md file content
  */
-export function formatAgentSkill({ frontmatter, body }) {
-  const lines = ["---"];
-
-  // Name (required)
-  lines.push(`name: ${frontmatter.name}`);
-
-  // Description (required) - handle multiline
-  const description = frontmatter.description.trim();
-  if (description.includes("\n")) {
-    lines.push("description: |");
-    for (const line of description.split("\n")) {
-      lines.push(`  ${line}`);
-    }
-  } else {
-    lines.push(`description: ${description}`);
-  }
-
-  lines.push("---");
-  lines.push("");
-  lines.push(body);
-
-  return lines.join("\n");
-}
-
-/**
- * Format agent skill for CLI output (markdown)
- * @param {Object} skill - Skill with frontmatter and body
- * @returns {string} Markdown formatted for CLI display
- */
-export function formatAgentSkillForCli({ frontmatter, body }) {
-  const lines = [];
-
-  lines.push(`# Skill: ${frontmatter.name}`);
-  lines.push("");
-  lines.push(`**Description:** ${frontmatter.description.trim()}`);
-  lines.push("");
-  lines.push("---");
-  lines.push("");
-  lines.push(body);
-
-  return lines.join("\n");
+export function formatAgentSkill(
+  { frontmatter, title, stages, reference },
+  template,
+) {
+  const data = {
+    name: frontmatter.name,
+    descriptionLines: frontmatter.description.trim().split("\n"),
+    title,
+    stages,
+    reference: reference ? reference.trim() : "",
+  };
+  return Mustache.render(template, data);
 }

package/app/formatters/behaviour/dom.js

@@ -23,6 +23,7 @@ import {
   getConceptEmoji,
 } from "../../model/levels.js";
 import { prepareBehaviourDetail } from "./shared.js";
+import { createJsonLdScript, behaviourToJsonLd } from "../json-ld.js";
 
 /**
  * Format behaviour detail as DOM elements
@@ -41,6 +42,8 @@ export function behaviourToDOM(
   const emoji = getConceptEmoji(framework, "behaviour");
   return div(
     { className: "detail-page behaviour-detail" },
+    // JSON-LD structured data
+    createJsonLdScript(behaviourToJsonLd(behaviour)),
     // Header
     div(
       { className: "page-header" },

package/app/formatters/behaviour/microdata.js

@@ -0,0 +1,106 @@
+/**
+ * Behaviour formatting for microdata HTML output
+ *
+ * Generates clean, class-less HTML with microdata aligned with behaviour.schema.json
+ * RDF vocab: https://schema.forwardimpact.team/rdf/
+ */
+
+import {
+  openTag,
+  prop,
+  propRaw,
+  metaTag,
+  section,
+  dl,
+  ul,
+  escapeHtml,
+  formatLevelName,
+  htmlDocument,
+} from "../microdata-shared.js";
+import { prepareBehavioursList, prepareBehaviourDetail } from "./shared.js";
+
+/**
+ * Format behaviour list as microdata HTML
+ * @param {Array} behaviours - Raw behaviour entities
+ * @returns {string} HTML with microdata
+ */
+export function behaviourListToMicrodata(behaviours) {
+  const { items } = prepareBehavioursList(behaviours);
+
+  const content = items
+    .map(
+      (
+        behaviour,
+      ) => `${openTag("article", { itemtype: "Behaviour", itemid: `#${behaviour.id}` })}
+${prop("h2", "name", behaviour.name)}
+${prop("p", "description", behaviour.truncatedDescription)}
+</article>`,
+    )
+    .join("\n");
+
+  return htmlDocument(
+    "Behaviours",
+    `<main>
+<h1>Behaviours</h1>
+${content}
+</main>`,
+  );
+}
+
+/**
+ * Format behaviour detail as microdata HTML
+ * @param {Object} behaviour - Raw behaviour entity
+ * @param {Object} context - Additional context
+ * @param {Array} context.drivers - All drivers
+ * @returns {string} HTML with microdata
+ */
+export function behaviourToMicrodata(behaviour, { drivers }) {
+  const view = prepareBehaviourDetail(behaviour, { drivers });
+
+  if (!view) return "";
+
+  const sections = [];
+
+  // Maturity descriptions - uses MaturityDescriptions itemtype
+  const maturityPairs = Object.entries(view.maturityDescriptions).map(
+    ([maturity, desc]) => ({
+      term: formatLevelName(maturity),
+      definition: desc,
+      itemprop: `${maturity.replace(/_([a-z])/g, (_, c) => c.toUpperCase())}Description`,
+    }),
+  );
+  sections.push(
+    section(
+      "Maturity Levels",
+      `${openTag("div", { itemtype: "MaturityDescriptions", itemprop: "maturityDescriptions" })}
+${dl(maturityPairs)}
+</div>`,
+      2,
+    ),
+  );
+
+  // Related drivers
+  if (view.relatedDrivers.length > 0) {
+    const driverItems = view.relatedDrivers.map(
+      (d) => `<a href="#${escapeHtml(d.id)}">${escapeHtml(d.name)}</a>`,
+    );
+    sections.push(section("Linked to Drivers", ul(driverItems), 2));
+  }
+
+  const body = `<main>
+${openTag("article", { itemtype: "Behaviour", itemid: `#${view.id}` })}
+${prop("h1", "name", view.name)}
+${metaTag("id", view.id)}
+${propRaw(
+  "div",
+  "human",
+  `${openTag("div", { itemtype: "BehaviourHumanSection" })}
+${prop("p", "description", view.description)}
+${sections.join("\n")}
+</div>`,
+)}
+</article>
+</main>`;
+
+  return htmlDocument(view.name, body);
+}

package/app/formatters/discipline/dom.js

@@ -20,6 +20,24 @@ import {
 } from "../../components/action-buttons.js";
 import { getConceptEmoji } from "../../model/levels.js";
 import { prepareDisciplineDetail } from "./shared.js";
+import { createJsonLdScript, disciplineToJsonLd } from "../json-ld.js";
+import { createBadge } from "../../components/card.js";
+
+/**
+ * Get type badges for discipline (Management/Professional)
+ * @param {Object} discipline - Raw discipline entity
+ * @returns {HTMLElement[]}
+ */
+function getDisciplineTypeBadges(discipline) {
+  const badges = [];
+  if (discipline.isProfessional) {
+    badges.push(createBadge("Professional", "secondary"));
+  }
+  if (discipline.isManagement) {
+    badges.push(createBadge("Management", "primary"));
+  }
+  return badges;
+}
 
 /**
  * Format discipline detail as DOM elements
@@ -44,15 +62,24 @@ export function disciplineToDOM(
 ) {
   const view = prepareDisciplineDetail(discipline, { skills, behaviours });
   const emoji = getConceptEmoji(framework, "discipline");
+  const typeBadges = getDisciplineTypeBadges(discipline);
   return div(
     { className: "detail-page discipline-detail" },
+    // JSON-LD structured data
+    createJsonLdScript(disciplineToJsonLd(discipline, { skills })),
     // Header
     div(
       { className: "page-header" },
       showBackLink
         ? createBackLink("/discipline", "← Back to Disciplines")
         : null,
-      heading1({ className: "page-title" }, `${emoji} `, view.name),
+      div(
+        { className: "page-title-row" },
+        heading1({ className: "page-title" }, `${emoji} `, view.name),
+        typeBadges.length > 0
+          ? div({ className: "page-title-badges" }, ...typeBadges)
+          : null,
+      ),
       p({ className: "page-description" }, view.description),
       showBackLink
         ? div(