@forwardimpact/schema 0.4.0 → 0.7.0

package/bin/fit-schema.js

@@ -116,7 +116,7 @@ function formatValidationResults(result) {
 async function runValidate(dataDir) {
   console.log(`🔍 Validating data in: ${dataDir}\n`);
 
-  const { runSchemaValidation, loadAllData } = await import("../lib/index.js");
+  const { runSchemaValidation, loadAllData } = await import("../src/index.js");
 
   // Load data first
   const data = await loadAllData(dataDir, { validate: false });
@@ -144,7 +144,7 @@ async function runValidate(dataDir) {
 async function runGenerateIndex(dataDir) {
   console.log(`📁 Generating index files in: ${dataDir}\n`);
 
-  const { generateAllIndexes } = await import("../lib/index.js");
+  const { generateAllIndexes } = await import("../src/index.js");
 
   const results = await generateAllIndexes(dataDir);
 

package/examples/capabilities/business.yaml

@@ -2,7 +2,7 @@
 
 name: Business
 emojiIcon: 💼
-displayOrder: 8
+ordinalRank: 8
 description: |
   Understanding and driving business value.
   Includes domain knowledge, stakeholder management, strategic thinking,
@@ -111,49 +111,65 @@ skills:
           focus: |
             Define documentation requirements and audience needs.
             Clarify what the documentation must accomplish.
-          activities:
+          readChecklist:
             - Identify target audience and their skill level
             - Document what questions the docs must answer
             - Define documentation type (README, API, spec, tutorial)
             - Specify accuracy and completeness requirements
             - Mark ambiguities with [NEEDS CLARIFICATION]
-          ready:
+          confirmChecklist:
             - Audience is identified
             - Questions to answer are documented
             - Documentation type is chosen
             - Requirements are clear
         plan:
           focus: Understanding audience and planning documentation
-          activities:
+          readChecklist:
             - Identify target audience and their needs
             - Determine document type and structure
             - List prerequisites and assumptions
             - Outline key sections and content
-          ready:
+          confirmChecklist:
             - Audience is identified
             - Document type and structure planned
             - Prerequisites listed
             - Outline complete
+        onboard:
+          focus: |
+            Set up the documentation environment. Install documentation
+            tools, configure rendering, and verify preview works.
+          readChecklist:
+            - Install documentation framework (MkDocs, Docusaurus, etc.)
+            - Configure markdown linter (markdownlint)
+            - Set up diagram rendering (Mermaid, PlantUML)
+            - Configure spell checker (cspell)
+            - Verify documentation preview server works
+          confirmChecklist:
+            - Documentation framework builds without errors
+            - Markdown linter runs and catches issues
+            - Diagrams render correctly in preview
+            - Spell checker configured with project dictionary
+            - Preview server shows formatted documentation
         code:
           focus: Writing clear and accurate documentation
-          activities:
+          readChecklist:
             - Write using simple, direct language
             - Structure content for scanning
             - Include tested, runnable examples
             - Define technical terms
-          ready:
+          confirmChecklist:
             - Purpose clear in first paragraph
             - Examples are tested and work
             - Technical terms are defined
             - Structure supports scanning
         review:
           focus: Verifying documentation quality
-          activities:
+          readChecklist:
             - Check accuracy against implementation
             - Verify examples are runnable
             - Review for clarity and completeness
             - Test with target audience if possible
-          ready:
+          confirmChecklist:
             - Documentation matches implementation
             - All examples verified working
             - No ambiguous pronouns
@@ -162,12 +178,12 @@ skills:
           focus: |
             Publish documentation and ensure it reaches the audience.
             Set up maintenance process.
-          activities:
+          readChecklist:
             - Publish to documentation site
             - Announce to relevant teams
             - Add to search indexes and navigation
             - Establish update and review schedule
-          ready:
+          confirmChecklist:
             - Documentation is published and accessible
             - Audience can discover and find it
             - Search and navigation are updated

package/examples/capabilities/delivery.yaml

@@ -2,7 +2,7 @@
 
 name: Delivery
 emojiIcon: 🚀
-displayOrder: 1
+ordinalRank: 1
 description: |
   Building and shipping solutions that solve real problems.
   Encompasses full-stack development, data integration, problem discovery,
@@ -83,51 +83,68 @@ skills:
           focus: |
             Define system requirements and constraints before design.
             Clarify functional and non-functional requirements.
-          activities:
+          readChecklist:
             - Document functional requirements and use cases
             - Identify non-functional requirements (scale, latency,
               availability)
             - Document system constraints and integration points
             - Identify stakeholders and their concerns
             - Mark ambiguities with [NEEDS CLARIFICATION]
-          ready:
+          confirmChecklist:
             - Functional requirements are documented
             - Non-functional requirements are specified
             - Constraints are identified
             - Stakeholder concerns are understood
         plan:
           focus: Understanding requirements and designing solutions
-          activities:
+          readChecklist:
             - Gather context about existing systems and constraints
             - Clarify non-functional requirements (scale, latency, availability)
             - Identify key decisions that are hard to change later
             - Evaluate trade-offs between architectural options
             - Document approach with rationale
-          ready:
+          confirmChecklist:
             - Requirements are clearly understood
             - Key decisions are documented with rationale
             - Trade-offs are explicit
             - Dependencies are identified
+        onboard:
+          focus: |
+            Set up the development environment for the planned
+            architecture. Install frameworks, configure project
+            structure, and verify tooling.
+          readChecklist:
+            - Install planned frameworks and dependencies
+            - Create project structure matching architecture design
+            - Configure Mermaid rendering for architecture docs
+            - Set up ADR directory for decision records
+            - Configure linter and formatter for the project
+          confirmChecklist:
+            - Project structure reflects architectural boundaries
+            - All planned frameworks installed and importable
+            - Documentation tooling renders diagrams correctly
+            - Linter and formatter configured and passing
+            - Build system compiles without errors
         code:
           focus: Implementing architecture faithfully while adapting to reality
-          activities:
+          readChecklist:
             - Verify implementation aligns with design decisions
             - Implement interfaces and boundaries before internals
             - Document any deviations from design with rationale
             - Keep architecture documentation in sync with implementation
-          ready:
+          confirmChecklist:
             - Implementation matches documented design
             - Deviations documented with rationale
             - Failure modes are considered and handled
             - Security implications are reviewed
         review:
           focus: Verifying architecture implementation and documentation
-          activities:
+          readChecklist:
             - Compare implementation to design documentation
             - Verify all decisions were followed or documented
             - Assess maintainability and extensibility
             - Ensure architecture enables future changes
-          ready:
+          confirmChecklist:
             - Design docs reflect actual implementation
             - Architecture decisions validated in practice
             - Scalability requirements addressed
@@ -135,12 +152,12 @@ skills:
           focus: |
             Deploy architecture and verify it performs as designed
             in production environment.
-          activities:
+          readChecklist:
             - Deploy system components to production
             - Verify architectural boundaries work under load
             - Monitor performance against requirements
             - Document any operational learnings
-          ready:
+          confirmChecklist:
             - System deployed successfully
             - Performance meets requirements
             - Monitoring confirms design assumptions
@@ -206,50 +223,69 @@ skills:
           focus: |
             Define full-stack feature requirements and acceptance criteria.
             Clarify user needs and system integration points.
-          activities:
+          readChecklist:
             - Identify user stories and acceptance criteria
             - Document expected user interactions
             - Clarify integration requirements with existing systems
             - Define non-functional requirements (performance, security)
             - Mark ambiguities with [NEEDS CLARIFICATION]
-          ready:
+          confirmChecklist:
             - User stories are documented
             - Acceptance criteria are defined
             - Integration points are identified
             - Non-functional requirements are clear
         plan:
           focus: Designing the complete solution across layers
-          activities:
+          readChecklist:
             - Define the API contract between frontend and backend
             - Design database schema to support the feature
             - Plan infrastructure requirements
             - Identify cross-layer dependencies
-          ready:
+          confirmChecklist:
             - API contract is defined
             - Database schema is designed
             - Infrastructure needs identified
             - Layer boundaries are clear
+        onboard:
+          focus: |
+            Set up the full-stack development environment.
+            Install dependencies for each layer and verify
+            connectivity between layers.
+          readChecklist:
+            - Install frontend dependencies (e.g., npm install)
+            - Install backend dependencies and runtime
+            - Start local database and verify connection
+            - Configure environment variables (.env files)
+            - Verify API layer can connect to database
+            - Set up linter and formatter for the project
+          confirmChecklist:
+            - Frontend dev server starts without errors
+            - Backend API responds to health checks
+            - Database is running and seeded with test data
+            - Environment variables configured for all layers
+            - Linter and formatter configured and passing
+            - Build commands succeed for all layers
         code:
           focus: Building vertically across all layers
-          activities:
+          readChecklist:
             - Implement backend API endpoints
             - Build frontend components and integrate with API
             - Set up database migrations and queries
             - Configure infrastructure as code
             - Test across layer boundaries
-          ready:
+          confirmChecklist:
             - Frontend connects to backend correctly
             - Database schema supports the feature
             - Error handling spans all layers
             - Feature works end-to-end
         review:
           focus: Verifying integration across the stack
-          activities:
+          readChecklist:
             - Test complete user flows end-to-end
             - Verify error handling at each layer
             - Check deployment pipeline works
             - Validate monitoring and logging
-          ready:
+          confirmChecklist:
             - End-to-end tests pass
             - Deployment is automated
             - Cross-layer errors are handled gracefully
@@ -257,13 +293,13 @@ skills:
           focus: |
             Deploy full-stack feature to production and verify end-to-end
             functionality in live environment.
-          activities:
+          readChecklist:
             - Deploy backend services
             - Deploy frontend changes
             - Run database migrations
             - Verify feature works in production
             - Monitor for errors and performance issues
-          ready:
+          confirmChecklist:
             - All components deployed successfully
             - Feature works end-to-end in production
             - No errors in monitoring
@@ -273,16 +309,18 @@ skills:
         url: https://developer.hashicorp.com/terraform/docs
         simpleIcon: terraform
         description: Infrastructure as code tool
-        useWhen: Provisioning and managing cloud infrastructure
+        useWhen: Provisioning and managing cloud infrastructure as code
       - 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/
+        useWhen: Managing cloud infrastructure using declarative templates
+      - name: Colima
+        url: https://github.com/abiosoft/colima
         simpleIcon: docker
-        description: Container platform
-        useWhen: Containerizing applications or managing container environments
+        description: Container runtime for macOS with Docker-compatible CLI
+        useWhen:
+          Running containers locally, building images, or containerizing
+          applications
     implementationReference: |
       ## Technology Stack
 

package/examples/capabilities/people.yaml

@@ -2,7 +2,7 @@
 
 name: People
 emojiIcon: 👥
-displayOrder: 6
+ordinalRank: 6
 description: |
   Growing individuals and building effective teams.
   Includes mentoring, coaching, hiring, performance management,

package/examples/capabilities/reliability.yaml

@@ -2,7 +2,7 @@
 
 name: Reliability
 emojiIcon: 🛡️
-displayOrder: 5
+ordinalRank: 5
 description: |
   Ensuring systems are dependable, secure, and observable.
   Includes DevOps practices, security, monitoring, incident response,
@@ -82,13 +82,13 @@ skills:
           focus: |
             Define CI/CD and infrastructure requirements.
             Clarify deployment strategy and operational needs.
-          activities:
+          readChecklist:
             - Document deployment frequency requirements
             - Identify rollback and recovery requirements
             - Specify monitoring and alerting needs
             - Define security and compliance constraints
             - Mark ambiguities with [NEEDS CLARIFICATION]
-          ready:
+          confirmChecklist:
             - Deployment requirements are documented
             - Recovery requirements are specified
             - Monitoring needs are identified
@@ -97,29 +97,45 @@ skills:
           focus: |
             Plan CI/CD pipeline architecture and infrastructure requirements.
             Consider deployment strategies and monitoring needs.
-          activities:
+          readChecklist:
             - Define pipeline stages (build, test, deploy)
             - Identify infrastructure requirements
             - Plan deployment strategy (rolling, blue-green, canary)
             - Consider monitoring and alerting needs
             - Plan secret management approach
-          ready:
+          confirmChecklist:
             - Pipeline architecture is documented
             - Deployment strategy is chosen and justified
             - Infrastructure requirements are identified
             - Monitoring approach is defined
+        onboard:
+          focus: |
+            Set up the CI/CD and infrastructure development environment.
+            Install pipeline tools, container runtime, and IaC tooling.
+          readChecklist:
+            - Install container runtime (Docker/Colima)
+            - Install infrastructure as code tools (Terraform)
+            - Configure CI/CD service credentials
+            - Initialize Terraform workspace and backend
+            - Set up secret management for pipeline credentials
+          confirmChecklist:
+            - Container runtime builds and runs images
+            - Terraform initialized with providers
+            - CI/CD credentials configured securely
+            - Pipeline configuration file created
+            - Secret management is in place
         code:
           focus: |
             Implement CI/CD pipelines and infrastructure as code. Follow
             best practices for containerization and deployment automation.
-          activities:
+          readChecklist:
             - Configure CI/CD pipeline stages
             - Implement infrastructure as code (Terraform, CloudFormation)
             - Create Dockerfiles with security best practices
             - Set up monitoring and alerting
             - Configure secret management
             - Implement deployment automation
-          ready:
+          confirmChecklist:
             - Pipeline runs on every commit
             - Tests run before deployment
             - Deployments are automated
@@ -130,13 +146,13 @@ skills:
           focus: |
             Verify pipeline reliability, security, and operational readiness.
             Ensure rollback procedures work and documentation is complete.
-          activities:
+          readChecklist:
             - Verify pipeline runs successfully end-to-end
             - Test rollback procedures
             - Review security configurations
             - Validate monitoring and alerts
             - Check documentation completeness
-          ready:
+          confirmChecklist:
             - Pipeline is tested and reliable
             - Rollback procedure is documented and tested
             - Alerts are configured and tested
@@ -145,12 +161,12 @@ skills:
           focus: |
             Deploy pipeline and infrastructure changes to production.
             Verify operational readiness.
-          activities:
+          readChecklist:
             - Deploy pipeline configuration to production
             - Verify deployment workflows work correctly
             - Confirm monitoring and alerting are operational
             - Run deployment through the new pipeline
-          ready:
+          confirmChecklist:
             - Pipeline deployed and operational
             - Workflows tested in production
             - Monitoring confirms healthy operation
@@ -160,12 +176,14 @@ skills:
         url: https://developer.hashicorp.com/terraform/docs
         simpleIcon: terraform
         description: Infrastructure as code tool
-        useWhen: Provisioning and managing cloud infrastructure
-      - name: Docker
-        url: https://docs.docker.com/
+        useWhen: Provisioning and managing cloud infrastructure as code
+      - name: Colima
+        url: https://github.com/abiosoft/colima
         simpleIcon: docker
-        description: Container platform
-        useWhen: Containerizing applications or managing container environments
+        description: Container runtime for macOS with Docker-compatible CLI
+        useWhen:
+          Running containers locally, building images, or containerizing
+          applications
     implementationReference: |
       ## CI/CD Pipeline Stages
 
@@ -189,13 +207,32 @@ skills:
 
       ## Infrastructure as Code
 
-      ### Terraform
+      ### Terraform Workflow
+      ```bash
+      terraform init      # Initialize providers and backend
+      terraform plan      # Preview changes before applying
+      terraform apply     # Apply changes to infrastructure
+      terraform destroy   # Tear down infrastructure
+      ```
+
+      ### Terraform in CI/CD Pipelines
+      1. **Plan on PR**: Run `terraform plan` on pull requests
+      2. **Review output**: Require approval for destructive changes
+      3. **Apply on merge**: Run `terraform apply` after merge to main
+      4. **State locking**: Use remote backend with locking (S3 + DynamoDB)
+
+      ### Terraform Structure
       ```hcl
-      # Define resources declaratively
-      resource "aws_instance" "example" {
-        ami           = "ami-0c55b159cbfafe1f0"
-        instance_type = "t2.micro"
+      # main.tf - Define resources declaratively
+      resource "aws_instance" "app" {
+        ami           = var.ami_id
+        instance_type = var.instance_type
+        tags = { Environment = var.environment }
       }
+
+      # variables.tf - Parameterize for environments
+      variable "environment" { type = string }
+      variable "instance_type" { default = "t3.micro" }
       ```
 
       ### Docker
@@ -263,13 +300,13 @@ skills:
           focus: |
             Define reliability requirements and SLO targets.
             Identify critical user journeys that need protection.
-          activities:
+          readChecklist:
             - Identify critical user journeys and business impact
             - Document reliability requirements (availability, latency)
             - Define SLO targets with stakeholder agreement
             - Specify acceptable error budgets
             - Mark ambiguities with [NEEDS CLARIFICATION]
-          ready:
+          confirmChecklist:
             - Critical user journeys are identified
             - Reliability requirements are documented
             - SLO targets are defined
@@ -278,30 +315,47 @@ skills:
           focus: |
             Define reliability requirements, SLIs/SLOs, and observability
             strategy. Plan for resilience and capacity needs.
-          activities:
+          readChecklist:
             - Define SLIs for key user journeys
             - Set SLOs with stakeholder agreement
             - Plan observability strategy (metrics, logs, traces)
             - Identify failure modes and resilience patterns
             - Define alerting thresholds
-          ready:
+          confirmChecklist:
             - SLIs defined for key user journeys
             - SLOs set with stakeholder agreement
             - Monitoring strategy is planned
             - Failure modes are identified
             - Alerting thresholds are defined
+        onboard:
+          focus: |
+            Set up the observability and monitoring environment.
+            Install monitoring tools, configure dashboards, and verify
+            instrumentation libraries work.
+          readChecklist:
+            - Install monitoring/observability tools (Prometheus, Grafana)
+            - Configure tracing library (OpenTelemetry)
+            - Set up logging framework with structured output
+            - Configure dashboard templates for SLI tracking
+            - Verify instrumentation exports metrics correctly
+          confirmChecklist:
+            - Monitoring tools installed and accessible
+            - Tracing library integrated and exporting spans
+            - Logging outputs structured data
+            - Dashboard templates render correctly
+            - Instrumentation verified with test traffic
         code:
           focus: |
             Implement observability, resilience patterns, and operational
             tooling. Build systems that fail gracefully and recover quickly.
-          activities:
+          readChecklist:
             - Implement metrics, logging, and tracing
             - Configure alerts based on SLOs
             - Implement resilience patterns (timeouts, retries, circuit
               breakers)
             - Create runbooks for common issues
             - Set up error budget tracking
-          ready:
+          confirmChecklist:
             - Comprehensive monitoring is in place
             - Alerts are actionable and low-noise
             - Resilience patterns are implemented
@@ -311,13 +365,13 @@ skills:
           focus: |
             Verify reliability implementation meets SLOs and operational
             readiness. Ensure incident response procedures are in place.
-          activities:
+          readChecklist:
             - Validate SLOs are measurable
             - Test failure scenarios
             - Review runbook completeness
             - Verify incident response procedures
             - Check alert quality and coverage
-          ready:
+          confirmChecklist:
             - SLOs are measurable and validated
             - Failure scenarios are tested
             - Incident response process documented
@@ -327,12 +381,12 @@ skills:
           focus: |
             Deploy reliability infrastructure and verify production
             monitoring. Ensure on-call readiness.
-          activities:
+          readChecklist:
             - Deploy monitoring and alerting to production
             - Verify dashboards and alerts work correctly
             - Confirm on-call rotation is ready
             - Run production readiness review
-          ready:
+          confirmChecklist:
             - Monitoring is live in production
             - Alerts fire correctly for SLO breaches
             - On-call team is trained and ready