@forwardimpact/pathway 0.3.0 → 0.4.0

package/app/commands/agent.js

@@ -454,7 +454,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));
+    .map((skill) => generateSkillMd(skill, data.stages));
 
   // Validate all profiles
   for (const profile of profiles) {

package/app/commands/index.js

@@ -4,13 +4,14 @@
  * Re-exports all command handlers for convenient importing.
  */
 
-export { runSkillCommand } from "./skill.js";
-export { runBehaviourCommand } from "./behaviour.js";
-export { runDriverCommand } from "./driver.js";
 export { runDisciplineCommand } from "./discipline.js";
 export { runGradeCommand } from "./grade.js";
 export { runTrackCommand } from "./track.js";
+export { runBehaviourCommand } from "./behaviour.js";
+export { runSkillCommand } from "./skill.js";
+export { runDriverCommand } from "./driver.js";
 export { runStageCommand } from "./stage.js";
+export { runToolCommand } from "./tool.js";
 export { runJobCommand } from "./job.js";
 export { runInterviewCommand } from "./interview.js";
 export { runProgressCommand } from "./progress.js";

package/app/commands/skill.js

@@ -7,6 +7,7 @@
  *   npx pathway skill              # Summary with stats
  *   npx pathway skill --list       # IDs only (for piping)
  *   npx pathway skill <id>         # Detail view
+ *   npx pathway skill <id> --agent # Agent SKILL.md output
  *   npx pathway skill --validate   # Validation checks
  */
 
@@ -14,7 +15,10 @@ import { createEntityCommand } from "./command-factory.js";
 import { skillToMarkdown } from "../formatters/skill/markdown.js";
 import { prepareSkillsList } from "../formatters/skill/shared.js";
 import { getConceptEmoji } from "../model/levels.js";
-import { formatTable } from "../lib/cli-output.js";
+import { formatTable, formatError } from "../lib/cli-output.js";
+import { generateSkillMd } from "../model/agent.js";
+import { formatAgentSkill } from "../formatters/agent/skill.js";
+import { loadSkillTemplate } from "../lib/template-loader.js";
 
 /**
  * Format skill summary output
@@ -59,7 +63,29 @@ function formatDetail(viewAndContext, framework) {
   );
 }
 
-export const runSkillCommand = createEntityCommand({
+/**
+ * Format skill as agent SKILL.md output
+ * @param {Object} skill - Skill entity with agent section
+ * @param {Array} stages - All stage entities
+ * @param {string} dataDir - Path to data directory for template loading
+ */
+async function formatAgentDetail(skill, stages, dataDir) {
+  if (!skill.agent) {
+    console.error(formatError(`Skill '${skill.id}' has no agent section`));
+    console.error(`\nSkills with agent support:`);
+    console.error(
+      `  npx pathway skill --list | xargs -I{} sh -c 'npx pathway skill {} --json | jq -e .skill.agent > /dev/null && echo {}'`,
+    );
+    process.exit(1);
+  }
+
+  const template = await loadSkillTemplate(dataDir);
+  const skillMd = generateSkillMd(skill, stages);
+  const output = formatAgentSkill(skillMd, template);
+  console.log(output);
+}
+
+const baseSkillCommand = createEntityCommand({
   entityName: "skill",
   pluralName: "skills",
   findEntity: (data, id) => data.skills.find((s) => s.id === id),
@@ -74,3 +100,31 @@ export const runSkillCommand = createEntityCommand({
   formatDetail,
   emoji: "📚",
 });
+
+/**
+ * Run skill command with --agent support
+ * @param {Object} params - Command parameters
+ * @param {Object} params.data - Loaded pathway data
+ * @param {string[]} params.args - Command arguments
+ * @param {Object} params.options - Command options
+ * @param {string} params.dataDir - Path to data directory
+ */
+export async function runSkillCommand({ data, args, options, dataDir }) {
+  // Handle --agent flag for detail view
+  if (options.agent && args.length > 0) {
+    const [id] = args;
+    const skill = data.skills.find((s) => s.id === id);
+
+    if (!skill) {
+      console.error(formatError(`Skill not found: ${id}`));
+      console.error(`Available: ${data.skills.map((s) => s.id).join(", ")}`);
+      process.exit(1);
+    }
+
+    await formatAgentDetail(skill, data.stages, dataDir);
+    return;
+  }
+
+  // Delegate to base command for all other cases
+  return baseSkillCommand({ data, args, options, dataDir });
+}

package/app/commands/tool.js

@@ -0,0 +1,112 @@
+/**
+ * Tool CLI Command
+ *
+ * Handles tool summary, listing, and detail display in the terminal.
+ *
+ * Usage:
+ *   npx pathway tool              # Summary with stats
+ *   npx pathway tool --list       # Tool names only (for piping)
+ *   npx pathway tool <name>       # Detail view for specific tool
+ */
+
+import { prepareToolsList } from "../formatters/tool/shared.js";
+import {
+  formatTable,
+  formatHeader,
+  formatSubheader,
+} from "../lib/cli-output.js";
+
+/**
+ * Run tool command
+ * @param {Object} params - Command parameters
+ * @param {Object} params.data - Loaded pathway data
+ * @param {string[]} params.args - Command arguments
+ * @param {Object} params.options - Command options
+ */
+export async function runToolCommand({ data, args, options }) {
+  const [name] = args;
+  const { tools, totalCount } = prepareToolsList(data.skills);
+
+  // --list: Output clean newline-separated tool names for piping
+  if (options.list) {
+    for (const tool of tools) {
+      console.log(tool.name);
+    }
+    return;
+  }
+
+  // No args: Show summary
+  if (!name) {
+    if (options.json) {
+      console.log(JSON.stringify(tools, null, 2));
+      return;
+    }
+    formatSummary(tools, totalCount);
+    return;
+  }
+
+  // With name: Show detail
+  const tool = tools.find((t) => t.name.toLowerCase() === name.toLowerCase());
+
+  if (!tool) {
+    console.error(`Tool not found: ${name}`);
+    console.error(`Available: ${tools.map((t) => t.name).join(", ")}`);
+    process.exit(1);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(tool, null, 2));
+    return;
+  }
+
+  formatDetail(tool);
+}
+
+/**
+ * Format tool summary output
+ * @param {Array} tools - Aggregated tools
+ * @param {number} totalCount - Total tool count
+ */
+function formatSummary(tools, totalCount) {
+  console.log(`\n🔧 Tools\n`);
+
+  // Show tools sorted by usage count
+  const sorted = [...tools].sort((a, b) => b.usages.length - a.usages.length);
+  const rows = sorted
+    .slice(0, 15)
+    .map((t) => [
+      t.name,
+      t.usages.length,
+      t.description.length > 50
+        ? t.description.slice(0, 47) + "..."
+        : t.description,
+    ]);
+
+  console.log(formatTable(["Tool", "Skills", "Description"], rows));
+  console.log(`\nTotal: ${totalCount} tools`);
+  if (sorted.length > 15) {
+    console.log(`(showing top 15 by usage)`);
+  }
+  console.log(`\nRun 'npx pathway tool --list' for all tool names`);
+  console.log(`Run 'npx pathway tool <name>' for details\n`);
+}
+
+/**
+ * Format tool detail output
+ * @param {Object} tool - Aggregated tool with usages
+ */
+function formatDetail(tool) {
+  console.log(formatHeader(`\n🔧 ${tool.name}\n`));
+  console.log(`${tool.description}\n`);
+
+  if (tool.url) {
+    console.log(`Documentation: ${tool.url}\n`);
+  }
+
+  if (tool.usages.length > 0) {
+    console.log(formatSubheader("Used in Skills\n"));
+    const rows = tool.usages.map((u) => [u.skillName, u.useWhen]);
+    console.log(formatTable(["Skill", "Use When"], rows));
+    console.log();
+  }
+}

package/app/components/checklist.js

@@ -43,7 +43,7 @@ export function createChecklist(checklist, options = {}) {
 function createChecklistGroup(group, options) {
   const { interactive, capabilities } = options;
   const emoji = getCapabilityEmoji(capabilities, group.capability);
-  const capabilityName = formatCapabilityName(group.capability);
+  const capabilityName = formatCapabilityName(group.capability, capabilities);
 
   return div(
     { className: "checklist-group" },
@@ -90,11 +90,13 @@ function createInteractiveCheckbox() {
 
 /**
  * Format capability name for display
- * @param {string} capability - Capability ID
+ * @param {string} capabilityId - Capability ID
+ * @param {Array} capabilities - Capabilities array
  * @returns {string}
  */
-function formatCapabilityName(capability) {
-  return capability.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+function formatCapabilityName(capabilityId, capabilities) {
+  const capability = capabilities.find((c) => c.id === capabilityId);
+  return capability?.name || capabilityId;
 }
 
 /**

package/app/components/markdown-textarea.js

@@ -0,0 +1,132 @@
+/**
+ * Markdown Textarea Component
+ *
+ * Reusable read-only textarea with copy buttons for displaying markdown content.
+ * Used by job descriptions and skill implementation patterns.
+ */
+
+/* global Prism */
+import { div, p, button } from "../lib/render.js";
+
+/**
+ * Create a copy button that copies content to clipboard
+ * @param {string} content - The text content to copy
+ * @param {string} label - Button label text
+ * @param {string} [className="btn btn-primary"] - Button class
+ * @returns {HTMLElement}
+ */
+export function createCopyButton(
+  content,
+  label,
+  className = "btn btn-primary",
+) {
+  const btn = button(
+    {
+      className: `${className} copy-btn`,
+      onClick: async () => {
+        try {
+          await navigator.clipboard.writeText(content);
+          btn.textContent = "✓ Copied!";
+          btn.classList.add("copied");
+          setTimeout(() => {
+            btn.textContent = label;
+            btn.classList.remove("copied");
+          }, 2000);
+        } catch (err) {
+          console.error("Failed to copy:", err);
+          btn.textContent = "Copy failed";
+          setTimeout(() => {
+            btn.textContent = label;
+          }, 2000);
+        }
+      },
+    },
+    label,
+  );
+  return btn;
+}
+
+/**
+ * Create a copy button that copies HTML to clipboard (for rich text pasting)
+ * @param {string} html - The HTML content to copy
+ * @param {string} label - Button label text
+ * @returns {HTMLElement}
+ */
+export function createCopyHtmlButton(html, label) {
+  const btn = button(
+    {
+      className: "btn btn-secondary copy-btn",
+      onClick: async () => {
+        try {
+          const blob = new Blob([html], { type: "text/html" });
+          const clipboardItem = new ClipboardItem({ "text/html": blob });
+          await navigator.clipboard.write([clipboardItem]);
+          btn.textContent = "✓ Copied!";
+          btn.classList.add("copied");
+          setTimeout(() => {
+            btn.textContent = label;
+            btn.classList.remove("copied");
+          }, 2000);
+        } catch (err) {
+          console.error("Failed to copy:", err);
+          btn.textContent = "Copy failed";
+          setTimeout(() => {
+            btn.textContent = label;
+          }, 2000);
+        }
+      },
+    },
+    label,
+  );
+  return btn;
+}
+
+/**
+ * Create a markdown textarea with copy buttons
+ * @param {Object} options
+ * @param {string} options.markdown - The markdown content to display
+ * @param {string} [options.description] - Optional description text above the textarea
+ * @param {string} [options.copyLabel="Copy Markdown"] - Label for the copy button
+ * @param {Function} [options.toHtml] - Optional function to convert markdown to HTML for rich copy
+ * @param {string} [options.copyHtmlLabel="Copy as HTML"] - Label for the HTML copy button
+ * @param {number} [options.minHeight=300] - Minimum height in pixels
+ * @returns {HTMLElement}
+ */
+export function createMarkdownTextarea({
+  markdown,
+  description,
+  copyLabel = "Copy Markdown",
+  toHtml,
+  copyHtmlLabel = "Copy as HTML",
+  minHeight = 300,
+}) {
+  // Create highlighted code block
+  const pre = document.createElement("pre");
+  pre.className = "markdown-display";
+  pre.style.minHeight = `${minHeight}px`;
+
+  const code = document.createElement("code");
+  code.className = "language-markdown";
+  code.textContent = markdown;
+  pre.appendChild(code);
+
+  // Apply Prism highlighting if available
+  if (typeof Prism !== "undefined") {
+    Prism.highlightElement(code);
+  }
+
+  const buttons = [createCopyButton(markdown, copyLabel)];
+  if (toHtml) {
+    buttons.push(createCopyHtmlButton(toHtml(markdown), copyHtmlLabel));
+  }
+
+  return div(
+    { className: "markdown-textarea-container" },
+    div(
+      { className: "markdown-textarea-header" },
+      description ? p({ className: "text-muted" }, description) : null,
+      div({ className: "button-group" }, ...buttons),
+    ),
+    pre,
+  );
+}

package/app/css/components/forms.css

@@ -102,4 +102,49 @@
     background: var(--color-primary-light, rgba(37, 99, 235, 0.1));
     color: var(--color-primary);
   }
+
+  /* Markdown display - read-only code block with copy buttons */
+  .markdown-textarea-container {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-md);
+  }
+
+  .markdown-textarea-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: var(--space-md);
+  }
+
+  .markdown-textarea-header .text-muted {
+    margin: 0;
+    flex: 1;
+    min-width: 200px;
+  }
+
+  .markdown-display {
+    width: 100%;
+    margin: 0;
+    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-surface) !important;
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-md);
+    overflow: auto;
+    color: var(--color-text);
+    white-space: pre-wrap;
+    word-wrap: break-word;
+  }
+
+  .markdown-display code {
+    background: transparent;
+    padding: 0;
+    font-size: inherit;
+    color: inherit;
+  }
 }

package/app/css/components/layout.css

@@ -95,6 +95,10 @@
     grid-template-columns: repeat(3, 1fr);
   }
 
+  .grid-4 {
+    grid-template-columns: repeat(4, 1fr);
+  }
+
   .grid-6 {
     grid-template-columns: repeat(6, 1fr);
   }
@@ -174,6 +178,10 @@
       grid-template-columns: repeat(2, 1fr);
     }
 
+    .grid-4 {
+      grid-template-columns: repeat(2, 1fr);
+    }
+
     .grid-6 {
       grid-template-columns: repeat(3, 1fr);
     }
@@ -198,6 +206,10 @@
       grid-template-columns: 1fr;
     }
 
+    .grid-4 {
+      grid-template-columns: repeat(2, 1fr);
+    }
+
     .grid-6 {
       grid-template-columns: repeat(2, 1fr);
     }

package/app/css/components/surfaces.css

@@ -53,6 +53,28 @@
     margin-top: var(--space-md);
   }
 
+  /* Tool skills list (inside cards) */
+  .tool-skills-list {
+    list-style: none;
+    padding: 0;
+    margin: var(--space-sm) 0 0 0;
+    font-size: var(--font-size-sm);
+  }
+
+  .tool-skills-list li {
+    padding: var(--space-xs) 0;
+  }
+
+  .tool-skills-list a {
+    color: var(--color-text-secondary);
+    text-decoration: none;
+  }
+
+  .tool-skills-list a:hover {
+    color: var(--color-primary);
+    text-decoration: underline;
+  }
+
   /* Stat cards */
   .stat-card {
     background: var(--color-surface);

package/app/css/pages/detail.css

@@ -56,4 +56,54 @@
     align-items: center;
     gap: var(--space-xs);
   }
+
+  /* Tools table (for skill detail page) */
+  .tools-table {
+    width: 100%;
+    border-collapse: separate;
+    border-spacing: 0;
+    margin-top: var(--space-md);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-lg);
+    overflow: hidden;
+    background: var(--color-surface);
+  }
+
+  .tools-table th,
+  .tools-table td {
+    padding: var(--space-md) var(--space-lg);
+    text-align: left;
+    border-bottom: 1px solid var(--color-border);
+  }
+
+  .tools-table th {
+    font-weight: 600;
+    font-size: var(--font-size-sm);
+    color: var(--color-text-secondary);
+    background: var(--color-bg);
+    text-transform: uppercase;
+    letter-spacing: 0.025em;
+  }
+
+  .tools-table th:first-child {
+    width: 200px;
+  }
+
+  .tools-table tbody tr:last-child td {
+    border-bottom: none;
+  }
+
+  .tools-table tbody tr:hover {
+    background: var(--color-bg);
+  }
+
+  /* See all link */
+  .see-all-link {
+    margin-top: var(--space-md);
+  }
+
+  .see-all-link a {
+    color: var(--color-primary);
+    font-size: var(--font-size-sm);
+  }
 }

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,14 +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);
 }