@forwardimpact/pathway 0.1.0 → 0.2.0

package/app/commands/agent.js

@@ -8,20 +8,21 @@
  * 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 <discipline> [--track=<track>] [--output=PATH] [--preview]
+ *   npx pathway agent <discipline> --track=<track> --stage=plan
+ *   npx pathway agent <discipline> --track=<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
+ *   npx pathway agent software_engineering --track=platform
+ *   npx pathway agent software_engineering --track=platform --stage=plan
+ *   npx pathway agent software_engineering --track=platform --preview
  */
 
 import { writeFile, mkdir, readFile } from "fs/promises";
 import { join, dirname } from "path";
 import { existsSync } from "fs";
+import { stringify as stringifyYaml } from "yaml";
 import { loadAgentData, loadSkillsWithAgentData } from "../model/loader.js";
 import {
   generateStageAgentProfile,
@@ -37,6 +38,10 @@ import {
 } from "../formatters/agent/profile.js";
 import { formatAgentSkill } from "../formatters/agent/skill.js";
 import { formatError, formatSuccess } from "../lib/cli-output.js";
+import {
+  loadAgentTemplate,
+  loadSkillTemplate,
+} from "../lib/template-loader.js";
 
 /**
  * Ensure directory exists for a file path
@@ -72,6 +77,64 @@ async function generateVSCodeSettings(baseDir, vscodeSettings) {
   console.log(formatSuccess(`Updated: ${settingsPath}`));
 }
 
+/**
+ * Generate devcontainer.json from template with VS Code settings embedded
+ * @param {string} baseDir - Base output directory
+ * @param {Object} devcontainerConfig - Devcontainer config loaded from data
+ * @param {Object} vscodeSettings - VS Code settings to embed in customizations
+ */
+async function generateDevcontainer(
+  baseDir,
+  devcontainerConfig,
+  vscodeSettings,
+) {
+  if (!devcontainerConfig || Object.keys(devcontainerConfig).length === 0) {
+    return;
+  }
+
+  const devcontainerPath = join(baseDir, ".devcontainer", "devcontainer.json");
+
+  // Build devcontainer.json with VS Code settings embedded
+  const devcontainer = {
+    ...devcontainerConfig,
+    customizations: {
+      vscode: {
+        settings: vscodeSettings,
+      },
+    },
+  };
+
+  await ensureDir(devcontainerPath);
+  await writeFile(
+    devcontainerPath,
+    JSON.stringify(devcontainer, null, 2) + "\n",
+    "utf-8",
+  );
+  console.log(formatSuccess(`Created: ${devcontainerPath}`));
+}
+
+/**
+ * Generate GitHub Actions workflow for Copilot Coding Agent setup steps
+ * @param {string} baseDir - Base output directory
+ * @param {Object|null} copilotSetupSteps - Workflow config loaded from data
+ */
+async function generateCopilotSetupSteps(baseDir, copilotSetupSteps) {
+  if (!copilotSetupSteps) {
+    return;
+  }
+
+  const workflowPath = join(
+    baseDir,
+    ".github",
+    "workflows",
+    "copilot-setup-steps.yml",
+  );
+
+  await ensureDir(workflowPath);
+  await writeFile(workflowPath, stringifyYaml(copilotSetupSteps), "utf-8");
+  console.log(formatSuccess(`Created: ${workflowPath}`));
+}
+
 /**
  * Show agent summary with stats
  * @param {Object} data - Pathway data
@@ -181,10 +244,11 @@ function listAgentCombinations(data, agentData, verbose = false) {
  * Write agent profile to file
  * @param {Object} profile - Generated profile
  * @param {string} baseDir - Base output directory
+ * @param {string} template - Mustache template for agent profile
  */
-async function writeProfile(profile, baseDir) {
+async function writeProfile(profile, baseDir, template) {
   const profilePath = join(baseDir, ".github", "agents", profile.filename);
-  const profileContent = formatAgentProfile(profile);
+  const profileContent = formatAgentProfile(profile, template);
   await ensureDir(profilePath);
   await writeFile(profilePath, profileContent, "utf-8");
   console.log(formatSuccess(`Created: ${profilePath}`));
@@ -195,8 +259,9 @@ async function writeProfile(profile, baseDir) {
  * Write skill files
  * @param {Array} skills - Generated skills
  * @param {string} baseDir - Base output directory
+ * @param {string} template - Mustache template for skills
  */
-async function writeSkills(skills, baseDir) {
+async function writeSkills(skills, baseDir, template) {
   for (const skill of skills) {
     const skillPath = join(
       baseDir,
@@ -205,7 +270,7 @@ async function writeSkills(skills, baseDir) {
       skill.dirname,
       "SKILL.md",
     );
-    const skillContent = formatAgentSkill(skill);
+    const skillContent = formatAgentSkill(skill, template);
     await ensureDir(skillPath);
     await writeFile(skillPath, skillContent, "utf-8");
     console.log(formatSuccess(`Created: ${skillPath}`));
@@ -216,7 +281,7 @@ async function writeSkills(skills, baseDir) {
  * 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 {string[]} params.args - Command arguments [discipline_id]
  * @param {Object} params.options - Command options
  * @param {string} params.dataDir - Path to data directory
  */
@@ -237,11 +302,14 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
     return;
   }
 
-  const [disciplineId, trackId] = args;
+  const [disciplineId] = args;
+  const trackId = options.track;
 
-  if (!disciplineId || !trackId) {
+  if (!disciplineId) {
     console.error(
-      formatError("Usage: npx pathway agent <discipline_id> <track_id>"),
+      formatError(
+        "Usage: npx pathway agent <discipline_id> [--track=<track_id>]",
+      ),
     );
     console.error(
       "\nRun 'npx pathway agent --list' to see available combinations.",
@@ -251,7 +319,7 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
 
   // Look up human definitions
   const humanDiscipline = data.disciplines.find((d) => d.id === disciplineId);
-  const humanTrack = data.tracks.find((t) => t.id === trackId);
+  const humanTrack = trackId ? data.tracks.find((t) => t.id === trackId) : null;
 
   if (!humanDiscipline) {
     console.error(formatError(`Unknown discipline: ${disciplineId}`));
@@ -262,7 +330,7 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
     process.exit(1);
   }
 
-  if (!humanTrack) {
+  if (trackId && !humanTrack) {
     console.error(formatError(`Unknown track: ${trackId}`));
     console.error("\nAvailable tracks:");
     for (const t of data.tracks) {
@@ -275,7 +343,9 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
   const agentDiscipline = agentData.disciplines.find(
     (d) => d.id === disciplineId,
   );
-  const agentTrack = agentData.tracks.find((t) => t.id === trackId);
+  const agentTrack = trackId
+    ? agentData.tracks.find((t) => t.id === trackId)
+    : null;
 
   if (!agentDiscipline) {
     console.error(
@@ -288,7 +358,7 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
     process.exit(1);
   }
 
-  if (!agentTrack) {
+  if (trackId && !agentTrack) {
     console.error(formatError(`No agent definition for track: ${trackId}`));
     console.error("\nAgent definitions exist for:");
     for (const t of agentData.tracks) {
@@ -346,8 +416,16 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
       return;
     }
 
-    await writeProfile(profile, baseDir);
+    // Load templates only when writing files
+    const agentTemplate = await loadAgentTemplate(dataDir);
+    await writeProfile(profile, baseDir, agentTemplate);
     await generateVSCodeSettings(baseDir, agentData.vscodeSettings);
+    await generateDevcontainer(
+      baseDir,
+      agentData.devcontainer,
+      agentData.vscodeSettings,
+    );
+    await generateCopilotSetupSteps(baseDir, agentData.copilotSetupSteps);
     console.log("");
     console.log(
       formatSuccess(`Generated stage agent: ${profile.frontmatter.name}`),
@@ -415,11 +493,21 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
     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);
+    await writeProfile(profile, baseDir, agentTemplate);
   }
-  await writeSkills(skillFiles, baseDir);
+  await writeSkills(skillFiles, baseDir, skillTemplate);
   await generateVSCodeSettings(baseDir, agentData.vscodeSettings);
+  await generateDevcontainer(
+    baseDir,
+    agentData.devcontainer,
+    agentData.vscodeSettings,
+  );
+  await generateCopilotSetupSteps(baseDir, agentData.copilotSetupSteps);
 
   console.log("");
   console.log(formatSuccess(`Generated ${profiles.length} agents:`));

package/app/commands/command-factory.js

@@ -157,8 +157,8 @@ function handleDetail({
  * @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.findEntities - Function to find entities: (data, args, options) => entities object
+ * @param {Function} config.validateEntities - Function to validate entities: (entities, data, options) => 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
@@ -184,7 +184,7 @@ export function createCompositeCommand({
     }
 
     const entities = findEntities(data, args, options);
-    const validationError = validateEntities(entities, data);
+    const validationError = validateEntities(entities, data, options);
 
     if (validationError) {
       console.error(validationError);

package/app/commands/interview.js

@@ -2,6 +2,11 @@
  * Interview CLI Command
  *
  * Generates and displays interview questions in the terminal.
+ *
+ * Usage:
+ *   npx pathway interview <discipline> <grade>                    # Interview for trackless job
+ *   npx pathway interview <discipline> <grade> --track=<track>    # Interview with track
+ *   npx pathway interview <discipline> <grade> --track=<track> --type=short
  */
 
 import { createCompositeCommand } from "./command-factory.js";
@@ -22,7 +27,7 @@ function formatInterview(view, options) {
 
 export const runInterviewCommand = createCompositeCommand({
   commandName: "interview",
-  requiredArgs: ["discipline_id", "track_id", "grade_id"],
+  requiredArgs: ["discipline_id", "grade_id"],
   findEntities: (data, args, options) => {
     const interviewType = options.type || "full";
 
@@ -34,20 +39,22 @@ export const runInterviewCommand = createCompositeCommand({
 
     return {
       discipline: data.disciplines.find((d) => d.id === args[0]),
-      track: data.tracks.find((t) => t.id === args[1]),
-      grade: data.grades.find((g) => g.id === args[2]),
+      grade: data.grades.find((g) => g.id === args[1]),
+      track: options.track
+        ? data.tracks.find((t) => t.id === options.track)
+        : null,
       interviewType,
     };
   },
-  validateEntities: (entities, _data) => {
+  validateEntities: (entities, _data, options) => {
     if (!entities.discipline) {
       return `Discipline not found: ${entities.discipline}`;
     }
     if (!entities.grade) {
       return `Grade not found: ${entities.grade}`;
     }
-    if (!entities.track) {
-      return `Track not found: ${entities.track}`;
+    if (options.track && !entities.track) {
+      return `Track not found: ${options.track}`;
     }
     return null;
   },
@@ -64,5 +71,5 @@ export const runInterviewCommand = createCompositeCommand({
   formatter: (view, options, data) =>
     formatInterview(view, { ...options, framework: data.framework }),
   usageExample:
-    "npx pathway interview software_engineering platform L4 --type=short",
+    "npx pathway interview software_engineering L4 --track=platform --type=short",
 });

package/app/commands/job.js

@@ -4,11 +4,12 @@
  * Generates and displays job definitions in the terminal.
  *
  * Usage:
- *   npx pathway job                              # Summary with stats
- *   npx pathway job --list                       # All valid combinations (for piping)
- *   npx pathway job <discipline> <track> <grade> # Detail view
- *   npx pathway job se platform L3 --checklist=code_to_review # Show checklist for handoff
- *   npx pathway job --validate                   # Validation checks
+ *   npx pathway job                                          # Summary with stats
+ *   npx pathway job --list                                   # All valid combinations (for piping)
+ *   npx pathway job <discipline> <grade>                     # Detail view (trackless)
+ *   npx pathway job <discipline> <grade> --track=<track>     # Detail view (with track)
+ *   npx pathway job se L3 --track=platform --checklist=code  # Show checklist for handoff
+ *   npx pathway job --validate                               # Validation checks
  */
 
 import { prepareJobDetail } from "../model/job.js";
@@ -47,10 +48,14 @@ export async function runJobCommand({ data, args, options }) {
     validationRules: data.framework.validationRules,
   });
 
-  // --list: Output clean lines for piping
+  // --list: Output clean lines for piping (discipline grade track format)
   if (options.list) {
     for (const job of jobs) {
-      console.log(`${job.discipline.id} ${job.track.id} ${job.grade.id}`);
+      if (job.track) {
+        console.log(`${job.discipline.id} ${job.grade.id} ${job.track.id}`);
+      } else {
+        console.log(`${job.discipline.id} ${job.grade.id}`);
+      }
     }
     return;
   }
@@ -71,22 +76,29 @@ export async function runJobCommand({ data, args, options }) {
     console.log(`\nTotal: ${jobs.length} valid job combinations`);
     console.log(`\nRun 'npx pathway job --list' for all combinations`);
     console.log(
-      `Run 'npx pathway job <discipline> <track> <grade>' for details\n`,
+      `Run 'npx pathway job <discipline> <grade> [--track=<track>]' for details\n`,
     );
     return;
   }
 
-  // Handle job detail view
-  if (args.length < 3) {
-    console.error("Usage: npx pathway job <discipline> <track> <grade>");
+  // Handle job detail view - requires discipline and grade
+  if (args.length < 2) {
+    console.error(
+      "Usage: npx pathway job <discipline> <grade> [--track=<track>]",
+    );
     console.error("       npx pathway job --list");
-    console.error("Example: npx pathway job software_engineering platform L4");
+    console.error("Example: npx pathway job software_engineering L4");
+    console.error(
+      "Example: npx pathway job software_engineering L4 --track=platform",
+    );
     process.exit(1);
   }
 
   const discipline = data.disciplines.find((d) => d.id === args[0]);
-  const track = data.tracks.find((t) => t.id === args[1]);
-  const grade = data.grades.find((g) => g.id === args[2]);
+  const grade = data.grades.find((g) => g.id === args[1]);
+  const track = options.track
+    ? data.tracks.find((t) => t.id === options.track)
+    : null;
 
   if (!discipline) {
     console.error(`Discipline not found: ${args[0]}`);
@@ -94,15 +106,15 @@ export async function runJobCommand({ data, args, options }) {
     process.exit(1);
   }
 
-  if (!track) {
-    console.error(`Track not found: ${args[1]}`);
-    console.error(`Available: ${data.tracks.map((t) => t.id).join(", ")}`);
+  if (!grade) {
+    console.error(`Grade not found: ${args[1]}`);
+    console.error(`Available: ${data.grades.map((g) => g.id).join(", ")}`);
     process.exit(1);
   }
 
-  if (!grade) {
-    console.error(`Grade not found: ${args[2]}`);
-    console.error(`Available: ${data.grades.map((g) => g.id).join(", ")}`);
+  if (options.track && !track) {
+    console.error(`Track not found: ${options.track}`);
+    console.error(`Available: ${data.tracks.map((t) => t.id).join(", ")}`);
     process.exit(1);
   }
 
@@ -126,28 +138,30 @@ export async function runJobCommand({ data, args, options }) {
     return;
   }
 
-  // --checklist: Show checklist for a specific handoff
+  // --checklist: Show checklist for a specific stage
   if (options.checklist) {
-    const validHandoffs = ["plan_to_code", "code_to_review"];
-    if (!validHandoffs.includes(options.checklist)) {
-      console.error(`Invalid handoff: ${options.checklist}`);
-      console.error(`Available: ${validHandoffs.join(", ")}`);
+    const validStages = ["plan", "code"];
+    if (!validStages.includes(options.checklist)) {
+      console.error(`Invalid stage: ${options.checklist}`);
+      console.error(`Available: ${validStages.join(", ")}`);
       process.exit(1);
     }
 
     const checklist = deriveChecklist({
-      handoff: options.checklist,
+      stageId: options.checklist,
       skillMatrix: view.skillMatrix,
+      skills: data.skills,
       capabilities: data.capabilities,
     });
 
     if (checklist.length === 0) {
-      console.log(`\nNo checklist items for ${options.checklist}\n`);
+      console.log(`\nNo checklist items for ${options.checklist} stage\n`);
       return;
     }
 
-    const handoffLabel = options.checklist.replace(/_/g, " → ");
-    console.log(`\n# ${view.title} — ${handoffLabel}\n`);
+    const stageLabel =
+      options.checklist.charAt(0).toUpperCase() + options.checklist.slice(1);
+    console.log(`\n# ${view.title} — ${stageLabel} Stage Checklist\n`);
     console.log(formatChecklistMarkdown(checklist));
     console.log("");
     return;

package/app/commands/progress.js

@@ -2,6 +2,11 @@
  * Progress CLI Command
  *
  * Shows career progression analysis in the terminal.
+ *
+ * Usage:
+ *   npx pathway progress <discipline> <grade>                            # Progress for trackless job
+ *   npx pathway progress <discipline> <grade> --track=<track>            # Progress with track
+ *   npx pathway progress <discipline> <from_grade> --compare=<to_grade>  # Compare grades
  */
 
 import { createCompositeCommand } from "./command-factory.js";
@@ -21,11 +26,13 @@ function formatProgress(view) {
 
 export const runProgressCommand = createCompositeCommand({
   commandName: "progress",
-  requiredArgs: ["discipline_id", "track_id", "grade_id"],
+  requiredArgs: ["discipline_id", "grade_id"],
   findEntities: (data, args, options) => {
     const discipline = data.disciplines.find((d) => d.id === args[0]);
-    const track = data.tracks.find((t) => t.id === args[1]);
-    const grade = data.grades.find((g) => g.id === args[2]);
+    const grade = data.grades.find((g) => g.id === args[1]);
+    const track = options.track
+      ? data.tracks.find((t) => t.id === options.track)
+      : null;
 
     let targetGrade;
     if (options.compare) {
@@ -44,15 +51,15 @@ export const runProgressCommand = createCompositeCommand({
 
     return { discipline, grade, track, targetGrade };
   },
-  validateEntities: (entities, _data) => {
+  validateEntities: (entities, _data, options) => {
     if (!entities.discipline) {
       return `Discipline not found`;
     }
     if (!entities.grade) {
       return `Grade not found`;
     }
-    if (!entities.track) {
-      return `Track not found`;
+    if (options.track && !entities.track) {
+      return `Track not found: ${options.track}`;
     }
     if (!entities.targetGrade) {
       return `Target grade not found`;
@@ -73,5 +80,5 @@ export const runProgressCommand = createCompositeCommand({
     }),
   formatter: formatProgress,
   usageExample:
-    "npx pathway progress software_engineering platform L3 --compare=L4",
+    "npx pathway progress software_engineering L3 --track=platform --compare=L4",
 });

package/app/commands/serve.js

@@ -15,6 +15,7 @@ import { loadFrameworkConfig } from "../model/loader.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const publicDir = join(__dirname, "..");
+const rootDir = join(__dirname, "../..");
 
 const MIME_TYPES = {
   ".html": "text/html; charset=utf-8",
@@ -23,6 +24,7 @@ const MIME_TYPES = {
   ".yaml": "text/yaml; charset=utf-8",
   ".yml": "text/yaml; charset=utf-8",
   ".json": "application/json; charset=utf-8",
+  ".md": "text/markdown; charset=utf-8",
   ".svg": "image/svg+xml",
   ".png": "image/png",
   ".ico": "image/x-icon",
@@ -113,6 +115,9 @@ export async function runServeCommand({ dataDir, options }) {
     if (pathname.startsWith("/data/")) {
       // Serve from user's data directory
       filePath = join(dataDir, pathname.slice(6));
+    } else if (pathname.startsWith("/templates/")) {
+      // Serve from templates directory
+      filePath = join(rootDir, pathname);
     } else if (pathname === "/" || pathname === "") {
       // Serve index.html for root
       filePath = join(publicDir, "index.html");

package/app/commands/stage.js

@@ -58,18 +58,8 @@ function formatDetail(viewAndContext, _framework) {
   const emoji = getStageEmoji(stages, stage.id);
 
   console.log(formatHeader(`\n${emoji} ${view.name}\n`));
-  console.log(`Mode: ${view.modeBadge}\n`);
   console.log(`${view.description}\n`);
 
-  // Tools
-  if (view.tools.length > 0) {
-    console.log(formatSubheader("Tools\n"));
-    for (const tool of view.tools) {
-      console.log(formatBullet(`${tool.icon} ${tool.label}`, 1));
-    }
-    console.log();
-  }
-
   // Entry criteria
   if (view.entryCriteria.length > 0) {
     console.log(formatSubheader("Entry Criteria\n"));

package/app/commands/track.js

@@ -12,13 +12,13 @@
 
 import { createEntityCommand } from "./command-factory.js";
 import { trackToMarkdown } from "../formatters/track/markdown.js";
-import { sortTracksByType } from "../formatters/track/shared.js";
+import { sortTracksByName } from "../formatters/track/shared.js";
 import { formatTable } from "../lib/cli-output.js";
 import { getConceptEmoji } from "../model/levels.js";
 
 /**
  * Format track summary output
- * @param {Array} tracks - Raw track entities (already sorted by type)
+ * @param {Array} tracks - Raw track entities
  * @param {Object} data - Full data context
  */
 function formatSummary(tracks, data) {
@@ -28,14 +28,11 @@ function formatSummary(tracks, data) {
   console.log(`\n${emoji} Tracks\n`);
 
   const rows = tracks.map((t) => {
-    const types = [];
-    if (t.isProfessional) types.push("P");
-    if (t.isManagement) types.push("M");
     const modCount = Object.keys(t.skillModifiers || {}).length;
-    return [t.id, t.name, types.join("/") || "-", modCount];
+    return [t.id, t.name, modCount];
   });
 
-  console.log(formatTable(["ID", "Name", "Type", "Modifiers"], rows));
+  console.log(formatTable(["ID", "Name", "Modifiers"], rows));
   console.log(`\nTotal: ${tracks.length} tracks`);
   console.log(`\nRun 'npx pathway track --list' for IDs`);
   console.log(`Run 'npx pathway track <id>' for details\n`);
@@ -63,7 +60,7 @@ export const runTrackCommand = createEntityCommand({
     behaviours: data.behaviours,
     disciplines: data.disciplines,
   }),
-  sortItems: sortTracksByType,
+  sortItems: sortTracksByName,
   formatSummary,
   formatDetail,
   emoji: "🛤️",