@forwardimpact/pathway 0.16.1 → 0.17.1

package/src/lib/template-loader.js

@@ -65,6 +65,24 @@ export async function loadSkillTemplate(dataDir) {
   return loadTemplate("skill.template.md", dataDir);
 }
 
+/**
+ * Load skill install script template
+ * @param {string} dataDir - Path to data directory
+ * @returns {Promise<string>} Install script template content
+ */
+export async function loadSkillInstallTemplate(dataDir) {
+  return loadTemplate("skill-install.template.sh", dataDir);
+}
+
+/**
+ * Load skill reference template
+ * @param {string} dataDir - Path to data directory
+ * @returns {Promise<string>} Reference template content
+ */
+export async function loadSkillReferenceTemplate(dataDir) {
+  return loadTemplate("skill-reference.template.md", dataDir);
+}
+
 /**
  * Load job description template
  * @param {string} dataDir - Path to data directory

package/src/lib/yaml-loader.js

@@ -76,6 +76,8 @@ async function loadSkillsFromCapabilities(capabilitiesDir) {
           isHumanOnly,
           human,
           agent,
+          instructions,
+          installScript,
           implementationReference,
           toolReferences,
         } = skill;
@@ -88,6 +90,9 @@ async function loadSkillsFromCapabilities(capabilitiesDir) {
           // Include isHumanOnly flag for agent filtering (defaults to false)
           ...(isHumanOnly && { isHumanOnly }),
           ...(agent && { agent }),
+          // Include agent skill content fields
+          ...(instructions && { instructions }),
+          ...(installScript && { installScript }),
           // Include implementation reference and tool references (shared by human and agent)
           ...(implementationReference && { implementationReference }),
           ...(toolReferences && { toolReferences }),

package/src/pages/agent-builder.js

@@ -37,8 +37,12 @@ import {
 import { createReactive } from "../lib/reactive.js";
 import { getStageEmoji } from "../formatters/stage/shared.js";
 import { formatAgentProfile } from "../formatters/agent/profile.js";
-import { formatAgentSkill } from "../formatters/agent/skill.js";
-import { createCodeDisplay } from "../components/code-display.js";
+import {
+  formatAgentSkill,
+  formatInstallScript,
+  formatReference,
+} from "../formatters/agent/skill.js";
+import { createFileCard } from "../components/file-card.js";
 import { createToolkitTable } from "../formatters/toolkit/dom.js";
 import { createDetailSection } from "../components/detail.js";
 
@@ -65,17 +69,21 @@ async function getAgentData(dataDir = "./data") {
 
 /**
  * Load templates with caching
- * @returns {Promise<{agent: string, skill: string}>}
+ * @returns {Promise<{agent: string, skill: string, install: string, reference: string}>}
  */
 async function getTemplates() {
   if (!templateCache) {
-    const [agentRes, skillRes] = await Promise.all([
+    const [agentRes, skillRes, installRes, referenceRes] = await Promise.all([
       fetch("./templates/agent.template.md"),
       fetch("./templates/skill.template.md"),
+      fetch("./templates/skill-install.template.sh"),
+      fetch("./templates/skill-reference.template.md"),
     ]);
     templateCache = {
       agent: await agentRes.text(),
       skill: await skillRes.text(),
+      install: await installRes.text(),
+      reference: await referenceRes.text(),
     };
   }
   return templateCache;
@@ -271,7 +279,6 @@ export async function renderAgentBuilder() {
       skills: data.skills,
       behaviours: data.behaviours,
       agentBehaviours: agentData.behaviours,
-      capabilities: data.capabilities,
       vscodeSettings: agentData.vscodeSettings,
       devcontainer: agentData.devcontainer,
       templates,
@@ -449,7 +456,6 @@ function createAllStagesPreview(context) {
     skills,
     behaviours,
     agentBehaviours,
-    capabilities,
     vscodeSettings,
     devcontainer,
     templates,
@@ -468,7 +474,6 @@ function createAllStagesPreview(context) {
       agentBehaviours,
       agentDiscipline,
       agentTrack,
-      capabilities,
       stages,
     });
 
@@ -482,7 +487,6 @@ function createAllStagesPreview(context) {
       agentBehaviours,
       agentDiscipline,
       agentTrack,
-      capabilities,
       stages,
       agentIndex,
     });
@@ -532,9 +536,24 @@ function createAllStagesPreview(context) {
       ),
       div(
         { className: "agent-cards-grid" },
-        ...stageAgents.map(({ stage, profile }) =>
-          createAgentCard(stage, profile, stages, templates.agent),
-        ),
+        ...stageAgents.map(({ stage, profile }) => {
+          const content = formatAgentProfile(profile, templates.agent);
+          const stageEmoji = getStageEmoji(stages, stage.id);
+          return createFileCard({
+            header: [
+              span({ className: "file-card-emoji" }, stageEmoji),
+              h3({}, `${stage.name} Agent`),
+            ],
+            files: [
+              {
+                filename: profile.filename,
+                content,
+                language: "markdown",
+              },
+            ],
+            maxHeight: 400,
+          });
+        }),
       ),
     ),
 
@@ -545,9 +564,7 @@ function createAllStagesPreview(context) {
       skillFiles.length > 0
         ? div(
             { className: "skill-cards-grid" },
-            ...skillFiles.map((skill) =>
-              createSkillCard(skill, templates.skill),
-            ),
+            ...skillFiles.map((skill) => buildSkillFileCard(skill, templates)),
           )
         : p(
             { className: "text-muted" },
@@ -581,7 +598,6 @@ function createSingleStagePreview(context, stage) {
     skills,
     behaviours,
     agentBehaviours,
-    capabilities,
     vscodeSettings,
     devcontainer,
     stages,
@@ -589,21 +605,6 @@ function createSingleStagePreview(context, stage) {
     agentIndex,
   } = context;
 
-  // Derive stage agent
-  const derived = deriveStageAgent({
-    discipline: humanDiscipline,
-    track: humanTrack,
-    stage,
-    grade,
-    skills,
-    behaviours,
-    agentBehaviours,
-    agentDiscipline,
-    agentTrack,
-    capabilities,
-    stages,
-  });
-
   const profile = generateStageAgentProfile({
     discipline: humanDiscipline,
     track: humanTrack,
@@ -614,7 +615,6 @@ function createSingleStagePreview(context, stage) {
     agentBehaviours,
     agentDiscipline,
     agentTrack,
-    capabilities,
     stages,
     agentIndex,
   });
@@ -656,7 +656,24 @@ function createSingleStagePreview(context, stage) {
       h2({}, "Agent"),
       div(
         { className: "agent-cards-grid single" },
-        createAgentCard(stage, profile, stages, templates.agent, derived),
+        (() => {
+          const content = formatAgentProfile(profile, templates.agent);
+          const stageEmoji = getStageEmoji(stages, stage.id);
+          return createFileCard({
+            header: [
+              span({ className: "file-card-emoji" }, stageEmoji),
+              h3({}, `${stage.name} Agent`),
+            ],
+            files: [
+              {
+                filename: profile.filename,
+                content,
+                language: "markdown",
+              },
+            ],
+            maxHeight: 400,
+          });
+        })(),
       ),
     ),
 
@@ -667,9 +684,7 @@ function createSingleStagePreview(context, stage) {
       skillFiles.length > 0
         ? div(
             { className: "skill-cards-grid" },
-            ...skillFiles.map((skill) =>
-              createSkillCard(skill, templates.skill),
-            ),
+            ...skillFiles.map((skill) => buildSkillFileCard(skill, templates)),
           )
         : p(
             { className: "text-muted" },
@@ -688,66 +703,53 @@ function createSingleStagePreview(context, stage) {
 }
 
 /**
- * Create an agent card for a stage
- * @param {Object} stage - Stage object
- * @param {Object} profile - Generated profile
- * @param {Array} stages - All stages for emoji lookup
- * @param {string} agentTemplate - Mustache template for agent profile
- * @param {Object} [_derived] - Optional derived agent data for extra info
+ * Build a file card for a skill with 1–3 file panes (accordion).
+ * @param {Object} skill - Skill with frontmatter and body
+ * @param {{skill: string, install: string, reference: string}} templates - Mustache templates
  * @returns {HTMLElement}
  */
-function createAgentCard(stage, profile, stages, agentTemplate, _derived) {
-  const content = formatAgentProfile(profile, agentTemplate);
-  const stageEmoji = getStageEmoji(stages, stage.id);
+function buildSkillFileCard(skill, templates) {
+  const content = formatAgentSkill(skill, templates.skill);
+
+  /** @type {import('../components/file-card.js').FileDescriptor[]} */
+  const files = [
+    {
+      filename: `${skill.dirname}/SKILL.md`,
+      content,
+      language: "markdown",
+    },
+  ];
 
-  const card = div(
-    { className: "agent-card" },
-    div(
-      { className: "agent-card-header" },
-      div(
-        { className: "agent-card-title" },
-        span({ className: "agent-card-emoji" }, stageEmoji),
-        h3({}, `${stage.name} Agent`),
-      ),
-    ),
-    div(
-      { className: "agent-card-preview" },
-      createCodeDisplay({
-        content,
-        filename: profile.filename,
-        maxHeight: 400,
-      }),
-    ),
-  );
+  if (skill.installScript) {
+    files.push({
+      filename: `${skill.dirname}/scripts/install.sh`,
+      content: formatInstallScript(skill, templates.install),
+      language: "bash",
+    });
+  }
 
-  return card;
-}
+  if (skill.implementationReference) {
+    files.push({
+      filename: `${skill.dirname}/references/REFERENCE.md`,
+      content: formatReference(skill, templates.reference),
+      language: "markdown",
+    });
+  }
 
-/**
- * Create a skill card
- * @param {Object} skill - Skill with frontmatter and body
- * @param {string} skillTemplate - Mustache template for skill
- * @returns {HTMLElement}
- */
-function createSkillCard(skill, skillTemplate) {
-  const content = formatAgentSkill(skill, skillTemplate);
-  const filename = `${skill.dirname}/SKILL.md`;
+  const headerChildren = [
+    span({ className: "file-card-name" }, skill.frontmatter.name),
+  ];
+  if (files.length > 1) {
+    headerChildren.push(
+      span({ className: "file-card-badge" }, `${files.length} files`),
+    );
+  }
 
-  return div(
-    { className: "skill-card" },
-    div(
-      { className: "skill-card-header" },
-      span({ className: "skill-card-name" }, skill.frontmatter.name),
-    ),
-    div(
-      { className: "skill-card-preview" },
-      createCodeDisplay({
-        content,
-        filename,
-        maxHeight: 300,
-      }),
-    ),
-  );
+  return createFileCard({
+    header: headerChildren,
+    files,
+    maxHeight: 300,
+  });
 }
 
 /**
@@ -787,10 +789,27 @@ function createDownloadAllButton(
         zip.file(`.github/agents/${profile.filename}`, content);
       }
 
-      // Add skills
+      // Add skills (SKILL.md + optional install script + optional reference)
       for (const skill of skillFiles) {
         const content = formatAgentSkill(skill, templates.skill);
         zip.file(`.claude/skills/${skill.dirname}/SKILL.md`, content);
+
+        if (skill.installScript) {
+          const installContent = formatInstallScript(skill, templates.install);
+          zip.file(
+            `.claude/skills/${skill.dirname}/scripts/install.sh`,
+            installContent,
+            { unixPermissions: "755" },
+          );
+        }
+
+        if (skill.implementationReference) {
+          const refContent = formatReference(skill, templates.reference);
+          zip.file(
+            `.claude/skills/${skill.dirname}/references/REFERENCE.md`,
+            refContent,
+          );
+        }
       }
 
       // Add VS Code settings
@@ -870,10 +889,27 @@ function createDownloadSingleButton(
       const content = formatAgentProfile(profile, templates.agent);
       zip.file(`.github/agents/${profile.filename}`, content);
 
-      // Add skills
+      // Add skills (SKILL.md + optional install script + optional reference)
       for (const skill of skillFiles) {
         const skillContent = formatAgentSkill(skill, templates.skill);
         zip.file(`.claude/skills/${skill.dirname}/SKILL.md`, skillContent);
+
+        if (skill.installScript) {
+          const installContent = formatInstallScript(skill, templates.install);
+          zip.file(
+            `.claude/skills/${skill.dirname}/scripts/install.sh`,
+            installContent,
+            { unixPermissions: "755" },
+          );
+        }
+
+        if (skill.implementationReference) {
+          const refContent = formatReference(skill, templates.reference);
+          zip.file(
+            `.claude/skills/${skill.dirname}/references/REFERENCE.md`,
+            refContent,
+          );
+        }
       }
 
       // Add VS Code settings

package/src/pages/skill.js

@@ -14,6 +14,23 @@ import {
   getCapabilityEmoji,
   getConceptEmoji,
 } from "@forwardimpact/schema/levels";
+import { generateSkillMarkdown } from "@forwardimpact/model";
+import { formatAgentSkill } from "../formatters/agent/skill.js";
+
+/** @type {string|null} Cached skill template */
+let skillTemplateCache = null;
+
+/**
+ * Load skill Mustache template with caching
+ * @returns {Promise<string>}
+ */
+async function getSkillTemplate() {
+  if (!skillTemplateCache) {
+    const res = await fetch("./templates/skill.template.md");
+    skillTemplateCache = await res.text();
+  }
+  return skillTemplateCache;
+}
 
 /**
  * Render skills list page
@@ -69,7 +86,7 @@ export function renderSkillsList() {
  * Render skill detail page
  * @param {Object} params - Route params
  */
-export function renderSkillDetail(params) {
+export async function renderSkillDetail(params) {
   const { data } = getState();
   const skill = data.skills.find((s) => s.id === params.id);
 
@@ -83,6 +100,14 @@ export function renderSkillDetail(params) {
     return;
   }
 
+  // Generate SKILL.md content if skill has an agent section
+  let agentSkillContent;
+  if (skill.agent) {
+    const template = await getSkillTemplate();
+    const skillData = generateSkillMarkdown(skill, data.stages);
+    agentSkillContent = formatAgentSkill(skillData, template);
+  }
+
   // Use DOM formatter - it handles transformation internally
   render(
     skillToDOM(skill, {
@@ -90,6 +115,7 @@ export function renderSkillDetail(params) {
       tracks: data.tracks,
       drivers: data.drivers,
       capabilities: data.capabilities,
+      agentSkillContent,
     }),
   );
 }

package/templates/agent.template.md

@@ -25,7 +25,7 @@ handoffs:
 
 {{{stageDescription}}}
 
-## Core Identity
+## Core identity
 
 {{{identity}}}
 {{#priority}}
@@ -34,13 +34,13 @@ handoffs:
 {{/priority}}
 {{#roleContext}}
 
-## Role Context
+## Role context
 
 {{{roleContext}}}
 {{/roleContext}}
 {{#hasWorkingStyles}}
 
-## Working Style
+## Working style
 {{#workingStyles}}
 
 ### {{title}}
@@ -50,14 +50,14 @@ handoffs:
 {{/hasWorkingStyles}}
 {{#hasSkills}}
 
-## Required Skills
+## Required skills
 
 **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.
 
-Each skill file contains XML-tagged sections for precise navigation:
+Each skill contains marked-up sections and references for precise navigation:
 
 - `<read_then_do_{{stageId}}>` — Read-Then-Do checklist for the
   {{stageName}} stage. Read and understand these items BEFORE starting work.
@@ -69,12 +69,15 @@ Each skill file contains XML-tagged sections for precise navigation:
   organizational standards that override general knowledge or personal
   preferences.
 {{#isOnboard}}
-- `<onboarding_steps>` — Step-by-step environment setup instructions.
-  Follow these to install prerequisites and configure the development
+- `scripts/install.sh` — Self-contained install script for environment setup.
+  Run this script to install prerequisites and configure the development
   environment. Focus on setup only — do not begin feature implementation.
+- `references/REFERENCE.md` — Detailed code examples and reference material.
+  Consult this for implementation patterns, common pitfalls, and verification
+  steps.
 {{/isOnboard}}
 
-| Skill | Location | Use When |
+| Skill | Location | Use when |
 | ----- | -------- | -------- |
 {{#skillIndex}}
 | {{{name}}} | `.claude/skills/{{dirname}}/SKILL.md` | {{{useWhen}}} |
@@ -82,7 +85,7 @@ Each skill file contains XML-tagged sections for precise navigation:
 {{/hasSkills}}
 {{#hasAgentIndex}}
 
-## Required Sub-Agent Delegations
+## Required subagent delegations
 
 **MANDATORY:** You MUST delegate work outside your speciality using the
 `runSubagent` tool. Do not attempt work that another agent is better suited for.
@@ -93,52 +96,19 @@ 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 |
+| Agent name | Speciality | Description |
 | ---------- | ---------- | ----------- |
 {{#agentIndex}}
 | `{{id}}` | {{{name}}} | {{{description}}} |
 {{/agentIndex}}
 {{/hasAgentIndex}}
-{{#hasReadChecklist}}
 
-## Read-Then-Do Checklist
-
-Before starting work, read and understand these items. They are prerequisites
-and context that must be absorbed before implementation begins:
-
-{{#readChecklist}}
-### {{{capability.emojiIcon}}} {{{skill.name}}}
-
-{{#items}}
-- [ ] {{{.}}}
-{{/items}}
-
-{{/readChecklist}}
-{{/hasReadChecklist}}
-{{#hasConfirmChecklist}}
-
-## Do-Then-Confirm Checklist
-
-Before offering a handoff, verify and summarize completion of these items:
-
-{{#confirmChecklist}}
-### {{{capability.emojiIcon}}} {{{skill.name}}}
-
-{{#items}}
-- [ ] {{{.}}}
-{{/items}}
-
-{{/confirmChecklist}}
-When verified, summarize what was accomplished then offer the handoff. If items
-are incomplete, explain what remains.
-{{/hasConfirmChecklist}}
-
-## Return Format
+## Return format
 
 When completing work (for handoff or as a subagent), provide:
 
 1. **Work completed**: What was accomplished
-2. **Checklist status**: Items verified from Before Handoff section
+2. **Checklist status**: Items verified from skill Do-Then-Confirm checklists
 3. **Recommendation**: Ready for next stage, or needs more work
 
 {{#hasConstraints}}

package/templates/skill-install.template.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Install script for {{name}}
+# Generated by @forwardimpact/pathway
+{{{installScript}}}

package/templates/skill-reference.template.md

@@ -0,0 +1,3 @@
+# {{{title}}} — Reference
+
+{{{implementationReference}}}

package/templates/skill.template.md

@@ -1,6 +1,6 @@
 ---
 name: {{name}}
-description: {{{description}}}{{#hasUseWhen}} Use When: {{{useWhen}}}{{/hasUseWhen}}
+description: {{{description}}}{{#hasUseWhen}} Use when {{{useWhen}}}{{/hasUseWhen}}
 ---
 
 # {{{title}}}
@@ -8,40 +8,28 @@ description: {{{description}}}{{#hasUseWhen}} Use When: {{{useWhen}}}{{/hasUseWh
 {{#descriptionLines}}
 {{{.}}}
 {{/descriptionLines}}
-{{#hasStages}}
-
-## Stage Guidance
-{{#stages}}
-
-### {{stageName}} Stage
-
-**Focus:** {{{focus}}}
-
-<read_then_do_{{stageId}}>
-
-**Read-Then-Do Checklist:**
-{{#readChecklist}}
-- [ ] {{{.}}}
-{{/readChecklist}}
 
-</read_then_do_{{stageId}}>
+{{#hasInstallScript}}
+Run this to install prerequisites: `scripts/install.sh`
+{{/hasInstallScript}}
+{{#hasReference}}
+See [implementation reference](references/REFERENCE.md) for code examples.
+{{/hasReference}}
+{{#hasUseWhen}}
 
-<do_then_confirm_{{stageId}}>
+## When to use this skill
 
-**Do-Then-Confirm Checklist:**
-{{#confirmChecklist}}
-- [ ] {{{.}}}
-{{/confirmChecklist}}
+Use this skill when {{{useWhen}}}
+{{/hasUseWhen}}
+{{#hasInstructions}}
 
-</do_then_confirm_{{stageId}}>
-{{/stages}}
-{{/hasStages}}
+{{{instructions}}}
+{{/hasInstructions}}
 {{#hasToolReferences}}
 
-<required_tools>
-
-## Required Tools
+# Required tools
 
+<required_tools>
 **MANDATORY:** You MUST use these tools when applying this skill. These are
 organizational standards that override general knowledge or personal preferences.
 
@@ -50,17 +38,32 @@ output: (1) which tool requirement you cannot meet, (2) the specific constraint
 preventing compliance, and (3) the alternative approach with acknowledged
 trade-offs.
 
-| Tool | Use When |
+| Tool | Use when |
 | ---- | -------- |
 {{#toolReferences}}
 | {{#url}}[{{{name}}}]({{{url}}}){{/url}}{{^url}}{{{name}}}{{/url}} | {{{useWhen}}} |
 {{/toolReferences}}
-
 </required_tools>
 {{/hasToolReferences}}
-{{#hasReference}}
+{{#hasStages}}
+
+# Stage checklists
+{{#stages}}
 
-# Reference
+## {{stageName}} stage
 
-{{{reference}}}
-{{/hasReference}}
+**Focus:** {{{focus}}}
+
+<read_then_do_{{stageId}}>
+{{#readChecklist}}
+- [ ] {{{.}}}
+{{/readChecklist}}
+</read_then_do_{{stageId}}>
+
+<do_then_confirm_{{stageId}}>
+{{#confirmChecklist}}
+- [ ] {{{.}}}
+{{/confirmChecklist}}
+</do_then_confirm_{{stageId}}>
+{{/stages}}
+{{/hasStages}}