@forwardimpact/pathway 0.8.1 → 0.10.0

package/bin/fit-pathway.js

@@ -48,9 +48,9 @@ import { runInterviewCommand } from "../src/commands/interview.js";
 import { runProgressCommand } from "../src/commands/progress.js";
 import { runQuestionsCommand } from "../src/commands/questions.js";
 import { runAgentCommand } from "../src/commands/agent.js";
-import { runServeCommand } from "../src/commands/serve.js";
+import { runDevCommand } from "../src/commands/dev.js";
 import { runInitCommand } from "../src/commands/init.js";
-import { runSiteCommand } from "../src/commands/site.js";
+import { runBuildCommand } from "../src/commands/build.js";
 
 const COMMANDS = {
   discipline: runDisciplineCommand,
@@ -85,8 +85,8 @@ GETTING STARTED
 ────────────────────────────────────────────────────────────────────────────────
 
   init                                Create ./data/ with example data
-  serve [--port=PORT]                 Serve web app at http://localhost:3000
-  site [--output=PATH]                Generate static site to ./site/
+  dev [--port=PORT]                   Run live development server
+  build [--output=PATH]               Generate static site to ./public/
 
 ────────────────────────────────────────────────────────────────────────────────
 ENTITY COMMANDS
@@ -104,7 +104,7 @@ All entity commands support: summary (default), --list (IDs for piping), <id> (d
   skill [<id>]          Browse skills
     --agent             Output as agent SKILL.md format
 
-  tool [<name>]         Browse recommended tools (aggregated from skills)
+  tool [<name>]         Browse required tools (aggregated from skills)
 
 ────────────────────────────────────────────────────────────────────────────────
 JOB COMMAND
@@ -400,16 +400,16 @@ async function main() {
 
   const dataDir = resolveDataPath(options);
 
-  // Handle serve command (needs data directory)
-  if (command === "serve") {
-    await runServeCommand({ dataDir, options });
-    // serve doesn't exit, keeps running
+  // Handle dev command (needs data directory)
+  if (command === "dev") {
+    await runDevCommand({ dataDir, options });
+    // dev doesn't exit, keeps running
     return;
   }
 
-  // Handle site command (generates static site)
-  if (command === "site") {
-    await runSiteCommand({ dataDir, options });
+  // Handle build command (generates static site)
+  if (command === "build") {
+    await runBuildCommand({ dataDir, options });
     process.exit(0);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/pathway",
-  "version": "0.8.1",
+  "version": "0.10.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.3.0",
-    "@forwardimpact/model": "^0.3.0",
+    "@forwardimpact/schema": "^0.4.0",
+    "@forwardimpact/model": "^0.5.0",
     "mustache": "^4.2.0",
     "simple-icons": "^16.7.0",
     "yaml": "^2.3.4"

package/src/commands/{site.js → build.js}

@@ -1,5 +1,5 @@
 /**
- * Site Command
+ * Build Command
  *
  * Generates a static site from the Engineering Pathway data.
  * Copies all necessary files (HTML, JS, CSS) and data to an output directory.
@@ -59,13 +59,13 @@ const PUBLIC_ASSETS = [
 const ROOT_ASSETS = ["templates"];
 
 /**
- * Run the site command
+ * Run the build command
  * @param {Object} params - Command parameters
  * @param {string} params.dataDir - Path to data directory
  * @param {Object} params.options - Command options
  */
-export async function runSiteCommand({ dataDir, options }) {
-  const outputDir = options.output || join(process.cwd(), "site");
+export async function runBuildCommand({ dataDir, options }) {
+  const outputDir = options.output || join(process.cwd(), "public");
   const clean = options.clean !== false;
 
   // Load framework config for display

package/src/commands/{serve.js → dev.js}

@@ -1,7 +1,7 @@
 /**
- * Serve Command
+ * Dev Command
  *
- * Serves the Engineering Pathway web application with local data.
+ * Runs a live development server for the Engineering Pathway web application.
  * Uses Node.js built-in http module (no external dependencies).
  */
 
@@ -96,12 +96,12 @@ async function isDirectory(path) {
 }
 
 /**
- * Run the serve command
+ * Run the dev command
  * @param {Object} params - Command parameters
  * @param {string} params.dataDir - Path to data directory
  * @param {Object} params.options - Command options
  */
-export async function runServeCommand({ dataDir, options }) {
+export async function runDevCommand({ dataDir, options }) {
   const port = options.port || 3000;
 
   // Load framework config for display

package/src/formatters/agent/profile.js

@@ -18,6 +18,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,7 +42,7 @@ 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
@@ -60,6 +67,13 @@ 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
     name: frontmatter.name,
@@ -77,7 +91,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 +117,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/skill/dom.js

@@ -33,7 +33,7 @@ import { createJsonLdScript, skillToJsonLd } from "../json-ld.js";
  * @param {Array} context.drivers - All drivers
  * @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 recommended tools and implementation patterns
+ * @param {boolean} [context.showToolsAndPatterns=true] - Whether to show required tools and implementation patterns
  * @returns {HTMLElement}
  */
 export function skillToDOM(
@@ -178,11 +178,11 @@ export function skillToDOM(
         )
       : null,
 
-    // Recommended Tools
+    // Required Tools
     showToolsAndPatterns && view.toolReferences.length > 0
       ? div(
           { className: "detail-section" },
-          heading2({ className: "section-title" }, "Recommended Tools"),
+          heading2({ className: "section-title" }, "Required Tools"),
           table(
             { className: "tools-table" },
             thead({}, tr({}, th({}, "Tool"), th({}, "Use When"))),
@@ -204,6 +204,7 @@ export function skillToDOM(
                             rel: "noopener noreferrer",
                           },
                           tool.name,
+                          span({ className: "external-icon" }, " ↗"),
                         )
                       : tool.name,
                   ),

package/src/formatters/skill/markdown.js

@@ -105,9 +105,9 @@ export function skillToMarkdown(
     lines.push("");
   }
 
-  // Recommended tools
+  // Required tools
   if (view.toolReferences.length > 0) {
-    lines.push("## Recommended Tools", "");
+    lines.push("## Required Tools", "");
     const toolRows = view.toolReferences.map((tool) => [
       tool.url ? `[${tool.name}](${tool.url})` : tool.name,
       tool.useWhen,

package/src/formatters/toolkit/dom.js

@@ -28,12 +28,9 @@ export function createToolkitTable(toolkit) {
   }
 
   const rows = toolkit.map((tool) => {
-    const iconCell = tool.simpleIcon
-      ? td(
-          { className: "tool-icon-cell" },
-          createToolIcon(tool.simpleIcon, tool.name),
-        )
-      : td({ className: "tool-icon-cell" });
+    const icon = tool.simpleIcon
+      ? createToolIcon(tool.simpleIcon, tool.name)
+      : null;
 
     const nameContent = tool.url
       ? a(
@@ -50,8 +47,7 @@ export function createToolkitTable(toolkit) {
 
     return tr(
       {},
-      iconCell,
-      td({ className: "tool-name-cell" }, nameContent),
+      td({ className: "tool-name-cell" }, icon, nameContent),
       td({ className: "tool-description-cell" }, tool.description),
     );
   });
@@ -60,15 +56,7 @@ export function createToolkitTable(toolkit) {
     { className: "table-container" },
     table(
       { className: "table toolkit-table" },
-      thead(
-        {},
-        tr(
-          {},
-          th({ style: "width: 40px" }, ""),
-          th({}, "Tool"),
-          th({}, "Description"),
-        ),
-      ),
+      thead({}, tr({}, th({}, "Tool"), th({}, "Description"))),
       tbody({}, ...rows),
     ),
   );

package/src/lib/card-mappers.js

@@ -190,7 +190,7 @@ export function toolToCardConfig(tool, capabilities) {
     title: tool.name,
     description: tool.description,
     // Docs link in header badges (upper right)
-    badges: tool.url ? [createExternalLink("Docs →", tool.url)] : [],
+    badges: tool.url ? [createExternalLink("Docs ↗", tool.url)] : [],
     content: skillsList,
     icon,
   };

package/templates/agent.template.md

@@ -50,17 +50,18 @@ handoffs:
 {{/hasWorkingStyles}}
 {{#hasSkills}}
 
-## Available Skills and Tools
+## Required Skills
 
-**IMPORTANT:** Before starting work, read the relevant skill file for
-project-specific guidance, tools and technology recommendations. Do not rely
-solely on pre-training knowledge.
+**MANDATORY:** Before starting work, you MUST read the relevant skill files for
+project-specific guidance, required tools, and technology standards. Pre-training
+knowledge alone is insufficient—skills contain organizational standards that
+override general knowledge.
 
-Skills represent validated organizational patterns. When a skill recommends
-specific tools in its "Recommended Tools" section, use them unless a blocking
-constraint exists. If you choose a different tool, document in your output: (1)
-which skill recommendation you're overriding, (2) the constraint preventing use,
-and (3) trade-offs of the alternative.
+Skills represent mandatory organizational patterns. When a skill specifies tools
+in its "Required Tools" section, you MUST use them. If a blocking constraint
+prevents use, document in your output: (1) which skill requirement you cannot
+meet, (2) the specific constraint preventing compliance, and (3) the alternative
+approach with acknowledged trade-offs.
 
 | Skill | Location | Use When |
 | ----- | -------- | -------- |
@@ -70,16 +71,16 @@ and (3) trade-offs of the alternative.
 {{/hasSkills}}
 {{#hasAgentIndex}}
 
-## Available Sub-Agents for Delegation
+## Required Sub-Agent Delegations
 
-**IMPORTANT:** If you come across work that is not strictly within your
-speciality, then you must delegate the task using the `runSubagent` tool.
+**MANDATORY:** You MUST delegate work outside your speciality using the
+`runSubagent` tool. Do not attempt work that another agent is better suited for.
 
-You are part of a team of agents and should not carry out all work yourself.
-Rely on other agents around you that have a speciality better suited for
-individual tasks. If you choose to not delegate specialised work to a sub-agent,
-document in your output: (1) what the specialised work is, (2) the constraint
-preventing delegation and (3) trade-offs of the alternative.
+You are part of an agentic team with specialized roles. Attempting work outside
+your speciality produces inferior results and violates team structure. If you
+cannot delegate due to a blocking constraint, document in your output: (1) the
+specialized work required, (2) the specific constraint preventing delegation,
+and (3) the compromised approach with acknowledged limitations.
 
 | Agent Name | Speciality | Description |
 | ---------- | ---------- | ----------- |
@@ -87,17 +88,23 @@ preventing delegation and (3) trade-offs of the alternative.
 | `{{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,17 @@
 ---
 name: {{name}}
 description: |
-{{#descriptionLines}}
-  {{{.}}}
-{{/descriptionLines}}
+  {{#descriptionLines}}{{{.}}} {{/descriptionLines}}
 {{#hasUseWhen}}
-  **Use When:** {{#useWhenLines}}{{{.}}}{{/useWhenLines}}
+  Use When: {{#useWhenLines}}{{{.}}} {{/useWhenLines}}
 {{/hasUseWhen}}
 ---
 
 # {{{title}}}
-{{#hasUseWhen}}
 
-**Use This Skill When:**
-{{#useWhenLines}}{{{.}}}{{/useWhenLines}}
-{{/hasUseWhen}}
+{{#descriptionLines}}
+{{{.}}}
+{{/descriptionLines}}
 {{#hasStages}}
 
 ## Stage Guidance
@@ -37,7 +34,10 @@ description: |
 {{/hasStages}}
 {{#hasToolReferences}}
 
-# Recommended Tools
+# Required Tools
+
+Use these tools when applying this skill. Alternative tools require documented
+justification with acknowledged trade-offs.
 
 | Tool | Use When |
 | ---- | -------- |