@forwardimpact/pathway 0.3.0 → 0.4.0

package/examples/capabilities/reliability.yaml

@@ -72,9 +72,11 @@ skills:
     agent:
       name: devops-cicd
       description: |
-        Guide for building CI/CD pipelines, managing infrastructure as code, and
-        implementing deployment best practices. Use when setting up pipelines,
-        containerizing applications, or configuring infrastructure.
+        Guide for building CI/CD pipelines, managing infrastructure as code,
+        and implementing deployment best practices.
+      useWhen: |
+        Setting up pipelines, containerizing applications, or configuring
+        infrastructure.
       stages:
         specify:
           focus: |
@@ -153,64 +155,73 @@ skills:
             - Workflows tested in production
             - Monitoring confirms healthy operation
             - First deployment through pipeline succeeded
-      reference: |
-        ## CI/CD Pipeline Stages
+    toolReferences:
+      - name: Terraform
+        url: https://developer.hashicorp.com/terraform/docs
+        description: Infrastructure as code tool
+        useWhen: Provisioning and managing cloud infrastructure
+      - name: Docker
+        url: https://docs.docker.com/
+        description: Container platform
+        useWhen: Containerizing applications or managing container environments
+    implementationReference: |
+      ## CI/CD Pipeline Stages
 
-        ### Build
-        - Install dependencies
-        - Compile/transpile code
-        - Generate artifacts
-        - Cache dependencies for speed
+      ### Build
+      - Install dependencies
+      - Compile/transpile code
+      - Generate artifacts
+      - Cache dependencies for speed
 
-        ### Test
-        - Run unit tests
-        - Run integration tests
-        - Static analysis and linting
-        - Security scanning
+      ### Test
+      - Run unit tests
+      - Run integration tests
+      - Static analysis and linting
+      - Security scanning
 
-        ### Deploy
-        - Deploy to staging environment
-        - Run smoke tests
-        - Deploy to production
-        - Verify deployment health
+      ### Deploy
+      - Deploy to staging environment
+      - Run smoke tests
+      - Deploy to production
+      - Verify deployment health
 
-        ## Infrastructure as Code
+      ## Infrastructure as Code
 
-        ### Terraform
-        ```hcl
-        # Define resources declaratively
-        resource "aws_instance" "example" {
-          ami           = "ami-0c55b159cbfafe1f0"
-          instance_type = "t2.micro"
-        }
-        ```
+      ### Terraform
+      ```hcl
+      # Define resources declaratively
+      resource "aws_instance" "example" {
+        ami           = "ami-0c55b159cbfafe1f0"
+        instance_type = "t2.micro"
+      }
+      ```
 
-        ### Docker
-        ```dockerfile
-        FROM node:18-alpine
-        WORKDIR /app
-        COPY package*.json ./
-        RUN npm ci --only=production
-        COPY . .
-        CMD ["node", "server.js"]
-        ```
+      ### Docker
+      ```dockerfile
+      FROM node:18-alpine
+      WORKDIR /app
+      COPY package*.json ./
+      RUN npm ci --only=production
+      COPY . .
+      CMD ["node", "server.js"]
+      ```
 
-        ## Deployment Strategies
+      ## Deployment Strategies
 
-        ### Rolling Deployment
-        - Gradual replacement of instances
-        - Zero downtime
-        - Easy rollback
+      ### Rolling Deployment
+      - Gradual replacement of instances
+      - Zero downtime
+      - Easy rollback
 
-        ### Blue-Green Deployment
-        - Two identical environments
-        - Switch traffic atomically
-        - Fast rollback
+      ### Blue-Green Deployment
+      - Two identical environments
+      - Switch traffic atomically
+      - Fast rollback
 
-        ### Canary Deployment
-        - Route small percentage to new version
-        - Monitor for issues
-        - Gradually increase traffic
+      ### Canary Deployment
+      - Route small percentage to new version
+      - Monitor for issues
+      - Gradually increase traffic
   - id: sre_practices
     name: Site Reliability Engineering
     human:
@@ -241,8 +252,10 @@ skills:
       name: sre-practices
       description: |
         Guide for ensuring system reliability through observability, incident
-        response, and capacity planning. Use when designing monitoring, handling
-        incidents, setting SLOs, or improving system resilience.
+        response, and capacity planning.
+      useWhen: |
+        Designing monitoring, handling incidents, setting SLOs, or improving
+        system resilience.
       stages:
         specify:
           focus: |
@@ -322,78 +335,78 @@ skills:
             - Alerts fire correctly for SLO breaches
             - On-call team is trained and ready
             - Production readiness review is complete
-      reference: |
-        ## Service Level Concepts
+    implementationReference: |
+      ## Service Level Concepts
 
-        ### SLI (Service Level Indicator)
-        Quantitative measure of service behavior:
-        - Request latency (p50, p95, p99)
-        - Error rate (% of failed requests)
-        - Availability (% of successful requests)
-        - Throughput (requests per second)
+      ### SLI (Service Level Indicator)
+      Quantitative measure of service behavior:
+      - Request latency (p50, p95, p99)
+      - Error rate (% of failed requests)
+      - Availability (% of successful requests)
+      - Throughput (requests per second)
 
-        ### SLO (Service Level Objective)
-        Target value for an SLI:
-        - "99.9% of requests complete in < 200ms"
-        - "Error rate < 0.1% over 30 days"
-        - "99.95% availability monthly"
+      ### SLO (Service Level Objective)
+      Target value for an SLI:
+      - "99.9% of requests complete in < 200ms"
+      - "Error rate < 0.1% over 30 days"
+      - "99.95% availability monthly"
 
-        ### Error Budget
-        Allowed unreliability: 100% - SLO
-        - 99.9% SLO = 0.1% error budget
-        - ~43 minutes downtime per month
-        - Spend on features or reliability
+      ### Error Budget
+      Allowed unreliability: 100% - SLO
+      - 99.9% SLO = 0.1% error budget
+      - ~43 minutes downtime per month
+      - Spend on features or reliability
 
-        ## Observability
+      ## Observability
 
-        ### Three Pillars
-        - **Metrics**: Aggregated numeric data (counters, gauges, histograms)
-        - **Logs**: Discrete event records with context
-        - **Traces**: Request flow across services
+      ### Three Pillars
+      - **Metrics**: Aggregated numeric data (counters, gauges, histograms)
+      - **Logs**: Discrete event records with context
+      - **Traces**: Request flow across services
 
-        ### Alerting Principles
-        - Alert on symptoms, not causes
-        - Every alert should be actionable
-        - Reduce noise ruthlessly
-        - Page only for user-impacting issues
-        - Use severity levels appropriately
+      ### Alerting Principles
+      - Alert on symptoms, not causes
+      - Every alert should be actionable
+      - Reduce noise ruthlessly
+      - Page only for user-impacting issues
+      - Use severity levels appropriately
 
-        ## Incident Response
+      ## Incident Response
 
-        ### Incident Lifecycle
-        1. **Detection**: Automated alerts or user reports
-        2. **Triage**: Assess severity and impact
-        3. **Mitigation**: Stop the bleeding first
-        4. **Resolution**: Fix the underlying issue
-        5. **Post-mortem**: Learn and improve
+      ### Incident Lifecycle
+      1. **Detection**: Automated alerts or user reports
+      2. **Triage**: Assess severity and impact
+      3. **Mitigation**: Stop the bleeding first
+      4. **Resolution**: Fix the underlying issue
+      5. **Post-mortem**: Learn and improve
 
-        ### During an Incident
-        - Communicate early and often
-        - Focus on mitigation before root cause
-        - Document actions in real-time
-        - Escalate when needed
-        - Update stakeholders regularly
+      ### During an Incident
+      - Communicate early and often
+      - Focus on mitigation before root cause
+      - Document actions in real-time
+      - Escalate when needed
+      - Update stakeholders regularly
 
-        ## Post-Mortem Process
+      ## Post-Mortem Process
 
-        ### Blameless Culture
-        - Focus on systems, not individuals
-        - Assume good intentions
-        - Ask "how did the system allow this?"
-        - Share findings openly
+      ### Blameless Culture
+      - Focus on systems, not individuals
+      - Assume good intentions
+      - Ask "how did the system allow this?"
+      - Share findings openly
 
-        ### Post-Mortem Template
-        1. Incident summary
-        2. Timeline of events
-        3. Root cause analysis
-        4. What went well
-        5. What could be improved
-        6. Action items with owners
+      ### Post-Mortem Template
+      1. Incident summary
+      2. Timeline of events
+      3. Root cause analysis
+      4. What went well
+      5. What could be improved
+      6. Action items with owners
 
-        ## Resilience Patterns
+      ## Resilience Patterns
 
-        - **Timeouts**: Don't wait forever
-        - **Retries**: With exponential backoff
-        - **Circuit breakers**: Fail fast when downstream is unhealthy
-        - **Bulkheads**: Isolate failures
-        - **Graceful degradation**: Partial functionality over total failure
+      - **Timeouts**: Don't wait forever
+      - **Retries**: With exponential backoff
+      - **Circuit breakers**: Fail fast when downstream is unhealthy
+      - **Bulkheads**: Isolate failures
+      - **Graceful degradation**: Partial functionality over total failure

package/examples/capabilities/scale.yaml

@@ -71,10 +71,10 @@ skills:
           recognized as an authority on cloud architecture.
     agent:
       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.
+      description: Guide for working with cloud infrastructure and services.
+      useWhen: |
+        Deploying to cloud, selecting cloud services, configuring
+        infrastructure, or solving cloud-specific challenges.
       stages:
         specify:
           focus: |
@@ -141,21 +141,21 @@ skills:
             - Failover tested in production
             - Monitoring is operational
             - Cost tracking is active
-      reference: |
-        ## Service Categories
+    implementationReference: |
+      ## Service Categories
 
-        | Category | Services | Use Case |
-        |----------|----------|----------|
-        | Compute | EC2, ECS, Lambda | VMs, Containers, Serverless |
-        | Storage | S3, EBS, EFS | Objects, Blocks, Files |
-        | Database | RDS, DynamoDB | SQL, NoSQL |
-        | Messaging | SQS, SNS, Kinesis | Queues, Pub/Sub, Streaming |
+      | Category | Services | Use Case |
+      |----------|----------|----------|
+      | Compute | EC2, ECS, Lambda | VMs, Containers, Serverless |
+      | Storage | S3, EBS, EFS | Objects, Blocks, Files |
+      | Database | RDS, DynamoDB | SQL, NoSQL |
+      | Messaging | SQS, SNS, Kinesis | Queues, Pub/Sub, Streaming |
 
-        ## Cloud-Native Principles
-        - Design for failure
-        - Use managed services
-        - Automate everything
-        - Monitor and alert
+      ## Cloud-Native Principles
+      - Design for failure
+      - Use managed services
+      - Automate everything
+      - Monitor and alert
   - id: code_quality
     name: Code Quality & Review
     human:
@@ -188,9 +188,9 @@ skills:
           engineering.
     agent:
       name: code-quality-review
-      description: |
-        Guide for writing quality code and conducting code reviews. Use when
-        reviewing code, checking for best practices, or verifying AI-generated
+      description: Guide for writing quality code and conducting code reviews.
+      useWhen: |
+        Reviewing code, checking for best practices, or verifying AI-generated
         code before committing.
       stages:
         specify:
@@ -258,13 +258,13 @@ skills:
             - CI pipeline passes all checks
             - No regressions detected
             - Deployment verified
-      reference: |
-        ## Review Checklist
+    implementationReference: |
+      ## Review Checklist
 
-        1. **Correctness**: Does it work as intended?
-        2. **Tests**: Is it properly tested?
-        3. **Maintainability**: Will it be easy to change?
-        4. **Style**: Does it follow conventions?
+      1. **Correctness**: Does it work as intended?
+      2. **Tests**: Is it properly tested?
+      3. **Maintainability**: Will it be easy to change?
+      4. **Style**: Does it follow conventions?
   - id: data_modeling
     name: Data Modeling
     human:
@@ -297,8 +297,10 @@ skills:
       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.
+        architectures.
+      useWhen: |
+        Designing tables, optimizing queries, or making decisions about data
+        storage technologies.
       stages:
         specify:
           focus: |
@@ -365,12 +367,12 @@ skills:
             - Data integrity verified
             - Performance meets requirements
             - Rollback procedure tested
-      reference: |
-        ## Storage Selection Guide
+    implementationReference: |
+      ## Storage Selection Guide
 
-        | Type | Use When | Examples |
-        |------|----------|----------|
-        | Relational | ACID needed, complex queries | PostgreSQL, MySQL |
-        | Document | Flexible schema, hierarchical | MongoDB, Firestore |
-        | Key-Value | Simple lookups, caching | Redis, DynamoDB |
-        | Time Series | Temporal data, metrics | InfluxDB, TimescaleDB |
+      | Type | Use When | Examples |
+      |------|----------|----------|
+      | Relational | ACID needed, complex queries | PostgreSQL, MySQL |
+      | Document | Flexible schema, hierarchical | MongoDB, Firestore |
+      | Key-Value | Simple lookups, caching | Redis, DynamoDB |
+      | Time Series | Temporal data, metrics | InfluxDB, TimescaleDB |

package/examples/disciplines/engineering_management.yaml

@@ -3,7 +3,7 @@
 specialization: Engineering Management
 roleTitle: Engineering Manager
 isManagement: true
-minGrade: SE
+minGrade: L2
 
 description: |
   People and delivery leadership, focusing on team effectiveness,

package/examples/framework.yaml

@@ -55,3 +55,15 @@ entityDefinitions:
     emoji: "🤖"
     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
+    emoji: "🔄"
+    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
+    emoji: "🔧"
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/pathway",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Engineering Pathway framework for human and AI collaboration",
   "license": "Apache-2.0",
   "repository": {

package/templates/skill.template.md

@@ -1,27 +1,46 @@
 ---
 
-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}}
-
-**Ready for {{nextStageName}} when:** {{#ready}}
-
-- [ ] {{{.}}} {{/ready}}
-
-{{/stages}} {{#reference}}
+**Activities:**
+{{#activities}}
+- {{{.}}}
+{{/activities}}
+
+**Ready for {{nextStageName}} when:**
+{{#ready}}
+- [ ] {{{.}}}
+{{/ready}}
+{{/stages}}
+{{#toolReferences.length}}
+
+## Recommended Tools
+
+| Tool | Use When |
+|------|----------|
+{{#toolReferences}}
+| {{#url}}[{{{name}}}]({{{url}}}){{/url}}{{^url}}{{{name}}}{{/url}} | {{{useWhen}}} |
+{{/toolReferences}}
+{{/toolReferences.length}} {{#reference}}
 
 ## Reference