@forwardimpact/pathway 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/pathway",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Career progression web app and CLI for exploring roles and generating agents",
   "license": "Apache-2.0",
   "repository": {
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@forwardimpact/schema": "^0.4.0",
-    "@forwardimpact/model": "^0.4.0",
+    "@forwardimpact/model": "^0.5.0",
     "mustache": "^4.2.0",
     "simple-icons": "^16.7.0",
     "yaml": "^2.3.4"

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
@@ -18,6 +22,13 @@ import { trimValue, trimRequired, trimFields } from "../shared.js";
  * @property {string} content - Working style content (markdown)
  */
 
+/**
+ * @typedef {Object} BeforeHandoffEntry
+ * @property {{id: string, name: string}} skill - Skill info
+ * @property {{id: string, name: string, emojiIcon: string}} capability - Capability info
+ * @property {string[]} items - Checklist items
+ */
+
 /**
  * Prepare agent profile data for template rendering
  * Normalizes string values by trimming trailing newlines for consistent template output.
@@ -35,15 +46,21 @@ import { trimValue, trimRequired, trimFields } from "../shared.js";
  * @param {Array<{name: string, dirname: string, useWhen: string}>} params.bodyData.skillIndex - Skill index entries
  * @param {string} params.bodyData.roleContext - Role context text
  * @param {WorkingStyleEntry[]} params.bodyData.workingStyles - Working style entries
- * @param {string} [params.bodyData.beforeHandoff] - Before handoff checklist markdown
+ * @param {BeforeHandoffEntry[]} [params.bodyData.beforeHandoff] - Before handoff checklist entries
  * @param {string[]} params.bodyData.constraints - List of constraints
  * @param {Array<{id: string, name: string, description: string}>} [params.bodyData.agentIndex] - List of all available agents
  * @param {boolean} [params.bodyData.hasAgentIndex] - Whether agent index is available
  * @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",
@@ -60,10 +77,17 @@ function prepareAgentProfileData({ frontmatter, bodyData }) {
     content: "required",
   });
 
+  // Process beforeHandoff: trim items in each entry
+  const beforeHandoff = (bodyData.beforeHandoff || []).map((entry) => ({
+    skill: entry.skill,
+    capability: entry.capability,
+    items: (entry.items || []).map((item) => trimRequired(item)),
+  }));
+
   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,
 
@@ -77,7 +101,8 @@ function prepareAgentProfileData({ frontmatter, bodyData }) {
     roleContext: trimValue(bodyData.roleContext),
     workingStyles,
     hasWorkingStyles: workingStyles.length > 0,
-    beforeHandoff: trimValue(bodyData.beforeHandoff),
+    beforeHandoff,
+    hasBeforeHandoff: beforeHandoff.length > 0,
     constraints,
     hasConstraints: constraints.length > 0,
     agentIndex,
@@ -102,7 +127,7 @@ function prepareAgentProfileData({ frontmatter, bodyData }) {
  * @param {Array<{name: string, dirname: string, useWhen: string}>} profile.bodyData.skillIndex - Skill index entries
  * @param {string} profile.bodyData.roleContext - Role context text
  * @param {WorkingStyleEntry[]} profile.bodyData.workingStyles - Working style entries
- * @param {string} [profile.bodyData.beforeHandoff] - Before handoff checklist markdown (optional)
+ * @param {BeforeHandoffEntry[]} [profile.bodyData.beforeHandoff] - Before handoff checklist entries (optional)
  * @param {string[]} profile.bodyData.constraints - List of constraints
  * @param {string} template - Mustache template string
  * @returns {string} Complete .agent.md file content

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/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/templates/agent.template.md

@@ -88,17 +88,23 @@ and (3) the compromised approach with acknowledged limitations.
 | `{{id}}` | {{{name}}} | {{{description}}} |
 {{/agentIndex}}
 {{/hasAgentIndex}}
-{{#beforeHandoff}}
+{{#hasBeforeHandoff}}
 
 ## Before Handoff
 
 Before offering a handoff, verify and summarize completion of these items:
 
-{{{beforeHandoff}}}
+{{#beforeHandoff}}
+### {{{capability.emojiIcon}}} {{{skill.name}}}
+
+{{#items}}
+- [ ] {{{.}}}
+{{/items}}
 
+{{/beforeHandoff}}
 When verified, summarize what was accomplished then offer the handoff. If items
 are incomplete, explain what remains.
-{{/beforeHandoff}}
+{{/hasBeforeHandoff}}
 
 ## Return Format
 

package/templates/skill.template.md

@@ -1,20 +1,13 @@
 ---
 name: {{name}}
-description: |
-{{#descriptionLines}}
-  {{{.}}}
-{{/descriptionLines}}
-{{#hasUseWhen}}
-  **Use When:** {{#useWhenLines}}{{{.}}}{{/useWhenLines}}
-{{/hasUseWhen}}
+description: {{{description}}}{{#hasUseWhen}} Use When: {{{useWhen}}}{{/hasUseWhen}}
 ---
 
 # {{{title}}}
-{{#hasUseWhen}}
 
-**Use This Skill When:**
-{{#useWhenLines}}{{{.}}}{{/useWhenLines}}
-{{/hasUseWhen}}
+{{#descriptionLines}}
+{{{.}}}
+{{/descriptionLines}}
 {{#hasStages}}
 
 ## Stage Guidance