@forwardimpact/pathway 0.1.0 → 0.3.0

package/bin/pathway.js

@@ -31,14 +31,10 @@
 import { fileURLToPath } from "url";
 import { dirname, join, resolve } from "path";
 import { existsSync } from "fs";
-import {
-  loadAllData,
-  loadAgentData,
-  loadSkillsWithAgentData,
-  loadQuestionBankFromFolder,
-} from "../app/model/loader.js";
+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 command handlers
 import { runSkillCommand } from "../app/commands/skill.js";
@@ -105,7 +101,7 @@ Composite Commands:
   progress <discipline> <track> <grade> [--compare=GRADE]
                                       Show career progression
   questions [filters]                 Browse interview questions
-  agent [<discipline> <track>]        Generate AI coding agent
+  agent <discipline> [--track=<track>] Generate AI coding agent
 
 Global Options:
   --list            Output IDs only (for piping to other commands)
@@ -125,10 +121,10 @@ Questions Filters:
   --format=FORMAT     Output format: table, yaml, json
 
 Agent Options:
-  --output=PATH       Output directory (default: current directory)
-  --preview           Show output without writing files
-  --role=ROLE         Generate specific role variant
-  --all-roles         Generate default + all role variants
+  --track=TRACK       Track for the agent (e.g., platform, forward_deployed)
+  --output=PATH       Write files to directory (without this, outputs to console)
+  --stage=STAGE       Generate specific stage agent (plan, code, review)
+  --all-stages        Generate all stage agents (default)
 
 Examples:
   npx pathway skill                    # Summary of all skills
@@ -143,7 +139,7 @@ Examples:
   npx pathway questions --level=practitioner
   npx pathway questions --stats
 
-  npx pathway agent software_engineering platform --output=./agents
+  npx pathway agent software_engineering --track=platform --output=./agents
   npx pathway --validate               # Validate all data
 `;
 
@@ -164,6 +160,8 @@ function parseArgs(args) {
     type: "full",
     compare: null,
     data: null,
+    // Shared command options
+    track: null,
     // Questions command options
     level: null,
     maturity: null,
@@ -176,9 +174,6 @@ function parseArgs(args) {
     checklist: null,
     // Agent command options
     output: null,
-    preview: false,
-    role: null,
-    "all-roles": false,
     stage: null,
     "all-stages": false,
     // Serve command options
@@ -200,14 +195,14 @@ function parseArgs(args) {
       result.validate = true;
     } else if (arg === "--generate-index") {
       result.generateIndex = true;
-    } else if (arg === "--preview") {
-      result.preview = true;
     } else if (arg.startsWith("--type=")) {
       result.type = arg.slice(7);
     } else if (arg.startsWith("--compare=")) {
       result.compare = arg.slice(10);
     } else if (arg.startsWith("--data=")) {
       result.data = arg.slice(7);
+    } else if (arg.startsWith("--track=")) {
+      result.track = arg.slice(8);
     } else if (arg.startsWith("--output=")) {
       result.output = arg.slice(9);
     } else if (arg.startsWith("--level=")) {
@@ -260,7 +255,7 @@ function printHelp() {
 }
 
 /**
- * Run full data validation
+ * Run full data validation using JSON schemas
  * @param {string} dataDir - Path to data directory
  */
 async function runFullValidation(dataDir) {
@@ -268,77 +263,34 @@ async function runFullValidation(dataDir) {
 
   let hasErrors = false;
 
-  // Load and validate core data
+  // Load data for referential integrity checking (without old validation)
   const data = await loadAllData(dataDir, {
-    validate: true,
+    validate: false,
     throwOnError: false,
   });
 
-  if (data.validation.valid) {
-    console.log("✅ Core data validation passed");
+  // Run schema validation + referential integrity
+  const result = await runSchemaValidation(dataDir, data);
+
+  if (result.valid) {
+    console.log("✅ Schema validation passed");
   } else {
-    console.log("❌ Core data validation failed");
+    console.log("❌ Schema validation failed");
     hasErrors = true;
-    for (const e of data.validation.errors) {
-      console.log(`  - [${e.type}] ${e.message}`);
+    for (const e of result.errors) {
+      console.log(
+        `  - [${e.type}] ${e.message}${e.path ? ` (${e.path})` : ""}`,
+      );
     }
   }
 
-  if (data.validation.warnings.length > 0) {
+  if (result.warnings.length > 0) {
     console.log("\n⚠️  Warnings:");
-    for (const w of data.validation.warnings) {
+    for (const w of result.warnings) {
       console.log(`  - [${w.type}] ${w.message}`);
     }
   }
 
-  // Validate question bank
-  try {
-    const questionBank = await loadQuestionBankFromFolder(
-      join(dataDir, "questions"),
-      data.skills,
-      data.behaviours,
-      { validate: true, throwOnError: false },
-    );
-
-    if (questionBank.validation?.valid) {
-      console.log("✅ Question bank validation passed");
-    } else if (questionBank.validation) {
-      console.log("❌ Question bank validation failed");
-      hasErrors = true;
-      for (const e of questionBank.validation.errors) {
-        console.log(`  - [${e.type}] ${e.message}`);
-      }
-    }
-  } catch (err) {
-    console.log("⚠️  Could not validate question bank:", err.message);
-  }
-
-  // Validate agent data
-  try {
-    const agentData = await loadAgentData(dataDir);
-    const skillsWithAgent = await loadSkillsWithAgentData(dataDir);
-
-    const skillsWithAgentCount = skillsWithAgent.filter((s) => s.agent).length;
-
-    console.log(
-      `✅ Agent data: ${agentData.disciplines.length} disciplines, ${agentData.tracks.length} tracks, ${skillsWithAgentCount} skills with agent sections`,
-    );
-
-    // Check for orphaned agent definitions
-    for (const d of agentData.disciplines) {
-      if (!data.disciplines.find((h) => h.id === d.id)) {
-        console.log(`  ⚠️  Agent discipline '${d.id}' has no human definition`);
-      }
-    }
-    for (const t of agentData.tracks) {
-      if (!data.tracks.find((h) => h.id === t.id)) {
-        console.log(`  ⚠️  Agent track '${t.id}' has no human definition`);
-      }
-    }
-  } catch (err) {
-    console.log("⚠️  Could not validate agent data:", err.message);
-  }
-
   // Summary
   console.log("\n📊 Data Summary:");
   console.log(`   Skills:      ${data.skills?.length || 0}`);
@@ -347,6 +299,7 @@ async function runFullValidation(dataDir) {
   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;

package/examples/agents/.claude/skills/architecture-design/SKILL.md

@@ -8,14 +8,66 @@ description: |
 
 # Architecture & Design
 
-## When to use this skill
+## Stage Guidance
 
-Use this skill when:
+### Plan Stage
 
-- Designing new systems or major features
-- Evaluating architectural options and trade-offs
-- Making decisions about code organization and structure
-- Reviewing or improving existing architecture
+**Focus:** Understand requirements and identify key architectural decisions.
+Document trade-offs and design rationale.
+
+**Activities:**
+
+- Clarify functional and non-functional requirements
+- Identify constraints (existing systems, team skills, timeline)
+- Document key decisions and trade-offs
+- Design for anticipated change
+
+**Ready for Code when:**
+
+- [ ] Requirements are clearly understood
+- [ ] Key decisions are documented with rationale
+- [ ] Trade-offs are explicit
+- [ ] Failure modes are considered
+
+### Code Stage
+
+**Focus:** Implement architecture with clear boundaries and interfaces. Ensure
+components can evolve independently.
+
+**Activities:**
+
+- Define clear interfaces between components
+- Implement with appropriate patterns
+- Document design decisions in code
+- Test architectural boundaries
+
+**Ready for Review when:**
+
+- [ ] Dependencies are minimal and explicit
+- [ ] Interfaces are well-defined
+- [ ] Design patterns are documented
+- [ ] Architecture tests pass
+
+### Review Stage
+
+**Focus:** Validate architecture meets requirements and is maintainable. Ensure
+scalability and security are addressed.
+
+**Activities:**
+
+- Verify architecture meets requirements
+- Review for scalability concerns
+- Check security implications
+- Validate documentation completeness
+
+**Ready for Complete when:**
+
+- [ ] Scalability requirements are addressed
+- [ ] Security implications are reviewed
+- [ ] Architecture is documented
+- [ ] Design is maintainable
+
+## Reference
 
 ## Design Process
 
@@ -76,13 +128,3 @@ Good architecture accommodates change:
 - REST: Synchronous, request-response
 - Event-driven: Asynchronous, loose coupling
 - gRPC: Efficient, strongly typed
-
-## Architecture Checklist
-
-- [ ] Requirements are clearly understood
-- [ ] Key decisions are documented with rationale
-- [ ] Trade-offs are explicit
-- [ ] Failure modes are considered
-- [ ] Scalability requirements are addressed
-- [ ] Security implications are reviewed
-- [ ] Dependencies are minimal and explicit

package/examples/agents/.claude/skills/cloud-platforms/SKILL.md

@@ -8,15 +8,67 @@ description: |
 
 # Cloud Platforms
 
-## When to use this skill
+## Stage Guidance
 
-Use this skill when:
+### Plan Stage
 
-- Deploying applications to cloud environments
-- Selecting appropriate cloud services
-- Configuring cloud infrastructure
-- Optimizing cloud costs and performance
-- Implementing cloud security best practices
+**Focus:** Select appropriate cloud services and design for availability,
+security, and cost efficiency.
+
+**Activities:**
+
+- Identify service requirements
+- Select appropriate cloud services
+- Plan for high availability
+- Consider security and cost
+
+**Ready for Code when:**
+
+- [ ] Service selection matches requirements
+- [ ] Availability approach planned
+- [ ] Security model defined
+- [ ] Cost controls considered
+
+### Code Stage
+
+**Focus:** Implement cloud infrastructure with security best practices. Use
+infrastructure as code for reproducibility.
+
+**Activities:**
+
+- Define infrastructure as code
+- Configure security groups and IAM
+- Set up monitoring and alerting
+- Implement deployment automation
+
+**Ready for Review when:**
+
+- [ ] Multi-AZ deployment for availability
+- [ ] Security groups properly configured
+- [ ] IAM follows least privilege
+- [ ] Data encrypted at rest and in transit
+- [ ] Infrastructure defined as code
+
+### Review Stage
+
+**Focus:** Validate security, availability, and operational readiness. Ensure
+cost controls are in place.
+
+**Activities:**
+
+- Verify security configuration
+- Test availability and failover
+- Review cost projections
+- Validate monitoring coverage
+
+**Ready for Complete when:**
+
+- [ ] Security review completed
+- [ ] Monitoring and alerting in place
+- [ ] Cost controls established
+- [ ] Operational runbooks exist
+
+## Reference
 
 ## Service Categories
 
@@ -77,14 +129,3 @@ Use this skill when:
 - Leverage spot/preemptible instances for fault-tolerant work
 - Set up billing alerts and budgets
 - Delete unused resources
-
-## Cloud Checklist
-
-- [ ] Service selection matches requirements
-- [ ] Multi-AZ deployment for availability
-- [ ] Security groups properly configured
-- [ ] IAM follows least privilege
-- [ ] Data encrypted at rest and in transit
-- [ ] Monitoring and alerting in place
-- [ ] Cost controls established
-- [ ] Infrastructure defined as code

package/examples/agents/.claude/skills/code-quality-review/SKILL.md

@@ -8,14 +8,66 @@ description: |
 
 # Code Quality & Review
 
-## When to use this skill
+## Stage Guidance
 
-Use this skill when:
+### Plan Stage
 
-- Reviewing code for quality issues
-- Checking code against best practices
-- Conducting or assisting with code reviews
-- Verifying AI-generated code before committing
+**Focus:** Understand code review scope and establish review criteria. Consider
+what quality standards apply.
+
+**Activities:**
+
+- Identify code review scope
+- Understand applicable standards
+- Plan review approach
+- Consider risk level
+
+**Ready for Code when:**
+
+- [ ] Review scope is clear
+- [ ] Standards are understood
+- [ ] Review approach is planned
+- [ ] Risk level is assessed
+
+### Code Stage
+
+**Focus:** Write clean, maintainable, tested code. Follow project conventions
+and ensure adequate coverage.
+
+**Activities:**
+
+- Write readable, well-structured code
+- Add appropriate tests
+- Follow project conventions
+- Document non-obvious logic
+
+**Ready for Review when:**
+
+- [ ] Code compiles and passes all tests
+- [ ] Changes are covered by tests
+- [ ] Code follows project conventions
+- [ ] No unnecessary complexity
+
+### Review Stage
+
+**Focus:** Verify correctness, maintainability, and adherence to standards.
+Ensure no code is shipped that isn't understood.
+
+**Activities:**
+
+- Verify code does what it claims
+- Check test coverage
+- Review for maintainability
+- Confirm style compliance
+
+**Ready for Complete when:**
+
+- [ ] No obvious security vulnerabilities
+- [ ] Error handling is appropriate
+- [ ] Documentation updated if needed
+- [ ] No code you don't fully understand
+
+## Reference
 
 ## Review Process
 
@@ -54,14 +106,3 @@ Verify consistency with project standards:
 - Consistent formatting and indentation
 - Appropriate comments for non-obvious logic
 - Documentation updated if needed
-
-## Quality Checklist
-
-- [ ] Code compiles and passes all tests
-- [ ] Changes are covered by tests
-- [ ] No obvious security vulnerabilities
-- [ ] Error handling is appropriate
-- [ ] Code follows project conventions
-- [ ] No unnecessary complexity
-- [ ] Documentation updated if needed
-- [ ] No code you don't fully understand

package/examples/agents/.claude/skills/devops-cicd/SKILL.md

@@ -8,15 +8,72 @@ description: |
 
 # DevOps & CI/CD
 
-## When to use this skill
+## Stage Guidance
 
-Use this skill when:
+### Plan Stage
 
-- Setting up or modifying CI/CD pipelines
-- Containerizing applications with Docker
-- Managing infrastructure as code
-- Troubleshooting deployment failures
-- Implementing monitoring and alerting
+**Focus:** Plan CI/CD pipeline architecture and infrastructure requirements.
+Consider deployment strategies and monitoring needs.
+
+**Activities:**
+
+- Define pipeline stages (build, test, deploy)
+- Identify infrastructure requirements
+- Plan deployment strategy (rolling, blue-green, canary)
+- Consider monitoring and alerting needs
+- Plan secret management approach
+
+**Ready for Code when:**
+
+- [ ] Pipeline architecture is documented
+- [ ] Deployment strategy is chosen and justified
+- [ ] Infrastructure requirements are identified
+- [ ] Monitoring approach is defined
+
+### Code Stage
+
+**Focus:** Implement CI/CD pipelines and infrastructure as code. Follow best
+practices for containerization and deployment automation.
+
+**Activities:**
+
+- Configure CI/CD pipeline stages
+- Implement infrastructure as code (Terraform, CloudFormation)
+- Create Dockerfiles with security best practices
+- Set up monitoring and alerting
+- Configure secret management
+- Implement deployment automation
+
+**Ready for Review when:**
+
+- [ ] Pipeline runs on every commit
+- [ ] Tests run before deployment
+- [ ] Deployments are automated
+- [ ] Infrastructure is version controlled
+- [ ] Secrets are managed securely
+- [ ] Monitoring is in place
+
+### Review Stage
+
+**Focus:** Verify pipeline reliability, security, and operational readiness.
+Ensure rollback procedures work and documentation is complete.
+
+**Activities:**
+
+- Verify pipeline runs successfully end-to-end
+- Test rollback procedures
+- Review security configurations
+- Validate monitoring and alerts
+- Check documentation completeness
+
+**Ready for Complete when:**
+
+- [ ] Pipeline is tested and reliable
+- [ ] Rollback procedure is documented and tested
+- [ ] Alerts are configured and tested
+- [ ] Runbooks exist for common issues
+
+## Reference
 
 ## CI/CD Pipeline Stages
 
@@ -83,14 +140,3 @@ CMD ["node", "server.js"]
 - Route small percentage to new version
 - Monitor for issues
 - Gradually increase traffic
-
-## DevOps Checklist
-
-- [ ] Pipeline runs on every commit
-- [ ] Tests run before deployment
-- [ ] Deployments are automated
-- [ ] Rollback procedure is documented
-- [ ] Infrastructure is version controlled
-- [ ] Secrets are managed securely
-- [ ] Monitoring is in place
-- [ ] Alerts are configured

package/examples/agents/.claude/skills/full-stack-development/SKILL.md

@@ -8,14 +8,67 @@ description: |
 
 # Full-Stack Development
 
-## When to use this skill
+## Stage Guidance
 
-Use this skill when:
+### Plan Stage
 
-- Building features that span multiple layers
-- Implementing end-to-end functionality
-- Working across frontend, backend, and infrastructure
-- Debugging issues that cross layer boundaries
+**Focus:** Design the full-stack solution architecture. Define API contracts and
+plan layer interactions.
+
+**Activities:**
+
+- Define the API contract first
+- Plan frontend and backend responsibilities
+- Design database schema
+- Plan infrastructure requirements
+
+**Ready for Code when:**
+
+- [ ] API contract is defined
+- [ ] Layer responsibilities are clear
+- [ ] Database schema is planned
+- [ ] Infrastructure approach is decided
+
+### Code Stage
+
+**Focus:** Build vertically—complete one feature end-to-end before starting
+another. Validates assumptions early.
+
+**Activities:**
+
+- Implement API endpoints
+- Build frontend integration
+- Create database schema and queries
+- Configure infrastructure as needed
+- Test across layers
+
+**Ready for Review when:**
+
+- [ ] Frontend connects to backend correctly
+- [ ] Database schema supports the feature
+- [ ] Error handling spans all layers
+- [ ] Feature works end-to-end
+- [ ] Deployment is automated
+
+### Review Stage
+
+**Focus:** Verify integration across layers and ensure deployment readiness.
+
+**Activities:**
+
+- Test integration across all layers
+- Verify error handling end-to-end
+- Check deployment configuration
+- Review documentation
+
+**Ready for Complete when:**
+
+- [ ] Integration tests pass
+- [ ] Deployment verified
+- [ ] Documentation is complete
+- [ ] Feature is production-ready
+
+## Reference
 
 ## Technology Stack
 
@@ -79,12 +132,3 @@ Use this skill when:
 - Unit tests per layer
 - Integration tests across layers
 - End-to-end tests for critical paths
-
-## Full-Stack Checklist
-
-- [ ] API contract is defined
-- [ ] Frontend connects to backend correctly
-- [ ] Database schema supports the feature
-- [ ] Error handling spans all layers
-- [ ] Feature works end-to-end
-- [ ] Deployment is automated