@forwardimpact/pathway 0.2.0 → 0.3.0

package/app/commands/agent.js

@@ -7,16 +7,18 @@
  * All agents are stage-specific. Use --stage for a single stage
  * or --all-stages (default) for all stages.
  *
+ * By default, outputs to console. Use --output to write files.
+ *
  * Usage:
- *   npx pathway agent <discipline> [--track=<track>] [--output=PATH] [--preview]
+ *   npx pathway agent <discipline> [--track=<track>]
  *   npx pathway agent <discipline> --track=<track> --stage=plan
- *   npx pathway agent <discipline> --track=<track> --all-stages
+ *   npx pathway agent <discipline> --track=<track> --output=./agents
  *   npx pathway agent --list
  *
  * Examples:
  *   npx pathway agent software_engineering --track=platform
  *   npx pathway agent software_engineering --track=platform --stage=plan
- *   npx pathway agent software_engineering --track=platform --preview
+ *   npx pathway agent software_engineering --track=platform --output=./agents
  */
 
 import { writeFile, mkdir, readFile } from "fs/promises";
@@ -32,10 +34,7 @@ import {
   deriveAgentSkills,
   generateSkillMd,
 } from "../model/agent.js";
-import {
-  formatAgentProfile,
-  formatAgentProfileForCli,
-} from "../formatters/agent/profile.js";
+import { formatAgentProfile } from "../formatters/agent/profile.js";
 import { formatAgentSkill } from "../formatters/agent/skill.js";
 import { formatError, formatSuccess } from "../lib/cli-output.js";
 import {
@@ -410,14 +409,15 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
       process.exit(1);
     }
 
-    // Preview or write
-    if (options.preview) {
-      console.log(formatAgentProfileForCli(profile));
+    // Load template
+    const agentTemplate = await loadAgentTemplate(dataDir);
+
+    // Output to console (default) or write to files (with --output)
+    if (!options.output) {
+      console.log(formatAgentProfile(profile, agentTemplate));
       return;
     }
 
-    // Load templates only when writing files
-    const agentTemplate = await loadAgentTemplate(dataDir);
     await writeProfile(profile, baseDir, agentTemplate);
     await generateVSCodeSettings(baseDir, agentData.vscodeSettings);
     await generateDevcontainer(
@@ -484,19 +484,19 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
     }
   }
 
-  // Preview or write
-  if (options.preview) {
+  // Load templates
+  const agentTemplate = await loadAgentTemplate(dataDir);
+  const skillTemplate = await loadSkillTemplate(dataDir);
+
+  // Output to console (default) or write to files (with --output)
+  if (!options.output) {
     for (const profile of profiles) {
-      console.log(formatAgentProfileForCli(profile));
+      console.log(formatAgentProfile(profile, agentTemplate));
       console.log("\n---\n");
     }
     return;
   }
 
-  // Load templates only when writing files
-  const agentTemplate = await loadAgentTemplate(dataDir);
-  const skillTemplate = await loadSkillTemplate(dataDir);
-
   for (const profile of profiles) {
     await writeProfile(profile, baseDir, agentTemplate);
   }

package/app/commands/job.js

@@ -20,15 +20,17 @@ import {
   deriveChecklist,
   formatChecklistMarkdown,
 } from "../model/checklist.js";
+import { loadJobTemplate } from "../lib/template-loader.js";
 
 /**
  * Format job output
  * @param {Object} view - Presenter view
  * @param {Object} _options - Command options
  * @param {Object} entities - Original entities
+ * @param {string} jobTemplate - Mustache template for job description
  */
-function formatJob(view, _options, entities) {
-  console.log(jobToMarkdown(view, entities));
+function formatJob(view, _options, entities, jobTemplate) {
+  console.log(jobToMarkdown(view, entities, jobTemplate));
 }
 
 /**
@@ -37,8 +39,9 @@ function formatJob(view, _options, entities) {
  * @param {Object} params.data - All loaded data
  * @param {string[]} params.args - Command arguments
  * @param {Object} params.options - Command options
+ * @param {string} params.dataDir - Path to data directory
  */
-export async function runJobCommand({ data, args, options }) {
+export async function runJobCommand({ data, args, options, dataDir }) {
   const jobs = generateAllJobs({
     disciplines: data.disciplines,
     grades: data.grades,
@@ -167,5 +170,7 @@ export async function runJobCommand({ data, args, options }) {
     return;
   }
 
-  formatJob(view, options, { discipline, grade, track });
+  // Load job template for description formatting
+  const jobTemplate = await loadJobTemplate(dataDir);
+  formatJob(view, options, { discipline, grade, track }, jobTemplate);
 }

package/app/components/builder.js

@@ -17,7 +17,10 @@ import {
 } 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";
 
 /**
@@ -213,9 +216,9 @@ export function createBuilder({
         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) => {

package/app/formatters/agent/profile.js

@@ -46,114 +46,3 @@ export function formatAgentProfile({ frontmatter, bodyData }, template) {
   };
   return Mustache.render(template, data);
 }
-
-/**
- * Format agent profile for CLI output (markdown)
- * @param {Object} profile - Profile with frontmatter and bodyData
- * @returns {string} Markdown formatted for CLI display
- */
-export function formatAgentProfileForCli({ frontmatter, bodyData }) {
-  const lines = [];
-
-  lines.push(`# Agent Profile: ${frontmatter.name}`);
-  lines.push("");
-  lines.push(`**Description:** ${frontmatter.description}`);
-  lines.push("");
-  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("");
-
-  // 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

@@ -35,57 +35,3 @@ export function formatAgentSkill(
   };
   return Mustache.render(template, data);
 }
-
-/**
- * Format agent skill for CLI output (markdown)
- * @param {Object} skill - Skill with frontmatter, title, stages, reference
- * @returns {string} Markdown formatted for CLI display
- */
-export function formatAgentSkillForCli({
-  frontmatter,
-  title,
-  stages,
-  reference,
-}) {
-  const lines = [];
-
-  lines.push(`# ${title}`);
-  lines.push("");
-  lines.push(`**Name:** ${frontmatter.name}`);
-  lines.push("");
-  lines.push(`**Description:** ${frontmatter.description.trim()}`);
-  lines.push("");
-
-  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/grade/dom.js

@@ -14,6 +14,7 @@ import {
   tr,
   th,
   td,
+  formatLevel,
 } from "../../lib/render.js";
 import { createBackLink } from "../../components/nav.js";
 import { createLevelDots } from "../../components/detail.js";
@@ -102,10 +103,7 @@ export function gradeToDOM(grade, { framework, showBackLink = true } = {}) {
             ...Object.entries(view.expectations).map(([key, value]) =>
               div(
                 { className: "list-item" },
-                p(
-                  { className: "label" },
-                  key.charAt(0).toUpperCase() + key.slice(1),
-                ),
+                p({ className: "label" }, formatLevel(key)),
                 p({}, value),
               ),
             ),

package/app/formatters/job/description.js

@@ -3,41 +3,28 @@
  *
  * Formats job data into markdown job description content.
  * Parallels formatters/agent/profile.js in structure.
+ *
+ * Uses Mustache templates for flexible output formatting.
+ * Templates are loaded from data/ directory with fallback to templates/ directory.
  */
 
+import Mustache from "mustache";
+
 import {
   SKILL_LEVEL_ORDER,
   BEHAVIOUR_MATURITY_ORDER,
 } from "../../model/levels.js";
 
 /**
- * Format job as a markdown job description
+ * Prepare job data for template rendering
  * @param {Object} params
  * @param {Object} params.job - The job definition
  * @param {Object} params.discipline - The discipline
  * @param {Object} params.grade - The grade
- * @param {Object} params.track - The track
- * @returns {string} Markdown formatted job description
+ * @param {Object} [params.track] - The track (optional)
+ * @returns {Object} Data object ready for Mustache template
  */
-export function formatJobDescription({ job, discipline, grade, track }) {
-  const lines = [];
-
-  // Title
-  lines.push(`# ${job.title}`);
-  lines.push("");
-
-  // Meta information
-  lines.push(`- **Level:** ${grade.id}`);
-  lines.push(`- **Experience:** ${grade.typicalExperienceRange}`);
-  if (track) {
-    lines.push(`- **Track:** ${track.name}`);
-  }
-  lines.push("");
-
-  // Role Summary
-  lines.push("## ROLE SUMMARY");
-  lines.push("");
-
+function prepareJobDescriptionData({ job, discipline, grade, track }) {
   // Build role summary from discipline - use manager version if applicable
   const isManagement = discipline.isManagement === true;
   let roleSummary =
@@ -48,16 +35,9 @@ export function formatJobDescription({ job, discipline, grade, track }) {
   const { roleTitle, specialization } = discipline;
   roleSummary = roleSummary.replace(/\{roleTitle\}/g, roleTitle);
   roleSummary = roleSummary.replace(/\{specialization\}/g, specialization);
-  lines.push(roleSummary);
-  lines.push("");
-
-  // Add track context
-  if (track?.roleContext) {
-    lines.push(track.roleContext);
-    lines.push("");
-  }
 
-  // Add grade expectations as natural paragraphs
+  // Build expectations paragraph
+  let expectationsParagraph = "";
   if (job.expectations) {
     const exp = job.expectations;
     const expectationSentences = [];
@@ -89,45 +69,20 @@ export function formatJobDescription({ job, discipline, grade, track }) {
     }
 
     if (expectationSentences.length > 0) {
-      lines.push(expectationSentences.join(" "));
-      lines.push("");
+      expectationsParagraph = expectationSentences.join(" ");
     }
   }
 
-  // Key Responsibilities
-  lines.push("## ROLE RESPONSIBILITIES");
-  lines.push("");
-
-  // Use derived responsibilities (already sorted by level descending)
-  const derivedResponsibilities = job.derivedResponsibilities || [];
-
-  for (const r of derivedResponsibilities) {
-    lines.push(`- **${r.capabilityName}:** ${r.responsibility}`);
-  }
-  lines.push("");
-
-  // Key Behaviours
-  lines.push("## ROLE BEHAVIOURS");
-  lines.push("");
-
   // Sort behaviours by maturity level (highest first)
   const sortedBehaviours = [...job.behaviourProfile].sort((a, b) => {
     const indexA = BEHAVIOUR_MATURITY_ORDER.indexOf(a.maturity);
     const indexB = BEHAVIOUR_MATURITY_ORDER.indexOf(b.maturity);
-    // Sort in reverse order (exemplifying first, emerging last)
     if (indexA === -1 && indexB === -1) return 0;
     if (indexA === -1) return 1;
     if (indexB === -1) return -1;
     return indexB - indexA;
   });
 
-  for (const behaviour of sortedBehaviours) {
-    lines.push(
-      `- **${behaviour.behaviourName}:** ${behaviour.maturityDescription || ""}`,
-    );
-  }
-  lines.push("");
-
   // Group skills by level
   const skillsByLevel = {};
   for (const skill of job.skillMatrix) {
@@ -138,41 +93,73 @@ export function formatJobDescription({ job, discipline, grade, track }) {
     skillsByLevel[level].push(skill);
   }
 
-  // Sort levels in a logical order using SKILL_LEVEL_ORDER from types.js
+  // Sort levels in reverse order (expert first, awareness last)
   const sortedLevels = Object.keys(skillsByLevel).sort((a, b) => {
     const indexA = SKILL_LEVEL_ORDER.indexOf(a.toLowerCase());
     const indexB = SKILL_LEVEL_ORDER.indexOf(b.toLowerCase());
-    // Sort in reverse order (expert first, awareness last)
     if (indexA === -1 && indexB === -1) return a.localeCompare(b);
     if (indexA === -1) return 1;
     if (indexB === -1) return -1;
     return indexB - indexA;
   });
 
-  for (const level of sortedLevels) {
-    const skills = skillsByLevel[level];
-    if (skills.length > 0) {
-      lines.push(`## ${level.toUpperCase()}-LEVEL SKILLS`);
-      lines.push("");
-      // Sort skills alphabetically by name
-      const sortedSkills = [...skills].sort((a, b) =>
-        (a.skillName || "").localeCompare(b.skillName || ""),
-      );
-      for (const skill of sortedSkills) {
-        lines.push(`- **${skill.skillName}:** ${skill.levelDescription || ""}`);
-      }
-      lines.push("");
-    }
-  }
+  // Keep only the top 2 skill levels for job descriptions
+  const topLevels = sortedLevels.slice(0, 2);
 
-  // Qualifications
-  lines.push("## QUALIFICATIONS");
-  lines.push("");
+  // Build skill levels array for template
+  const skillLevels = topLevels.map((level) => {
+    const skills = skillsByLevel[level];
+    const sortedSkills = [...skills].sort((a, b) =>
+      (a.skillName || "").localeCompare(b.skillName || ""),
+    );
+    return {
+      levelHeading: `${level.toUpperCase()}-LEVEL SKILLS`,
+      skills: sortedSkills.map((s) => ({
+        skillName: s.skillName,
+        levelDescription: s.levelDescription || "",
+      })),
+    };
+  });
 
-  if (grade.qualificationSummary) {
-    lines.push(grade.qualificationSummary);
-    lines.push("");
-  }
+  return {
+    title: job.title,
+    gradeId: grade.id,
+    typicalExperienceRange: grade.typicalExperienceRange,
+    trackName: track?.name || null,
+    roleSummary,
+    trackRoleContext: track?.roleContext || null,
+    expectationsParagraph: expectationsParagraph || null,
+    responsibilities: (job.derivedResponsibilities || []).map((r) => ({
+      capabilityName: r.capabilityName,
+      responsibility: r.responsibility,
+    })),
+    behaviours: sortedBehaviours.map((b) => ({
+      behaviourName: b.behaviourName,
+      maturityDescription: b.maturityDescription || "",
+    })),
+    skillLevels,
+    qualificationSummary:
+      (grade.qualificationSummary || "").replace(
+        /\{typicalExperienceRange\}/g,
+        grade.typicalExperienceRange || "",
+      ) || null,
+  };
+}
 
-  return lines.join("\n");
+/**
+ * Format job as a markdown job description using Mustache template
+ * @param {Object} params
+ * @param {Object} params.job - The job definition
+ * @param {Object} params.discipline - The discipline
+ * @param {Object} params.grade - The grade
+ * @param {Object} [params.track] - The track (optional)
+ * @param {string} template - Mustache template string
+ * @returns {string} Markdown formatted job description
+ */
+export function formatJobDescription(
+  { job, discipline, grade, track },
+  template,
+) {
+  const data = prepareJobDescriptionData({ job, discipline, grade, track });
+  return Mustache.render(template, data);
 }

package/app/formatters/job/dom.js

@@ -2,18 +2,7 @@
  * Job formatting for DOM/web output
  */
 
-import {
-  div,
-  h1,
-  h2,
-  p,
-  a,
-  span,
-  button,
-  section,
-  details,
-  summary,
-} from "../../lib/render.js";
+import { div, h1, h2, p, a, span, button, section } from "../../lib/render.js";
 import { createBackLink } from "../../components/nav.js";
 import {
   createDetailSection,
@@ -39,6 +28,7 @@ import { formatJobDescription } from "./description.js";
  * @param {Object} [options.discipline] - Discipline entity for job description
  * @param {Object} [options.grade] - Grade entity for job description
  * @param {Object} [options.track] - Track entity for job description
+ * @param {string} [options.jobTemplate] - Mustache template for job description
  * @returns {HTMLElement}
  */
 export function jobToDOM(view, options = {}) {
@@ -50,9 +40,10 @@ export function jobToDOM(view, options = {}) {
     discipline,
     grade,
     track,
+    jobTemplate,
   } = options;
 
-  const hasEntities = discipline && grade && track;
+  const hasEntities = discipline && grade && jobTemplate;
 
   return div(
     { className: "job-detail-page" },
@@ -108,6 +99,7 @@ export function jobToDOM(view, options = {}) {
           discipline,
           grade,
           track,
+          template: jobTemplate,
         })
       : null,
 
@@ -140,14 +132,6 @@ export function jobToDOM(view, options = {}) {
                 ),
               })
             : null,
-
-          // Handoff Checklists
-          view.checklists && hasChecklistItems(view.checklists)
-            ? createDetailSection({
-                title: "📋 Handoff Checklists",
-                content: createChecklistSections(view.checklists),
-              })
-            : null,
         )
       : null,
 
@@ -164,6 +148,7 @@ export function jobToDOM(view, options = {}) {
           discipline,
           grade,
           track,
+          template: jobTemplate,
         })
       : null,
   );
@@ -211,84 +196,6 @@ function getScoreColor(score) {
   return "#ef4444"; // Red
 }
 
-/**
- * Check if any checklist has items
- * @param {Object} checklists - Checklists object keyed by handoff type
- * @returns {boolean}
- */
-function hasChecklistItems(checklists) {
-  for (const items of Object.values(checklists)) {
-    if (items && items.length > 0) {
-      return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Create collapsible checklist sections for all handoffs
- * @param {Object} checklists - Checklists object keyed by handoff type
- * @returns {HTMLElement}
- */
-function createChecklistSections(checklists) {
-  const handoffLabels = {
-    plan_to_code: "📋 → 💻 Plan → Code",
-    code_to_review: "💻 → ✅ Code → Review",
-  };
-
-  const sections = Object.entries(checklists)
-    .filter(([_, items]) => items && items.length > 0)
-    .map(([handoff, groups]) => {
-      const label = handoffLabels[handoff] || handoff;
-      const totalItems = groups.reduce((sum, g) => sum + g.items.length, 0);
-
-      return details(
-        { className: "checklist-section" },
-        summary(
-          { className: "checklist-section-header" },
-          span({ className: "checklist-section-label" }, label),
-          span({ className: "badge badge-default" }, `${totalItems} items`),
-        ),
-        div(
-          { className: "checklist-section-content" },
-          ...groups.map((group) => createChecklistGroup(group)),
-        ),
-      );
-    });
-
-  return div({ className: "checklist-sections" }, ...sections);
-}
-
-/**
- * Create a checklist group for a capability
- * @param {Object} group - Group with capability, level, and items
- * @returns {HTMLElement}
- */
-function createChecklistGroup(group) {
-  const emoji = group.capability.emoji || "📌";
-  const capabilityName = group.capability.name || group.capability.id;
-
-  return div(
-    { className: "checklist-group" },
-    div(
-      { className: "checklist-group-header" },
-      span({ className: "checklist-emoji" }, emoji),
-      span({ className: "checklist-capability" }, capabilityName),
-      span({ className: "badge badge-secondary" }, group.level),
-    ),
-    div(
-      { className: "checklist-items" },
-      ...group.items.map((item) =>
-        div(
-          { className: "checklist-item" },
-          span({ className: "checklist-checkbox" }, "☐"),
-          span({}, item),
-        ),
-      ),
-    ),
-  );
-}
-
 /**
  * Create the job description section with copy button
  * @param {Object} params
@@ -296,15 +203,25 @@ function createChecklistGroup(group) {
  * @param {Object} params.discipline - The discipline
  * @param {Object} params.grade - The grade
  * @param {Object} params.track - The track
+ * @param {string} params.template - Mustache template for job description
  * @returns {HTMLElement} The job description section element
  */
-export function createJobDescriptionSection({ job, discipline, grade, track }) {
-  const markdown = formatJobDescription({
-    job,
-    discipline,
-    grade,
-    track,
-  });
+export function createJobDescriptionSection({
+  job,
+  discipline,
+  grade,
+  track,
+  template,
+}) {
+  const markdown = formatJobDescription(
+    {
+      job,
+      discipline,
+      grade,
+      track,
+    },
+    template,
+  );
 
   const copyButton = button(
     {
@@ -388,15 +305,25 @@ export function createJobDescriptionSection({ job, discipline, grade, track }) {
  * @param {Object} params.discipline - The discipline
  * @param {Object} params.grade - The grade
  * @param {Object} params.track - The track
+ * @param {string} params.template - Mustache template for job description
  * @returns {HTMLElement} The job description HTML element (print-only)
  */
-export function createJobDescriptionHtml({ job, discipline, grade, track }) {
-  const markdown = formatJobDescription({
-    job,
-    discipline,
-    grade,
-    track,
-  });
+export function createJobDescriptionHtml({
+  job,
+  discipline,
+  grade,
+  track,
+  template,
+}) {
+  const markdown = formatJobDescription(
+    {
+      job,
+      discipline,
+      grade,
+      track,
+    },
+    template,
+  );
 
   const html = markdownToHtml(markdown);
 

package/app/formatters/job/markdown.js

@@ -15,9 +15,10 @@ import { SKILL_LEVEL_ORDER } from "../../model/levels.js";
  * Format job detail as markdown
  * @param {Object} view - Job detail view from presenter
  * @param {Object} [entities] - Original entities (for job description)
+ * @param {string} [jobTemplate] - Mustache template for job description
  * @returns {string}
  */
-export function jobToMarkdown(view, entities = {}) {
+export function jobToMarkdown(view, entities = {}, jobTemplate) {
   const lines = [
     `# ${view.title}`,
     "",
@@ -77,23 +78,26 @@ export function jobToMarkdown(view, entities = {}) {
   }
 
   // Job Description (copyable markdown)
-  if (entities.discipline && entities.grade && entities.track) {
+  if (entities.discipline && entities.grade && jobTemplate) {
     lines.push("---", "");
     lines.push("## Job Description", "");
     lines.push("```markdown");
     lines.push(
-      formatJobDescription({
-        job: {
-          title: view.title,
-          skillMatrix: view.skillMatrix,
-          behaviourProfile: view.behaviourProfile,
-          expectations: view.expectations,
-          derivedResponsibilities: view.derivedResponsibilities,
+      formatJobDescription(
+        {
+          job: {
+            title: view.title,
+            skillMatrix: view.skillMatrix,
+            behaviourProfile: view.behaviourProfile,
+            expectations: view.expectations,
+            derivedResponsibilities: view.derivedResponsibilities,
+          },
+          discipline: entities.discipline,
+          grade: entities.grade,
+          track: entities.track,
         },
-        discipline: entities.discipline,
-        grade: entities.grade,
-        track: entities.track,
-      }),
+        jobTemplate,
+      ),
     );
     lines.push("```");
   }

package/app/formatters/shared.js

@@ -36,7 +36,7 @@ export function tableToMarkdown(headers, rows) {
 export function objectToMarkdownList(obj, indent = 0) {
   const prefix = "  ".repeat(indent);
   return Object.entries(obj)
-    .map(([key, value]) => `${prefix}- **${key}**: ${value}`)
+    .map(([key, value]) => `${prefix}- **${capitalize(key)}**: ${value}`)
     .join("\n");
 }
 
@@ -51,12 +51,17 @@ export function formatPercent(value) {
 
 /**
  * Capitalize first letter of each word
+ * Handles both snake_case and camelCase
  * @param {string} str
  * @returns {string}
  */
 export function capitalize(str) {
   if (!str) return "";
-  return str.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  // Insert space before uppercase letters (for camelCase), then handle snake_case
+  return str
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/_/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
 /**

package/app/handout.html

@@ -5,6 +5,13 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Engineering Pathway - Handout View</title>
     <link rel="stylesheet" href="css/bundles/handout.css" />
+    <script type="importmap">
+      {
+        "imports": {
+          "mustache": "https://esm.sh/mustache@4.2.0"
+        }
+      }
+    </script>
   </head>
   <body class="slide-view handout-view">
     <header

package/app/lib/form-controls.js

@@ -2,7 +2,7 @@
  * Reusable form control components
  */
 
-import { select, option } from "./render.js";
+import { select, option, optgroup } from "./render.js";
 
 /**
  * Create a select element with initial value and change handler
@@ -45,3 +45,66 @@ export function createSelectWithValue({
 
   return selectEl;
 }
+
+/**
+ * Create a discipline select with optgroups for Professional and Management
+ * @param {Object} options - Configuration options
+ * @param {string} options.id - Element ID
+ * @param {Array} options.disciplines - Array of discipline objects
+ * @param {string} options.initialValue - Initial selected value
+ * @param {string} options.placeholder - Placeholder text for empty option
+ * @param {Function} options.onChange - Callback when selection changes
+ * @param {Function} [options.getDisplayName] - Optional function to get display name from item
+ * @returns {HTMLElement}
+ */
+export function createDisciplineSelect({
+  id,
+  disciplines,
+  initialValue,
+  placeholder,
+  onChange,
+  getDisplayName,
+}) {
+  const displayFn = getDisplayName || ((d) => d.specialization || d.name);
+
+  // Separate disciplines by type
+  const professional = disciplines.filter((d) => d.isProfessional);
+  const management = disciplines.filter((d) => d.isManagement);
+
+  // Sort each group alphabetically by display name
+  professional.sort((a, b) => displayFn(a).localeCompare(displayFn(b)));
+  management.sort((a, b) => displayFn(a).localeCompare(displayFn(b)));
+
+  // Build options for a group
+  const buildOptions = (items) =>
+    items.map((item) => {
+      const opt = option({ value: item.id }, displayFn(item));
+      if (item.id === initialValue) {
+        opt.selected = true;
+      }
+      return opt;
+    });
+
+  // Build optgroups - Professional first, then Management
+  const groups = [];
+  if (professional.length > 0) {
+    groups.push(
+      optgroup({ label: "Professional" }, ...buildOptions(professional)),
+    );
+  }
+  if (management.length > 0) {
+    groups.push(optgroup({ label: "Management" }, ...buildOptions(management)));
+  }
+
+  const selectEl = select(
+    { className: "form-select", id },
+    option({ value: "" }, placeholder),
+    ...groups,
+  );
+
+  selectEl.addEventListener("change", (e) => {
+    onChange(e.target.value);
+  });
+
+  return selectEl;
+}

package/app/lib/render.js

@@ -118,6 +118,8 @@ export const select = (attrs, ...children) =>
   createElement("select", attrs, ...children);
 export const option = (attrs, ...children) =>
   createElement("option", attrs, ...children);
+export const optgroup = (attrs, ...children) =>
+  createElement("optgroup", attrs, ...children);
 export const label = (attrs, ...children) =>
   createElement("label", attrs, ...children);
 export const form = (attrs, ...children) =>
@@ -185,12 +187,17 @@ export function showError(message) {
 
 /**
  * Format a skill level or behaviour maturity for display
+ * Handles both snake_case and camelCase
  * @param {string} value - The level/maturity value
  * @returns {string}
  */
 export function formatLevel(value) {
   if (!value) return "";
-  return value.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  // Insert space before uppercase letters (for camelCase), then handle snake_case
+  return value
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/_/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
 /**

package/app/lib/template-loader.js

@@ -64,3 +64,12 @@ export async function loadAgentTemplate(dataDir) {
 export async function loadSkillTemplate(dataDir) {
   return loadTemplate("skill.template.md", dataDir);
 }
+
+/**
+ * Load job description template
+ * @param {string} dataDir - Path to data directory
+ * @returns {Promise<string>} Job template content
+ */
+export async function loadJobTemplate(dataDir) {
+  return loadTemplate("job.template.md", dataDir);
+}

package/app/pages/agent-builder.js

@@ -26,7 +26,10 @@ import {
   deriveAgentSkills,
   deriveReferenceGrade,
 } from "../model/agent.js";
-import { createSelectWithValue } from "../lib/form-controls.js";
+import {
+  createSelectWithValue,
+  createDisciplineSelect,
+} from "../lib/form-controls.js";
 import { createReactive } from "../lib/reactive.js";
 import { getStageEmoji } from "../formatters/stage/shared.js";
 import { formatAgentProfile } from "../formatters/agent/profile.js";
@@ -242,9 +245,9 @@ export async function renderAgentBuilder() {
           { className: "form-group" },
           label({ className: "form-label" }, "Discipline"),
           availableDisciplines.length > 0
-            ? createSelectWithValue({
+            ? createDisciplineSelect({
                 id: "agent-discipline-select",
-                items: availableDisciplines,
+                disciplines: availableDisciplines,
                 initialValue: selection.get().discipline,
                 placeholder: "Select a discipline...",
                 onChange: (value) => {

package/app/pages/job.js

@@ -2,17 +2,32 @@
  * Job detail page with visualizations
  */
 
-import { render } from "../lib/render.js";
+import { render, div, p } from "../lib/render.js";
 import { getState } from "../lib/state.js";
 import { renderError } from "../components/error-page.js";
 import { prepareJobDetail } from "../model/job.js";
 import { jobToDOM } from "../formatters/job/dom.js";
 
+/** @type {string|null} Cached job template */
+let jobTemplateCache = null;
+
+/**
+ * Load job template with caching
+ * @returns {Promise<string>}
+ */
+async function getJobTemplate() {
+  if (!jobTemplateCache) {
+    const response = await fetch("./templates/job.template.md");
+    jobTemplateCache = await response.text();
+  }
+  return jobTemplateCache;
+}
+
 /**
  * Render job detail page
  * @param {Object} params - Route params
  */
-export function renderJobDetail(params) {
+export async function renderJobDetail(params) {
   const { discipline: disciplineId, grade: gradeId, track: trackId } = params;
   const { data } = getState();
 
@@ -63,7 +78,16 @@ export function renderJobDetail(params) {
     return;
   }
 
-  // Format using DOM formatter
-  const page = jobToDOM(jobView, { discipline, grade, track });
+  // Show loading while fetching template
+  render(
+    div(
+      { className: "job-detail-page" },
+      div({ className: "loading" }, p({}, "Loading...")),
+    ),
+  );
+
+  // Load template and format
+  const jobTemplate = await getJobTemplate();
+  const page = jobToDOM(jobView, { discipline, grade, track, jobTemplate });
   render(page);
 }

package/app/pages/progress.js

@@ -13,7 +13,10 @@ import {
 } from "../components/comparison-radar.js";
 import { createProgressionTable } from "../components/progression-table.js";
 import { renderError } from "../components/error-page.js";
-import { createSelectWithValue } from "../lib/form-controls.js";
+import {
+  createSelectWithValue,
+  createDisciplineSelect,
+} from "../lib/form-controls.js";
 import {
   prepareCurrentJob,
   prepareCustomProgression,
@@ -513,11 +516,9 @@ function createComparisonSelectorsSection({
       div(
         { className: "form-group" },
         label({ for: "compare-discipline-select" }, "Target Discipline"),
-        createSelectWithValue({
+        createDisciplineSelect({
           id: "compare-discipline-select",
-          items: data.disciplines.sort((a, b) =>
-            a.specialization.localeCompare(b.specialization),
-          ),
+          disciplines: data.disciplines,
           initialValue: selectedDisciplineId,
           placeholder: "Select discipline...",
           getDisplayName: (d) => d.specialization,

package/app/pages/self-assessment.js

@@ -17,7 +17,7 @@ import {
 } from "../lib/render.js";
 import { getState } from "../lib/state.js";
 import { createBadge } from "../components/card.js";
-import { createSelectWithValue } from "../lib/form-controls.js";
+import { createDisciplineSelect } from "../lib/form-controls.js";
 import {
   SKILL_LEVEL_ORDER,
   BEHAVIOUR_MATURITY_ORDER,
@@ -306,9 +306,9 @@ function renderIntroStep(data) {
           "Select a discipline to highlight which skills are most relevant for that role. " +
             "You can still assess all skills.",
         ),
-        createSelectWithValue({
+        createDisciplineSelect({
           id: "discipline-filter-select",
-          items: data.disciplines,
+          disciplines: data.disciplines,
           initialValue: assessmentState.discipline || "",
           placeholder: "Select discipline",
           onChange: (value) => {

package/app/slides.html

@@ -5,6 +5,13 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Engineering Pathway - Slide View</title>
     <link rel="stylesheet" href="css/bundles/slides.css" />
+    <script type="importmap">
+      {
+        "imports": {
+          "mustache": "https://esm.sh/mustache@4.2.0"
+        }
+      }
+    </script>
   </head>
   <body class="slide-view">
     <header

package/bin/pathway.js

@@ -101,7 +101,7 @@ Composite Commands:
   progress <discipline> <track> <grade> [--compare=GRADE]
                                       Show career progression
   questions [filters]                 Browse interview questions
-  agent [<discipline> <track>]        Generate AI coding agent
+  agent <discipline> [--track=<track>] Generate AI coding agent
 
 Global Options:
   --list            Output IDs only (for piping to other commands)
@@ -121,10 +121,10 @@ Questions Filters:
   --format=FORMAT     Output format: table, yaml, json
 
 Agent Options:
-  --output=PATH       Output directory (default: current directory)
-  --preview           Show output without writing files
-  --role=ROLE         Generate specific role variant
-  --all-roles         Generate default + all role variants
+  --track=TRACK       Track for the agent (e.g., platform, forward_deployed)
+  --output=PATH       Write files to directory (without this, outputs to console)
+  --stage=STAGE       Generate specific stage agent (plan, code, review)
+  --all-stages        Generate all stage agents (default)
 
 Examples:
   npx pathway skill                    # Summary of all skills
@@ -139,7 +139,7 @@ Examples:
   npx pathway questions --level=practitioner
   npx pathway questions --stats
 
-  npx pathway agent software_engineering platform --output=./agents
+  npx pathway agent software_engineering --track=platform --output=./agents
   npx pathway --validate               # Validate all data
 `;
 
@@ -160,6 +160,8 @@ function parseArgs(args) {
     type: "full",
     compare: null,
     data: null,
+    // Shared command options
+    track: null,
     // Questions command options
     level: null,
     maturity: null,
@@ -172,9 +174,6 @@ function parseArgs(args) {
     checklist: null,
     // Agent command options
     output: null,
-    preview: false,
-    role: null,
-    "all-roles": false,
     stage: null,
     "all-stages": false,
     // Serve command options
@@ -196,14 +195,14 @@ function parseArgs(args) {
       result.validate = true;
     } else if (arg === "--generate-index") {
       result.generateIndex = true;
-    } else if (arg === "--preview") {
-      result.preview = true;
     } else if (arg.startsWith("--type=")) {
       result.type = arg.slice(7);
     } else if (arg.startsWith("--compare=")) {
       result.compare = arg.slice(10);
     } else if (arg.startsWith("--data=")) {
       result.data = arg.slice(7);
+    } else if (arg.startsWith("--track=")) {
+      result.track = arg.slice(8);
     } else if (arg.startsWith("--output=")) {
       result.output = arg.slice(9);
     } else if (arg.startsWith("--level=")) {

package/examples/grades.yaml

@@ -28,9 +28,9 @@
   managementTitle: Manager
   typicalExperienceRange: "2-5"
   ordinalRank: 2
-  qualificationSummary:
-    2-5 years of relevant experience. Demonstrated ability to complete tasks
-    independently and contribute effectively to team projects.
+  qualificationSummary: >
+    {typicalExperienceRange} years of relevant experience. Demonstrated ability
+    to complete tasks independently and contribute effectively to team projects.
   baseSkillLevels:
     primary: foundational
     secondary: foundational
@@ -50,9 +50,9 @@
   managementTitle: Senior Manager
   typicalExperienceRange: "5-8"
   ordinalRank: 3
-  qualificationSummary:
-    5-8 years of relevant experience. Proven track record of leading technical
-    initiatives and mentoring team members.
+  qualificationSummary: >
+    {typicalExperienceRange} years of relevant experience. Proven track record
+    of leading technical initiatives and mentoring team members.
   baseSkillLevels:
     primary: practitioner
     secondary: working
@@ -71,9 +71,9 @@
   managementTitle: Director
   typicalExperienceRange: "8-12"
   ordinalRank: 4
-  qualificationSummary:
-    8-12 years of relevant experience. Extensive experience leading complex
-    technical projects with multi-team impact.
+  qualificationSummary: >
+    {typicalExperienceRange} years of relevant experience. Extensive experience
+    leading complex technical projects with multi-team impact.
   baseSkillLevels:
     primary: expert
     secondary: practitioner
@@ -94,9 +94,10 @@
   managementTitle: VP of Engineering
   typicalExperienceRange: "12+"
   ordinalRank: 5
-  qualificationSummary:
-    12+ years of relevant experience. Deep technical expertise with a proven
-    track record of organization-wide technical leadership.
+  qualificationSummary: >
+    {typicalExperienceRange} years of relevant experience. Deep technical
+    expertise with a proven track record of organization-wide technical
+    leadership.
   baseSkillLevels:
     primary: expert
     secondary: expert

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/pathway",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Engineering Pathway framework for human and AI collaboration",
   "license": "Apache-2.0",
   "repository": {

package/templates/job.template.md

@@ -0,0 +1,47 @@
+# {{title}}
+
+- **Level:** {{gradeId}}
+- **Experience:** {{typicalExperienceRange}}
+{{#trackName}}- **Track:** {{trackName}}
+{{/trackName}}
+
+## ROLE SUMMARY
+
+{{{roleSummary}}}
+
+{{#trackRoleContext}}
+{{{trackRoleContext}}}
+
+{{/trackRoleContext}}
+{{#expectationsParagraph}}
+{{{expectationsParagraph}}}
+
+{{/expectationsParagraph}}
+
+## ROLE RESPONSIBILITIES
+
+{{#responsibilities}}
+- **{{capabilityName}}:** {{responsibility}}
+{{/responsibilities}}
+
+## ROLE BEHAVIOURS
+
+{{#behaviours}}
+- **{{behaviourName}}:** {{maturityDescription}}
+{{/behaviours}}
+
+{{#skillLevels}}
+
+## {{levelHeading}}
+
+{{#skills}}
+- **{{skillName}}:** {{levelDescription}}
+{{/skills}}
+
+{{/skillLevels}}
+
+## QUALIFICATIONS
+
+{{#qualificationSummary}}
+{{{qualificationSummary}}}
+{{/qualificationSummary}}