@forwardimpact/pathway 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/pathway",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Career progression web app and CLI for exploring roles and generating agents",
   "license": "Apache-2.0",
   "repository": {
@@ -40,8 +40,8 @@
     "./commands": "./src/commands/index.js"
   },
   "dependencies": {
-    "@forwardimpact/schema": "^0.4.0",
-    "@forwardimpact/model": "^0.5.0",
+    "@forwardimpact/schema": "^0.5.0",
+    "@forwardimpact/model": "^0.6.0",
     "mustache": "^4.2.0",
     "simple-icons": "^16.7.0",
     "yaml": "^2.3.4"

package/src/commands/agent.js

@@ -37,7 +37,7 @@ import {
   validateAgentSkill,
   deriveReferenceGrade,
   deriveAgentSkills,
-  generateSkillMd,
+  generateSkillMarkdown,
   deriveToolkit,
   buildAgentIndex,
 } from "@forwardimpact/model";
@@ -502,7 +502,7 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
   const skillFiles = derivedSkills
     .map((derived) => skillsWithAgent.find((s) => s.id === derived.skillId))
     .filter((skill) => skill?.agent)
-    .map((skill) => generateSkillMd(skill, data.stages));
+    .map((skill) => generateSkillMarkdown(skill, data.stages));
 
   // Validate all profiles
   for (const profile of profiles) {

package/src/commands/skill.js

@@ -16,7 +16,7 @@ import { skillToMarkdown } from "../formatters/skill/markdown.js";
 import { prepareSkillsList } from "../formatters/skill/shared.js";
 import { getConceptEmoji } from "@forwardimpact/schema/levels";
 import { formatTable, formatError } from "../lib/cli-output.js";
-import { generateSkillMd } from "@forwardimpact/model/agent";
+import { generateSkillMarkdown } from "@forwardimpact/model/agent";
 import { formatAgentSkill } from "../formatters/agent/skill.js";
 import { loadSkillTemplate } from "../lib/template-loader.js";
 
@@ -80,7 +80,7 @@ async function formatAgentDetail(skill, stages, dataDir) {
   }
 
   const template = await loadSkillTemplate(dataDir);
-  const skillMd = generateSkillMd(skill, stages);
+  const skillMd = generateSkillMarkdown(skill, stages);
   const output = formatAgentSkill(skillMd, template);
   console.log(output);
 }

package/src/components/comparison-radar.js

@@ -13,7 +13,7 @@ import {
   getBehaviourMaturityIndex,
   formatLevel,
 } from "../lib/render.js";
-import { getCapabilityIndex } from "@forwardimpact/schema/levels";
+import { compareByCapability } from "@forwardimpact/model/policies";
 
 /**
  * Create a comparison skill radar chart
@@ -24,7 +24,7 @@ import { getCapabilityIndex } from "@forwardimpact/schema/levels";
  */
 export function createComparisonSkillRadar(
   currentMatrix,
-  targetMatrix,
+  targetMatrix = [],
   options = {},
 ) {
   const container = div(
@@ -80,9 +80,11 @@ export function createComparisonSkillRadar(
     }
 
     // Sort by capability order, then by skill name within capability
+    const capabilityComparator = options.capabilities
+      ? compareByCapability(options.capabilities)
+      : (a, b) => a.capability.localeCompare(b.capability);
     skillEntries.sort((a, b) => {
-      const capDiff =
-        getCapabilityIndex(a.capability) - getCapabilityIndex(b.capability);
+      const capDiff = capabilityComparator(a, b);
       if (capDiff !== 0) return capDiff;
       return a.skillName.localeCompare(b.skillName);
     });
@@ -141,7 +143,7 @@ export function createComparisonSkillRadar(
  */
 export function createComparisonBehaviourRadar(
   currentProfile,
-  targetProfile,
+  targetProfile = [],
   options = {},
 ) {
   const container = div(

package/src/css/components/badges.css

@@ -93,50 +93,30 @@
     font-weight: 500;
   }
 
-  /* Capability badges */
+  /* Capability badges - each capability ID maps to its own distinct color */
   .badge-delivery {
-    background: var(--color-cat-delivery-light);
-    color: var(--color-cat-delivery);
+    background: var(--color-cap-delivery-light);
+    color: var(--color-cap-delivery);
   }
 
   .badge-scale {
-    background: var(--color-cat-scale-light);
-    color: var(--color-cat-scale);
+    background: var(--color-cap-scale-light);
+    color: var(--color-cap-scale);
   }
 
   .badge-reliability {
-    background: var(--color-cat-reliability-light);
-    color: var(--color-cat-reliability);
-  }
-
-  .badge-data {
-    background: var(--color-cat-data-light);
-    color: var(--color-cat-data);
-  }
-
-  .badge-ai {
-    background: var(--color-cat-ai-light);
-    color: var(--color-cat-ai);
-  }
-
-  .badge-process {
-    background: var(--color-cat-process-light);
-    color: var(--color-cat-process);
+    background: var(--color-cap-reliability-light);
+    color: var(--color-cap-reliability);
   }
 
   .badge-business {
-    background: var(--color-cat-business-light);
-    color: var(--color-cat-business);
+    background: var(--color-cap-business-light);
+    color: var(--color-cap-business);
   }
 
   .badge-people {
-    background: var(--color-cat-people-light);
-    color: var(--color-cat-people);
-  }
-
-  .badge-documentation {
-    background: var(--color-cat-documentation-light);
-    color: var(--color-cat-documentation);
+    background: var(--color-cap-people-light);
+    color: var(--color-cap-people);
   }
 
   /* Tool badge */

package/src/css/tokens.css

@@ -43,30 +43,22 @@
     --color-maturity-5: #c4b5fd;
 
     /* --------------------------------------------------------------------------
-     Colors - Categories (text)
+     Colors - Capabilities (text)
      -------------------------------------------------------------------------- */
-    --color-cat-delivery: #dc2626; /* red - rapid delivery focus */
-    --color-cat-scale: #1d4ed8; /* blue - infrastructure/platform */
-    --color-cat-reliability: #0369a1; /* sky - SRE/operations */
-    --color-cat-data: #0f766e; /* teal */
-    --color-cat-ai: #7c3aed; /* violet */
-    --color-cat-process: #c2410c; /* orange */
-    --color-cat-business: #a16207; /* amber */
-    --color-cat-people: #be185d; /* pink */
-    --color-cat-documentation: #15803d; /* green */
+    --color-cap-delivery: #dc2626; /* red - speed and efficiency */
+    --color-cap-scale: #1d4ed8; /* blue - infrastructure and systems */
+    --color-cap-reliability: #0891b2; /* cyan - stability and operations */
+    --color-cap-business: #b45309; /* amber - strategy and outcomes */
+    --color-cap-people: #be185d; /* pink - collaboration and leadership */
 
     /* --------------------------------------------------------------------------
-     Colors - Categories (backgrounds)
+     Colors - Capabilities (backgrounds)
      -------------------------------------------------------------------------- */
-    --color-cat-delivery-light: #fecaca; /* red */
-    --color-cat-scale-light: #dbeafe; /* blue */
-    --color-cat-reliability-light: #e0f2fe; /* sky */
-    --color-cat-data-light: #ccfbf1; /* teal */
-    --color-cat-ai-light: #ede9fe; /* violet */
-    --color-cat-process-light: #ffedd5; /* orange */
-    --color-cat-business-light: #fef3c7; /* amber */
-    --color-cat-people-light: #fce7f3; /* pink */
-    --color-cat-documentation-light: #dcfce7; /* green */
+    --color-cap-delivery-light: #fecaca; /* red */
+    --color-cap-scale-light: #dbeafe; /* blue */
+    --color-cap-reliability-light: #cffafe; /* cyan */
+    --color-cap-business-light: #fef3c7; /* amber */
+    --color-cap-people-light: #fce7f3; /* pink */
 
     /* --------------------------------------------------------------------------
      Colors - Neutrals

package/src/formatters/agent/profile.js

@@ -11,6 +11,10 @@
 import Mustache from "mustache";
 
 import { trimValue, trimRequired, trimFields } from "../shared.js";
+import {
+  flattenToLine,
+  preprocessArrayFrontmatter,
+} from "../template-preprocess.js";
 
 /**
  * @typedef {Object} WorkingStyleEntry
@@ -49,8 +53,14 @@ import { trimValue, trimRequired, trimFields } from "../shared.js";
  * @returns {Object} Data object ready for Mustache template
  */
 function prepareAgentProfileData({ frontmatter, bodyData }) {
-  // Trim array fields using shared helpers
-  const handoffs = trimFields(frontmatter.handoffs, { prompt: "required" });
+  // Preprocess handoffs - flatten prompt field for front matter compatibility
+  const preprocessedHandoffs = preprocessArrayFrontmatter(
+    frontmatter.handoffs,
+    ["prompt"],
+  );
+  // Then trim as before
+  const handoffs = trimFields(preprocessedHandoffs, { prompt: "required" });
+
   const constraints = (bodyData.constraints || []).map((c) => trimRequired(c));
   const skillIndex = trimFields(bodyData.skillIndex, {
     name: "required",
@@ -75,9 +85,9 @@ function prepareAgentProfileData({ frontmatter, bodyData }) {
   }));
 
   return {
-    // Frontmatter
+    // Frontmatter - flatten description for single-line front matter
     name: frontmatter.name,
-    description: trimRequired(frontmatter.description),
+    description: flattenToLine(frontmatter.description),
     infer: frontmatter.infer,
     handoffs,
 

package/src/formatters/agent/skill.js

@@ -11,6 +11,7 @@
 import Mustache from "mustache";
 
 import { trimValue, splitLines, trimFields } from "../shared.js";
+import { flattenToLine } from "../template-preprocess.js";
 
 /**
  * Prepare agent skill data for template rendering
@@ -40,17 +41,25 @@ function prepareAgentSkillData({
     ready: "array",
   });
 
+  // Flatten multi-line strings to single line for front matter compatibility
+  const description = flattenToLine(frontmatter.description);
+  const useWhen = flattenToLine(frontmatter.useWhen);
+
+  // Keep line arrays for body rendering
   const descriptionLines = splitLines(frontmatter.description);
-  const useWhenLines = splitLines(frontmatter.useWhen);
+
   const trimmedReference = trimValue(reference) || "";
   const tools = toolReferences || [];
 
   return {
     name: frontmatter.name,
+    // Single-line versions for front matter
+    description,
+    hasDescription: !!description,
+    useWhen,
+    hasUseWhen: !!useWhen,
+    // Line arrays for body content
     descriptionLines,
-    hasDescription: descriptionLines.length > 0,
-    useWhenLines,
-    hasUseWhen: useWhenLines.length > 0,
     title,
     stages: processedStages,
     hasStages: processedStages.length > 0,

package/src/formatters/skill/shared.js

@@ -43,7 +43,7 @@ export function prepareSkillsList(
   capabilities,
   descriptionLimit = 120,
 ) {
-  const grouped = groupSkillsByCapability(skills);
+  const grouped = groupSkillsByCapability(skills, capabilities);
 
   const groups = {};
   for (const [capability, capabilitySkills] of Object.entries(grouped)) {

package/src/formatters/template-preprocess.js

@@ -0,0 +1,60 @@
+/**
+ * Template Preprocessing Utilities
+ *
+ * Functions to prepare template data for front matter compatibility.
+ * Ensures all front matter values are single-line strings for maximum
+ * compatibility with coding agents that have limited YAML parsing.
+ */
+
+/**
+ * Flatten a multi-line string into a single line
+ * Replaces newlines with spaces and collapses multiple spaces.
+ * @param {string|null|undefined} value - Value to flatten
+ * @returns {string} Single-line string (empty string if no value)
+ */
+export function flattenToLine(value) {
+  if (value == null) return "";
+  return value
+    .replace(/\s*\n\s*/g, " ") // Replace newlines (with surrounding whitespace) with single space
+    .replace(/\s+/g, " ") // Collapse multiple spaces
+    .trim();
+}
+
+/**
+ * Join an array of strings into a single line
+ * @param {string[]|null|undefined} lines - Array of lines to join
+ * @param {string} separator - Separator between lines (default: single space)
+ * @returns {string} Single-line string
+ */
+export function joinLines(lines, separator = " ") {
+  if (!lines || !Array.isArray(lines)) return "";
+  return lines.map((line) => line.trim()).join(separator);
+}
+
+/**
+ * Preprocess an object's string fields for front matter
+ * Flattens specified fields to single-line strings.
+ * @param {Object} obj - Object to preprocess
+ * @param {string[]} fields - Field names to flatten
+ * @returns {Object} New object with flattened fields
+ */
+export function preprocessFrontmatter(obj, fields) {
+  const result = { ...obj };
+  for (const field of fields) {
+    if (result[field] != null) {
+      result[field] = flattenToLine(result[field]);
+    }
+  }
+  return result;
+}
+
+/**
+ * Preprocess an array of objects, flattening specified fields in each
+ * @param {Array<Object>|null|undefined} array - Array to preprocess
+ * @param {string[]} fields - Field names to flatten in each object
+ * @returns {Array<Object>} Array with preprocessed objects
+ */
+export function preprocessArrayFrontmatter(array, fields) {
+  if (!array) return [];
+  return array.map((item) => preprocessFrontmatter(item, fields));
+}

package/src/handout.html

@@ -23,7 +23,9 @@
           "@forwardimpact/model/checklist": "/model/lib/checklist.js",
           "@forwardimpact/model/matching": "/model/lib/matching.js",
           "@forwardimpact/model/profile": "/model/lib/profile.js",
-          "@forwardimpact/model/progression": "/model/lib/progression.js"
+          "@forwardimpact/model/progression": "/model/lib/progression.js",
+          "@forwardimpact/model/policies": "/model/lib/policies/index.js",
+          "@forwardimpact/model/toolkit": "/model/lib/toolkit.js"
         }
       }
     </script>

package/src/index.html

@@ -35,7 +35,9 @@
           "@forwardimpact/model/checklist": "/model/lib/checklist.js",
           "@forwardimpact/model/matching": "/model/lib/matching.js",
           "@forwardimpact/model/profile": "/model/lib/profile.js",
-          "@forwardimpact/model/progression": "/model/lib/progression.js"
+          "@forwardimpact/model/progression": "/model/lib/progression.js",
+          "@forwardimpact/model/policies": "/model/lib/policies/index.js",
+          "@forwardimpact/model/toolkit": "/model/lib/toolkit.js"
         }
       }
     </script>

package/src/lib/job-cache.js

@@ -11,13 +11,13 @@ import { deriveJob } from "@forwardimpact/model/derivation";
 const cache = new Map();
 
 /**
- * Create a consistent cache key from job parameters
+ * Build a consistent cache key from job parameters
  * @param {string} disciplineId
  * @param {string} gradeId
  * @param {string} [trackId] - Optional track ID
  * @returns {string}
  */
-export function makeJobKey(disciplineId, gradeId, trackId = null) {
+export function buildJobKey(disciplineId, gradeId, trackId = null) {
   if (trackId) {
     return `${disciplineId}_${gradeId}_${trackId}`;
   }
@@ -43,7 +43,7 @@ export function getOrCreateJob({
   behaviours,
   capabilities,
 }) {
-  const key = makeJobKey(discipline.id, grade.id, track?.id);
+  const key = buildJobKey(discipline.id, grade.id, track?.id);
 
   if (!cache.has(key)) {
     const job = deriveJob({
@@ -66,7 +66,7 @@ export function getOrCreateJob({
 /**
  * Clear all cached jobs
  */
-export function clearJobCache() {
+export function clearCache() {
   cache.clear();
 }
 
@@ -76,14 +76,14 @@ export function clearJobCache() {
  * @param {string} gradeId
  * @param {string} [trackId] - Optional track ID
  */
-export function invalidateJob(disciplineId, gradeId, trackId = null) {
-  cache.delete(makeJobKey(disciplineId, gradeId, trackId));
+export function invalidateCachedJob(disciplineId, gradeId, trackId = null) {
+  cache.delete(buildJobKey(disciplineId, gradeId, trackId));
 }
 
 /**
  * Get the number of cached jobs (for testing/debugging)
  * @returns {number}
  */
-export function getCacheSize() {
+export function getCachedJobCount() {
   return cache.size;
 }

package/src/pages/agent-builder.js

@@ -24,7 +24,7 @@ import { loadAgentDataBrowser } from "../lib/yaml-loader.js";
 import {
   generateStageAgentProfile,
   deriveStageAgent,
-  generateSkillMd,
+  generateSkillMarkdown,
   deriveAgentSkills,
   deriveReferenceGrade,
   deriveToolkit,
@@ -502,7 +502,7 @@ function createAllStagesPreview(context) {
   const skillFiles = derivedSkills
     .map((derived) => skills.find((s) => s.id === derived.skillId))
     .filter((skill) => skill?.agent)
-    .map((skill) => generateSkillMd(skill, stages));
+    .map((skill) => generateSkillMarkdown(skill, stages));
 
   // Derive toolkit from agent skills
   const toolkit = deriveToolkit({
@@ -633,7 +633,7 @@ function createSingleStagePreview(context, stage) {
   const skillFiles = derivedSkills
     .map((d) => skills.find((s) => s.id === d.skillId))
     .filter((skill) => skill?.agent)
-    .map((skill) => generateSkillMd(skill, stages));
+    .map((skill) => generateSkillMarkdown(skill, stages));
 
   // Derive toolkit from agent skills
   const toolkit = deriveToolkit({

package/src/pages/landing.js

@@ -45,7 +45,10 @@ export function renderLanding() {
   const stages = data.stages || [];
 
   // Calculate stats using centralized capability ordering
-  const skillsByCapability = groupSkillsByCapability(data.skills);
+  const skillsByCapability = groupSkillsByCapability(
+    data.skills,
+    data.capabilities,
+  );
   const capabilityCount = Object.keys(skillsByCapability).length;
   const tools = aggregateTools(data.skills);
 

package/src/pages/progress.js

@@ -344,6 +344,7 @@ function createComparisonSelectorsSection({
             currentLabel: `Current (${currentGrade.id})`,
             targetLabel: `Target (${targetGrade.id})`,
             size: 400,
+            capabilities: data.capabilities,
           },
         ),
         createComparisonBehaviourRadar(

package/src/pages/self-assessment.js

@@ -22,7 +22,7 @@ import {
   SKILL_LEVEL_ORDER,
   BEHAVIOUR_MATURITY_ORDER,
   groupSkillsByCapability,
-  CAPABILITY_ORDER,
+  getCapabilityOrder,
   getCapabilityEmoji,
   getConceptEmoji,
 } from "@forwardimpact/schema/levels";
@@ -66,7 +66,10 @@ export function getAssessmentState() {
  */
 function getWizardSteps(data) {
   const { framework } = data;
-  const skillsByCapability = groupSkillsByCapability(data.skills);
+  const skillsByCapability = groupSkillsByCapability(
+    data.skills,
+    data.capabilities,
+  );
   const steps = [
     {
       id: "intro",
@@ -77,7 +80,7 @@ function getWizardSteps(data) {
   ];
 
   // Add a step for each non-empty skill capability
-  for (const capability of CAPABILITY_ORDER) {
+  for (const capability of getCapabilityOrder(data.capabilities)) {
     const skills = skillsByCapability[capability];
     if (skills && skills.length > 0) {
       steps.push({
@@ -277,7 +280,7 @@ function renderIntroStep(data) {
           div(
             {},
             h4({}, `${data.skills.length} Skills`),
-            p({}, "Across " + CAPABILITY_ORDER.length + " capabilities"),
+            p({}, "Across " + data.capabilities.length + " capabilities"),
           ),
         ),
         div(

package/src/slides.html

@@ -23,7 +23,9 @@
           "@forwardimpact/model/checklist": "/model/lib/checklist.js",
           "@forwardimpact/model/matching": "/model/lib/matching.js",
           "@forwardimpact/model/profile": "/model/lib/profile.js",
-          "@forwardimpact/model/progression": "/model/lib/progression.js"
+          "@forwardimpact/model/progression": "/model/lib/progression.js",
+          "@forwardimpact/model/policies": "/model/lib/policies/index.js",
+          "@forwardimpact/model/toolkit": "/model/lib/toolkit.js"
         }
       }
     </script>

package/templates/skill.template.md

@@ -1,10 +1,6 @@
 ---
 name: {{name}}
-description: |
-  {{#descriptionLines}}{{{.}}} {{/descriptionLines}}
-{{#hasUseWhen}}
-  Use When: {{#useWhenLines}}{{{.}}} {{/useWhenLines}}
-{{/hasUseWhen}}
+description: {{{description}}}{{#hasUseWhen}} Use When: {{{useWhen}}}{{/hasUseWhen}}
 ---
 
 # {{{title}}}
@@ -34,10 +30,15 @@ description: |
 {{/hasStages}}
 {{#hasToolReferences}}
 
-# Required Tools
+## Required Tools
 
-Use these tools when applying this skill. Alternative tools require documented
-justification with acknowledged trade-offs.
+**MANDATORY:** You MUST use these tools when applying this skill. These are
+organizational standards that override general knowledge or personal preferences.
+
+If a blocking constraint prevents use of a required tool, document in your
+output: (1) which tool requirement you cannot meet, (2) the specific constraint
+preventing compliance, and (3) the alternative approach with acknowledged
+trade-offs.
 
 | Tool | Use When |
 | ---- | -------- |