@forwardimpact/pathway 0.1.0 → 0.2.0

package/app/components/builder.js

@@ -12,6 +12,8 @@ import {
   button,
   label,
   section,
+  select,
+  option,
 } from "../lib/render.js";
 import { getState } from "../lib/state.js";
 import { createBadge } from "./card.js";
@@ -89,9 +91,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 +164,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,7 +209,7 @@ 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"),
@@ -156,27 +219,19 @@ export function createBuilder({
             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 +246,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 +369,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 +385,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,116 +3,62 @@
  *
  * 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");
+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);
 }
 
 /**
  * Format agent profile for CLI output (markdown)
- * @param {Object} profile - Profile with frontmatter and body
+ * @param {Object} profile - Profile with frontmatter and bodyData
  * @returns {string} Markdown formatted for CLI display
  */
-export function formatAgentProfileForCli({ frontmatter, body }) {
+export function formatAgentProfileForCli({ frontmatter, bodyData }) {
   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) {
@@ -127,7 +73,87 @@ export function formatAgentProfileForCli({ frontmatter, body }) {
   lines.push("");
   lines.push("---");
   lines.push("");
-  lines.push(body);
+
+  // Render structured body data
+  lines.push(`# ${bodyData.title}`);
+  lines.push("");
+  lines.push(bodyData.stageDescription);
+  lines.push("");
+
+  lines.push("## Core Identity");
+  lines.push("");
+  lines.push(bodyData.identity);
+  lines.push("");
+
+  if (bodyData.priority) {
+    lines.push(bodyData.priority);
+    lines.push("");
+  }
+
+  if (bodyData.capabilities && bodyData.capabilities.length > 0) {
+    lines.push("Your primary capabilities:");
+    for (const cap of bodyData.capabilities) {
+      lines.push(`- ${cap}`);
+    }
+    lines.push("");
+  }
+
+  if (bodyData.beforeMakingChanges && bodyData.beforeMakingChanges.length > 0) {
+    lines.push("Before making changes:");
+    for (const step of bodyData.beforeMakingChanges) {
+      lines.push(`${step.index}. ${step.text}`);
+    }
+    lines.push("");
+  }
+
+  if (bodyData.delegation) {
+    lines.push("## Delegation");
+    lines.push("");
+    lines.push(bodyData.delegation);
+    lines.push("");
+  }
+
+  lines.push("## Operational Context");
+  lines.push("");
+  lines.push(bodyData.operationalContext);
+  lines.push("");
+
+  lines.push(bodyData.workingStyle);
+
+  if (bodyData.beforeHandoff) {
+    lines.push("## Before Handoff");
+    lines.push("");
+    lines.push(
+      "Before offering a handoff, verify and summarize completion of these items:",
+    );
+    lines.push("");
+    lines.push(bodyData.beforeHandoff);
+    lines.push("");
+    lines.push(
+      "When verified, summarize what was accomplished then offer the handoff.",
+    );
+    lines.push("If items are incomplete, explain what remains.");
+    lines.push("");
+  }
+
+  lines.push("## Return Format");
+  lines.push("");
+  lines.push("When completing work (for handoff or as a subagent), provide:");
+  lines.push("");
+  lines.push("1. **Work completed**: What was accomplished");
+  lines.push(
+    "2. **Checklist status**: Items verified from Before Handoff section",
+  );
+  lines.push("3. **Recommendation**: Ready for next stage, or needs more work");
+  lines.push("");
+
+  if (bodyData.constraints && bodyData.constraints.length > 0) {
+    lines.push("## Constraints");
+    lines.push("");
+    for (const constraint of bodyData.constraints) {
+      lines.push(`- ${constraint}`);
+    }
+  }
 
   return lines.join("\n");
 }

package/app/formatters/agent/skill.js

@@ -3,56 +3,89 @@
  *
  * 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");
+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);
 }
 
 /**
  * Format agent skill for CLI output (markdown)
- * @param {Object} skill - Skill with frontmatter and body
+ * @param {Object} skill - Skill with frontmatter, title, stages, reference
  * @returns {string} Markdown formatted for CLI display
  */
-export function formatAgentSkillForCli({ frontmatter, body }) {
+export function formatAgentSkillForCli({
+  frontmatter,
+  title,
+  stages,
+  reference,
+}) {
   const lines = [];
 
-  lines.push(`# Skill: ${frontmatter.name}`);
+  lines.push(`# ${title}`);
   lines.push("");
-  lines.push(`**Description:** ${frontmatter.description.trim()}`);
+  lines.push(`**Name:** ${frontmatter.name}`);
   lines.push("");
-  lines.push("---");
+  lines.push(`**Description:** ${frontmatter.description.trim()}`);
   lines.push("");
-  lines.push(body);
+
+  if (stages && stages.length > 0) {
+    lines.push("## Stage Guidance");
+    lines.push("");
+    for (const stage of stages) {
+      lines.push(`### ${stage.stageName} Stage`);
+      lines.push("");
+      lines.push(`**Focus:** ${stage.focus.trim()}`);
+      lines.push("");
+      if (stage.activities && stage.activities.length > 0) {
+        lines.push("**Activities:**");
+        for (const item of stage.activities) {
+          lines.push(`- ${item}`);
+        }
+        lines.push("");
+      }
+      if (stage.ready && stage.ready.length > 0) {
+        lines.push(`**Ready for ${stage.nextStageName} when:**`);
+        for (const item of stage.ready) {
+          lines.push(`- [ ] ${item}`);
+        }
+        lines.push("");
+      }
+    }
+  }
+
+  if (reference) {
+    lines.push("## Reference");
+    lines.push("");
+    lines.push(reference.trim());
+  }
 
   return lines.join("\n");
 }

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