@forwardimpact/pathway 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/pathway",
-  "version": "0.1.0",
+  "version": "0.3.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": {

package/templates/agent.template.md

@@ -0,0 +1,65 @@
+---
+
+{{#name}}name: {{name}} {{/name}}description: {{{description}}} {{#infer}}infer:
+{{infer}} {{/infer}}{{#handoffs.length}}handoffs: {{#handoffs}} - label:
+{{label}} {{#agent}} agent: {{agent}} {{/agent}} prompt: "{{{prompt}}}"
+{{#send}} send: {{send}} {{/send}}{{/handoffs}}{{/handoffs.length}}---
+
+# {{title}}
+
+{{{stageDescription}}}
+
+## Core Identity
+
+{{{identity}}}
+
+{{#priority}} {{{priority}}}
+
+{{/priority}} {{#capabilities.length}} Your primary capabilities:
+{{#capabilities}}
+
+- {{{.}}} {{/capabilities}}
+
+{{/capabilities.length}} {{#beforeMakingChanges.length}} Before making changes:
+{{#beforeMakingChanges}} {{index}}. {{{text}}} {{/beforeMakingChanges}}
+
+{{/beforeMakingChanges.length}} {{#delegation}}
+
+## Delegation
+
+{{{delegation}}}
+
+{{/delegation}}
+
+## Operational Context
+
+{{{operationalContext}}}
+
+{{{workingStyle}}} {{#beforeHandoff}}
+
+## Before Handoff
+
+Before offering a handoff, verify and summarize completion of these items:
+
+{{{beforeHandoff}}}
+
+When verified, summarize what was accomplished then offer the handoff. If items
+are incomplete, explain what remains.
+
+{{/beforeHandoff}}
+
+## Return Format
+
+When completing work (for handoff or as a subagent), provide:
+
+1. **Work completed**: What was accomplished
+2. **Checklist status**: Items verified from Before Handoff section
+3. **Recommendation**: Ready for next stage, or needs more work
+
+{{#constraints.length}}
+
+## Constraints
+
+{{#constraints}}
+
+- {{{.}}} {{/constraints}} {{/constraints.length}}

package/templates/job.template.md

@@ -0,0 +1,47 @@
+# {{title}}
+
+- **Level:** {{gradeId}}
+- **Experience:** {{typicalExperienceRange}}
+{{#trackName}}- **Track:** {{trackName}}
+{{/trackName}}
+
+## ROLE SUMMARY
+
+{{{roleSummary}}}
+
+{{#trackRoleContext}}
+{{{trackRoleContext}}}
+
+{{/trackRoleContext}}
+{{#expectationsParagraph}}
+{{{expectationsParagraph}}}
+
+{{/expectationsParagraph}}
+
+## ROLE RESPONSIBILITIES
+
+{{#responsibilities}}
+- **{{capabilityName}}:** {{responsibility}}
+{{/responsibilities}}
+
+## ROLE BEHAVIOURS
+
+{{#behaviours}}
+- **{{behaviourName}}:** {{maturityDescription}}
+{{/behaviours}}
+
+{{#skillLevels}}
+
+## {{levelHeading}}
+
+{{#skills}}
+- **{{skillName}}:** {{levelDescription}}
+{{/skills}}
+
+{{/skillLevels}}
+
+## QUALIFICATIONS
+
+{{#qualificationSummary}}
+{{{qualificationSummary}}}
+{{/qualificationSummary}}

package/templates/skill.template.md

@@ -0,0 +1,28 @@
+---
+
+name: {{name}} description: | {{#descriptionLines}} {{{.}}}
+{{/descriptionLines}}---
+
+# {{{title}}}
+
+## Stage Guidance
+
+{{#stages}}
+
+### {{stageName}} Stage
+
+**Focus:** {{{focus}}}
+
+**Activities:** {{#activities}}
+
+- {{{.}}} {{/activities}}
+
+**Ready for {{nextStageName}} when:** {{#ready}}
+
+- [ ] {{{.}}} {{/ready}}
+
+{{/stages}} {{#reference}}
+
+## Reference
+
+{{{reference}}} {{/reference}}

package/examples/agents/.claude/skills/data-modeling/SKILL.md

@@ -1,99 +0,0 @@
----
-name: data-modeling
-description: |
-  Guide for designing database schemas, data structures, and data
-  architectures. Use when designing tables, optimizing queries, or
-  making decisions about data storage technologies.
----
-
-# Data Modeling
-
-## When to use this skill
-
-Use this skill when:
-
-- Designing database schemas
-- Optimizing query performance
-- Choosing storage technologies
-- Planning schema migrations
-- Balancing normalization with performance
-
-## Schema Design
-
-### Normalization
-
-- **1NF**: Atomic values, no repeating groups
-- **2NF**: No partial dependencies
-- **3NF**: No transitive dependencies
-- Normalize first, then denormalize strategically
-
-### Denormalization Trade-offs
-
-- Improves read performance
-- Complicates writes and updates
-- Risk of data inconsistency
-- Use for read-heavy workloads
-
-## Data Store Selection
-
-### Relational (SQL)
-
-- Strong consistency requirements
-- Complex queries and joins
-- ACID transactions needed
-- Well-defined schema
-
-### Document (NoSQL)
-
-- Flexible, evolving schemas
-- Hierarchical data
-- Horizontal scaling priority
-- Read-heavy workloads
-
-### Key-Value
-
-- Simple lookup patterns
-- Extreme performance needs
-- Caching layer
-- Session storage
-
-### Time Series
-
-- Temporal data patterns
-- High write throughput
-- Time-based queries
-- Sensor and metrics data
-
-## Indexing Strategy
-
-### When to Index
-
-- Columns in WHERE clauses
-- Join columns
-- ORDER BY columns
-- High-cardinality columns
-
-### Index Trade-offs
-
-- Faster reads, slower writes
-- Storage overhead
-- Maintenance cost
-- Query planner complexity
-
-## Schema Migrations
-
-### Safe Migration Practices
-
-- Make changes backward compatible
-- Add columns before using them
-- Migrate data before dropping columns
-- Test migrations on production-like data
-
-## Data Modeling Checklist
-
-- [ ] Requirements understood
-- [ ] Appropriate storage technology selected
-- [ ] Schema normalized appropriately
-- [ ] Indexes support query patterns
-- [ ] Migration plan is safe
-- [ ] Backward compatibility maintained

package/examples/agents/.claude/skills/developer-experience/SKILL.md

@@ -1,99 +0,0 @@
----
-name: developer-experience
-description: |
-  Guide for improving developer experience and creating self-service
-  platforms. Use when designing golden paths, creating getting-started
-  guides, reducing developer friction, or building internal platforms.
----
-
-# Developer Experience
-
-## When to use this skill
-
-Use this skill when:
-
-- Designing developer onboarding experiences
-- Creating golden paths for common workflows
-- Building self-service platform capabilities
-- Reducing friction in developer workflows
-- Writing getting-started documentation
-
-## Golden Path Design
-
-### Principles
-
-- Opinionated but not restrictive
-- Works out of the box with minimal configuration
-- Covers 80% of use cases well
-- Easy to discover, hard to miss
-
-### Components
-
-- **Templates**: Starter projects with best practices
-- **CLI tools**: Automate common tasks
-- **Documentation**: Clear, task-focused guides
-- **Examples**: Working code for common patterns
-
-## Friction Log Process
-
-### Observation
-
-1. Shadow developers doing real tasks
-2. Note every hesitation, confusion, or workaround
-3. Time how long each step takes
-4. Record what documentation they consult
-
-### Analysis
-
-- Categorize friction points (tooling, docs, process)
-- Identify patterns across multiple observations
-- Prioritize by frequency × severity
-- Distinguish symptoms from root causes
-
-### Action
-
-- Quick wins: Fix in days, high impact
-- Medium-term: Requires design, weeks
-- Strategic: Platform changes, months
-
-## Self-Service Design
-
-### Day 1 Experience
-
-- New developer can deploy in < 1 hour
-- No tickets or approvals needed
-- Immediate feedback on success/failure
-- Clear next steps after initial success
-
-### Day 50 Experience
-
-- Common tasks are still easy
-- Edge cases are documented
-- Escape hatches exist for advanced needs
-- Platform grows with team needs
-
-## Documentation Standards
-
-### Getting Started Guides
-
-- Prerequisites clearly listed
-- Copy-paste commands that work
-- Expected output shown
-- Troubleshooting for common issues
-
-### Reference Documentation
-
-- Complete API coverage
-- Examples for every feature
-- Search-friendly structure
-- Kept in sync with code
-
-## DX Checklist
-
-- [ ] New developer can get started without help
-- [ ] Golden path covers common use cases
-- [ ] Friction points are documented and prioritized
-- [ ] Self-service for common operations
-- [ ] Documentation is discoverable and accurate
-- [ ] Feedback mechanisms exist
-- [ ] Metrics track developer productivity

package/examples/agents/.claude/skills/knowledge-management/SKILL.md

@@ -1,100 +0,0 @@
----
-name: knowledge-management
-description: |
-  Guide for capturing, organizing, and sharing organizational knowledge.
-  Use when creating knowledge bases, organizing documentation, reducing
-  knowledge silos, or establishing knowledge sharing practices.
----
-
-# Knowledge Management
-
-## When to use this skill
-
-Use this skill when:
-
-- Creating or organizing knowledge bases
-- Documenting institutional knowledge
-- Reducing single-person dependencies
-- Establishing knowledge sharing practices
-- Making information discoverable
-
-## Knowledge Capture
-
-### What to Document
-
-- **Decisions**: Why we chose X over Y
-- **Context**: What we knew when we decided
-- **Procedures**: How to do recurring tasks
-- **Troubleshooting**: Common problems and solutions
-- **Architecture**: How systems work and why
-
-### When to Capture
-
-- After making significant decisions
-- After solving novel problems
-- Before someone leaves or changes roles
-- When you explain something more than twice
-- During incident post-mortems
-
-## Knowledge Organization
-
-### Structure Principles
-
-- Organize by task, not by team
-- Use consistent naming conventions
-- Create clear navigation paths
-- Link related content together
-- Maintain a clear hierarchy
-
-### Discoverability
-
-- Searchable titles and headings
-- Keywords and tags for filtering
-- Landing pages for major topics
-- Recently updated sections visible
-- Cross-linking between related docs
-
-## Knowledge Maintenance
-
-### Keep Current
-
-- Review docs when code changes
-- Date-stamp time-sensitive content
-- Archive rather than delete outdated info
-- Assign ownership for key documents
-- Schedule periodic review cycles
-
-### Quality Standards
-
-- Clear ownership for each document
-- Last-updated dates visible
-- Contact for questions listed
-- Review schedule defined
-- Deprecation process documented
-
-## Reducing Knowledge Silos
-
-### Identify Risks
-
-- Single points of knowledge failure
-- Undocumented tribal knowledge
-- Expertise concentrated in individuals
-- Critical processes in one person's head
-
-### Mitigation Strategies
-
-- Pair programming and shadowing
-- Recorded walkthroughs for complex systems
-- Cross-training sessions
-- Written runbooks for critical processes
-- Regular knowledge sharing meetings
-
-## Knowledge Management Checklist
-
-- [ ] Key decisions are documented with rationale
-- [ ] Procedures are written and discoverable
-- [ ] No critical single-person dependencies
-- [ ] Documentation ownership is clear
-- [ ] Content is regularly reviewed and updated
-- [ ] New team members can self-serve information
-- [ ] Search finds relevant content quickly

package/examples/agents/.claude/skills/pattern-generalization/SKILL.md

@@ -1,102 +0,0 @@
----
-name: pattern-generalization
-description: |
-  Guide for extracting reusable patterns from specific solutions. Use when
-  identifying candidates for generalization, designing abstractions, or
-  building platform capabilities from field-validated solutions.
----
-
-# Pattern Generalization
-
-## When to use this skill
-
-Use this skill when:
-
-- Identifying solutions that could benefit other teams
-- Extracting reusable components from custom code
-- Designing abstractions for common patterns
-- Building platform capabilities from field solutions
-- Deciding when to generalize vs keep custom
-
-## Generalization Criteria
-
-### When to Generalize
-
-- Pattern appears in 3+ implementations
-- Solution has been validated in production
-- Multiple teams would benefit
-- Core logic is stable and understood
-- Customization needs are well-defined
-
-### When to Keep Custom
-
-- Only one team needs it
-- Requirements are still evolving
-- Context is highly specific
-- Generalization cost exceeds benefit
-- Speed to market is critical
-
-## Abstraction Design
-
-### Principles
-
-- Solve the common case simply
-- Allow escape hatches for edge cases
-- Make the right thing easy, wrong thing possible
-- Prefer composition over configuration
-- Hide complexity, expose simplicity
-
-### Trade-offs
-
-- **Flexibility vs Simplicity**: More options = more complexity
-- **Generality vs Performance**: Generic solutions may be slower
-- **Reusability vs Fit**: Shared code may not fit any use case perfectly
-- **Maintainability vs Features**: More features = more maintenance
-
-## Extraction Process
-
-### 1. Identify the Pattern
-
-- What's common across implementations?
-- What varies between uses?
-- What are the extension points?
-- What are the invariants?
-
-### 2. Design the Interface
-
-- Start with the simplest API that works
-- Make common cases one-liners
-- Provide sensible defaults
-- Document customization options
-
-### 3. Validate in New Context
-
-- Test with a different team/use case
-- Gather feedback on API usability
-- Identify missing flexibility
-- Refine based on real usage
-
-### 4. Document and Publish
-
-- Clear getting-started guide
-- Examples for common patterns
-- Migration guide from custom solutions
-- Support and contribution process
-
-## Generalization Anti-patterns
-
-- **Premature generalization**: Abstracting before understanding
-- **Kitchen sink**: Adding every possible feature
-- **Leaky abstraction**: Implementation details exposed
-- **Configuration overload**: Too many options to understand
-- **Orphaned abstraction**: No clear owner or support
-
-## Pattern Generalization Checklist
-
-- [ ] Pattern validated in multiple contexts
-- [ ] Clear benefit over custom solutions
-- [ ] Simple API for common cases
-- [ ] Extension points for customization
-- [ ] Documentation and examples ready
-- [ ] Migration path from existing solutions
-- [ ] Ownership and support defined