@forwardimpact/pathway 0.1.0

package/app/commands/agent.js

@@ -0,0 +1,430 @@
+/**
+ * Agent Command
+ *
+ * CLI command for generating AI coding agent configurations
+ * from Engineering Pathway data.
+ *
+ * All agents are stage-specific. Use --stage for a single stage
+ * or --all-stages (default) for all stages.
+ *
+ * Usage:
+ *   npx pathway agent <discipline> <track> [--output=PATH] [--preview]
+ *   npx pathway agent <discipline> <track> --stage=plan
+ *   npx pathway agent <discipline> <track> --all-stages
+ *   npx pathway agent --list
+ *
+ * Examples:
+ *   npx pathway agent software_engineering platform
+ *   npx pathway agent software_engineering platform --stage=plan
+ *   npx pathway agent software_engineering platform --preview
+ */
+
+import { writeFile, mkdir, readFile } from "fs/promises";
+import { join, dirname } from "path";
+import { existsSync } from "fs";
+import { loadAgentData, loadSkillsWithAgentData } from "../model/loader.js";
+import {
+  generateStageAgentProfile,
+  validateAgentProfile,
+  validateAgentSkill,
+  deriveReferenceGrade,
+  deriveAgentSkills,
+  generateSkillMd,
+} from "../model/agent.js";
+import {
+  formatAgentProfile,
+  formatAgentProfileForCli,
+} from "../formatters/agent/profile.js";
+import { formatAgentSkill } from "../formatters/agent/skill.js";
+import { formatError, formatSuccess } from "../lib/cli-output.js";
+
+/**
+ * Ensure directory exists for a file path
+ * @param {string} filePath - Full file path
+ */
+async function ensureDir(filePath) {
+  await mkdir(dirname(filePath), { recursive: true });
+}
+
+/**
+ * Generate VS Code settings file with required settings
+ * Merges with existing settings if file exists
+ * @param {string} baseDir - Base output directory
+ * @param {Object} vscodeSettings - Settings loaded from data
+ */
+async function generateVSCodeSettings(baseDir, vscodeSettings) {
+  const settingsPath = join(baseDir, ".vscode", "settings.json");
+
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    const content = await readFile(settingsPath, "utf-8");
+    settings = JSON.parse(content);
+  }
+
+  const merged = { ...settings, ...vscodeSettings };
+
+  await ensureDir(settingsPath);
+  await writeFile(
+    settingsPath,
+    JSON.stringify(merged, null, 2) + "\n",
+    "utf-8",
+  );
+  console.log(formatSuccess(`Updated: ${settingsPath}`));
+}
+
+/**
+ * Show agent summary with stats
+ * @param {Object} data - Pathway data
+ * @param {Object} agentData - Agent-specific data
+ * @param {Array} skillsWithAgent - Skills with agent sections
+ */
+function showAgentSummary(data, agentData, skillsWithAgent) {
+  // Count valid combinations
+  let validCombinations = 0;
+  for (const discipline of agentData.disciplines) {
+    for (const track of agentData.tracks) {
+      const humanDiscipline = data.disciplines.find(
+        (d) => d.id === discipline.id,
+      );
+      const humanTrack = data.tracks.find((t) => t.id === track.id);
+      if (humanDiscipline && humanTrack) {
+        validCombinations++;
+      }
+    }
+  }
+
+  const skillsWithAgentCount = skillsWithAgent.filter((s) => s.agent).length;
+
+  console.log(`\n🤖 Agent\n`);
+  console.log(
+    `Disciplines: ${agentData.disciplines.length}/${data.disciplines.length} with agent definitions`,
+  );
+  console.log(
+    `Tracks:      ${agentData.tracks.length}/${data.tracks.length} with agent definitions`,
+  );
+  console.log(
+    `Skills:      ${skillsWithAgentCount}/${skillsWithAgent.length} with agent sections`,
+  );
+  console.log(`Stages:      ${data.stages.length} available`);
+  console.log(`\nValid combinations: ${validCombinations}`);
+  console.log(`\nRun 'npx pathway agent --list' for all combinations`);
+  console.log(
+    `Run 'npx pathway agent <discipline> <track>' to generate files\n`,
+  );
+}
+
+/**
+ * List available agent combinations (clean output for piping)
+ * @param {Object} data - Pathway data
+ * @param {Object} agentData - Agent-specific data
+ * @param {boolean} verbose - Show verbose output
+ */
+function listAgentCombinations(data, agentData, verbose = false) {
+  if (!verbose) {
+    // Clean output for piping
+    for (const discipline of agentData.disciplines) {
+      for (const track of agentData.tracks) {
+        const humanDiscipline = data.disciplines.find(
+          (d) => d.id === discipline.id,
+        );
+        const humanTrack = data.tracks.find((t) => t.id === track.id);
+        if (humanDiscipline && humanTrack) {
+          console.log(`${discipline.id} ${track.id}`);
+        }
+      }
+    }
+    return;
+  }
+
+  // Verbose output
+  console.log("# 🤖 Available Agent Combinations\n");
+
+  const agentDisciplineIds = new Set(agentData.disciplines.map((d) => d.id));
+  const agentTrackIds = new Set(agentData.tracks.map((t) => t.id));
+
+  console.log("## Disciplines with agent definitions:\n");
+  for (const discipline of data.disciplines) {
+    const hasAgent = agentDisciplineIds.has(discipline.id);
+    const status = hasAgent ? "✅" : "⬜";
+    console.log(
+      `  ${status} ${discipline.id} - ${discipline.specialization || discipline.name}`,
+    );
+  }
+
+  console.log("\n## Tracks with agent definitions:\n");
+  for (const track of data.tracks) {
+    const hasAgent = agentTrackIds.has(track.id);
+    const status = hasAgent ? "✅" : "⬜";
+    console.log(`  ${status} ${track.id} - ${track.name}`);
+  }
+
+  console.log("\n## Valid combinations:\n");
+  for (const discipline of agentData.disciplines) {
+    for (const track of agentData.tracks) {
+      const humanDiscipline = data.disciplines.find(
+        (d) => d.id === discipline.id,
+      );
+      const humanTrack = data.tracks.find((t) => t.id === track.id);
+      if (humanDiscipline && humanTrack) {
+        console.log(`  npx pathway agent ${discipline.id} ${track.id}`);
+      }
+    }
+  }
+
+  console.log("\n## Available stages:\n");
+  for (const stage of data.stages) {
+    console.log(`  --stage=${stage.id}: ${stage.description.split(" - ")[0]}`);
+  }
+}
+
+/**
+ * Write agent profile to file
+ * @param {Object} profile - Generated profile
+ * @param {string} baseDir - Base output directory
+ */
+async function writeProfile(profile, baseDir) {
+  const profilePath = join(baseDir, ".github", "agents", profile.filename);
+  const profileContent = formatAgentProfile(profile);
+  await ensureDir(profilePath);
+  await writeFile(profilePath, profileContent, "utf-8");
+  console.log(formatSuccess(`Created: ${profilePath}`));
+  return profilePath;
+}
+
+/**
+ * Write skill files
+ * @param {Array} skills - Generated skills
+ * @param {string} baseDir - Base output directory
+ */
+async function writeSkills(skills, baseDir) {
+  for (const skill of skills) {
+    const skillPath = join(
+      baseDir,
+      ".claude",
+      "skills",
+      skill.dirname,
+      "SKILL.md",
+    );
+    const skillContent = formatAgentSkill(skill);
+    await ensureDir(skillPath);
+    await writeFile(skillPath, skillContent, "utf-8");
+    console.log(formatSuccess(`Created: ${skillPath}`));
+  }
+}
+
+/**
+ * Run the agent command
+ * @param {Object} params - Command parameters
+ * @param {Object} params.data - Loaded pathway data
+ * @param {string[]} params.args - Command arguments [discipline_id, track_id]
+ * @param {Object} params.options - Command options
+ * @param {string} params.dataDir - Path to data directory
+ */
+export async function runAgentCommand({ data, args, options, dataDir }) {
+  // Load agent-specific data
+  const agentData = await loadAgentData(dataDir);
+  const skillsWithAgent = await loadSkillsWithAgentData(dataDir);
+
+  // --list: Output clean lines for piping
+  if (options.list) {
+    listAgentCombinations(data, agentData, false);
+    return;
+  }
+
+  // No args: Show summary
+  if (args.length === 0) {
+    showAgentSummary(data, agentData, skillsWithAgent);
+    return;
+  }
+
+  const [disciplineId, trackId] = args;
+
+  if (!disciplineId || !trackId) {
+    console.error(
+      formatError("Usage: npx pathway agent <discipline_id> <track_id>"),
+    );
+    console.error(
+      "\nRun 'npx pathway agent --list' to see available combinations.",
+    );
+    process.exit(1);
+  }
+
+  // Look up human definitions
+  const humanDiscipline = data.disciplines.find((d) => d.id === disciplineId);
+  const humanTrack = data.tracks.find((t) => t.id === trackId);
+
+  if (!humanDiscipline) {
+    console.error(formatError(`Unknown discipline: ${disciplineId}`));
+    console.error("\nAvailable disciplines:");
+    for (const d of data.disciplines) {
+      console.error(`  - ${d.id}`);
+    }
+    process.exit(1);
+  }
+
+  if (!humanTrack) {
+    console.error(formatError(`Unknown track: ${trackId}`));
+    console.error("\nAvailable tracks:");
+    for (const t of data.tracks) {
+      console.error(`  - ${t.id}`);
+    }
+    process.exit(1);
+  }
+
+  // Look up agent definitions
+  const agentDiscipline = agentData.disciplines.find(
+    (d) => d.id === disciplineId,
+  );
+  const agentTrack = agentData.tracks.find((t) => t.id === trackId);
+
+  if (!agentDiscipline) {
+    console.error(
+      formatError(`No agent definition for discipline: ${disciplineId}`),
+    );
+    console.error("\nAgent definitions exist for:");
+    for (const d of agentData.disciplines) {
+      console.error(`  - ${d.id}`);
+    }
+    process.exit(1);
+  }
+
+  if (!agentTrack) {
+    console.error(formatError(`No agent definition for track: ${trackId}`));
+    console.error("\nAgent definitions exist for:");
+    for (const t of agentData.tracks) {
+      console.error(`  - ${t.id}`);
+    }
+    process.exit(1);
+  }
+
+  // Get reference grade for derivation
+  const grade = deriveReferenceGrade(data.grades);
+
+  const baseDir = options.output || ".";
+
+  // Common params for stage-based generation
+  const stageParams = {
+    discipline: humanDiscipline,
+    track: humanTrack,
+    grade,
+    skills: skillsWithAgent,
+    behaviours: data.behaviours,
+    agentBehaviours: agentData.behaviours,
+    agentDiscipline,
+    agentTrack,
+    capabilities: data.capabilities,
+    stages: data.stages,
+  };
+
+  // Handle --stage flag for single stage agent
+  if (options.stage) {
+    const stage = data.stages.find((s) => s.id === options.stage);
+    if (!stage) {
+      console.error(formatError(`Unknown stage: ${options.stage}`));
+      console.error("\nAvailable stages:");
+      for (const s of data.stages) {
+        console.error(`  - ${s.id}`);
+      }
+      process.exit(1);
+    }
+
+    const profile = generateStageAgentProfile({ ...stageParams, stage });
+
+    // Validate
+    const errors = validateAgentProfile(profile);
+    if (errors.length > 0) {
+      console.error(formatError("Profile validation failed:"));
+      for (const err of errors) {
+        console.error(`  - ${err}`);
+      }
+      process.exit(1);
+    }
+
+    // Preview or write
+    if (options.preview) {
+      console.log(formatAgentProfileForCli(profile));
+      return;
+    }
+
+    await writeProfile(profile, baseDir);
+    await generateVSCodeSettings(baseDir, agentData.vscodeSettings);
+    console.log("");
+    console.log(
+      formatSuccess(`Generated stage agent: ${profile.frontmatter.name}`),
+    );
+    return;
+  }
+
+  // Default behavior: generate all stage agents (or single stage if --stage specified)
+  // No generic agents - all agents are stage-specific
+  const profiles = [];
+
+  // Generate all stage agents
+  for (const stage of data.stages) {
+    const profile = generateStageAgentProfile({ ...stageParams, stage });
+    profiles.push(profile);
+  }
+
+  // Derive skills once for all stages
+  const derivedSkills = deriveAgentSkills({
+    discipline: humanDiscipline,
+    track: humanTrack,
+    grade,
+    skills: skillsWithAgent,
+  });
+
+  const skillFiles = derivedSkills
+    .map((derived) => skillsWithAgent.find((s) => s.id === derived.skillId))
+    .filter((skill) => skill?.agent)
+    .map((skill) => generateSkillMd(skill));
+
+  // Validate all profiles
+  for (const profile of profiles) {
+    const errors = validateAgentProfile(profile);
+    if (errors.length > 0) {
+      console.error(
+        formatError(`Profile ${profile.frontmatter.name} validation failed:`),
+      );
+      for (const err of errors) {
+        console.error(`  - ${err}`);
+      }
+      process.exit(1);
+    }
+  }
+
+  // Validate all skills
+  for (const skill of skillFiles) {
+    const errors = validateAgentSkill(skill);
+    if (errors.length > 0) {
+      console.error(
+        formatError(`Skill ${skill.frontmatter.name} validation failed:`),
+      );
+      for (const err of errors) {
+        console.error(`  - ${err}`);
+      }
+      process.exit(1);
+    }
+  }
+
+  // Preview or write
+  if (options.preview) {
+    for (const profile of profiles) {
+      console.log(formatAgentProfileForCli(profile));
+      console.log("\n---\n");
+    }
+    return;
+  }
+
+  for (const profile of profiles) {
+    await writeProfile(profile, baseDir);
+  }
+  await writeSkills(skillFiles, baseDir);
+  await generateVSCodeSettings(baseDir, agentData.vscodeSettings);
+
+  console.log("");
+  console.log(formatSuccess(`Generated ${profiles.length} agents:`));
+  for (const profile of profiles) {
+    console.log(`  - ${profile.frontmatter.name}`);
+  }
+  console.log(`  Skills: ${skillFiles.length} files`);
+}

package/app/commands/behaviour.js

@@ -0,0 +1,61 @@
+/**
+ * Behaviour CLI Command
+ *
+ * Handles behaviour summary, listing, and detail display in the terminal.
+ *
+ * Usage:
+ *   npx pathway behaviour              # Summary with stats
+ *   npx pathway behaviour --list       # IDs only (for piping)
+ *   npx pathway behaviour <id>         # Detail view
+ *   npx pathway behaviour --validate   # Validation checks
+ */
+
+import { createEntityCommand } from "./command-factory.js";
+import { behaviourToMarkdown } from "../formatters/behaviour/markdown.js";
+import { formatTable } from "../lib/cli-output.js";
+
+/**
+ * Format behaviour summary output
+ * @param {Array} behaviours - Raw behaviour entities
+ * @param {Object} data - Full data context
+ */
+function formatSummary(behaviours, data) {
+  const { drivers } = data;
+
+  console.log(`\n🧠 Behaviours\n`);
+
+  // Summary table
+  const rows = behaviours.map((b) => {
+    const linkedDrivers = drivers.filter((d) =>
+      d.contributingBehaviours?.includes(b.id),
+    ).length;
+    return [b.id, b.name, linkedDrivers];
+  });
+
+  console.log(formatTable(["ID", "Name", "Drivers"], rows));
+  console.log(`\nTotal: ${behaviours.length} behaviours`);
+  console.log(`\nRun 'npx pathway behaviour --list' for IDs`);
+  console.log(`Run 'npx pathway behaviour <id>' for details\n`);
+}
+
+/**
+ * Format behaviour detail output
+ * @param {Object} viewAndContext - Contains behaviour entity and context
+ */
+function formatDetail(viewAndContext) {
+  const { behaviour, drivers } = viewAndContext;
+  console.log(behaviourToMarkdown(behaviour, { drivers }));
+}
+
+export const runBehaviourCommand = createEntityCommand({
+  entityName: "behaviour",
+  pluralName: "behaviours",
+  findEntity: (data, id) => data.behaviours.find((b) => b.id === id),
+  presentDetail: (entity, data) => ({
+    behaviour: entity,
+    drivers: data.drivers,
+  }),
+  formatSummary,
+  formatDetail,
+  emoji: "🧠",
+});

package/app/commands/command-factory.js

@@ -0,0 +1,211 @@
+/**
+ * Command Factory
+ *
+ * Provides factory functions to create CLI commands with standard behavior.
+ * Reduces boilerplate and ensures consistency across commands.
+ *
+ * All entity commands support three modes:
+ * - Base (no args): Concise summary with stats
+ * - --list: Clean newline-separated list of IDs (for piping)
+ * - <id>: Detailed entity view
+ * - --validate: Run data validation checks
+ */
+
+import { capitalize } from "../formatters/shared.js";
+
+/**
+ * Create an entity command with standard behavior
+ * @param {Object} config - Command configuration
+ * @param {string} config.entityName - Entity name (singular, e.g., 'skill')
+ * @param {string} config.pluralName - Entity name (plural, e.g., 'skills')
+ * @param {Function} config.findEntity - Function to find entity by ID: (data, id) => entity
+ * @param {Function} config.presentDetail - Function to present detail: (entity, data, options) => view
+ * @param {Function} config.formatSummary - Function to format summary output: (items, data) => void
+ * @param {Function} config.formatDetail - Function to format detail output: (view, framework) => void
+ * @param {Function} [config.sortItems] - Optional function to sort items: (items) => sortedItems
+ * @param {Function} [config.validate] - Optional validation function: (data) => {errors: [], warnings: []}
+ * @param {string} [config.emoji] - Optional emoji for the entity
+ * @returns {Function} Command handler
+ */
+export function createEntityCommand({
+  entityName,
+  pluralName,
+  findEntity,
+  presentDetail,
+  formatSummary,
+  formatDetail,
+  sortItems,
+  validate,
+  _emoji = "",
+}) {
+  return async function runCommand({ data, args, options }) {
+    const [id] = args;
+    const rawItems = data[pluralName];
+    const items = sortItems ? sortItems(rawItems) : rawItems;
+
+    // --validate: Run validation checks
+    if (options.validate) {
+      return handleValidate({ data, entityName, pluralName, validate });
+    }
+
+    // --list: Output clean newline-separated IDs for piping
+    if (options.list) {
+      for (const item of items) {
+        console.log(item.id);
+      }
+      return;
+    }
+
+    // No args: Show summary
+    if (!id) {
+      if (options.json) {
+        console.log(JSON.stringify(items, null, 2));
+        return;
+      }
+      formatSummary(items, data);
+      return;
+    }
+
+    // With ID: Show detail
+    return handleDetail({
+      data,
+      id,
+      options,
+      entityName,
+      pluralName,
+      findEntity,
+      presentDetail,
+      formatDetail,
+    });
+  };
+}
+
+/**
+ * Handle validation for an entity type
+ * @param {Object} params
+ */
+function handleValidate({ data, _entityName, pluralName, validate }) {
+  if (!validate) {
+    console.log(`No specific validation for ${pluralName}.`);
+    console.log(`Run 'npx pathway --validate' for full data validation.`);
+    return;
+  }
+
+  const result = validate(data);
+  const { errors = [], warnings = [] } = result;
+
+  if (errors.length === 0 && warnings.length === 0) {
+    console.log(`✅ ${capitalize(pluralName)} validation passed`);
+    return;
+  }
+
+  if (warnings.length > 0) {
+    console.log(`⚠️  Warnings:`);
+    for (const w of warnings) {
+      console.log(`  - ${w}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    console.log(`❌ Errors:`);
+    for (const e of errors) {
+      console.log(`  - ${e}`);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Handle detail view for an entity
+ * @param {Object} params
+ */
+function handleDetail({
+  data,
+  id,
+  options,
+  entityName,
+  pluralName,
+  findEntity,
+  presentDetail,
+  formatDetail,
+}) {
+  const entity = findEntity(data, id);
+
+  if (!entity) {
+    console.error(`${capitalize(entityName)} not found: ${id}`);
+    console.error(`Available: ${data[pluralName].map((e) => e.id).join(", ")}`);
+    process.exit(1);
+  }
+
+  const view = presentDetail(entity, data, options);
+
+  if (!view) {
+    console.error(`Failed to present ${entityName}: ${id}`);
+    process.exit(1);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(view, null, 2));
+    return;
+  }
+
+  formatDetail(view, data.framework);
+}
+
+/**
+ * Create a composite command for multi-entity operations (job, interview, progress)
+ * @param {Object} config - Command configuration
+ * @param {string} config.commandName - Command name for error messages
+ * @param {string[]} config.requiredArgs - Array of required argument names
+ * @param {Function} config.findEntities - Function to find entities: (data, args) => entities object
+ * @param {Function} config.validateEntities - Function to validate entities: (entities, data) => error string | null
+ * @param {Function} config.presenter - Function to present data: (entities, data, options) => view
+ * @param {Function} config.formatter - Function to format output: (view, options, data) => void
+ * @param {string} [config.usageExample] - Optional usage example
+ * @returns {Function} Command handler
+ */
+export function createCompositeCommand({
+  commandName,
+  requiredArgs,
+  findEntities,
+  validateEntities,
+  presenter,
+  formatter,
+  usageExample,
+}) {
+  return async function runCommand({ data, args, options }) {
+    if (args.length < requiredArgs.length) {
+      const argsList = requiredArgs.map((arg) => `<${arg}>`).join(" ");
+      console.error(`Usage: npx pathway ${commandName} ${argsList}`);
+      if (usageExample) {
+        console.error(`Example: ${usageExample}`);
+      }
+      process.exit(1);
+    }
+
+    const entities = findEntities(data, args, options);
+    const validationError = validateEntities(entities, data);
+
+    if (validationError) {
+      console.error(validationError);
+      process.exit(1);
+    }
+
+    const view = presenter(entities, data, options);
+
+    if (!view) {
+      console.error(`Failed to generate ${commandName} output.`);
+      process.exit(1);
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify(view, null, 2));
+      return;
+    }
+
+    formatter(view, options, data);
+  };
+}
+
+// Legacy alias for backward compatibility during refactor
+export const createListDetailCommand = createEntityCommand;