@forwardimpact/model 0.2.0 → 0.4.0

package/lib/agent.js

@@ -177,21 +177,25 @@ function findAgentBehaviour(agentBehaviours, id) {
 }
 
 /**
- * Build working style section from emphasized behaviours
- * Includes workflow patterns when available
+ * @typedef {Object} WorkingStyleEntry
+ * @property {string} title - Section title (e.g. "Own the outcome end-to-end")
+ * @property {string} content - Working style content (markdown)
+ */
+
+/**
+ * Build working style entries from emphasized behaviours
+ * Returns structured data for template iteration
  * @param {Array} derivedBehaviours - Behaviours sorted by maturity (highest first)
  * @param {Array} agentBehaviours - Agent behaviour definitions with principles
  * @param {number} topN - Number of top behaviours to include
- * @returns {string} Working style markdown section
+ * @returns {WorkingStyleEntry[]} Array of working style entries
  */
 function buildWorkingStyleFromBehaviours(
   derivedBehaviours,
   agentBehaviours,
   topN = 3,
 ) {
-  const sections = [];
-  sections.push("## Working Style");
-  sections.push("");
+  const entries = [];
 
   // Get top N behaviours by maturity
   const topBehaviours = derivedBehaviours.slice(0, topN);
@@ -207,22 +211,16 @@ function buildWorkingStyleFromBehaviours(
 
     // Use title as section header
     const title = agentBehaviour.title || derived.behaviourName;
-    sections.push(`### ${title}`);
-    sections.push("");
-
-    // Include workingStyle if available (structured guidance)
-    if (agentBehaviour.workingStyle) {
-      sections.push(agentBehaviour.workingStyle.trim());
-      sections.push("");
-    } else if (agentBehaviour.principles) {
-      // Fall back to principles
-      const principles = agentBehaviour.principles.trim();
-      sections.push(principles);
-      sections.push("");
-    }
+
+    // Include workingStyle if available, otherwise fall back to principles
+    const content = agentBehaviour.workingStyle
+      ? agentBehaviour.workingStyle.trim()
+      : agentBehaviour.principles.trim();
+
+    entries.push({ title, content });
   }
 
-  return sections.join("\n");
+  return entries;
 }
 
 /**
@@ -308,8 +306,7 @@ function estimateBodyDataLength(bodyData) {
     "stageDescription",
     "identity",
     "priority",
-    "delegation",
-    "operationalContext",
+    "roleContext",
     "workingStyle",
     "beforeHandoff",
   ];
@@ -326,11 +323,6 @@ function estimateBodyDataLength(bodyData) {
         skill.name.length + skill.dirname.length + skill.useWhen.length + 50;
     }
   }
-  if (bodyData.beforeMakingChanges) {
-    for (const item of bodyData.beforeMakingChanges) {
-      length += item.text.length + 5; // +5 for "1. " prefix
-    }
-  }
   if (bodyData.constraints) {
     for (const c of bodyData.constraints) {
       length += c.length + 2; // +2 for "- " prefix
@@ -496,6 +488,7 @@ function getChecklistStage(stageId) {
  * @param {Array} params.agentBehaviours - Agent behaviour definitions
  * @param {Array} params.skills - All skill definitions (for agent section lookup)
  * @param {string} params.checklistMarkdown - Pre-formatted checklist markdown
+ * @param {Array<{id: string, name: string, description: string}>} [params.agentIndex] - List of all available agents
  * @returns {Object} Structured profile body data
  */
 function buildStageProfileBodyData({
@@ -509,6 +502,7 @@ function buildStageProfileBodyData({
   agentBehaviours,
   skills,
   checklistMarkdown,
+  agentIndex,
 }) {
   const name = `${humanDiscipline.specialization || humanDiscipline.name} - ${humanTrack.name}`;
   const stageName = stage.name.charAt(0).toUpperCase() + stage.name.slice(1);
@@ -523,20 +517,6 @@ function buildStageProfileBodyData({
     ? substituteTemplateVars(rawPriority, humanDiscipline)
     : null;
 
-  // Build beforeMakingChanges list - prefer track, fall back to discipline
-  const rawSteps =
-    agentTrack.beforeMakingChanges || agentDiscipline.beforeMakingChanges || [];
-  const beforeMakingChanges = rawSteps.map((text, i) => ({
-    index: i + 1,
-    text: substituteTemplateVars(text, humanDiscipline),
-  }));
-
-  // Delegation (from discipline only, optional)
-  const rawDelegation = agentDiscipline.delegation;
-  const delegation = rawDelegation
-    ? substituteTemplateVars(rawDelegation, humanDiscipline)
-    : null;
-
   // Build skill index from derived skills with agent sections
   const skillIndex = derivedSkills
     .map((derived) => {
@@ -550,11 +530,11 @@ function buildStageProfileBodyData({
     })
     .filter(Boolean);
 
-  // Operational Context - use track's roleContext (shared with human job descriptions)
-  const operationalContext = humanTrack.roleContext.trim();
+  // Role Context - use track's roleContext (shared with human job descriptions)
+  const roleContext = humanTrack.roleContext.trim();
 
-  // Working Style from derived behaviours (still markdown for now)
-  const workingStyle = buildWorkingStyleFromBehaviours(
+  // Working styles from derived behaviours (structured for template iteration)
+  const workingStyles = buildWorkingStyleFromBehaviours(
     derivedBehaviours,
     agentBehaviours,
     3,
@@ -567,18 +547,26 @@ function buildStageProfileBodyData({
     ...(agentTrack.constraints || []),
   ];
 
+  // Filter agent index to only include agents with same track and stage (different disciplines)
+  // Agent IDs follow pattern: {discipline-abbrev}-{track-id-kebab}-{stage-id}
+  const trackSuffix = `-${toKebabCase(humanTrack.id)}-${stage.id}`;
+  const currentAgentId = `${getDisciplineAbbreviation(humanDiscipline.id)}${trackSuffix}`;
+  const filteredAgentIndex = (agentIndex || []).filter(
+    (agent) => agent.id.endsWith(trackSuffix) && agent.id !== currentAgentId,
+  );
+
   return {
     title: `${name} - ${stageName} Agent`,
     stageDescription: stage.description,
     identity: identity.trim(),
     priority: priority ? priority.trim() : null,
     skillIndex,
-    beforeMakingChanges,
-    delegation: delegation ? delegation.trim() : null,
-    operationalContext,
-    workingStyle,
+    roleContext,
+    workingStyles,
     beforeHandoff: checklistMarkdown || null,
     constraints,
+    agentIndex: filteredAgentIndex,
+    hasAgentIndex: filteredAgentIndex.length > 0,
   };
 }
 
@@ -681,6 +669,7 @@ export function deriveStageAgent({
  * @param {Object} params.agentTrack - Agent track definition
  * @param {Array} params.capabilities - Capabilities with checklists
  * @param {Array} params.stages - All stages (for handoff entry criteria)
+ * @param {Array<{id: string, name: string, description: string}>} [params.agentIndex] - List of all available agents
  * @returns {Object} Profile with frontmatter, bodyData, and filename
  */
 export function generateStageAgentProfile({
@@ -695,6 +684,7 @@ export function generateStageAgentProfile({
   agentTrack,
   capabilities,
   stages,
+  agentIndex,
 }) {
   // Derive the complete agent
   const agent = deriveStageAgent({
@@ -716,10 +706,8 @@ export function generateStageAgentProfile({
   const fullName = `${abbrev}-${toKebabCase(track.id)}-${stage.id}`;
   const filename = `${fullName}.agent.md`;
 
-  // Build description
-  const disciplineDesc = discipline.description.trim().split("\n")[0];
-  const stageDesc = stage.description.split(" - ")[0]; // Just the short part
-  const description = `${stageDesc} agent for ${discipline.specialization || discipline.name} on ${track.name} track. ${disciplineDesc}`;
+  // Build description using shared helper
+  const description = buildAgentDescription(discipline, track, stage);
 
   // Format checklist as markdown
   const checklistMarkdown = formatChecklistMarkdown(agent.checklist);
@@ -736,6 +724,7 @@ export function generateStageAgentProfile({
     agentBehaviours,
     skills,
     checklistMarkdown,
+    agentIndex,
   });
 
   // Build frontmatter
@@ -752,3 +741,71 @@ export function generateStageAgentProfile({
     filename,
   };
 }
+
+/**
+ * Build an agent description from discipline, track, and stage
+ * Uses stage.summary for third-person metadata description
+ * @param {Object} discipline - Human discipline definition
+ * @param {Object} track - Human track definition
+ * @param {Object} stage - Stage definition with summary field
+ * @returns {string} Agent description
+ */
+function buildAgentDescription(discipline, track, stage) {
+  const disciplineDesc = discipline.description.trim().split("\n")[0];
+  const stageSummary = stage.summary || stage.name;
+  return `${stageSummary} agent for ${discipline.specialization || discipline.name} on ${track.name} track. ${disciplineDesc}`;
+}
+
+/**
+ * Build a list of all available agents in the system
+ * Enumerates all valid discipline × track × stage combinations
+ * Returns id, name, and description for each agent
+ * @param {Object} params - Parameters
+ * @param {Array} params.disciplines - Human discipline definitions
+ * @param {Array} params.tracks - Human track definitions
+ * @param {Array} params.stages - Stage definitions
+ * @param {Array} params.agentDisciplines - Agent discipline definitions (to filter valid combinations)
+ * @param {Array} params.agentTracks - Agent track definitions (to filter valid combinations)
+ * @returns {Array<{id: string, name: string, description: string}>} List of all agents
+ */
+export function buildAgentIndex({
+  disciplines,
+  tracks,
+  stages,
+  agentDisciplines,
+  agentTracks,
+}) {
+  const agents = [];
+
+  // Build lookup sets for valid agent combinations
+  const agentDisciplineIds = new Set(agentDisciplines.map((d) => d.id));
+  const agentTrackIds = new Set(agentTracks.map((t) => t.id));
+
+  for (const discipline of disciplines) {
+    // Skip disciplines without agent definitions
+    if (!agentDisciplineIds.has(discipline.id)) continue;
+
+    for (const track of tracks) {
+      // Skip tracks without agent definitions
+      if (!agentTrackIds.has(track.id)) continue;
+
+      // Build base name (matches filename pattern)
+      const abbrev = getDisciplineAbbreviation(discipline.id);
+      const baseName = `${abbrev}-${toKebabCase(track.id)}`;
+
+      for (const stage of stages) {
+        const id = `${baseName}-${stage.id}`;
+        const fullName = `${discipline.specialization || discipline.name} - ${track.name} - ${stage.name.charAt(0).toUpperCase() + stage.name.slice(1)} Agent`;
+        const description = buildAgentDescription(discipline, track, stage);
+
+        agents.push({
+          id,
+          name: fullName,
+          description,
+        });
+      }
+    }
+  }
+
+  return agents;
+}

package/lib/index.js

@@ -102,11 +102,15 @@ export {
   deriveHandoffs,
   deriveStageAgent,
   generateStageAgentProfile,
+  buildAgentIndex,
 } from "./agent.js";
 
 // Checklists
 export { deriveChecklist, formatChecklistMarkdown } from "./checklist.js";
 
+// Toolkit
+export { deriveToolkit } from "./toolkit.js";
+
 // Profile filtering (for agents)
 export {
   getPositiveTrackCapabilities,

package/lib/job.js

@@ -12,6 +12,7 @@ import {
   getDisciplineSkillIds,
 } from "./derivation.js";
 import { deriveChecklist } from "./checklist.js";
+import { deriveToolkit } from "./toolkit.js";
 import { getOrCreateJob } from "./job-cache.js";
 
 /**
@@ -28,6 +29,7 @@ import { getOrCreateJob } from "./job-cache.js";
  * @property {Array} behaviourProfile
  * @property {Array} derivedResponsibilities
  * @property {Array} driverCoverage
+ * @property {Array} toolkit - De-duplicated tools from skills
  * @property {Object} checklists - Handoff checklists keyed by handoff type
  */
 
@@ -85,6 +87,12 @@ export function prepareJobDetail({
     }
   }
 
+  // Derive toolkit from skill matrix
+  const toolkit = deriveToolkit({
+    skillMatrix: job.skillMatrix,
+    skills,
+  });
+
   return {
     title: job.title,
     disciplineId: discipline.id,
@@ -98,6 +106,8 @@ export function prepareJobDetail({
     skillMatrix: job.skillMatrix,
     behaviourProfile: job.behaviourProfile,
     derivedResponsibilities: job.derivedResponsibilities || [],
+    // Derived toolkit
+    toolkit,
     // Transformed driver coverage for display
     driverCoverage: driverCoverage.map((d) => ({
       id: d.driverId,

package/lib/toolkit.js

@@ -0,0 +1,76 @@
+/**
+ * Toolkit Derivation Functions
+ *
+ * Derives a de-duplicated list of tools from a skill matrix by looking up
+ * toolReferences from skill definitions. Only skills at the highest derived
+ * level contribute tools, ensuring focused toolkits for both jobs and agents.
+ */
+
+import { filterByHighestLevel } from "./profile.js";
+
+/**
+ * @typedef {Object} ToolkitEntry
+ * @property {string} name - Tool name
+ * @property {string} description - Tool description
+ * @property {string} [url] - Tool documentation URL
+ * @property {string} [simpleIcon] - Simple Icons slug for the tool icon
+ * @property {string[]} skillIds - IDs of skills that reference this tool
+ */
+
+/**
+ * Derive a de-duplicated toolkit from a skill matrix
+ *
+ * Extracts tools from skills at the highest derived level, de-duplicates by name,
+ * and collects which skills reference each tool. This keeps toolkits focused on
+ * the engineer's core competencies for both jobs and agents.
+ *
+ * @param {Object} params
+ * @param {Array<{skillId: string, level: string}>} params.skillMatrix - Skill matrix with skill IDs and levels
+ * @param {Array} params.skills - All skill definitions with toolReferences
+ * @returns {ToolkitEntry[]} De-duplicated toolkit sorted by name
+ */
+export function deriveToolkit({ skillMatrix, skills }) {
+  // Filter to highest level skills only
+  const sourceMatrix = filterByHighestLevel(skillMatrix);
+
+  // Build skill lookup map for O(1) access
+  const skillMap = new Map(skills.map((s) => [s.id, s]));
+
+  // Tool map for de-duplication: name -> ToolkitEntry
+  const toolMap = new Map();
+
+  for (const entry of sourceMatrix) {
+    const skill = skillMap.get(entry.skillId);
+    if (!skill?.toolReferences) continue;
+
+    for (const tool of skill.toolReferences) {
+      const existing = toolMap.get(tool.name);
+      if (existing) {
+        // Add skill ID if not already present
+        if (!existing.skillIds.includes(skill.id)) {
+          existing.skillIds.push(skill.id);
+        }
+        // Prefer first occurrence's metadata, but fill in missing values
+        if (!existing.url && tool.url) {
+          existing.url = tool.url;
+        }
+        if (!existing.simpleIcon && tool.simpleIcon) {
+          existing.simpleIcon = tool.simpleIcon;
+        }
+      } else {
+        toolMap.set(tool.name, {
+          name: tool.name,
+          description: tool.description,
+          url: tool.url,
+          simpleIcon: tool.simpleIcon,
+          skillIds: [skill.id],
+        });
+      }
+    }
+  }
+
+  // Sort by name and return
+  return Array.from(toolMap.values()).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/model",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Derivation engine for roles, skills, and AI agent profiles",
   "license": "Apache-2.0",
   "repository": {
@@ -28,7 +28,7 @@
     "./progression": "./lib/progression.js"
   },
   "dependencies": {
-    "@forwardimpact/schema": "^0.2.0"
+    "@forwardimpact/schema": "^0.4.0"
   },
   "engines": {
     "node": ">=18.0.0"