@forwardimpact/pathway 0.3.0 → 0.5.0

package/examples/framework.yaml

@@ -1,7 +1,7 @@
 # yaml-language-server: $schema=https://schema.forwardimpact.team/json/framework.schema.json
 
 title: Engineering Pathway
-emoji: "🧭"
+emojiIcon: "🧭"
 tag: "#AcmeCorp"
 description: |
   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. The pathway aligns human capabilities with AI assistance, enabling productive teams in the AI era.
@@ -10,48 +10,60 @@ description: |
 entityDefinitions:
   driver:
     title: Drivers
-    emoji: "🎯"
+    emojiIcon: "🎯"
     description: |
       Organizational outcomes that productive teams achieve. Drivers link skills and behaviours to business value, helping teams understand how their capabilities contribute to organizational success.
 
   skill:
     title: Skills
-    emoji: "💡"
+    emojiIcon: "💡"
     description: |
       Capabilities required to perform work effectively. Skills are organized by capability and measured across five levels from Awareness to Expert. They form the foundation of technical and professional competence.
 
   behaviour:
     title: Behaviours
-    emoji: "🧠"
+    emojiIcon: "🧠"
     description: |
       Mindsets and ways of working that underpin effective application of skills. Behaviours are measured across five maturity levels from Emerging to Exemplifying. They describe how engineers approach their work, collaborate with others, and drive outcomes.
 
   discipline:
     title: Disciplines
-    emoji: "🔧"
+    emojiIcon: "🔧"
     description: |
       Engineering specializations that define T-shaped skill profiles. Each discipline specifies primary skills for deep expertise, secondary skills for supporting capabilities, and broad skills for general awareness. Disciplines answer the question: "What kind of engineer are you?"
 
   grade:
     title: Grades
-    emoji: "📊"
+    emojiIcon: "📊"
     description: |
       Career levels that define expectations for skill proficiency, behaviour maturity, and scope of impact. Grades provide a clear progression path from entry-level to distinguished leadership roles, with defined expectations at each stage.
 
   track:
     title: Tracks
-    emoji: "🛤️"
+    emojiIcon: "🛤️"
     description: |
       Work contexts that modify skill and behaviour expectations based on the nature of the role. Tracks answer the question: "Where and how do you work?" They apply modifiers to adjust expectations for different working environments and responsibilities.
 
   job:
     title: Jobs
-    emoji: "📋"
+    emojiIcon: "📋"
     description: |
       Complete role specifications that combine discipline, track, and grade into actionable job definitions with skill matrices, behaviour profiles, and derived responsibilities. Jobs represent the practical application of the framework to define concrete engineering positions.
 
   agent:
     title: Agents
-    emoji: "🤖"
+    emojiIcon: "🤖"
     description: |
       AI coding agent configurations generated from the same disciplines, tracks, and skills that define human roles. Agent profiles and skills follow the GitHub Copilot specification, ensuring AI assistants understand context, constraints, and working styles aligned with human engineering expectations.
+
+  stage:
+    title: Stages
+    emojiIcon: "🔄"
+    description: |
+      Defined phases of the engineering lifecycle that structure work from planning through delivery and review. Stages provide context for AI agents and define entry criteria, exit criteria, and appropriate handoffs between phases.
+
+  tool:
+    title: Tools
+    emojiIcon: "🔧"
+    description: |
+      Recommended tools and utilities referenced by skills for effective engineering workflows. Tools are linked to specific skills with guidance on when and how to use them, surfacing best practices directly in skill definitions.

package/examples/grades.yaml

@@ -82,10 +82,10 @@
   breadthCriteria:
     practitioner: 4
   expectations:
-    impactScope: Multi-team initiatives with organizational impact
+    impactScope: Multi-team initiatives with area-wide impact
     autonomyExpectation: Set own direction within broader strategic goals
     influenceScope:
-      Influence multiple teams and be recognized as a domain expert
+      Influence teams in your area and be recognized as a domain expert
     complexityHandled:
       Very high complexity driving through ambiguity to deliver results
 
@@ -107,11 +107,9 @@
     practitioner: 5
     expert: 2
   expectations:
-    impactScope:
-      Organization-wide technical strategy and architectural direction
+    impactScope: Business unit technical strategy and architectural direction
     autonomyExpectation:
       Define strategic direction and be accountable for outcomes
     influenceScope:
-      Shape organizational practices and maintain external industry visibility
-    complexityHandled:
-      Organizational-scale complexity creating clarity from chaos
+      Shape practices across the business unit and maintain external visibility
+    complexityHandled: Business unit complexity creating clarity from ambiguity

package/examples/self-assessments.yaml

@@ -44,7 +44,7 @@
 # Example: Data Scientist - R&D Focus
 - id: example_ds_rd
   skillLevels:
-    machine_learning: working
+    model_development: working
     data_analysis: working
     statistical_modeling: working
     data_modeling: foundational

package/examples/stages.yaml

@@ -2,9 +2,10 @@
 
 - id: specify
   name: Specify
-  emoji: "🎯"
+  emojiIcon: "🎯"
   description:
-    Define What and Why - User stories, acceptance criteria, requirements
+    Your primary task is to define WHAT users need and WHY, not how to build it.
+    Gather requirements, write user stories, and define acceptance criteria.
   handoffs:
     - targetStage: specify
       label: Refine Spec
@@ -28,9 +29,10 @@
 
 - id: plan
   name: Plan
-  emoji: "📐"
+  emojiIcon: "📐"
   description:
-    Define How - Technology choices, architecture, contracts, data models
+    Your primary task is to define HOW to build the solution. Make technology
+    choices, design architecture, define contracts and data models.
   handoffs:
     - targetStage: plan
       label: Refine Plan
@@ -57,8 +59,10 @@
 
 - id: code
   name: Code
-  emoji: "💻"
-  description: Build and Iterate - Implement, test, refine
+  emojiIcon: "💻"
+  description:
+    Your primary task is to implement the solution. Write code, write tests, and
+    iterate until the implementation is complete.
   handoffs:
     - targetStage: review
       label: Request Review
@@ -78,8 +82,10 @@
 
 - id: review
   name: Review
-  emoji: "🔍"
-  description: Verify and Ship - Review, approve, document
+  emojiIcon: "🔍"
+  description:
+    Your primary task is to verify the implementation works correctly. Run the
+    application, test against acceptance criteria, document findings.
   handoffs:
     - targetStage: code
       label: Request Changes
@@ -109,8 +115,10 @@
 
 - id: deploy
   name: Deploy
-  emoji: "🚀"
-  description: Ship to Production - Push, monitor workflows, verify deployment
+  emojiIcon: "🚀"
+  description:
+    Your primary task is to ship the changes to production. Push code, monitor
+    CI/CD workflows, and verify successful deployment.
   handoffs:
     - targetStage: code
       label: Fix Pipeline

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/pathway",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Engineering Pathway framework for human and AI collaboration",
   "license": "Apache-2.0",
   "repository": {
@@ -59,6 +59,7 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "mustache": "^4.2.0",
+    "simple-icons": "^16.7.0",
     "yaml": "^2.3.4"
   },
   "devDependencies": {

package/templates/agent.template.md

@@ -1,9 +1,25 @@
 ---
-
-{{#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}}---
+{{#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}}
 
@@ -13,29 +29,43 @@
 
 {{{identity}}}
 
-{{#priority}} {{{priority}}}
+{{#priority}}
+{{{priority}}}
+
+{{/priority}}
+{{#hasSkills}}
+## Available Skills
 
-{{/priority}} {{#capabilities.length}} Your primary capabilities:
-{{#capabilities}}
+IMPORTANT: Before starting work, read the relevant skill file for project-specific
+guidance. Do not rely solely on pre-training knowledge.
 
-- {{{.}}} {{/capabilities}}
+| Skill | Location | Use When |
+|-------|----------|----------|
+{{#skillIndex}}
+| {{{name}}} | `.claude/skills/{{dirname}}/SKILL.md` | {{{useWhen}}} |
+{{/skillIndex}}
 
-{{/capabilities.length}} {{#beforeMakingChanges.length}} Before making changes:
-{{#beforeMakingChanges}} {{index}}. {{{text}}} {{/beforeMakingChanges}}
+{{/hasSkills}}
+{{#beforeMakingChanges.length}}
+Before making changes:
 
-{{/beforeMakingChanges.length}} {{#delegation}}
+{{#beforeMakingChanges}}
+{{index}}. {{{text}}}
+{{/beforeMakingChanges}}
+{{/beforeMakingChanges.length}}
 
+{{#delegation}}
 ## Delegation
 
 {{{delegation}}}
-
 {{/delegation}}
 
 ## Operational Context
 
 {{{operationalContext}}}
 
-{{{workingStyle}}} {{#beforeHandoff}}
+{{{workingStyle}}}
+{{#beforeHandoff}}
 
 ## Before Handoff
 
@@ -57,9 +87,9 @@ When completing work (for handoff or as a subagent), provide:
 3. **Recommendation**: Ready for next stage, or needs more work
 
 {{#constraints.length}}
-
 ## Constraints
 
 {{#constraints}}
-
-- {{{.}}} {{/constraints}} {{/constraints.length}}
+- {{{.}}}
+{{/constraints}}
+{{/constraints.length}}

package/templates/job.template.md

@@ -1,8 +1,8 @@
-# {{title}}
+# {{{title}}}
 
-- **Level:** {{gradeId}}
-- **Experience:** {{typicalExperienceRange}}
-{{#trackName}}- **Track:** {{trackName}}
+- **Level:** {{{gradeId}}}
+- **Experience:** {{{typicalExperienceRange}}}
+{{#trackName}}- **Track:** {{{trackName}}}
 {{/trackName}}
 
 ## ROLE SUMMARY
@@ -21,21 +21,21 @@
 ## ROLE RESPONSIBILITIES
 
 {{#responsibilities}}
-- **{{capabilityName}}:** {{responsibility}}
+- **{{{capabilityName}}}:** {{{responsibility}}}
 {{/responsibilities}}
 
 ## ROLE BEHAVIOURS
 
 {{#behaviours}}
-- **{{behaviourName}}:** {{maturityDescription}}
+- **{{{behaviourName}}}:** {{{maturityDescription}}}
 {{/behaviours}}
 
 {{#skillLevels}}
 
-## {{levelHeading}}
+## {{{levelHeading}}}
 
 {{#skills}}
-- **{{skillName}}:** {{levelDescription}}
+- **{{{skillName}}}:** {{{levelDescription}}}
 {{/skills}}
 
 {{/skillLevels}}

package/templates/skill.template.md

@@ -1,28 +1,50 @@
 ---
-
-name: {{name}} description: | {{#descriptionLines}} {{{.}}}
-{{/descriptionLines}}---
+name: {{name}}
+description: |
+{{#descriptionLines}}
+  {{{.}}}
+{{/descriptionLines}}
+{{#useWhenLines.length}}
+  **Use When:** {{#useWhenLines}}{{{.}}}{{/useWhenLines}}
+{{/useWhenLines.length}}
+---
 
 # {{{title}}}
 
-## Stage Guidance
+{{#useWhenLines.length}}
+**Use This Skill When:** {{#useWhenLines}}{{{.}}}{{/useWhenLines}}
+{{/useWhenLines.length}}
 
+## Stage Guidance
 {{#stages}}
 
 ### {{stageName}} Stage
 
 **Focus:** {{{focus}}}
 
-**Activities:** {{#activities}}
-
-- {{{.}}} {{/activities}}
+**Activities:**
+{{#activities}}
+- {{{.}}}
+{{/activities}}
 
-**Ready for {{nextStageName}} when:** {{#ready}}
+**Ready for {{nextStageName}} when:**
+{{#ready}}
+- [ ] {{{.}}}
+{{/ready}}
+{{/stages}}
+{{#toolReferences.length}}
 
-- [ ] {{{.}}} {{/ready}}
+## Recommended Tools
 
-{{/stages}} {{#reference}}
+| Tool | Use When |
+|------|----------|
+{{#toolReferences}}
+| {{#url}}[{{{name}}}]({{{url}}}){{/url}}{{^url}}{{{name}}}{{/url}} | {{{useWhen}}} |
+{{/toolReferences}}
+{{/toolReferences.length}}
+{{#reference}}
 
 ## Reference
 
-{{{reference}}} {{/reference}}
+{{{reference}}}
+{{/reference}}

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

@@ -1,130 +0,0 @@
----
-name: architecture-design
-description: |
-  Guide for designing software systems and making architectural decisions.
-  Use when asked to design a system, evaluate architecture options, or
-  make structural decisions about code organization.
----
-
-# Architecture & Design
-
-## Stage Guidance
-
-### Plan Stage
-
-**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
-
-### 1. Understand Requirements
-
-Before designing, clarify:
-
-- What problem are we solving?
-- What are the non-functional requirements (scale, latency, availability)?
-- What are the constraints (existing systems, team skills, timeline)?
-- What will change over time?
-
-### 2. Identify Key Decisions
-
-Architecture is the set of decisions that are hard to change:
-
-- Data storage and schema design
-- Service boundaries and communication patterns
-- Synchronous vs asynchronous processing
-- Stateful vs stateless components
-
-### 3. Evaluate Trade-offs
-
-Every architectural choice has trade-offs:
-
-- Consistency vs availability
-- Simplicity vs flexibility
-- Performance vs maintainability
-- Build vs buy
-
-Document trade-offs explicitly.
-
-### 4. Design for Change
-
-Good architecture accommodates change:
-
-- Separate what changes from what stays the same
-- Define clear interfaces between components
-- Prefer composition over inheritance
-- Make dependencies explicit
-
-## Common Patterns
-
-### Service Architecture
-
-- Microservices: Independent deployment, clear boundaries
-- Monolith: Simpler deployment, easier refactoring
-- Modular monolith: Boundaries within single deployment
-
-### Data Patterns
-
-- Event sourcing: Full audit trail, complex queries
-- CQRS: Separate read and write models
-- Repository pattern: Abstract data access
-
-### Communication Patterns
-
-- REST: Synchronous, request-response
-- Event-driven: Asynchronous, loose coupling
-- gRPC: Efficient, strongly typed

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

@@ -1,131 +0,0 @@
----
-name: cloud-platforms
-description: |
-  Guide for working with cloud infrastructure and services. Use when
-  deploying to cloud, selecting cloud services, configuring infrastructure,
-  or solving cloud-specific challenges.
----
-
-# Cloud Platforms
-
-## Stage Guidance
-
-### Plan Stage
-
-**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
-
-### Compute
-
-- **VMs/EC2**: Full control, any workload
-- **Containers/ECS/GKE**: Portable, scalable applications
-- **Serverless/Lambda**: Event-driven, pay-per-use
-- **Kubernetes**: Container orchestration at scale
-
-### Storage
-
-- **Object Storage (S3/GCS)**: Unstructured data, backups, static assets
-- **Block Storage (EBS)**: VM disks, databases
-- **File Storage (EFS)**: Shared file systems
-- **Archive (Glacier)**: Long-term, infrequent access
-
-### Databases
-
-- **Managed SQL (RDS/Cloud SQL)**: Relational, ACID transactions
-- **NoSQL (DynamoDB/Firestore)**: Flexible schema, high scale
-- **Cache (ElastiCache/Memorystore)**: Low-latency data access
-- **Data Warehouse (Redshift/BigQuery)**: Analytics at scale
-
-### Messaging
-
-- **Queues (SQS/Cloud Tasks)**: Decoupled processing
-- **Pub/Sub (SNS/Cloud Pub/Sub)**: Event distribution
-- **Streaming (Kinesis/Dataflow)**: Real-time data processing
-
-## Cloud-Native Design
-
-### Principles
-
-- Design for failure (everything fails eventually)
-- Use managed services when possible
-- Automate everything (infrastructure as code)
-- Monitor and alert on all services
-
-### High Availability
-
-- Deploy across multiple availability zones
-- Use load balancers for traffic distribution
-- Implement health checks and auto-healing
-- Design for graceful degradation
-
-### Security
-
-- Principle of least privilege for IAM
-- Encrypt data at rest and in transit
-- Use security groups and network policies
-- Rotate credentials regularly
-
-## Cost Optimization
-
-- Right-size instances based on actual usage
-- Use reserved instances for predictable workloads
-- Leverage spot/preemptible instances for fault-tolerant work
-- Set up billing alerts and budgets
-- Delete unused resources