@forwardimpact/pathway 0.1.0 → 0.2.0

package/examples/disciplines/engineering_management.yaml

@@ -0,0 +1,63 @@
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/discipline.schema.json
+
+specialization: Engineering Management
+roleTitle: Engineering Manager
+isManagement: true
+minGrade: SE
+
+description: |
+  People and delivery leadership, focusing on team effectiveness,
+  career development, and organizational outcomes.
+
+# null = allow trackless (generalist)
+validTracks:
+  - null
+
+coreSkills:
+  - stakeholder_management
+  - team_collaboration
+supportingSkills:
+  - code_quality
+  - devops
+broadSkills:
+  - architecture_design
+  - technical_writing
+
+behaviourModifiers:
+  outcome_ownership: 1
+  systems_thinking: 1
+
+# Human-specific content
+human:
+  professionalRoleSummary:
+    We are seeking a skilled {roleTitle} who will lead engineering teams,
+    focusing on team effectiveness, career development, and organizational
+    outcomes. In this role, you will create space for curiosity and
+    experimentation while modeling ownership behaviours.
+  managementRoleSummary:
+    We are seeking an experienced {specialization} leader to build and lead
+    high-performing engineering teams. In this role, you will drive team
+    effectiveness and career development while ensuring organizational outcomes
+    are achieved. You will create space for innovation and model the ownership
+    behaviors that define our engineering culture.
+
+# Agent-specific content
+agent:
+  identity: |
+    You are an {specialization} leadership support agent. Your primary 
+    focus is supporting engineering managers with team effectiveness, 
+    process design, and communication.
+  priority: |
+    People and process over direct implementation. You help create space 
+    for curiosity and experimentation, model ownership behaviors, and 
+    remove organizational friction.
+
+    Your role is to support engineering judgment, not replace it.
+  beforeMakingChanges:
+    - Consider team dynamics and individual growth
+    - Think about systemic improvements over individual fixes
+    - Focus on enabling others rather than doing directly
+  constraints:
+    - Focus on enabling and empowering rather than doing directly
+    - Consider long-term team health over short-term fixes
+    - Support engineering judgment, don't replace it

package/examples/disciplines/software_engineering.yaml

@@ -1,8 +1,13 @@
-# Discipline: Software Engineering
-# Builds and maintains software systems
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/discipline.schema.json
 
 specialization: Software Engineering
 roleTitle: Software Engineer
+isProfessional: true
+# null = allow trackless (generalist)
+validTracks:
+  - null
+  - platform
+  - sre
 
 # Shared content (human and agent)
 description:
@@ -47,21 +52,18 @@ human:
 
 # Agent-specific content
 agent:
-  coreInstructions: |
+  identity: |
     You are a {roleTitle} agent. Your primary focus is writing 
     correct, maintainable, well-tested code.
-
-    Before making changes:
-    1. Understand the existing architecture and patterns
-    2. Identify test coverage requirements
-    3. Consider backward compatibility implications
-
+  priority: |
     Code review is more important than code generation. Every line of code
     you produce must be understood and verified. Never ship code without
     comprehensive testing.
-
-    ## Delegation
-
+  beforeMakingChanges:
+    - Understand the existing architecture and patterns
+    - Identify test coverage requirements
+    - Consider backward compatibility implications
+  delegation: |
     When facing tasks outside your expertise, use `runSubagent` to delegate:
     - Data modeling or statistical analysis → data science subagent
     - Security assessment or threat modeling → research subagent

package/examples/drivers.yaml

@@ -1,8 +1,5 @@
-# Drivers - What outcomes matter?
-# Organizational outcomes that productive teams achieve
-# Links skills and behaviours to business impact
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/drivers.schema.json
 
-# Direction & Strategy
 - id: clear_direction
   name: Clear Direction
   description:

package/examples/framework.yaml

@@ -1,5 +1,4 @@
-# Framework - High-level definitions about the Engineering Pathway
-# Drives page content for landing page, entity list pages, and handout chapters
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/framework.schema.json
 
 title: Engineering Pathway
 emoji: "🧭"

package/examples/grades.yaml

@@ -1,6 +1,4 @@
-# Grades - What career level?
-# Base skill levels and behaviour maturities by seniority
-# See domain-concepts.instructions.md for level progressions
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/grades.schema.json
 
 - id: L1
   professionalTitle: Engineer I

package/examples/questions/behaviours/outcome_ownership.yaml

@@ -1,5 +1,4 @@
-# outcome_ownership questions
-# See skills.yaml or behaviours.yaml for metadata
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/behaviour-questions.schema.json
 
 emerging:
   - id: own_emerg_1

package/examples/questions/behaviours/polymathic_knowledge.yaml

@@ -1,5 +1,4 @@
-# polymathic_knowledge questions
-# See skills.yaml or behaviours.yaml for metadata
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/behaviour-questions.schema.json
 
 emerging:
   - id: poly_emerg_1

package/examples/questions/behaviours/precise_communication.yaml

@@ -1,5 +1,4 @@
-# precise_communication questions
-# See skills.yaml or behaviours.yaml for metadata
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/behaviour-questions.schema.json
 
 emerging:
   - id: comm_emerg_1

package/examples/questions/behaviours/relentless_curiosity.yaml

@@ -1,5 +1,4 @@
-# relentless_curiosity questions
-# See skills.yaml or behaviours.yaml for metadata
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/behaviour-questions.schema.json
 
 emerging:
   - id: cur_emerg_1

package/examples/questions/behaviours/systems_thinking.yaml

@@ -1,5 +1,4 @@
-# systems_thinking questions
-# See skills.yaml or behaviours.yaml for metadata
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/behaviour-questions.schema.json
 
 emerging:
   - id: sys_emerg_1

package/examples/questions/skills/architecture_design.yaml

@@ -1,5 +1,4 @@
-# architecture_design questions
-# See skills.yaml or behaviours.yaml for metadata
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/skill-questions.schema.json
 
 awareness:
   - id: arch_aware_1

package/examples/questions/skills/cloud_platforms.yaml

@@ -1,5 +1,4 @@
-# cloud_platforms questions
-# See skills.yaml for metadata
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/skill-questions.schema.json
 
 awareness:
   - id: cp_aware_1

package/examples/questions/skills/code_quality.yaml

@@ -1,5 +1,4 @@
-# code_quality questions
-# See skills.yaml for metadata
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/skill-questions.schema.json
 
 awareness:
   - id: cq_aware_1

package/examples/questions/skills/data_modeling.yaml

@@ -1,5 +1,4 @@
-# data_modeling questions
-# See skills.yaml or behaviours.yaml for metadata
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/skill-questions.schema.json
 
 awareness:
   - id: dm_aware_1

package/examples/questions/skills/devops.yaml

@@ -1,5 +1,4 @@
-# devops questions
-# See skills.yaml or behaviours.yaml for metadata
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/skill-questions.schema.json
 
 awareness:
   - id: devops_aware_1

package/examples/questions/skills/full_stack_development.yaml

@@ -1,5 +1,4 @@
-# full_stack_development questions
-# See skills.yaml or behaviours.yaml for metadata
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/skill-questions.schema.json
 
 awareness:
   - id: fs_aware_1

package/examples/questions/skills/sre_practices.yaml

@@ -1,5 +1,4 @@
-# sre_practices questions
-# See skills.yaml or behaviours.yaml for metadata
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/skill-questions.schema.json
 
 awareness:
   - id: sre_aware_1

package/examples/questions/skills/stakeholder_management.yaml

@@ -1,5 +1,4 @@
-# stakeholder_management questions
-# See skills.yaml or behaviours.yaml for metadata
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/skill-questions.schema.json
 
 awareness:
   - id: stk_aware_1

package/examples/questions/skills/team_collaboration.yaml

@@ -1,5 +1,4 @@
-# team_collaboration questions
-# See skills.yaml or behaviours.yaml for metadata
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/skill-questions.schema.json
 
 awareness:
   - id: tc_aware_1

package/examples/questions/skills/technical_writing.yaml

@@ -1,5 +1,4 @@
-# technical_writing questions
-# See skills.yaml or behaviours.yaml for metadata
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/skill-questions.schema.json
 
 awareness:
   - id: tw_aware_1

package/examples/self-assessments.yaml

@@ -1,7 +1,5 @@
-# Self Assessments - Example profiles for testing candidate matching
-# Maps skills to levels and behaviours to maturities
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/self-assessments.schema.json
 
-# Example: Mid-level Software Engineer
 - id: example_mid_swe
   skillLevels:
     architecture_design: working

package/examples/stages.yaml

@@ -1,76 +1,131 @@
-# Stages - What part of the lifecycle?
-#
-# Defines the three stages of the engineering lifecycle with their tools,
-# handoffs, and constraints. Used for both human checklists and AI agent
-# profile generation.
-#
-# Entry criteria define what must be complete before starting work in a stage.
-# Exit criteria are implicit: they equal the entry criteria of the next stage.
-#
-# See concept/lifecycle.md for full documentation.
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/stages.schema.json
+
+- id: specify
+  name: Specify
+  emoji: "🎯"
+  description:
+    Define What and Why - User stories, acceptance criteria, requirements
+  handoffs:
+    - targetStage: specify
+      label: Refine Spec
+      prompt: Refine spec.md with more detail or clarity.
+    - targetStage: specify
+      label: Alternative Spec
+      prompt: Create an alternative spec.md exploring a different approach.
+    - targetStage: plan
+      label: Create Plan
+      prompt: Create plan.md based on spec.md.
+  constraints:
+    - Do not make code edits or execute commands
+    - Focus on WHAT users need and WHY, not HOW to implement
+    - Write specifications as markdown files under specs/[feature-name]/spec.md
+    - Mark ambiguities with [NEEDS CLARIFICATION]; ask the user; do not guess
+    - No technology choices, APIs, or code structure in specifications
+  entryCriteria: []
+  exitCriteria:
+    - spec.md exists with user stories and acceptance criteria
+    - No unresolved [NEEDS CLARIFICATION] markers in spec.md
 
 - id: plan
   name: Plan
-  emoji: "📋"
+  emoji: "📐"
   description:
-    Research & Design - Understand the problem, gather context, design the
-    solution
-  availableTools:
-    - search
-    - web/fetch
-    - search/codebase
-    - read
-    - todos
+    Define How - Technology choices, architecture, contracts, data models
   handoffs:
+    - targetStage: plan
+      label: Refine Plan
+      prompt: Refine plan.md with more detail or clarity.
+    - targetStage: plan
+      label: Alternative Plan
+      prompt: Create an alternative plan.md exploring a different approach.
     - targetStage: code
       label: Start Coding
-      prompt: Implement the planned changes.
+      prompt: Implement the tasks defined in plan.md.
   constraints:
-    - Do not make code edits
-    - Do not execute commands
-    - Research thoroughly before proposing solutions
-  entryCriteria: [] # Entry stage, no prior work expected
+    - Do not make code edits or execute commands
+    - Every technology choice must trace back to a specific requirement
+    - Write plans as markdown files under specs/[feature-name]/plan.md
+    - Define contracts and data models before implementation details
+    - Document rationale for architectural decisions
+  entryCriteria:
+    - spec.md exists with user stories and acceptance criteria
+    - No unresolved [NEEDS CLARIFICATION] markers in spec.md
+  exitCriteria:
+    - plan.md exists with technology choices and architecture
+    - Contracts and data models defined where applicable
+    - No unresolved [NEEDS CLARIFICATION] markers in plan.md
 
 - id: code
   name: Code
   emoji: "💻"
-  description: Build & Iterate - Implement, test, refine
-  availableTools:
-    - search
-    - search/codebase
-    - read
-    - edit
-    - todos
+  description: Build and Iterate - Implement, test, refine
   handoffs:
     - targetStage: review
       label: Request Review
       prompt: Review the implemented changes.
-  constraints: []
+  constraints:
+    - Implement one task at a time, verify before moving on
+    - Write tests alongside implementation
+    - Track progress with the todo tool
   entryCriteria:
-    - Problem statement documented
-    - Approach selected with rationale
-    - Implementation plan exists
+    - spec.md exists with user stories and acceptance criteria
+    - plan.md exists with technology choices and architecture
+    - No unresolved [NEEDS CLARIFICATION] markers in plan.md
+  exitCriteria:
+    - Implementation complete according to plan.md
+    - Tests written and passing
+    - Self-review completed
 
 - id: review
   name: Review
-  emoji: "✅"
-  description: Verify & Ship - Review, approve, deploy, document
-  availableTools:
-    - search
-    - search/codebase
-    - read
-    - todos
+  emoji: "🔍"
+  description: Verify and Ship - Review, approve, document
   handoffs:
     - targetStage: code
       label: Request Changes
-      prompt: Address the review feedback.
+      prompt: Address the findings in review.md.
     - targetStage: plan
-      label: Needs Replanning
-      prompt: The implementation needs replanning.
+      label: Needs Re-planning
+      prompt: Update plan.md to address issues found in review.md.
+    - targetStage: deploy
+      label: Deploy
+      prompt: Deploy the approved changes.
   constraints:
     - Do not make code edits
+    - Write review findings as markdown under specs/[feature-name]/review.md
     - Prioritize actionable feedback over exhaustive lists
+    - Track findings and required changes with the todo tool
+    - Run the application locally and verify changes work as expected
+    - Test user-facing functionality against acceptance criteria
   entryCriteria:
-    - Implementation complete
+    - Implementation complete according to plan.md
     - Tests written and passing
     - Self-review completed
+  exitCriteria:
+    - Application runs locally without errors
+    - Changes verified against acceptance criteria through manual testing
+    - No blocking issues identified in review
+    - Review approved
+
+- id: deploy
+  name: Deploy
+  emoji: "🚀"
+  description: Ship to Production - Push, monitor workflows, verify deployment
+  handoffs:
+    - targetStage: code
+      label: Fix Pipeline
+      prompt: Fix the failing workflow issues identified during deployment.
+  constraints:
+    - Use git push to deploy changes
+    - Use gh CLI to monitor triggered workflows (gh run list, gh run watch)
+    - Do not make code edits; hand off to code stage if fixes are needed
+    - Verify all workflows complete successfully before considering deployment
+      done
+  entryCriteria:
+    - Application runs locally without errors
+    - Changes verified against acceptance criteria through manual testing
+    - No blocking issues identified in review
+    - Review approved
+  exitCriteria:
+    - All triggered workflows are green
+    - Deployment verified in target environment

package/examples/tracks/_index.yaml

@@ -1,6 +1,5 @@
 # Auto-generated index for browser loading
 # Do not edit manually - regenerate with: npx pathway --generate-index
 files:
-  - manager
   - platform
   - sre

package/examples/tracks/platform.yaml

@@ -1,11 +1,7 @@
-# Track: Platform
-# Internal tooling and infrastructure focus
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/track.schema.json
 
 name: Platform
 
-# Track type - professional track (default)
-isProfessional: true
-
 # Shared content (used by both human job descriptions and agent profiles)
 description:
   Internal tooling and infrastructure focus, building shared capabilities that
@@ -31,22 +27,21 @@ assessmentWeights:
 
 # Agent-specific content
 agent:
-  coreInstructions: |
+  identity: |
     You are a Platform {roleTitle} agent. Your primary focus is 
     building self-service capabilities that enable other engineers.
-
+  priority: |
     Developer experience is paramount. You design golden paths, maintain 
     backward compatibility, and document everything. Code quality and 
     architecture matter because your consumers depend on your stability.
 
-    Before making changes:
-    1. Understand the existing architecture and patterns
-    2. Identify test coverage requirements
-    3. Consider backward compatibility implications
-    4. Plan documentation updates
-
     Every API change must consider developer experience. Treat breaking 
     changes with extreme caution—your consumers build on your stability.
+  beforeMakingChanges:
+    - Understand the existing architecture and patterns
+    - Identify test coverage requirements
+    - Consider backward compatibility implications
+    - Plan documentation updates
   constraints:
     - Maintain backward compatibility
     - Document breaking changes with migration guides

package/examples/tracks/sre.yaml

@@ -1,11 +1,7 @@
-# Track: SRE
-# Site Reliability Engineering focus
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/track.schema.json
 
 name: SRE
 
-# Track type - professional track (default)
-isProfessional: true
-
 # Shared content (used by both human job descriptions and agent profiles)
 description:
   Site Reliability Engineering focus on system reliability, observability, and
@@ -28,29 +24,23 @@ assessmentWeights:
   skillWeight: 0.6
   behaviourWeight: 0.4
 
-# SRE track is only valid for Software Engineering and Data Engineering
-validDisciplines:
-  - software_engineering
-  - data_engineering
-
 # Agent-specific content
 agent:
-  coreInstructions: |
+  identity: |
     You are an SRE {roleTitle} agent. Your primary focus is 
     system reliability, observability, and incident response.
-
+  priority: |
     Reliability is non-negotiable. You instrument everything, design for 
     graceful degradation, and maintain error budgets. Every change 
     considers blast radius and recovery paths.
 
-    Before making changes:
-    1. Understand system dependencies and failure modes
-    2. Ensure observability instrumentation is in place
-    3. Consider rollback procedures and blast radius
-    4. Verify runbooks are updated
-
     Production stability trumps feature velocity. No change ships without
     understanding its impact on system reliability.
+  beforeMakingChanges:
+    - Understand system dependencies and failure modes
+    - Ensure observability instrumentation is in place
+    - Consider rollback procedures and blast radius
+    - Verify runbooks are updated
   constraints:
     - Never compromise on observability instrumentation
     - Document all runbooks and incident response procedures

package/examples/vscode-settings.yaml

@@ -1,8 +1,3 @@
-# VS Code Settings for Agent Features
-# These settings are exported when generating agent configurations
-# to ensure the target workspace has the required VS Code configuration.
-
-# Enable agent mode in chat
 chat.agent.enabled: true
 
 # Maximum requests per agent session (high limit for complex tasks)
@@ -18,5 +13,5 @@ chat.extensionUnification.enabled: true
 # Required for multi-agent workflows with handoffs
 chat.customAgentInSubagent.enabled: true
 
-# Enable Claude skills for enhanced agent capabilities
-chat.useClaudeSkills: true
+# Enable agent skills for enhanced agent capabilities
+chat.useAgentSkills: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/pathway",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Engineering Pathway framework for human and AI collaboration",
   "license": "Apache-2.0",
   "repository": {
@@ -25,7 +25,8 @@
   "files": [
     "bin/",
     "app/",
-    "examples/"
+    "examples/",
+    "templates/"
   ],
   "exports": {
     ".": "./app/model/loader.js",
@@ -40,7 +41,7 @@
   "scripts": {
     "start": "node bin/pathway.js serve",
     "prestart": "npm run generate-index",
-    "check": "npm run format && npm run lint && npm run test",
+    "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",
@@ -49,17 +50,22 @@
     "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"
   },
   "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "mustache": "^4.2.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": {