@forwardimpact/pathway 0.2.0 → 0.4.0

package/app/css/pages/job-builder.css

@@ -89,46 +89,4 @@
     font-weight: 600;
     color: var(--color-primary);
   }
-
-  /* Job description section */
-  .job-description-container {
-    display: flex;
-    flex-direction: column;
-    gap: var(--space-md);
-  }
-
-  .job-description-header {
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
-    flex-wrap: wrap;
-    gap: var(--space-md);
-  }
-
-  .job-description-header .text-muted {
-    margin: 0;
-    flex: 1;
-    min-width: 200px;
-  }
-
-  .job-description-textarea {
-    width: 100%;
-    min-height: 400px;
-    padding: var(--space-md);
-    font-family:
-      ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
-    font-size: var(--font-size-sm);
-    line-height: 1.6;
-    background-color: var(--color-bg);
-    border: 1px solid var(--color-border);
-    border-radius: var(--radius-md);
-    resize: vertical;
-    color: var(--color-text);
-  }
-
-  .job-description-textarea:focus {
-    outline: none;
-    border-color: var(--color-primary);
-    box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
-  }
 }

package/app/formatters/agent/profile.js

@@ -10,6 +10,66 @@
 
 import Mustache from "mustache";
 
+import { trimValue, trimRequired, trimFields } from "../shared.js";
+
+/**
+ * Prepare agent profile data for template rendering
+ * Normalizes string values by trimming trailing newlines for consistent template output.
+ * @param {Object} params
+ * @param {Object} params.frontmatter - YAML frontmatter data
+ * @param {string} params.frontmatter.name - Agent name
+ * @param {string} params.frontmatter.description - Agent description
+ * @param {boolean} params.frontmatter.infer - Whether to auto-select
+ * @param {Array} [params.frontmatter.handoffs] - Handoff definitions
+ * @param {Object} params.bodyData - Structured body data
+ * @param {string} params.bodyData.title - Agent title
+ * @param {string} params.bodyData.stageDescription - Stage description text
+ * @param {string} params.bodyData.identity - Core identity text
+ * @param {string} [params.bodyData.priority] - Priority/philosophy statement
+ * @param {string[]} params.bodyData.capabilities - List of capability names
+ * @param {Array<{index: number, text: string}>} params.bodyData.beforeMakingChanges - Numbered steps
+ * @param {string} [params.bodyData.delegation] - Delegation guidance
+ * @param {string} params.bodyData.operationalContext - Operational context text
+ * @param {string} params.bodyData.workingStyle - Working style markdown section
+ * @param {string} [params.bodyData.beforeHandoff] - Before handoff checklist markdown
+ * @param {string[]} params.bodyData.constraints - List of constraints
+ * @returns {Object} Data object ready for Mustache template
+ */
+function prepareAgentProfileData({ frontmatter, bodyData }) {
+  // Trim array fields using helpers
+  const handoffs = trimFields(frontmatter.handoffs, { prompt: "required" });
+  const beforeMakingChanges = trimFields(bodyData.beforeMakingChanges, {
+    text: "required",
+  });
+
+  // Trim simple string arrays
+  const constraints = (bodyData.constraints || []).map((c) => trimRequired(c));
+  const capabilities = (bodyData.capabilities || []).map((c) =>
+    trimRequired(c),
+  );
+
+  return {
+    // Frontmatter
+    name: frontmatter.name,
+    description: trimRequired(frontmatter.description),
+    infer: frontmatter.infer,
+    handoffs,
+
+    // Body data - trim all string fields
+    title: bodyData.title,
+    stageDescription: trimValue(bodyData.stageDescription),
+    identity: trimValue(bodyData.identity),
+    priority: trimValue(bodyData.priority),
+    capabilities,
+    beforeMakingChanges,
+    delegation: trimValue(bodyData.delegation),
+    operationalContext: trimValue(bodyData.operationalContext),
+    workingStyle: trimValue(bodyData.workingStyle),
+    beforeHandoff: trimValue(bodyData.beforeHandoff),
+    constraints,
+  };
+}
+
 /**
  * Format agent profile as .agent.md file content using Mustache template
  * @param {Object} profile - Profile with frontmatter and bodyData
@@ -35,125 +95,6 @@ import Mustache from "mustache";
  * @returns {string} Complete .agent.md file content
  */
 export function formatAgentProfile({ frontmatter, bodyData }, template) {
-  const data = {
-    // Frontmatter
-    name: frontmatter.name,
-    description: frontmatter.description,
-    infer: frontmatter.infer,
-    handoffs: frontmatter.handoffs || [],
-    // Body data
-    ...bodyData,
-  };
+  const data = prepareAgentProfileData({ frontmatter, bodyData });
   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

@@ -10,6 +10,47 @@
 
 import Mustache from "mustache";
 
+import { trimValue, splitLines, trimFields } from "../shared.js";
+
+/**
+ * Prepare agent skill data for template rendering
+ * Normalizes string values by trimming trailing newlines for consistent template output.
+ * @param {Object} params
+ * @param {Object} params.frontmatter - YAML frontmatter data
+ * @param {string} params.frontmatter.name - Skill name (required)
+ * @param {string} params.frontmatter.description - Skill description (required)
+ * @param {string} [params.frontmatter.useWhen] - When to use this skill
+ * @param {string} params.title - Human-readable skill title for heading
+ * @param {Array} params.stages - Array of stage objects with stageName, focus, activities, ready
+ * @param {string} params.reference - Reference content (markdown)
+ * @param {Array} [params.toolReferences] - Array of tool reference objects
+ * @returns {Object} Data object ready for Mustache template
+ */
+function prepareAgentSkillData({
+  frontmatter,
+  title,
+  stages,
+  reference,
+  toolReferences,
+}) {
+  // Process stages - trim focus and array values
+  const processedStages = trimFields(stages, {
+    focus: "required",
+    activities: "array",
+    ready: "array",
+  });
+
+  return {
+    name: frontmatter.name,
+    descriptionLines: splitLines(frontmatter.description),
+    useWhenLines: splitLines(frontmatter.useWhen),
+    title,
+    stages: processedStages,
+    reference: trimValue(reference) || "",
+    toolReferences: toolReferences || [],
+  };
+}
+
 /**
  * Format agent skill as SKILL.md file content using Mustache template
  * @param {Object} skill - Skill with frontmatter, title, stages, reference
@@ -19,73 +60,20 @@ import Mustache from "mustache";
  * @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 {Array} [skill.toolReferences] - Array of tool reference objects
  * @param {string} template - Mustache template string
  * @returns {string} Complete SKILL.md file content
  */
 export function formatAgentSkill(
-  { frontmatter, title, stages, reference },
+  { frontmatter, title, stages, reference, toolReferences },
   template,
 ) {
-  const data = {
-    name: frontmatter.name,
-    descriptionLines: frontmatter.description.trim().split("\n"),
+  const data = prepareAgentSkillData({
+    frontmatter,
     title,
     stages,
-    reference: reference ? reference.trim() : "",
-  };
+    reference,
+    toolReferences,
+  });
   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,29 @@
  *
  * 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";
+import { trimValue, trimFields } from "../shared.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 +36,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 +70,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 +94,77 @@ 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("");
-  }
+  // Build qualification summary with placeholder replacement
+  const qualificationSummary =
+    (grade.qualificationSummary || "").replace(
+      /\{typicalExperienceRange\}/g,
+      grade.typicalExperienceRange || "",
+    ) || null;
+
+  return {
+    title: job.title,
+    gradeId: grade.id,
+    typicalExperienceRange: grade.typicalExperienceRange,
+    trackName: track?.name || null,
+    roleSummary: trimValue(roleSummary),
+    trackRoleContext: trimValue(track?.roleContext),
+    expectationsParagraph: trimValue(expectationsParagraph),
+    responsibilities: trimFields(job.derivedResponsibilities, {
+      responsibility: "required",
+    }),
+    behaviours: trimFields(sortedBehaviours, {
+      maturityDescription: "optional",
+    }),
+    skillLevels: skillLevels.map((level) => ({
+      ...level,
+      skills: trimFields(level.skills, { levelDescription: "optional" }),
+    })),
+    qualificationSummary: trimValue(qualificationSummary),
+  };
+}
 
-  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);
 }