@forwardimpact/pathway 0.5.0 → 0.7.0

package/README.md

@@ -1,104 +1,67 @@
-# Engineering Pathway
+# @forwardimpact/pathway
 
-A unified framework for human and AI collaboration in engineering. Define roles,
-track skills and behaviours, build career paths, and generate AI coding
-agents—all from the same coherent foundation.
+Career progression web app and CLI for exploring roles and generating agents.
 
-## Quick Start
-
-### Install as a Package
-
-```sh
-# Create a new project
-mkdir my-org-pathway && cd my-org-pathway
-npm init -y
-npm install @forwardimpact/pathway
+## Role in the Vision
 
-# Initialize with example data
-npx pathway init
+Pathway is the primary interface for interacting with engineering competency
+data. It provides tools for browsing career paths, generating job descriptions,
+creating AI agent profiles, and preparing interviews—all from a unified web
+experience and command line.
 
-# Validate data
-npx pathway --validate
+## What It Does
 
-# Start web app
-npx pathway serve
-```
+- **Web application** — Interactive browser for jobs, skills, and career paths
+- **CLI tools** — Command-line access to all functionality
+- **Agent generation** — Create VS Code Custom Agent profiles (`.agent.md`)
+- **Skill generation** — Generate Agent Skills files (`SKILL.md`)
+- **Interview prep** — Build interview question sets by role
+- **Static site** — Export everything as a static site
 
-Open http://localhost:3000 to explore jobs, skills, and behaviours.
+## Quick Start
 
-### For Development
+```sh
+# Start the web app
+npx fit-pathway serve
 
-Clone the repository and run locally:
+# Browse entities
+npx fit-pathway skill --list
+npx fit-pathway job software_engineering senior --track=platform
 
-```sh
-git clone https://github.com/forwardimpact/pathway.git
-cd pathway
-npm install
-npm start
+# Generate agent profiles
+npx fit-pathway agent software_engineering --track=platform --output=./.github/agents
 ```
 
-## Customization
+## CLI Commands
 
-Edit files in `./data/` to match your organization:
+| Command     | Description                  |
+| ----------- | ---------------------------- |
+| `serve`     | Start web server             |
+| `site`      | Generate static site         |
+| `init`      | Create data directory        |
+| `skill`     | Browse skills                |
+| `behaviour` | Browse behaviours            |
+| `job`       | Generate job definitions     |
+| `agent`     | Generate agent profiles      |
+| `interview` | Generate interview questions |
+| `progress`  | Analyze career progression   |
+| `questions` | Browse interview questions   |
 
-- `grades.yaml` — Career levels
-- `disciplines/*.yaml` — Engineering disciplines
-- `tracks/*.yaml` — Role tracks (platform, frontend, etc.)
-- `skills/*.yaml` — Technical skills with level descriptions
-- `behaviours/*.yaml` — Behavioural expectations
+Use `--help` with any command for full options.
 
-## CLI Reference
+## Web App Features
 
-```sh
-# Getting started
-npx pathway init                      # Create ./data/ with examples
-npx pathway serve --port=8080         # Serve web app
-
-# Browse data
-npx pathway skill                     # Summary of all skills
-npx pathway skill --list              # Skill IDs for piping
-npx pathway job software_engineering platform senior
-
-# Generate outputs
-npx pathway interview software_engineering platform L4
-npx pathway agent software_engineering platform --output=./.github/agents
-
-# Validation
-npx pathway --validate                # Validate all data files
-npx pathway --help                    # Full command reference
-```
+- **Job Builder** — Select discipline, track, and grade to explore roles
+- **Skill Browser** — View all skills with level descriptions
+- **Career Progression** — Compare grades and identify growth areas
+- **Interview Prep** — Generate role-specific question sets
+- **Agent Preview** — Preview generated agent profiles
 
-## API Usage
+## Package Exports
 
 ```javascript
-import { loadAllData } from "@forwardimpact/pathway";
-import { deriveJob } from "@forwardimpact/pathway/derivation";
-
-const data = await loadAllData("./data");
-const job = deriveJob({
-  discipline: data.disciplines[0],
-  track: data.tracks[0],
-  grade: data.grades[0],
-  skills: data.skills,
-  behaviours: data.behaviours,
-});
+import { formatSkillForMarkdown } from "@forwardimpact/pathway/formatters";
+import { runCommand } from "@forwardimpact/pathway/commands";
 ```
 
-## Documentation
-
-1. [Overview](docs/index.md) — Overview of all topics
-2. [Core Model](docs/model.md) — Disciplines, Tracks, Grades, Skills,
-   Behaviours, Capabilities, Drivers, and Job Derivation
-3. [Lifecycle](docs/lifecycle.md) — Stages, handoffs, and checklists (applies to
-   both humans and agents)
-4. [Agents](docs/agents.md) — Agent profile derivation, SKILL.md format, and VS
-   Code integration
-5. [Reference](docs/reference.md) — File organization, templates, and CLI usage
-
-## Development
-
-```sh
-npm run check      # Format, lint, and test
-npm run validate   # Validate YAML data files
-npm run test:e2e   # Run end-to-end tests
-```
+See the [documentation](../../docs/pathway/index.md) for usage details.

package/bin/{pathway.js → fit-pathway.js}

@@ -6,7 +6,7 @@
  * interview questions, career progression analysis, and AI agent configurations.
  *
  * Usage:
- *   npx pathway <command> [options]
+ *   npx fit-pathway <command> [options]
  *
  * Commands:
  *   discipline [<id>]           Show disciplines
@@ -25,40 +25,36 @@
  *
  * Global Options:
  *   --list         Output IDs only (for piping)
- *   --validate     Run validation checks
  *   --json         Output as JSON
  *   --help         Show help
+ *
+ * Validation (moved to fit-schema):
+ *   npx fit-schema validate
+ *   npx fit-schema generate-index
  */
 
-import { fileURLToPath } from "url";
-import { dirname, join, resolve } from "path";
+import { join, resolve } from "path";
 import { existsSync } from "fs";
-import { loadAllData } from "../app/model/loader.js";
-import { generateAllIndexes } from "../app/model/index-generator.js";
-import { formatError } from "../app/lib/cli-output.js";
-import { runSchemaValidation } from "../app/model/schema-validation.js";
+import { loadAllData } from "@forwardimpact/schema/loader";
+import { formatError } from "../src/lib/cli-output.js";
 
 // Import command handlers
-import { runDisciplineCommand } from "../app/commands/discipline.js";
-import { runGradeCommand } from "../app/commands/grade.js";
-import { runTrackCommand } from "../app/commands/track.js";
-import { runBehaviourCommand } from "../app/commands/behaviour.js";
-import { runSkillCommand } from "../app/commands/skill.js";
-import { runDriverCommand } from "../app/commands/driver.js";
-import { runStageCommand } from "../app/commands/stage.js";
-import { runToolCommand } from "../app/commands/tool.js";
-import { runJobCommand } from "../app/commands/job.js";
-import { runInterviewCommand } from "../app/commands/interview.js";
-import { runProgressCommand } from "../app/commands/progress.js";
-import { runQuestionsCommand } from "../app/commands/questions.js";
-import { runAgentCommand } from "../app/commands/agent.js";
-import { runServeCommand } from "../app/commands/serve.js";
-import { runInitCommand } from "../app/commands/init.js";
-import { runSiteCommand } from "../app/commands/site.js";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const rootDir = join(__dirname, "..");
+import { runDisciplineCommand } from "../src/commands/discipline.js";
+import { runGradeCommand } from "../src/commands/grade.js";
+import { runTrackCommand } from "../src/commands/track.js";
+import { runBehaviourCommand } from "../src/commands/behaviour.js";
+import { runSkillCommand } from "../src/commands/skill.js";
+import { runDriverCommand } from "../src/commands/driver.js";
+import { runStageCommand } from "../src/commands/stage.js";
+import { runToolCommand } from "../src/commands/tool.js";
+import { runJobCommand } from "../src/commands/job.js";
+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 { runInitCommand } from "../src/commands/init.js";
+import { runSiteCommand } from "../src/commands/site.js";
 
 const COMMANDS = {
   discipline: runDisciplineCommand,
@@ -80,9 +76,11 @@ const HELP_TEXT = `
 Engineering Pathway CLI
 
 Usage:
-  npx pathway <command> [options]
-  npx pathway --validate              Run full data validation
-  npx pathway --generate-index        Generate browser index files
+  npx fit-pathway <command> [options]
+
+Validation (use fit-schema instead):
+  npx fit-schema validate             Run full data validation
+  npx fit-schema generate-index       Generate browser index files
 
 Getting Started:
   init                                Create ./data/ with example data
@@ -111,8 +109,6 @@ Composite Commands:
 
 Global Options:
   --list            Output IDs only (for piping to other commands)
-  --validate        Run validation checks
-  --generate-index  Generate _index.yaml files for browser loading
   --json            Output as JSON
   --data=PATH       Path to data directory (default: ./data or examples/)
   --help            Show this help message
@@ -133,26 +129,25 @@ Agent Options:
   --all-stages        Generate all stage agents (default)
 
 Examples:
-  npx pathway skill                    # Summary of all skills
-  npx pathway skill --list             # Skill IDs for piping
-  npx pathway skill ai_evaluation      # Detail view
-  npx pathway skill architecture_design --agent  # Agent SKILL.md output
-
-  npx pathway tool                     # Summary of all tools
-  npx pathway tool --list              # Tool names for piping
-  npx pathway tool DuckDB              # Tool detail with skill usages
-
-  npx pathway job                      # Summary of valid combinations
-  npx pathway job --list               # All combinations for piping
-  npx pathway job software_engineering L4
-  npx pathway job software_engineering L4 --track=platform
-  npx pathway job se L3 --track=platform --checklist=code
-
-  npx pathway questions --level=practitioner
-  npx pathway questions --stats
-
-  npx pathway agent software_engineering --track=platform --output=./agents
-  npx pathway --validate               # Validate all data
+  npx fit-pathway skill                    # Summary of all skills
+  npx fit-pathway skill --list             # Skill IDs for piping
+  npx fit-pathway skill ai_evaluation      # Detail view
+  npx fit-pathway skill architecture_design --agent  # Agent SKILL.md output
+
+  npx fit-pathway tool                     # Summary of all tools
+  npx fit-pathway tool --list              # Tool names for piping
+  npx fit-pathway tool DuckDB              # Tool detail with skill usages
+
+  npx fit-pathway job                      # Summary of valid combinations
+  npx fit-pathway job --list               # All combinations for piping
+  npx fit-pathway job software_engineering L4
+  npx fit-pathway job software_engineering L4 --track=platform
+  npx fit-pathway job se L3 --track=platform --checklist=code
+
+  npx fit-pathway questions --level=practitioner
+  npx fit-pathway questions --stats
+
+  npx fit-pathway agent software_engineering --track=platform --output=./agents
 `;
 
 /**
@@ -167,8 +162,6 @@ function parseArgs(args) {
     list: false,
     json: false,
     help: false,
-    validate: false,
-    generateIndex: false,
     type: "full",
     compare: null,
     data: null,
@@ -204,10 +197,6 @@ function parseArgs(args) {
       result.list = true;
     } else if (arg === "--json") {
       result.json = true;
-    } else if (arg === "--validate") {
-      result.validate = true;
-    } else if (arg === "--generate-index") {
-      result.generateIndex = true;
     } else if (arg.startsWith("--type=")) {
       result.type = arg.slice(7);
     } else if (arg.startsWith("--compare=")) {
@@ -269,85 +258,14 @@ function printHelp() {
   console.log(HELP_TEXT);
 }
 
-/**
- * Run full data validation using JSON schemas
- * @param {string} dataDir - Path to data directory
- */
-async function runFullValidation(dataDir) {
-  console.log(`\n🔍 Validating data in: ${dataDir}\n`);
-
-  let hasErrors = false;
-
-  // Load data for referential integrity checking (without old validation)
-  const data = await loadAllData(dataDir, {
-    validate: false,
-    throwOnError: false,
-  });
-
-  // Run schema validation + referential integrity
-  const result = await runSchemaValidation(dataDir, data);
-
-  if (result.valid) {
-    console.log("✅ Schema validation passed");
-  } else {
-    console.log("❌ Schema validation failed");
-    hasErrors = true;
-    for (const e of result.errors) {
-      console.log(
-        `  - [${e.type}] ${e.message}${e.path ? ` (${e.path})` : ""}`,
-      );
-    }
-  }
-
-  if (result.warnings.length > 0) {
-    console.log("\n⚠️  Warnings:");
-    for (const w of result.warnings) {
-      console.log(`  - [${w.type}] ${w.message}`);
-    }
-  }
-
-  // Summary
-  console.log("\n📊 Data Summary:");
-  console.log(`   Skills:      ${data.skills?.length || 0}`);
-  console.log(`   Behaviours:  ${data.behaviours?.length || 0}`);
-  console.log(`   Disciplines: ${data.disciplines?.length || 0}`);
-  console.log(`   Tracks:      ${data.tracks?.length || 0}`);
-  console.log(`   Grades:      ${data.grades?.length || 0}`);
-  console.log(`   Drivers:     ${data.drivers?.length || 0}`);
-  console.log(`   Stages:      ${data.stages?.length || 0}`);
-  console.log("");
-
-  return hasErrors ? 1 : 0;
-}
-
-/**
- * Run index generation
- * @param {string} dataDir - Path to data directory
- */
-async function runGenerateIndex(dataDir) {
-  console.log(`\n📁 Generating index files in: ${dataDir}\n`);
-
-  const results = await generateAllIndexes(dataDir);
-
-  for (const [dir, files] of Object.entries(results)) {
-    if (files.error) {
-      console.log(`❌ ${dir}: ${files.error}`);
-    } else {
-      console.log(`✅ ${dir}/_index.yaml (${files.length} files)`);
-    }
-  }
-
-  console.log("\n✨ Index generation complete\n");
-  return 0;
-}
-
 /**
  * Resolve the data directory path.
  * Resolution order:
  * 1. --data=<path> flag (explicit override)
  * 2. PATHWAY_DATA environment variable
  * 3. ./data/ relative to current working directory
- * 4. Package examples (for demo/testing)
+ * 4. ./examples/ relative to current working directory
+ * 5. apps/schema/examples/ for monorepo development
  *
  * @param {Object} options - Parsed command options
  * @returns {string} Resolved absolute path to data directory
@@ -363,16 +281,22 @@ function resolveDataPath(options) {
     return resolve(process.env.PATHWAY_DATA);
   }
 
-  // 3. Current working directory
+  // 3. Current working directory ./data/
   const cwdData = join(process.cwd(), "data");
   if (existsSync(cwdData)) {
     return cwdData;
   }
 
-  // 4. Package examples (for demo/testing)
-  const examplesData = join(rootDir, "examples");
-  if (existsSync(examplesData)) {
-    return examplesData;
+  // 4. Current working directory ./examples/
+  const cwdExamples = join(process.cwd(), "examples");
+  if (existsSync(cwdExamples)) {
+    return cwdExamples;
+  }
+
+  // 5. Monorepo: apps/schema/examples/
+  const schemaExamples = join(process.cwd(), "apps/schema/examples");
+  if (existsSync(schemaExamples)) {
+    return schemaExamples;
   }
 
   throw new Error(
@@ -392,21 +316,7 @@ async function main() {
     process.exit(0);
   }
 
-  const dataDir = resolveDataPath(options);
-
-  // Handle global --generate-index (no command)
-  if (options.generateIndex && !options.command) {
-    const exitCode = await runGenerateIndex(dataDir);
-    process.exit(exitCode);
-  }
-
-  // Handle global --validate (no command)
-  if (options.validate && !options.command) {
-    const exitCode = await runFullValidation(dataDir);
-    process.exit(exitCode);
-  }
-
-  // No command and no flags: show help
+  // No command: show help
   if (!options.command) {
     printHelp();
     process.exit(0);
@@ -420,6 +330,8 @@ async function main() {
     process.exit(0);
   }
 
+  const dataDir = resolveDataPath(options);
+
   // Handle serve command (needs data directory)
   if (command === "serve") {
     await runServeCommand({ dataDir, options });
@@ -437,7 +349,7 @@ async function main() {
 
   if (!handler) {
     console.error(formatError(`Unknown command: ${command}`));
-    console.error(`Run 'npx pathway --help' for usage.`);
+    console.error(`Run 'npx fit-pathway --help' for usage.`);
     process.exit(1);
   }
 

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@forwardimpact/pathway",
-  "version": "0.5.0",
-  "description": "Engineering Pathway framework for human and AI collaboration",
+  "version": "0.7.0",
+  "description": "Career progression web app and CLI for exploring roles and generating agents",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/forwardimpact/pathway"
+    "url": "https://github.com/forwardimpact/monorepo",
+    "directory": "apps/pathway"
   },
+  "homepage": "https://www.forwardimpact.team/pathway",
   "keywords": [
     "career",
     "competency",
@@ -18,57 +20,32 @@
     "engineering"
   ],
   "type": "module",
-  "main": "app/model/loader.js",
+  "main": "src/index.js",
   "bin": {
-    "pathway": "./bin/pathway.js"
+    "fit-pathway": "./bin/fit-pathway.js"
+  },
+  "scripts": {
+    "start": "node ./bin/fit-pathway.js serve",
+    "pathway": "node ./bin/fit-pathway.js",
+    "site": "node ./bin/fit-pathway.js site"
   },
   "files": [
     "bin/",
-    "app/",
-    "examples/",
+    "src/",
     "templates/"
   ],
   "exports": {
-    ".": "./app/model/loader.js",
-    "./derivation": "./app/model/derivation.js",
-    "./interview": "./app/model/interview.js",
-    "./levels": "./app/model/levels.js",
-    "./loader": "./app/model/loader.js",
-    "./matching": "./app/model/matching.js",
-    "./types": "./app/model/levels.js",
-    "./validation": "./app/model/validation.js"
-  },
-  "scripts": {
-    "start": "node bin/pathway.js serve",
-    "prestart": "npm run generate-index",
-    "check": "npm run format && npm run lint && npm run test && npm run validate:shacl",
-    "check:fix": "npm run format:fix && npm run lint:fix",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "format": "prettier --check .",
-    "format:fix": "prettier --write .",
-    "test": "find ./tests -name '*.test.js' | xargs node --test",
-    "test:e2e": "npx playwright test",
-    "validate": "node bin/pathway.js --validate",
-    "validate:shacl": "node scripts/validate-shacl.js",
-    "generate-index": "node bin/pathway.js --generate-index",
-    "pathway": "node bin/pathway.js",
-    "demo": "node scripts/demo.js"
+    ".": "./src/index.js",
+    "./formatters": "./src/formatters/index.js",
+    "./commands": "./src/commands/index.js"
   },
   "dependencies": {
-    "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1",
+    "@forwardimpact/schema": "^0.2.0",
+    "@forwardimpact/model": "^0.2.0",
     "mustache": "^4.2.0",
     "simple-icons": "^16.7.0",
     "yaml": "^2.3.4"
   },
-  "devDependencies": {
-    "@playwright/test": "^1.49.0",
-    "eslint": "^9.39.1",
-    "eslint-config-prettier": "^10.1.8",
-    "n3": "^2.0.1",
-    "prettier": "^3.7.4"
-  },
   "engines": {
     "node": ">=18.0.0"
   }

package/{app → src}/commands/agent.js

@@ -25,7 +25,10 @@ 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 {
+  loadAgentData,
+  loadSkillsWithAgentData,
+} from "@forwardimpact/schema/loader";
 import {
   generateStageAgentProfile,
   validateAgentProfile,
@@ -33,7 +36,7 @@ import {
   deriveReferenceGrade,
   deriveAgentSkills,
   generateSkillMd,
-} from "../model/agent.js";
+} from "@forwardimpact/model/agent";
 import { formatAgentProfile } from "../formatters/agent/profile.js";
 import { formatAgentSkill } from "../formatters/agent/skill.js";
 import { formatError, formatSuccess } from "../lib/cli-output.js";

package/{app → src}/commands/driver.js

@@ -18,7 +18,7 @@ import {
   formatSubheader,
   formatBullet,
 } from "../lib/cli-output.js";
-import { getConceptEmoji } from "../model/levels.js";
+import { getConceptEmoji } from "@forwardimpact/schema/levels";
 
 /**
  * Format driver summary output

package/{app → src}/commands/grade.js

@@ -13,7 +13,7 @@
 import { createEntityCommand } from "./command-factory.js";
 import { gradeToMarkdown } from "../formatters/grade/markdown.js";
 import { formatTable } from "../lib/cli-output.js";
-import { getConceptEmoji } from "../model/levels.js";
+import { getConceptEmoji } from "@forwardimpact/schema/levels";
 import { capitalize } from "../formatters/shared.js";
 
 /**

package/{app → src}/commands/job.js

@@ -12,14 +12,14 @@
  *   npx pathway job --validate                               # Validation checks
  */
 
-import { prepareJobDetail } from "../model/job.js";
+import { prepareJobDetail } from "@forwardimpact/model/job";
 import { jobToMarkdown } from "../formatters/job/markdown.js";
-import { generateAllJobs } from "../model/derivation.js";
+import { generateAllJobs } from "@forwardimpact/model/derivation";
 import { formatTable } from "../lib/cli-output.js";
 import {
   deriveChecklist,
   formatChecklistMarkdown,
-} from "../model/checklist.js";
+} from "@forwardimpact/model/checklist";
 import { loadJobTemplate } from "../lib/template-loader.js";
 
 /**

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

@@ -9,14 +9,30 @@ import { createServer } from "http";
 import { readFile, stat } from "fs/promises";
 import { join, extname, dirname } from "path";
 import { fileURLToPath } from "url";
-import { generateAllIndexes } from "../model/index-generator.js";
-import { loadFrameworkConfig } from "../model/loader.js";
+import { generateAllIndexes } from "@forwardimpact/schema/index-generator";
+import { loadFrameworkConfig } from "@forwardimpact/schema/loader";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const publicDir = join(__dirname, "..");
 const rootDir = join(__dirname, "../..");
 
+/**
+ * Resolve package directory using Node's module resolution.
+ * Works in both monorepo (development) and installed (production) contexts.
+ * @param {string} packageName - Package specifier (e.g., '@forwardimpact/schema')
+ * @returns {string} Absolute path to package lib directory
+ */
+function resolvePackageLib(packageName) {
+  // import.meta.resolve returns file:// URL to package's main entry (lib/index.js)
+  const mainUrl = import.meta.resolve(packageName);
+  // Convert to path and get lib directory
+  return dirname(fileURLToPath(mainUrl));
+}
+
+const schemaLibDir = resolvePackageLib("@forwardimpact/schema");
+const modelLibDir = resolvePackageLib("@forwardimpact/model");
+
 const MIME_TYPES = {
   ".html": "text/html; charset=utf-8",
   ".css": "text/css; charset=utf-8",
@@ -118,6 +134,12 @@ export async function runServeCommand({ dataDir, options }) {
     } else if (pathname.startsWith("/templates/")) {
       // Serve from templates directory
       filePath = join(rootDir, pathname);
+    } else if (pathname.startsWith("/schema/lib/")) {
+      // Serve @forwardimpact/schema package files (resolved via Node module resolution)
+      filePath = join(schemaLibDir, pathname.slice(12));
+    } else if (pathname.startsWith("/model/lib/")) {
+      // Serve @forwardimpact/model package files (resolved via Node module resolution)
+      filePath = join(modelLibDir, pathname.slice(11));
     } else if (pathname === "/" || pathname === "") {
       // Serve index.html for root
       filePath = join(publicDir, "index.html");