@forwardimpact/schema 0.6.0 → 0.7.0

package/examples/capabilities/scale.yaml

@@ -80,49 +80,66 @@ skills:
           focus: |
             Define cloud infrastructure requirements and constraints.
             Clarify availability, security, and cost expectations.
-          activities:
+          readChecklist:
             - 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:
+          confirmChecklist:
             - Availability requirements are documented
             - Security requirements are specified
             - Cost constraints are defined
             - Performance requirements are clear
         plan:
           focus: Selecting and designing cloud architecture
-          activities:
+          readChecklist:
             - 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:
+          confirmChecklist:
             - Service selection matches requirements
             - Architecture designed for availability
             - Security approach documented
             - Cost estimate prepared
+        onboard:
+          focus: |
+            Set up cloud development environment. Configure CLI tools,
+            authenticate with cloud provider, and verify infrastructure
+            tooling works.
+          readChecklist:
+            - Install cloud CLI tools (AWS CLI, Terraform)
+            - Configure cloud credentials and authentication
+            - Initialize Terraform workspace and providers
+            - Verify cloud account access and permissions
+            - Set up environment variables for cloud configuration
+          confirmChecklist:
+            - Cloud CLI authenticated and working
+            - Terraform initialized with correct providers
+            - IAM permissions verified for planned resources
+            - Environment variables configured securely
+            - Infrastructure as code directory structure created
         code:
           focus: Implementing cloud infrastructure and deployments
-          activities:
+          readChecklist:
             - 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:
+          confirmChecklist:
             - 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:
+          readChecklist:
             - Verify IAM follows least privilege
             - Check multi-AZ deployment
             - Validate cost controls are in place
             - Review security configuration
-          ready:
+          confirmChecklist:
             - IAM permissions are minimal
             - Multi-AZ deployment confirmed
             - Cost controls established
@@ -131,12 +148,12 @@ skills:
           focus: |
             Deploy cloud infrastructure and verify production readiness.
             Confirm failover and monitoring work correctly.
-          activities:
+          readChecklist:
             - Deploy infrastructure to production
             - Verify multi-AZ failover works
             - Confirm monitoring and alerting are operational
             - Validate cost tracking is in place
-          ready:
+          confirmChecklist:
             - Infrastructure deployed successfully
             - Failover tested in production
             - Monitoring is operational
@@ -197,49 +214,67 @@ skills:
           focus: |
             Define code quality requirements and review criteria.
             Clarify standards and acceptance criteria for the change.
-          activities:
+          readChecklist:
             - 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:
+          confirmChecklist:
             - 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:
+          readChecklist:
             - Review project coding conventions
             - Plan testing strategy for the feature
             - Identify edge cases to handle
             - Consider error handling approach
-          ready:
+          confirmChecklist:
             - Coding conventions understood
             - Testing strategy defined
             - Edge cases identified
             - Error handling planned
+        onboard:
+          focus: |
+            Set up code quality tooling. Configure linters, formatters,
+            testing frameworks, and pre-commit hooks for the project.
+          readChecklist:
+            - Install linter (ESLint for JS/TS, Ruff for Python)
+            - Install formatter (Prettier for JS/TS, Ruff for Python)
+            - Configure linter rules matching project standards
+            - Set up pre-commit hooks (husky/lint-staged or pre-commit)
+            - Install testing framework (Node.js test runner, pytest)
+            - Configure editor settings for format-on-save
+          confirmChecklist:
+            - Linter runs without configuration errors
+            - Formatter produces consistent output
+            - Pre-commit hooks catch style violations
+            - Test runner discovers and runs existing tests
+            - Editor integration works (format-on-save, inline errors)
+            - CI pipeline includes quality checks
         code:
           focus: Writing and testing quality code
-          activities:
+          readChecklist:
             - Follow project coding conventions
             - Write tests alongside implementation
             - Handle error conditions appropriately
             - Self-review before requesting review
-          ready:
+          confirmChecklist:
             - Code follows project conventions
             - Changes are covered by tests
             - Error handling is appropriate
             - Self-review completed
         review:
           focus: Verifying code quality and correctness
-          activities:
+          readChecklist:
             - Verify code does what it claims
             - Check test coverage is adequate
             - Evaluate maintainability
             - Ensure no code you don't understand
-          ready:
+          confirmChecklist:
             - Code compiles and passes all tests
             - No obvious security vulnerabilities
             - No unnecessary complexity
@@ -248,12 +283,12 @@ skills:
           focus: |
             Merge and deploy reviewed code. Verify quality checks pass
             in production pipeline.
-          activities:
+          readChecklist:
             - Merge approved changes
             - Verify CI pipeline passes
             - Monitor for issues after deployment
             - Document any lessons learned
-          ready:
+          confirmChecklist:
             - Code merged successfully
             - CI pipeline passes all checks
             - No regressions detected
@@ -306,49 +341,66 @@ skills:
           focus: |
             Define data requirements and access patterns.
             Clarify schema requirements before designing.
-          activities:
+          readChecklist:
             - 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:
+          confirmChecklist:
             - 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:
+          readChecklist:
             - Gather data requirements and access patterns
             - Choose appropriate storage technology
             - Design normalized schema
             - Plan indexing strategy
-          ready:
+          confirmChecklist:
             - Requirements understood
             - Storage technology selected
             - Schema design documented
             - Index strategy planned
+        onboard:
+          focus: |
+            Set up the database environment. Install ORM/query tools,
+            configure database connections, and verify migration
+            tooling works.
+          readChecklist:
+            - Install database client and ORM (Prisma, SQLAlchemy)
+            - Configure database connection in .env file
+            - Start local database (Supabase, PostgreSQL, etc.)
+            - Initialize migration tooling and verify it connects
+            - Create database user with appropriate privileges
+          confirmChecklist:
+            - Database running locally and accepting connections
+            - ORM/client configured and connected
+            - Migration tooling initialized and working
+            - Test data can be seeded and queried
+            - Database credentials stored securely in .env
         code:
           focus: Implementing schema and migrations
-          activities:
+          readChecklist:
             - Create database migrations
             - Implement schema changes
             - Add indexes for query patterns
             - Write efficient queries
-          ready:
+          confirmChecklist:
             - Schema implemented correctly
             - Indexes support query patterns
             - Migrations are reversible
             - Queries are optimized
         review:
           focus: Validating schema design and performance
-          activities:
+          readChecklist:
             - Verify schema matches requirements
             - Check migration safety
             - Validate query performance
             - Review backward compatibility
-          ready:
+          confirmChecklist:
             - Schema meets requirements
             - Migrations tested on production-like data
             - Query performance acceptable
@@ -357,12 +409,12 @@ skills:
           focus: |
             Deploy schema changes to production safely.
             Verify data integrity and query performance.
-          activities:
+          readChecklist:
             - Run migrations in production
             - Verify data integrity after migration
             - Monitor query performance
             - Confirm rollback plan works
-          ready:
+          confirmChecklist:
             - Migration completed successfully
             - Data integrity verified
             - Performance meets requirements

package/examples/framework.yaml

@@ -6,6 +6,10 @@ tag: "#AcmeCorp"
 description: |
   A unified framework for human and AI collaboration in engineering. Define roles, track skills and behaviours, build career paths, and generate AI coding agents—all from the same coherent foundation. The pathway aligns human capabilities with AI assistance, enabling productive teams in the AI era.
 
+# Distribution configuration
+distribution:
+  siteUrl: https://pathway.example.com
+
 # Entity definitions for pages and chapters
 entityDefinitions:
   driver:
@@ -28,7 +32,7 @@ entityDefinitions:
 
   discipline:
     title: Disciplines
-    emojiIcon: "🔧"
+    emojiIcon: "🔬"
     description: |
       Engineering specializations that define T-shaped skill profiles. Each discipline specifies primary skills for deep expertise, secondary skills for supporting capabilities, and broad skills for general awareness. Disciplines answer the question: "What kind of engineer are you?"
 

package/examples/stages.yaml

@@ -23,8 +23,8 @@
     - Write specifications as markdown files under specs/[feature-name]/spec.md
     - Mark ambiguities with [NEEDS CLARIFICATION]; ask the user; do not guess
     - No technology choices, APIs, or code structure in specifications
-  entryCriteria: []
-  exitCriteria:
+  readChecklist: []
+  confirmChecklist:
     - spec.md exists with user stories and acceptance criteria
     - No unresolved [NEEDS CLARIFICATION] markers in spec.md
 
@@ -42,23 +42,59 @@
     - targetStage: plan
       label: Alternative Plan
       prompt: Create an alternative plan.md exploring a different approach.
-    - targetStage: code
-      label: Start Coding
-      prompt: Implement the tasks defined in plan.md.
+    - targetStage: onboard
+      label: Set Up Environment
+      prompt: Prepare the development environment based on plan.md requirements.
   constraints:
     - Do not make code edits or execute commands
     - Every technology choice must trace back to a specific requirement
     - Write plans as markdown files under specs/[feature-name]/plan.md
     - Define contracts and data models before implementation details
     - Document rationale for architectural decisions
-  entryCriteria:
+  readChecklist: []
+  confirmChecklist:
     - spec.md exists with user stories and acceptance criteria
     - No unresolved [NEEDS CLARIFICATION] markers in spec.md
-  exitCriteria:
     - plan.md exists with technology choices and architecture
     - Contracts and data models defined where applicable
     - No unresolved [NEEDS CLARIFICATION] markers in plan.md
 
+- id: onboard
+  name: Onboard
+  emojiIcon: "🔧"
+  summary:
+    Prepares the development environment with dependencies, tools, and credentials
+  description:
+    Your primary task is to prepare the development environment with all
+    prerequisites for coding. Install dependencies, configure tools, set up
+    credentials, and verify the environment is ready for implementation.
+  handoffs:
+    - targetStage: onboard
+      label: Retry Setup
+      prompt: Re-run the environment setup to fix remaining issues.
+    - targetStage: plan
+      label: Update Plan
+      prompt: Update plan.md because the environment setup revealed issues.
+    - targetStage: code
+      label: Start Coding
+      prompt: Implement the tasks defined in plan.md.
+  constraints:
+    - Do not implement feature code; focus only on environment setup
+    - Verify each tool and dependency works before moving on
+    - Document all environment configuration in a reproducible way
+    - Never hardcode secrets; use .env files or secret managers
+    - Track progress with the todo tool
+  readChecklist: []
+  confirmChecklist:
+    - plan.md exists with technology choices and architecture
+    - No unresolved [NEEDS CLARIFICATION] markers in plan.md
+    - All dependencies installed and versions verified
+    - Environment variables and secrets configured (.env files, tokens)
+    - Linter and formatter configured and passing on existing code
+    - Build and test commands run successfully
+    - Version control hooks and CI checks are operational
+    - Development server or runtime starts without errors
+
 - id: code
   name: Code
   emojiIcon: "💻"
@@ -74,11 +110,14 @@
     - Implement one task at a time, verify before moving on
     - Write tests alongside implementation
     - Track progress with the todo tool
-  entryCriteria:
+  readChecklist: []
+  confirmChecklist:
     - spec.md exists with user stories and acceptance criteria
     - plan.md exists with technology choices and architecture
     - No unresolved [NEEDS CLARIFICATION] markers in plan.md
-  exitCriteria:
+    - All dependencies installed and versions verified
+    - Linter and formatter configured and passing
+    - Build and test commands run successfully
     - Implementation complete according to plan.md
     - Tests written and passing
     - Self-review completed
@@ -108,11 +147,11 @@
     - Track findings and required changes with the todo tool
     - Run the application locally and verify changes work as expected
     - Test user-facing functionality against acceptance criteria
-  entryCriteria:
+  readChecklist: []
+  confirmChecklist:
     - Implementation complete according to plan.md
     - Tests written and passing
     - Self-review completed
-  exitCriteria:
     - Application runs locally without errors
     - Changes verified against acceptance criteria through manual testing
     - No blocking issues identified in review
@@ -135,11 +174,11 @@
     - Do not make code edits; hand off to code stage if fixes are needed
     - Verify all workflows complete successfully before considering deployment
       done
-  entryCriteria:
+  readChecklist: []
+  confirmChecklist:
     - Application runs locally without errors
     - Changes verified against acceptance criteria through manual testing
     - No blocking issues identified in review
     - Review approved
-  exitCriteria:
     - All triggered workflows are green
     - Deployment verified in target environment

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/schema",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Schema definitions and data loading for skills, behaviours, and role frameworks",
   "license": "Apache-2.0",
   "repository": {

package/schema/json/capability.schema.json

@@ -186,6 +186,7 @@
           "properties": {
             "specify": { "$ref": "#/$defs/skillStage" },
             "plan": { "$ref": "#/$defs/skillStage" },
+            "onboard": { "$ref": "#/$defs/skillStage" },
             "code": { "$ref": "#/$defs/skillStage" },
             "review": { "$ref": "#/$defs/skillStage" },
             "deploy": { "$ref": "#/$defs/skillStage" }
@@ -197,20 +198,20 @@
     },
     "skillStage": {
       "type": "object",
-      "required": ["focus", "activities", "ready"],
+      "required": ["focus", "readChecklist", "confirmChecklist"],
       "properties": {
         "focus": {
           "type": "string",
           "description": "Primary focus for this stage"
         },
-        "activities": {
+        "readChecklist": {
           "type": "array",
-          "description": "Key activities to perform in this stage",
+          "description": "Read-Then-Do Checklist: steps to follow in order during this stage",
           "items": { "type": "string" }
         },
-        "ready": {
+        "confirmChecklist": {
           "type": "array",
-          "description": "Criteria that indicate readiness to move to next stage",
+          "description": "Do-Then-Confirm Checklist: items to verify before moving to next stage",
           "items": { "type": "string" }
         }
       },

package/schema/json/framework.schema.json

@@ -28,6 +28,19 @@
       "additionalProperties": {
         "$ref": "#/$defs/entityDefinition"
       }
+    },
+    "distribution": {
+      "type": "object",
+      "description": "Distribution configuration for publishing and installing the framework",
+      "properties": {
+        "siteUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "Base URL for the published static site (e.g. https://pathway.myorg.com)"
+        }
+      },
+      "required": ["siteUrl"],
+      "additionalProperties": false
     }
   },
   "additionalProperties": false,

package/schema/json/stages.schema.json

@@ -14,7 +14,7 @@
       "properties": {
         "id": {
           "type": "string",
-          "enum": ["specify", "plan", "code", "review", "deploy"],
+          "enum": ["specify", "plan", "onboard", "code", "review", "deploy"],
           "description": "Stage identifier"
         },
         "name": {
@@ -47,16 +47,16 @@
             "type": "string"
           }
         },
-        "entryCriteria": {
+        "readChecklist": {
           "type": "array",
-          "description": "Conditions that must be met before entering this stage",
+          "description": "Read-Then-Do Checklist: steps to follow in order during this stage",
           "items": {
             "type": "string"
           }
         },
-        "exitCriteria": {
+        "confirmChecklist": {
           "type": "array",
-          "description": "Conditions that must be met before leaving this stage",
+          "description": "Do-Then-Confirm Checklist: items to verify before handing off to next stage",
           "items": {
             "type": "string"
           }
@@ -70,7 +70,7 @@
       "properties": {
         "targetStage": {
           "type": "string",
-          "enum": ["specify", "plan", "code", "review", "deploy"],
+          "enum": ["specify", "plan", "onboard", "code", "review", "deploy"],
           "description": "The stage to transition to"
         },
         "label": {

package/schema/rdf/capability.ttl

@@ -153,14 +153,14 @@ fit:focus a rdf:Property ;
     rdfs:comment "Primary focus for this stage"@en ;
     rdfs:range xsd:string .
 
-fit:activities a rdf:Property ;
-    rdfs:label "activities"@en ;
-    rdfs:comment "Key activities to perform in this stage"@en ;
+fit:readChecklist a rdf:Property ;
+    rdfs:label "readChecklist"@en ;
+    rdfs:comment "Read-Then-Do Checklist: steps to follow in order during this stage"@en ;
     rdfs:range xsd:string .
 
-fit:ready a rdf:Property ;
-    rdfs:label "ready"@en ;
-    rdfs:comment "Criteria that indicate readiness to move to next stage"@en ;
+fit:confirmChecklist a rdf:Property ;
+    rdfs:label "confirmChecklist"@en ;
+    rdfs:comment "Do-Then-Confirm Checklist: items to verify before moving to next stage"@en ;
     rdfs:range xsd:string .
 
 # =============================================================================
@@ -425,16 +425,16 @@ fit:SkillStageShape a sh:NodeShape ;
         sh:description "Primary focus for this stage" ;
     ] ;
     sh:property [
-        sh:path fit:activities ;
+        sh:path fit:readChecklist ;
         sh:datatype xsd:string ;
         sh:minCount 1 ;
-        sh:name "activities" ;
-        sh:description "Key activities to perform in this stage" ;
+        sh:name "readChecklist" ;
+        sh:description "Read-Then-Do Checklist: steps to follow in order during this stage" ;
     ] ;
     sh:property [
-        sh:path fit:ready ;
+        sh:path fit:confirmChecklist ;
         sh:datatype xsd:string ;
         sh:minCount 1 ;
-        sh:name "ready" ;
-        sh:description "Criteria that indicate readiness to move to next stage" ;
+        sh:name "confirmChecklist" ;
+        sh:description "Do-Then-Confirm Checklist: items to verify before moving to next stage" ;
     ] .

package/schema/rdf/framework.ttl

@@ -22,6 +22,10 @@ fit:EntityDefinition a rdfs:Class ;
     rdfs:label "Entity Definition"@en ;
     rdfs:comment "Definition for an entity type used in pages and chapters"@en .
 
+fit:Distribution a rdfs:Class ;
+    rdfs:label "Distribution"@en ;
+    rdfs:comment "Distribution configuration for publishing and installing the framework"@en .
+
 # -----------------------------------------------------------------------------
 # Properties
 # -----------------------------------------------------------------------------
@@ -38,6 +42,18 @@ fit:entityDefinitions a rdf:Property ;
     rdfs:domain fit:Framework ;
     rdfs:range fit:EntityDefinition .
 
+fit:distribution a rdf:Property ;
+    rdfs:label "distribution"@en ;
+    rdfs:comment "Distribution configuration for the framework"@en ;
+    rdfs:domain fit:Framework ;
+    rdfs:range fit:Distribution .
+
+fit:siteUrl a rdf:Property ;
+    rdfs:label "siteUrl"@en ;
+    rdfs:comment "Base URL for the published static site"@en ;
+    rdfs:domain fit:Distribution ;
+    rdfs:range xsd:anyURI .
+
 fit:entityType a rdf:Property ;
     rdfs:label "entityType"@en ;
     rdfs:comment "The type of entity this definition describes"@en ;
@@ -88,6 +104,28 @@ fit:FrameworkShape a sh:NodeShape ;
         sh:node fit:EntityDefinitionShape ;
         sh:name "entityDefinitions" ;
         sh:description "Definitions for each entity type" ;
+    ] ;
+    sh:property [
+        sh:path fit:distribution ;
+        sh:node fit:DistributionShape ;
+        sh:maxCount 1 ;
+        sh:name "distribution" ;
+        sh:description "Distribution configuration for the framework" ;
+    ] .
+
+# -----------------------------------------------------------------------------
+# Distribution Shape
+# -----------------------------------------------------------------------------
+
+fit:DistributionShape a sh:NodeShape ;
+    sh:targetClass fit:Distribution ;
+    sh:property [
+        sh:path fit:siteUrl ;
+        sh:datatype xsd:anyURI ;
+        sh:minCount 1 ;
+        sh:maxCount 1 ;
+        sh:name "siteUrl" ;
+        sh:description "Base URL for the published static site" ;
     ] .
 
 # -----------------------------------------------------------------------------