@forwardimpact/pathway 0.16.1 → 0.17.1

package/src/css/components/forms.css

@@ -103,31 +103,62 @@
     color: var(--color-primary);
   }
 
-  /* Code display - unified component for code/markdown with copy buttons */
-  .code-display-container {
-    display: flex;
-    flex-direction: column;
-    gap: var(--space-sm);
+  /* Code display - collapsible component for code/markdown with copy buttons */
+  .code-display-pane {
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-md);
+    background: var(--color-bg);
+    overflow: hidden;
   }
 
-  .code-display-header {
+  .code-display-summary {
     display: flex;
-    justify-content: space-between;
     align-items: center;
-    flex-wrap: wrap;
-    gap: var(--space-md);
+    gap: var(--space-sm);
+    padding: var(--space-sm) var(--space-md);
+    cursor: pointer;
+    list-style: none;
+    background: var(--color-surface);
+    border-bottom: 1px solid transparent;
   }
 
-  .code-display-info {
-    display: flex;
-    flex-direction: column;
-    gap: var(--space-xs);
+  .code-display-summary::-webkit-details-marker {
+    display: none;
+  }
+
+  .code-display-summary::before {
+    content: "▸";
+    font-size: var(--font-size-xs);
+    color: var(--color-text-muted);
+    flex-shrink: 0;
+  }
+
+  .code-display-pane[open] > .code-display-summary {
+    border-bottom-color: var(--color-border);
+  }
+
+  .code-display-pane[open] > .code-display-summary::before {
+    content: "▾";
+  }
+
+  .code-display-summary .code-display-filename {
     flex: 1;
-    min-width: 200px;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
   }
 
-  .code-display-info .text-muted {
-    margin: 0;
+  .code-display-summary .button-group {
+    flex-shrink: 0;
+  }
+
+  .code-display-body {
+    padding: var(--space-sm) var(--space-md) var(--space-md);
+  }
+
+  .code-display-body .text-muted {
+    margin: 0 0 var(--space-sm);
   }
 
   .code-display-filename {

package/src/css/components/skill-file-viewer.css

@@ -0,0 +1,18 @@
+/**
+ * Skill File Viewer
+ *
+ * Vertically stacked collapsible panes for viewing skill files
+ * (SKILL.md, install.sh, REFERENCE.md).
+ * Uses code-display-pane component with sfv-pane modifier.
+ */
+
+@layer components {
+  .sfv {
+    display: flex;
+    flex-direction: column;
+  }
+
+  .sfv-pane + .sfv-pane {
+    margin-top: var(--space-sm);
+  }
+}

package/src/css/pages/agent-builder.css

@@ -1,7 +1,8 @@
 /**
  * Agent Builder Page Styles
  *
- * Agent builder form, preview, and card components.
+ * Agent builder form, preview, and card grid layout.
+ * Card surfaces are in components/file-card.css.
  */
 
 @layer pages {
@@ -32,11 +33,9 @@
     gap: var(--space-xl);
   }
 
+  /* Agent section — spacing container, no surface */
   .agent-section {
-    background: var(--color-surface);
-    border-radius: var(--radius-lg);
-    padding: var(--space-lg);
-    box-shadow: var(--shadow-md);
+    margin-bottom: var(--space-lg);
   }
 
   .agent-section .section-header {
@@ -50,13 +49,6 @@
     margin: 0;
   }
 
-  .agent-section .filename {
-    font-family: var(--font-family-mono);
-    font-size: var(--font-size-xs);
-    color: var(--color-text-muted);
-    margin-bottom: var(--space-sm);
-  }
-
   /* Agent cards grid */
   .agent-cards-grid {
     display: grid;
@@ -69,51 +61,6 @@
     max-width: 800px;
   }
 
-  .agent-card {
-    border: 1px solid var(--color-border);
-    border-radius: var(--radius-lg);
-    background: var(--color-bg);
-    overflow: hidden;
-  }
-
-  .agent-card-header {
-    display: flex;
-    justify-content: space-between;
-    align-items: flex-start;
-    padding: var(--space-md);
-    background: var(--color-surface);
-    border-bottom: 1px solid var(--color-border);
-    gap: var(--space-sm);
-  }
-
-  .agent-card-title {
-    display: flex;
-    align-items: center;
-    gap: var(--space-sm);
-    flex-wrap: wrap;
-  }
-
-  .agent-card-title h3 {
-    margin: 0;
-    font-size: var(--font-size-md);
-  }
-
-  .agent-card-emoji {
-    font-size: 1.5rem;
-  }
-
-  .agent-card-preview {
-    padding: var(--space-md);
-  }
-
-  .agent-card-preview .code-display-container {
-    margin: 0;
-  }
-
-  .agent-card-preview .code-display {
-    max-height: 400px;
-  }
-
   /* Skill cards grid */
   .skill-cards-grid {
     display: grid;
@@ -121,39 +68,6 @@
     gap: var(--space-md);
   }
 
-  .skill-card {
-    border: 1px solid var(--color-border);
-    border-radius: var(--radius-md);
-    background: var(--color-bg);
-    overflow: hidden;
-  }
-
-  .skill-card-header {
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
-    padding: var(--space-sm) var(--space-md);
-    background: var(--color-surface);
-    border-bottom: 1px solid var(--color-border);
-  }
-
-  .skill-card-name {
-    font-weight: 600;
-    font-size: var(--font-size-sm);
-  }
-
-  .skill-card-preview {
-    padding: var(--space-sm) var(--space-md) var(--space-md);
-  }
-
-  .skill-card-preview .code-display-container {
-    margin: 0;
-  }
-
-  .skill-card-preview .code-display {
-    max-height: 300px;
-  }
-
   .skills-list {
     display: flex;
     flex-direction: column;
@@ -167,59 +81,6 @@
     gap: var(--space-md);
   }
 
-  .role-agent-card {
-    border: 1px solid var(--color-border);
-    border-radius: var(--radius-md);
-    overflow: hidden;
-  }
-
-  .role-agent-card > summary {
-    cursor: pointer;
-    padding: var(--space-md);
-    background: var(--color-bg);
-    border-bottom: 1px solid transparent;
-    list-style: none;
-  }
-
-  .role-agent-card > summary::-webkit-details-marker {
-    display: none;
-  }
-
-  .role-agent-card[open] > summary {
-    border-bottom-color: var(--color-border);
-  }
-
-  .role-agent-header {
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
-  }
-
-  .role-name {
-    font-weight: var(--font-weight-semibold);
-    color: var(--color-text);
-  }
-
-  .role-filename {
-    font-family: var(--font-family-mono);
-    font-size: var(--font-size-xs);
-    color: var(--color-text-muted);
-  }
-
-  .role-agent-content {
-    padding: var(--space-md);
-  }
-
-  .role-description {
-    margin-bottom: var(--space-md);
-  }
-
-  .role-agent-actions {
-    display: flex;
-    gap: var(--space-sm);
-    margin-bottom: var(--space-sm);
-  }
-
   /* Stage agent preview */
   .stage-agent-preview .stage-header {
     display: flex;

package/src/formatters/agent/dom.js

@@ -5,17 +5,7 @@
  * Includes copy and download functionality.
  */
 
-import {
-  div,
-  h2,
-  h3,
-  p,
-  span,
-  button,
-  section,
-  details,
-  summary,
-} from "../../lib/render.js";
+import { div, h2, h3, p, span, button, section } from "../../lib/render.js";
 import { createCodeDisplay } from "../../components/code-display.js";
 import { formatAgentProfile } from "./profile.js";
 import { formatAgentSkill } from "./skill.js";
@@ -163,33 +153,13 @@ function createSkillCard(skill) {
  */
 function createRoleAgentCard(agent) {
   const content = formatAgentProfile(agent);
-  const roleName = agent.frontmatter.name.split("-").pop(); // Extract role suffix (plan, review)
 
-  return details(
-    { className: "role-agent-card" },
-    summary(
-      {},
-      div(
-        { className: "role-agent-header" },
-        span(
-          { className: "role-name" },
-          `${roleName.charAt(0).toUpperCase() + roleName.slice(1)} Agent`,
-        ),
-        span({ className: "role-filename" }, agent.filename),
-      ),
-    ),
-    div(
-      { className: "role-agent-content" },
-      p(
-        { className: "text-muted role-description" },
-        agent.frontmatter.description,
-      ),
-      createCodeDisplay({
-        content,
-        maxHeight: 400,
-      }),
-    ),
-  );
+  return createCodeDisplay({
+    content,
+    filename: agent.filename,
+    description: agent.frontmatter.description,
+    maxHeight: 400,
+  });
 }
 
 /**

package/src/formatters/agent/profile.js

@@ -22,13 +22,6 @@ import {
  * @property {string} content - Working style content (markdown)
  */
 
-/**
- * @typedef {Object} ChecklistEntry
- * @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.
@@ -49,8 +42,6 @@ import {
  * @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 {ChecklistEntry[]} [params.bodyData.readChecklist] - Read-Then-Do Checklist entries
- * @param {ChecklistEntry[]} [params.bodyData.confirmChecklist] - Do-Then-Confirm 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
@@ -81,20 +72,6 @@ function prepareAgentProfileData({ frontmatter, bodyData }) {
     content: "required",
   });
 
-  // Process readChecklist: trim items in each entry
-  const readChecklist = (bodyData.readChecklist || []).map((entry) => ({
-    skill: entry.skill,
-    capability: entry.capability,
-    items: (entry.items || []).map((item) => trimRequired(item)),
-  }));
-
-  // Process confirmChecklist: trim items in each entry
-  const confirmChecklist = (bodyData.confirmChecklist || []).map((entry) => ({
-    skill: entry.skill,
-    capability: entry.capability,
-    items: (entry.items || []).map((item) => trimRequired(item)),
-  }));
-
   return {
     // Frontmatter - flatten description for single-line front matter
     name: frontmatter.name,
@@ -115,10 +92,6 @@ function prepareAgentProfileData({ frontmatter, bodyData }) {
     roleContext: trimValue(bodyData.roleContext),
     workingStyles,
     hasWorkingStyles: workingStyles.length > 0,
-    readChecklist,
-    hasReadChecklist: readChecklist.length > 0,
-    confirmChecklist,
-    hasConfirmChecklist: confirmChecklist.length > 0,
     constraints,
     hasConstraints: constraints.length > 0,
     agentIndex,
@@ -143,8 +116,6 @@ 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 {ChecklistEntry[]} [profile.bodyData.readChecklist] - Read-Then-Do Checklist entries (optional)
- * @param {ChecklistEntry[]} [profile.bodyData.confirmChecklist] - Do-Then-Confirm 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

@@ -1,8 +1,9 @@
 /**
  * Agent Skill Formatter
  *
- * Formats agent skill data into SKILL.md file content
- * following the Agent Skills Standard specification.
+ * Formats agent skill data into SKILL.md, scripts/install.sh, and
+ * references/REFERENCE.md file content following the Agent Skills Standard
+ * specification with progressive disclosure.
  *
  * Uses Mustache templates for flexible output formatting.
  * Templates are loaded from data/ directory with fallback to templates/ directory.
@@ -13,6 +14,13 @@ import Mustache from "mustache";
 import { trimValue, splitLines, trimFields } from "../shared.js";
 import { flattenToLine } from "../template-preprocess.js";
 
+/**
+ * Lowercase the first character of a string
+ * @param {string} s
+ * @returns {string}
+ */
+const lcFirst = (s) => (s ? s[0].toLowerCase() + s.slice(1) : s);
+
 /**
  * Prepare agent skill data for template rendering
  * Normalizes string values by trimming trailing newlines for consistent template output.
@@ -23,7 +31,9 @@ import { flattenToLine } from "../template-preprocess.js";
  * @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, readChecklist, confirmChecklist
- * @param {string} params.reference - Reference content (markdown)
+ * @param {string} params.instructions - Workflow guidance content (markdown)
+ * @param {string} params.installScript - Shell commands for install script
+ * @param {string} params.implementationReference - Reference content (markdown)
  * @param {Array} [params.toolReferences] - Array of tool reference objects
  * @returns {Object} Data object ready for Mustache template
  */
@@ -31,7 +41,9 @@ function prepareAgentSkillData({
   frontmatter,
   title,
   stages,
-  reference,
+  instructions,
+  installScript,
+  implementationReference,
   toolReferences,
 }) {
   // Process stages - trim focus and array values
@@ -43,12 +55,14 @@ function prepareAgentSkillData({
 
   // Flatten multi-line strings to single line for front matter compatibility
   const description = flattenToLine(frontmatter.description);
-  const useWhen = flattenToLine(frontmatter.useWhen);
+  const useWhen = lcFirst(flattenToLine(frontmatter.useWhen));
 
   // Keep line arrays for body rendering
   const descriptionLines = splitLines(frontmatter.description);
 
-  const trimmedReference = trimValue(reference) || "";
+  const trimmedInstructions = trimValue(instructions) || "";
+  const trimmedInstallScript = trimValue(installScript) || "";
+  const trimmedReference = trimValue(implementationReference) || "";
   const tools = toolReferences || [];
 
   return {
@@ -63,7 +77,11 @@ function prepareAgentSkillData({
     title,
     stages: processedStages,
     hasStages: processedStages.length > 0,
-    reference: trimmedReference,
+    instructions: trimmedInstructions,
+    hasInstructions: !!trimmedInstructions,
+    installScript: trimmedInstallScript,
+    hasInstallScript: !!trimmedInstallScript,
+    implementationReference: trimmedReference,
     hasReference: !!trimmedReference,
     toolReferences: tools,
     hasToolReferences: tools.length > 0,
@@ -72,27 +90,67 @@ function prepareAgentSkillData({
 
 /**
  * Format agent skill as SKILL.md file content using Mustache template
- * @param {Object} skill - Skill with frontmatter, title, stages, reference
+ * @param {Object} skill - Skill with frontmatter, title, stages, instructions, installScript, implementationReference
  * @param {Object} skill.frontmatter - YAML frontmatter data
  * @param {string} skill.frontmatter.name - Skill name (required)
  * @param {string} skill.frontmatter.description - Skill description (required)
  * @param {string} skill.title - Human-readable skill title for heading
  * @param {Array} skill.stages - Array of stage objects with stageName, focus, readChecklist, confirmChecklist
- * @param {string} skill.reference - Reference content (markdown)
+ * @param {string} skill.instructions - Workflow guidance (markdown)
+ * @param {string} skill.installScript - Shell commands for install script
+ * @param {string} skill.implementationReference - 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, toolReferences },
+  {
+    frontmatter,
+    title,
+    stages,
+    instructions,
+    installScript,
+    implementationReference,
+    toolReferences,
+  },
   template,
 ) {
   const data = prepareAgentSkillData({
     frontmatter,
     title,
     stages,
-    reference,
+    instructions,
+    installScript,
+    implementationReference,
     toolReferences,
   });
   return Mustache.render(template, data);
 }
+
+/**
+ * Format install script file content using Mustache template
+ * @param {Object} skill - Skill data with installScript and frontmatter
+ * @param {string} template - Mustache template string for install script
+ * @returns {string} Complete install.sh file content
+ */
+export function formatInstallScript(skill, template) {
+  const data = {
+    name: skill.frontmatter.name,
+    installScript: trimValue(skill.installScript) || "",
+  };
+  return Mustache.render(template, data);
+}
+
+/**
+ * Format reference file content using Mustache template
+ * @param {Object} skill - Skill data with implementationReference and title
+ * @param {string} template - Mustache template string for reference
+ * @returns {string} Complete REFERENCE.md file content
+ */
+export function formatReference(skill, template) {
+  const data = {
+    title: skill.title,
+    implementationReference: trimValue(skill.implementationReference) || "",
+  };
+  return Mustache.render(template, data);
+}

package/src/formatters/job/dom.js

@@ -233,16 +233,18 @@ export function createJobDescriptionSection({
     template,
   );
 
-  return createDetailSection({
-    title: "Job Description",
-    content: createCodeDisplay({
+  return section(
+    { className: "section section-detail" },
+    h2({ className: "section-title" }, "Job Description"),
+    createCodeDisplay({
       content: markdown,
+      filename: "job-description.md",
       description:
         "Copy this markdown-formatted job description for use in job postings, documentation, or sharing.",
       toHtml: markdownToHtml,
       minHeight: 450,
     }),
-  });
+  );
 }
 
 /**

package/src/formatters/skill/dom.js

@@ -18,7 +18,7 @@ import {
 } from "../../lib/render.js";
 import { createBackLink } from "../../components/nav.js";
 import { createLevelCell } from "../../components/detail.js";
-import { createCodeDisplay } from "../../components/code-display.js";
+import { createSkillFileViewer } from "../../components/skill-file-viewer.js";
 import { createToolIcon } from "../../lib/card-mappers.js";
 import { SKILL_LEVEL_ORDER } from "@forwardimpact/schema/levels";
 import { prepareSkillDetail } from "./shared.js";
@@ -34,6 +34,7 @@ import { createJsonLdScript, skillToJsonLd } from "../json-ld.js";
  * @param {Array} context.capabilities - Capability entities
  * @param {boolean} [context.showBackLink=true] - Whether to show back navigation link
  * @param {boolean} [context.showToolsAndPatterns=true] - Whether to show required tools and implementation patterns
+ * @param {string} [context.agentSkillContent] - Pre-generated SKILL.md content for agent file viewer
  * @returns {HTMLElement}
  */
 export function skillToDOM(
@@ -45,6 +46,7 @@ export function skillToDOM(
     capabilities,
     showBackLink = true,
     showToolsAndPatterns = true,
+    agentSkillContent,
   } = {},
 ) {
   const view = prepareSkillDetail(skill, {
@@ -222,18 +224,54 @@ export function skillToDOM(
         )
       : null,
 
-    // Implementation Reference
-    showToolsAndPatterns && view.implementationReference
+    // Agent Skill Files
+    showToolsAndPatterns &&
+      (agentSkillContent || view.implementationReference || view.installScript)
       ? div(
           { className: "detail-section" },
-          heading2({ className: "section-title" }, "Implementation Patterns"),
-          createCodeDisplay({
-            content: view.implementationReference,
-            description:
-              "Project-specific implementation guidance for this skill.",
-            minHeight: 450,
+          heading2({ className: "section-title" }, "Agent Skill Files"),
+          createSkillFileViewer({
+            files: buildSkillFiles(view, agentSkillContent),
+            maxHeight: 450,
           }),
         )
       : null,
   );
 }
+
+/**
+ * Build file descriptors for the skill file viewer
+ * @param {import('./shared.js').SkillDetailView} view
+ * @param {string} [agentSkillContent] - Pre-generated SKILL.md content
+ * @returns {import('../../components/skill-file-viewer.js').SkillFile[]}
+ */
+function buildSkillFiles(view, agentSkillContent) {
+  /** @type {import('../../components/skill-file-viewer.js').SkillFile[]} */
+  const files = [];
+
+  if (agentSkillContent) {
+    files.push({
+      filename: "SKILL.md",
+      content: agentSkillContent,
+      language: "markdown",
+    });
+  }
+
+  if (view.installScript) {
+    files.push({
+      filename: "scripts/install.sh",
+      content: view.installScript,
+      language: "bash",
+    });
+  }
+
+  if (view.implementationReference) {
+    files.push({
+      filename: "references/REFERENCE.md",
+      content: view.implementationReference,
+      language: "markdown",
+    });
+  }
+
+  return files;
+}

package/src/formatters/skill/shared.js

@@ -74,6 +74,7 @@ export function prepareSkillsList(
  * @property {Array<{id: string, name: string, modifier: number}>} relatedTracks
  * @property {Array<{id: string, name: string}>} relatedDrivers
  * @property {Array<{name: string, url?: string, description: string, useWhen: string}>} toolReferences
+ * @property {string|null} installScript
  * @property {string|null} implementationReference
  */
 
@@ -130,6 +131,7 @@ export function prepareSkillDetail(
     toolReferences: (skill.toolReferences || [])
       .slice()
       .sort((a, b) => a.name.localeCompare(b.name)),
+    installScript: skill.installScript || null,
     implementationReference: skill.implementationReference || null,
   };
 }