@forwardimpact/pathway 0.2.0 → 0.4.0

package/app/commands/agent.js

@@ -7,16 +7,18 @@
  * All agents are stage-specific. Use --stage for a single stage
  * or --all-stages (default) for all stages.
  *
+ * By default, outputs to console. Use --output to write files.
+ *
  * Usage:
- *   npx pathway agent <discipline> [--track=<track>] [--output=PATH] [--preview]
+ *   npx pathway agent <discipline> [--track=<track>]
  *   npx pathway agent <discipline> --track=<track> --stage=plan
- *   npx pathway agent <discipline> --track=<track> --all-stages
+ *   npx pathway agent <discipline> --track=<track> --output=./agents
  *   npx pathway agent --list
  *
  * Examples:
  *   npx pathway agent software_engineering --track=platform
  *   npx pathway agent software_engineering --track=platform --stage=plan
- *   npx pathway agent software_engineering --track=platform --preview
+ *   npx pathway agent software_engineering --track=platform --output=./agents
  */
 
 import { writeFile, mkdir, readFile } from "fs/promises";
@@ -32,10 +34,7 @@ import {
   deriveAgentSkills,
   generateSkillMd,
 } from "../model/agent.js";
-import {
-  formatAgentProfile,
-  formatAgentProfileForCli,
-} from "../formatters/agent/profile.js";
+import { formatAgentProfile } from "../formatters/agent/profile.js";
 import { formatAgentSkill } from "../formatters/agent/skill.js";
 import { formatError, formatSuccess } from "../lib/cli-output.js";
 import {
@@ -410,14 +409,15 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
       process.exit(1);
     }
 
-    // Preview or write
-    if (options.preview) {
-      console.log(formatAgentProfileForCli(profile));
+    // Load template
+    const agentTemplate = await loadAgentTemplate(dataDir);
+
+    // Output to console (default) or write to files (with --output)
+    if (!options.output) {
+      console.log(formatAgentProfile(profile, agentTemplate));
       return;
     }
 
-    // Load templates only when writing files
-    const agentTemplate = await loadAgentTemplate(dataDir);
     await writeProfile(profile, baseDir, agentTemplate);
     await generateVSCodeSettings(baseDir, agentData.vscodeSettings);
     await generateDevcontainer(
@@ -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) {
@@ -484,19 +484,19 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
     }
   }
 
-  // Preview or write
-  if (options.preview) {
+  // Load templates
+  const agentTemplate = await loadAgentTemplate(dataDir);
+  const skillTemplate = await loadSkillTemplate(dataDir);
+
+  // Output to console (default) or write to files (with --output)
+  if (!options.output) {
     for (const profile of profiles) {
-      console.log(formatAgentProfileForCli(profile));
+      console.log(formatAgentProfile(profile, agentTemplate));
       console.log("\n---\n");
     }
     return;
   }
 
-  // Load templates only when writing files
-  const agentTemplate = await loadAgentTemplate(dataDir);
-  const skillTemplate = await loadSkillTemplate(dataDir);
-
   for (const profile of profiles) {
     await writeProfile(profile, baseDir, agentTemplate);
   }

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/job.js

@@ -20,15 +20,17 @@ import {
   deriveChecklist,
   formatChecklistMarkdown,
 } from "../model/checklist.js";
+import { loadJobTemplate } from "../lib/template-loader.js";
 
 /**
  * Format job output
  * @param {Object} view - Presenter view
  * @param {Object} _options - Command options
  * @param {Object} entities - Original entities
+ * @param {string} jobTemplate - Mustache template for job description
  */
-function formatJob(view, _options, entities) {
-  console.log(jobToMarkdown(view, entities));
+function formatJob(view, _options, entities, jobTemplate) {
+  console.log(jobToMarkdown(view, entities, jobTemplate));
 }
 
 /**
@@ -37,8 +39,9 @@ function formatJob(view, _options, entities) {
  * @param {Object} params.data - All loaded data
  * @param {string[]} params.args - Command arguments
  * @param {Object} params.options - Command options
+ * @param {string} params.dataDir - Path to data directory
  */
-export async function runJobCommand({ data, args, options }) {
+export async function runJobCommand({ data, args, options, dataDir }) {
   const jobs = generateAllJobs({
     disciplines: data.disciplines,
     grades: data.grades,
@@ -167,5 +170,7 @@ export async function runJobCommand({ data, args, options }) {
     return;
   }
 
-  formatJob(view, options, { discipline, grade, track });
+  // Load job template for description formatting
+  const jobTemplate = await loadJobTemplate(dataDir);
+  formatJob(view, options, { discipline, grade, track }, jobTemplate);
 }

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/builder.js

@@ -17,7 +17,10 @@ import {
 } from "../lib/render.js";
 import { getState } from "../lib/state.js";
 import { createBadge } from "./card.js";
-import { createSelectWithValue } from "../lib/form-controls.js";
+import {
+  createSelectWithValue,
+  createDisciplineSelect,
+} from "../lib/form-controls.js";
 import { createReactive } from "../lib/reactive.js";
 
 /**
@@ -213,9 +216,9 @@ export function createBuilder({
         div(
           { className: "form-group" },
           label({ className: "form-label" }, labels.discipline || "Discipline"),
-          createSelectWithValue({
+          createDisciplineSelect({
             id: "discipline-select",
-            items: data.disciplines,
+            disciplines: data.disciplines,
             initialValue: selection.get().discipline,
             placeholder: "Select a discipline...",
             onChange: (value) => {

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