@forwardimpact/pathway 0.2.0 → 0.4.0

package/examples/capabilities/business.yaml

@@ -102,10 +102,10 @@ skills:
           initiatives.
     agent:
       name: technical-writing
-      description: |
-        Guide for creating clear technical documentation. Use when writing
-        READMEs, API docs, specifications, or any technical content that needs
-        to be clear and accurate.
+      description: Guide for creating clear technical documentation.
+      useWhen: |
+        Writing READMEs, API docs, specifications, or any technical content
+        that needs to be clear and accurate.
       stages:
         specify:
           focus: |
@@ -172,18 +172,18 @@ skills:
             - Audience can discover and find it
             - Search and navigation are updated
             - Maintenance schedule is established
-      reference: |
-        ## Document Types
+    implementationReference: |
+      ## Document Types
 
-        | Type | Purpose | Key Sections |
-        |------|---------|--------------|
-        | README | Project overview | Description, Getting Started, Usage |
-        | API Docs | API reference | Endpoints, Parameters, Examples |
-        | Spec | Design proposal | Problem, Solution, Alternatives |
-        | Tutorial | Learning guide | Objective, Steps, Outcomes |
+      | Type | Purpose | Key Sections |
+      |------|---------|--------------|
+      | README | Project overview | Description, Getting Started, Usage |
+      | API Docs | API reference | Endpoints, Parameters, Examples |
+      | Spec | Design proposal | Problem, Solution, Alternatives |
+      | Tutorial | Learning guide | Objective, Steps, Outcomes |
 
-        ## Writing Principles
-        - Use simple, direct language
-        - One idea per sentence
-        - Active voice over passive
-        - Lead with most important info
+      ## Writing Principles
+      - Use simple, direct language
+      - One idea per sentence
+      - Active voice over passive
+      - Lead with most important info

package/examples/capabilities/delivery.yaml

@@ -73,10 +73,11 @@ skills:
           architecture authority.
     agent:
       name: architecture-design
-      description: |
+      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.
+      useWhen: |
+        Asked to design a system, evaluate architecture options, or make
+        structural decisions about code organization.
       stages:
         specify:
           focus: |
@@ -144,23 +145,23 @@ skills:
             - Performance meets requirements
             - Monitoring confirms design assumptions
             - Operational procedures are documented
-      reference: |
-        ## Common Patterns
+    implementationReference: |
+      ## Common Patterns
 
-        ### Service Architecture
-        - **Microservices**: Independent deployment, clear boundaries
-        - **Monolith**: Simpler deployment, easier refactoring
-        - **Modular monolith**: Boundaries within single deployment
+      ### 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
+      ### 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
+      ### Communication Patterns
+      - **REST**: Synchronous, request-response
+      - **Event-driven**: Asynchronous, loose coupling
+      - **gRPC**: Efficient, strongly typed
   - id: full_stack_development
     name: Full-Stack Development
     human:
@@ -195,10 +196,11 @@ skills:
           polymathic engineering.
     agent:
       name: full-stack-development
-      description: |
+      description:
         Guide for building complete solutions across the full technology stack.
-        Use when implementing features spanning frontend, backend, database,
-        and infrastructure layers.
+      useWhen: |
+        Implementing features spanning frontend, backend, database, and
+        infrastructure layers.
       stages:
         specify:
           focus: |
@@ -266,23 +268,36 @@ skills:
             - Feature works end-to-end in production
             - No errors in monitoring
             - Performance meets requirements
-      reference: |
-        ## Technology Stack
+    toolReferences:
+      - name: Terraform
+        url: https://developer.hashicorp.com/terraform/docs
+        description: Infrastructure as code tool
+        useWhen: Provisioning and managing cloud infrastructure
+      - name: CloudFormation
+        url: https://docs.aws.amazon.com/cloudformation/
+        description: AWS infrastructure as code service
+        useWhen: Managing AWS infrastructure as code
+      - name: Docker
+        url: https://docs.docker.com/
+        description: Container platform
+        useWhen: Containerizing applications or managing container environments
+    implementationReference: |
+      ## Technology Stack
 
-        ### Primary Languages
-        - **JavaScript/TypeScript**: Frontend and Node.js backend
-        - **Python**: Backend APIs and data processing
+      ### Primary Languages
+      - **JavaScript/TypeScript**: Frontend and Node.js backend
+      - **Python**: Backend APIs and data processing
 
-        ### Infrastructure
-        - **Terraform**: Cloud infrastructure as code
-        - **CloudFormation**: AWS-specific infrastructure
-        - **Docker**: Containerization
+      ### Infrastructure
+      - **Terraform**: Cloud infrastructure as code
+      - **CloudFormation**: AWS-specific infrastructure
+      - **Docker**: Containerization
 
-        ## Layer Responsibilities
+      ## Layer Responsibilities
 
-        | Layer | Responsibilities |
-        |-------|-----------------|
-        | Frontend | UI/UX, client validation, API integration |
-        | Backend | Business logic, auth, external services |
-        | Database | Persistence, queries, migrations |
-        | Infrastructure | Deployment, scaling, monitoring |
+      | Layer | Responsibilities |
+      |-------|-----------------|
+      | Frontend | UI/UX, client validation, API integration |
+      | Backend | Business logic, auth, external services |
+      | Database | Persistence, queries, migrations |
+      | Infrastructure | Deployment, scaling, monitoring |

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.