@forwardimpact/schema 0.1.0

package/examples/capabilities/scale.yaml

@@ -0,0 +1,378 @@
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/capability.schema.json
+
+name: Scale
+emojiIcon: 📐
+displayOrder: 4
+description: |
+  Building systems that grow gracefully.
+  Encompasses architecture, code quality, testing, performance,
+  and technical decision-making.
+professionalResponsibilities:
+  awareness:
+    Follow established architectural patterns and coding standards with guidance
+    from senior engineers
+  foundational:
+    Contribute to scalable designs, write quality code with appropriate tests,
+    and understand architectural trade-offs
+  working:
+    Design scalable components, make sound architectural decisions, ensure code
+    quality, and review others' designs
+  practitioner:
+    Lead architectural decisions for complex systems across teams, establish
+    quality standards for your area, mentor engineers on architecture, and own
+    technical debt strategy
+  expert:
+    Define technical standards across the business unit, guide enterprise
+    architecture, be recognized externally for architectural expertise, and
+    drive innovation
+managementResponsibilities:
+  awareness:
+    Understand technical architecture decisions and their resource and timeline
+    implications
+  foundational:
+    Support team technical decisions, ensure alignment with architectural
+    standards, and escalate technical risks
+  working:
+    Facilitate architectural discussions, manage technical debt prioritization,
+    champion quality, and balance technical investment with delivery
+  practitioner:
+    Drive technical excellence across teams, establish quality standards for
+    your area, own cross-team technical direction, and advise on architecture
+    trade-offs
+  expert:
+    Shape technical strategy across the business unit, guide enterprise
+    architecture governance, and represent technical priorities at executive
+    level
+skills:
+  - id: cloud_platforms
+    name: Cloud Platforms
+    human:
+      description:
+        Working effectively with cloud infrastructure (AWS, Azure, GCP)
+      levelDescriptions:
+        awareness:
+          You understand cloud computing concepts (IaaS, PaaS, SaaS) and can use
+          cloud services through consoles and defined interfaces with guidance.
+        foundational:
+          You deploy applications to cloud platforms and use common services
+          (compute, storage, databases, queues). You understand cloud pricing
+          and basic security configuration.
+        working:
+          You design cloud-native solutions, manage infrastructure as code,
+          implement security best practices, and make informed service
+          selections. You troubleshoot cloud-specific issues.
+        practitioner:
+          You architect multi-region, highly available solutions across teams.
+          You optimize for cost and performance, lead cloud migrations for your
+          area, and mentor engineers on cloud architecture patterns.
+        expert:
+          You shape cloud strategy across the business unit. You solve
+          large-scale cloud challenges, define cloud governance, and are
+          recognized as an authority on cloud architecture.
+    agent:
+      name: cloud-platforms
+      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: |
+            Define cloud infrastructure requirements and constraints.
+            Clarify availability, security, and cost expectations.
+          activities:
+            - Document availability and reliability requirements
+            - Identify security and compliance constraints
+            - Specify cost budget and constraints
+            - Define performance requirements (latency, throughput)
+            - Mark ambiguities with [NEEDS CLARIFICATION]
+          ready:
+            - Availability requirements are documented
+            - Security requirements are specified
+            - Cost constraints are defined
+            - Performance requirements are clear
+        plan:
+          focus: Selecting and designing cloud architecture
+          activities:
+            - Evaluate service options for the use case
+            - Plan multi-AZ deployment for availability
+            - Design IAM roles with least privilege
+            - Estimate costs and plan resource sizing
+          ready:
+            - Service selection matches requirements
+            - Architecture designed for availability
+            - Security approach documented
+            - Cost estimate prepared
+        code:
+          focus: Implementing cloud infrastructure and deployments
+          activities:
+            - Define infrastructure as code (Terraform/CloudFormation)
+            - Configure security groups and network policies
+            - Set up encryption at rest and in transit
+            - Implement monitoring and alerting
+          ready:
+            - Infrastructure defined as code
+            - Security groups properly configured
+            - Encryption enabled for data
+            - Monitoring and alerting in place
+        review:
+          focus: Validating cloud configuration and security
+          activities:
+            - Verify IAM follows least privilege
+            - Check multi-AZ deployment
+            - Validate cost controls are in place
+            - Review security configuration
+          ready:
+            - IAM permissions are minimal
+            - Multi-AZ deployment confirmed
+            - Cost controls established
+            - Security review complete
+        deploy:
+          focus: |
+            Deploy cloud infrastructure and verify production readiness.
+            Confirm failover and monitoring work correctly.
+          activities:
+            - Deploy infrastructure to production
+            - Verify multi-AZ failover works
+            - Confirm monitoring and alerting are operational
+            - Validate cost tracking is in place
+          ready:
+            - Infrastructure deployed successfully
+            - Failover tested in production
+            - Monitoring is operational
+            - Cost tracking is active
+    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 |
+
+      ## Cloud-Native Principles
+      - Design for failure
+      - Use managed services
+      - Automate everything
+      - Monitor and alert
+  - id: code_quality
+    name: Code Quality & Review
+    human:
+      description:
+        Writing and reviewing clean, maintainable, tested, and well-documented
+        code. In the AI era, code review becomes more important than code
+        generation—every line must be understood and verified regardless of its
+        source.
+      levelDescriptions:
+        awareness:
+          You follow team coding conventions and style guides with guidance. You
+          understand why code quality matters and can run linters and tests
+          others have written.
+        foundational:
+          You write readable, well-structured code. You use linting tools, write
+          basic unit tests, and participate constructively in code reviews—both
+          giving and receiving feedback.
+        working:
+          You produce consistently high-quality, well-tested code. You review
+          AI-generated code critically and never ship code you don't fully
+          understand. You identify edge cases and ensure adequate test coverage.
+        practitioner:
+          You establish and enforce quality standards across teams in your area.
+          You mentor engineers on effective code review, ensure verification
+          depth for AI-assisted development, and drive testing strategies.
+        expert:
+          You shape coding standards and quality practices across the business
+          unit. You champion code review as a critical engineering skill, define
+          AI-assisted development guidelines, and are recognized for quality
+          engineering.
+    agent:
+      name: code-quality-review
+      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:
+          focus: |
+            Define code quality requirements and review criteria.
+            Clarify standards and acceptance criteria for the change.
+          activities:
+            - Identify applicable coding standards
+            - Document quality acceptance criteria
+            - Specify test coverage requirements
+            - Define review depth based on risk level
+            - Mark ambiguities with [NEEDS CLARIFICATION]
+          ready:
+            - Coding standards are identified
+            - Quality criteria are documented
+            - Test requirements are specified
+            - Review approach matches risk level
+        plan:
+          focus: Planning for quality before implementation
+          activities:
+            - Review project coding conventions
+            - Plan testing strategy for the feature
+            - Identify edge cases to handle
+            - Consider error handling approach
+          ready:
+            - Coding conventions understood
+            - Testing strategy defined
+            - Edge cases identified
+            - Error handling planned
+        code:
+          focus: Writing and testing quality code
+          activities:
+            - Follow project coding conventions
+            - Write tests alongside implementation
+            - Handle error conditions appropriately
+            - Self-review before requesting review
+          ready:
+            - Code follows project conventions
+            - Changes are covered by tests
+            - Error handling is appropriate
+            - Self-review completed
+        review:
+          focus: Verifying code quality and correctness
+          activities:
+            - Verify code does what it claims
+            - Check test coverage is adequate
+            - Evaluate maintainability
+            - Ensure no code you don't understand
+          ready:
+            - Code compiles and passes all tests
+            - No obvious security vulnerabilities
+            - No unnecessary complexity
+            - Documentation updated if needed
+        deploy:
+          focus: |
+            Merge and deploy reviewed code. Verify quality checks pass
+            in production pipeline.
+          activities:
+            - Merge approved changes
+            - Verify CI pipeline passes
+            - Monitor for issues after deployment
+            - Document any lessons learned
+          ready:
+            - Code merged successfully
+            - CI pipeline passes all checks
+            - No regressions detected
+            - Deployment verified
+    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?
+  - id: data_modeling
+    name: Data Modeling
+    human:
+      description:
+        Designing data structures and database schemas that support application
+        needs
+      levelDescriptions:
+        awareness:
+          You understand the difference between relational and non-relational
+          data stores. You can create basic schemas from specifications with
+          guidance.
+        foundational:
+          You design normalized schemas for straightforward use cases and
+          understand indexing basics. You write efficient queries for common
+          patterns.
+        working:
+          You create efficient data models that balance normalization with query
+          performance. You optimize queries, handle schema migrations safely,
+          and choose appropriate storage technologies.
+        practitioner:
+          You design complex data architectures spanning multiple systems across
+          teams. You make strategic trade-offs between consistency, performance,
+          and maintainability. You mentor engineers in your area on data
+          modeling best practices.
+        expert:
+          You define data modeling standards across the business unit. You
+          handle extreme scale and complex distributed data challenges, innovate
+          on approaches, and are recognized as a data architecture authority.
+    agent:
+      name: data-modeling
+      description: |
+        Guide for designing database schemas, data structures, and data
+        architectures.
+      useWhen: |
+        Designing tables, optimizing queries, or making decisions about data
+        storage technologies.
+      stages:
+        specify:
+          focus: |
+            Define data requirements and access patterns.
+            Clarify schema requirements before designing.
+          activities:
+            - Document data entities and relationships
+            - Identify query patterns and access requirements
+            - Specify consistency and performance requirements
+            - Define data retention and compliance needs
+            - Mark ambiguities with [NEEDS CLARIFICATION]
+          ready:
+            - Data entities are documented
+            - Query patterns are identified
+            - Performance requirements are specified
+            - Compliance needs are clear
+        plan:
+          focus: Understanding data requirements and designing schema
+          activities:
+            - Gather data requirements and access patterns
+            - Choose appropriate storage technology
+            - Design normalized schema
+            - Plan indexing strategy
+          ready:
+            - Requirements understood
+            - Storage technology selected
+            - Schema design documented
+            - Index strategy planned
+        code:
+          focus: Implementing schema and migrations
+          activities:
+            - Create database migrations
+            - Implement schema changes
+            - Add indexes for query patterns
+            - Write efficient queries
+          ready:
+            - Schema implemented correctly
+            - Indexes support query patterns
+            - Migrations are reversible
+            - Queries are optimized
+        review:
+          focus: Validating schema design and performance
+          activities:
+            - Verify schema matches requirements
+            - Check migration safety
+            - Validate query performance
+            - Review backward compatibility
+          ready:
+            - Schema meets requirements
+            - Migrations tested on production-like data
+            - Query performance acceptable
+            - Backward compatibility maintained
+        deploy:
+          focus: |
+            Deploy schema changes to production safely.
+            Verify data integrity and query performance.
+          activities:
+            - Run migrations in production
+            - Verify data integrity after migration
+            - Monitor query performance
+            - Confirm rollback plan works
+          ready:
+            - Migration completed successfully
+            - Data integrity verified
+            - Performance meets requirements
+            - Rollback procedure tested
+    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 |

package/examples/copilot-setup-steps.yaml

@@ -0,0 +1,25 @@
+# Copilot Coding Agent setup steps workflow
+# This workflow is executed when a Copilot Coding Agent starts
+# to prepare the environment for the agent session.
+#
+# Reference: https://docs.github.com/en/copilot/customizing-copilot/customizing-the-development-environment-for-copilot-coding-agent
+
+name: Copilot Setup Steps
+
+on: copilot_setup_steps
+
+jobs:
+  setup:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci

package/examples/devcontainer.yaml

@@ -0,0 +1,21 @@
+# Dev Container configuration template
+# Settings are dynamically populated at generation time
+
+# Base image for Node.js development
+image: mcr.microsoft.com/devcontainers/javascript-node:22-bookworm
+
+# VS Code customizations are populated dynamically from vscode-settings.yaml
+# customizations:
+#   vscode:
+#     settings: { ... dynamically injected ... }
+
+# Features to add to the dev container
+features:
+  ghcr.io/devcontainers/features/github-cli:1: {}
+
+# Lifecycle commands
+postCreateCommand: npm install
+
+# Forward ports from the container (e.g., for dev server)
+forwardPorts:
+  - 3000

package/examples/disciplines/_index.yaml

@@ -0,0 +1,6 @@
+# Auto-generated index for browser loading
+# Do not edit manually - regenerate with: npx pathway --generate-index
+files:
+  - data_engineering
+  - engineering_management
+  - software_engineering

package/examples/disciplines/data_engineering.yaml

@@ -0,0 +1,78 @@
+# yaml-language-server: $schema=https://schema.forwardimpact.team/json/discipline.schema.json
+
+specialization: Data Engineering
+roleTitle: Data Engineer
+isProfessional: true
+# null = allow trackless (generalist)
+validTracks:
+  - null
+  - platform
+  - sre
+
+# Shared content (human and agent)
+description:
+  Designs and builds data integration, storage systems, and data infrastructure
+  to enable analytics and AI. Masters the art of gaining access to enterprise
+  data and making it usable.
+
+# Derivation inputs
+coreSkills:
+  - data_modeling
+  - architecture_design
+  - cloud_platforms
+supportingSkills:
+  - code_quality
+  - full_stack_development
+  - devops
+  - sre_practices
+broadSkills:
+  - stakeholder_management
+  - technical_writing
+  - team_collaboration
+behaviourModifiers:
+  systems_thinking: 1
+  outcome_ownership: 1
+  relentless_curiosity: 1
+
+# Human-specific content
+human:
+  professionalRoleSummary:
+    We are seeking a skilled {roleTitle} who will design and build data
+    integration, storage systems, and data infrastructure that enable analytics
+    and AI capabilities. In this role, you will master the art of gaining access
+    to enterprise data and making it usable for decision-making across the
+    organization.
+  managementRoleSummary:
+    We are seeking an experienced {specialization} leader to build and lead
+    high-performing data engineering teams. In this role, you will drive the
+    strategic direction of our data infrastructure while developing talent and
+    ensuring data capabilities meet business needs. You will champion data
+    quality, governance, and the democratization of data across the
+    organization.
+
+# Agent-specific content
+agent:
+  identity: |
+    You are a {roleTitle} agent. Your focus is designing and building
+    data integration, storage systems, and data infrastructure that enables
+    analytics and AI capabilities.
+  priority: |
+    Data quality is paramount. Always validate data at ingestion points and
+    document schema assumptions. Treat undocumented schemas with suspicion.
+  beforeMakingChanges:
+    - Understand the data sources and their quality characteristics
+    - Map data lineage and dependencies
+    - Consider performance implications for downstream consumers
+  delegation: |
+    When facing tasks outside your expertise, use `runSubagent` to delegate:
+    - Statistical analysis or model validation → data science subagent
+    - Application code changes → software engineering subagent
+    - Infrastructure or deployment → SRE subagent
+
+    Subagents run in isolated context. Provide clear task descriptions and
+    specify what information to return.
+  constraints:
+    - Ignoring data quality issues
+    - Creating pipelines without proper error handling
+    - Undocumented schema changes
+    - Tight coupling between data producers and consumers

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: L2
+
+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

@@ -0,0 +1,78 @@
+# 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:
+  Builds and maintains software systems, focusing on code quality, architecture,
+  and reliable delivery of business value. In the AI era, emphasizes
+  verification and review of AI-generated code.
+
+# Derivation inputs
+coreSkills:
+  - architecture_design
+  - code_quality
+  - full_stack_development
+supportingSkills:
+  - devops
+  - cloud_platforms
+  - sre_practices
+broadSkills:
+  - data_modeling
+  - stakeholder_management
+  - technical_writing
+  - team_collaboration
+behaviourModifiers:
+  outcome_ownership: 1
+  systems_thinking: 1
+  relentless_curiosity: 1
+
+# Human-specific content
+human:
+  professionalRoleSummary:
+    We are seeking a skilled {roleTitle} who will design, build, and maintain
+    software systems that deliver business value. In this role, you will focus
+    on code quality, architecture decisions, and reliable delivery while
+    leveraging AI tools to enhance productivity. You will verify and review
+    AI-generated code to ensure it meets our quality standards.
+  managementRoleSummary:
+    We are seeking an experienced {specialization} leader to build and lead
+    high-performing software engineering teams. In this role, you will drive
+    technical excellence while developing talent and ensuring delivery of
+    business value. You will set technical direction, create space for
+    innovation, and model the ownership behaviors that define our engineering
+    culture.
+
+# Agent-specific content
+agent:
+  identity: |
+    You are a {roleTitle} agent. Your primary focus is writing 
+    correct, maintainable, well-tested code.
+  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.
+  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
+    - Complex debugging across unfamiliar systems → research subagent
+
+    Subagents run in isolated context. Provide clear task descriptions and
+    specify what information to return.
+  constraints:
+    - Committing code without running tests
+    - Making changes without understanding the existing codebase
+    - Ignoring error handling and edge cases
+    - Over-engineering simple solutions