@forwardimpact/schema 0.4.0 → 0.7.0

package/examples/questions/skills/technical_writing.yaml

@@ -1,42 +1,91 @@
 # yaml-language-server: $schema=https://www.forwardimpact.team/schema/json/skill-questions.schema.json
 
-awareness:
-  - id: tw_aware_1
-    text: How do you approach documenting your code and work?
-    lookingFor:
-      - Basic documentation habits
-      - Understanding of documentation importance
-    expectedDurationMinutes: 5
-foundational:
-  - id: tw_found_1
-    text: What makes a good README file? Walk me through what you'd include.
-    lookingFor:
-      - README best practices
-      - Reader-centric documentation
-    expectedDurationMinutes: 5
-working:
-  - id: tw_work_1
-    text:
-      How do you write technical specifications that enable others to implement
-      features?
-    followUps:
-      - How detailed do you go?
-    lookingFor:
-      - Spec writing skills
-      - Communication of technical requirements
-    expectedDurationMinutes: 8
-practitioner:
-  - id: tw_pract_1
-    text:
-      How do you establish documentation standards and practices in your team?
-    lookingFor:
-      - Documentation leadership
-      - Spec-driven development advocacy
-    expectedDurationMinutes: 8
-expert:
-  - id: tw_expert_1
-    text: How do you create organizational documentation culture and systems?
-    lookingFor:
-      - Enterprise documentation strategy
-      - Knowledge management systems
-    expectedDurationMinutes: 10
+professionalQuestions:
+  awareness:
+    - id: tw_pro_aware_1
+      text: How do you approach documenting your code and work?
+      lookingFor:
+        - Basic documentation habits
+        - Understanding of documentation importance
+      expectedDurationMinutes: 5
+  foundational:
+    - id: tw_pro_found_1
+      text: What makes a good README file? Walk me through what you'd include.
+      lookingFor:
+        - README best practices
+        - Reader-centric documentation
+      expectedDurationMinutes: 5
+  working:
+    - id: tw_pro_work_1
+      text:
+        How do you write technical specifications that enable others to
+        implement features?
+      followUps:
+        - How detailed do you go?
+      lookingFor:
+        - Spec writing skills
+        - Communication of technical requirements
+      expectedDurationMinutes: 8
+  practitioner:
+    - id: tw_pro_pract_1
+      text:
+        How do you establish documentation standards and practices in your team?
+      lookingFor:
+        - Documentation leadership
+        - Spec-driven development advocacy
+      expectedDurationMinutes: 8
+  expert:
+    - id: tw_pro_expert_1
+      text: How do you create organizational documentation culture and systems?
+      lookingFor:
+        - Enterprise documentation strategy
+        - Knowledge management systems
+      expectedDurationMinutes: 10
+
+managementQuestions:
+  awareness:
+    - id: tw_mgmt_aware_1
+      text: How do you ensure your team documents their work appropriately?
+      lookingFor:
+        - Basic documentation expectations
+        - Team documentation awareness
+      expectedDurationMinutes: 5
+  foundational:
+    - id: tw_mgmt_found_1
+      text:
+        How do you set documentation expectations and standards for your team?
+      followUps:
+        - How do you handle resistance to documentation?
+      lookingFor:
+        - Documentation standard setting
+        - Team buy-in practices
+      expectedDurationMinutes: 5
+  working:
+    - id: tw_mgmt_work_1
+      text:
+        How do you balance documentation effort with delivery speed in your
+        team?
+      followUps:
+        - What is the minimum documentation you require?
+      lookingFor:
+        - Documentation vs velocity trade-offs
+        - Pragmatic documentation approach
+      expectedDurationMinutes: 8
+  practitioner:
+    - id: tw_mgmt_pract_1
+      text: How do you build a documentation culture within your team?
+      followUps:
+        - How do you keep documentation current?
+      lookingFor:
+        - Documentation culture development
+        - Knowledge management practices
+      expectedDurationMinutes: 8
+  expert:
+    - id: tw_mgmt_expert_1
+      text:
+        How do you drive documentation practices and knowledge sharing across
+        multiple teams?
+      lookingFor:
+        - Cross-team documentation leadership
+        - Organizational knowledge strategy
+      expectedDurationMinutes: 10

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.4.0",
+  "version": "0.7.0",
   "description": "Schema definitions and data loading for skills, behaviours, and role frameworks",
   "license": "Apache-2.0",
   "repository": {
@@ -10,7 +10,7 @@
   },
   "homepage": "https://www.forwardimpact.team/schema",
   "type": "module",
-  "main": "lib/index.js",
+  "main": "src/index.js",
   "bin": {
     "fit-schema": "./bin/fit-schema.js"
   },
@@ -21,16 +21,16 @@
   "files": [
     "bin/",
     "examples/",
-    "lib/",
+    "src/",
     "schema/"
   ],
   "exports": {
-    ".": "./lib/index.js",
-    "./loader": "./lib/loader.js",
-    "./validation": "./lib/validation.js",
-    "./schema-validation": "./lib/schema-validation.js",
-    "./index-generator": "./lib/index-generator.js",
-    "./levels": "./lib/levels.js",
+    ".": "./src/index.js",
+    "./loader": "./src/loader.js",
+    "./validation": "./src/validation.js",
+    "./schema-validation": "./src/schema-validation.js",
+    "./index-generator": "./src/index-generator.js",
+    "./levels": "./src/levels.js",
     "./examples/*": "./examples/*",
     "./schema/json/*": "./schema/json/*",
     "./schema/rdf/*": "./schema/rdf/*"

package/schema/json/behaviour-questions.schema.json

@@ -2,35 +2,50 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://www.forwardimpact.team/schema/json/behaviour-questions.schema.json",
   "title": "Behaviour Interview Questions",
-  "description": "Interview questions for a behaviour, organized by maturity level",
+  "description": "Stakeholder simulation interview questions for a behaviour, organized by role type (professional/management) and maturity level. Each question presents a realistic stakeholder scenario to assess behavioural maturity.",
   "type": "object",
   "properties": {
-    "emerging": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/question" }
+    "professionalQuestions": {
+      "description": "Questions for professional/IC roles (e.g., engineers)",
+      "$ref": "#/$defs/maturityQuestions"
     },
-    "developing": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/question" }
-    },
-    "practicing": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/question" }
-    },
-    "role_modeling": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/question" }
-    },
-    "exemplifying": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/question" }
+    "managementQuestions": {
+      "description": "Questions for management roles (e.g., engineering managers, product managers)",
+      "$ref": "#/$defs/maturityQuestions"
     }
   },
   "additionalProperties": false,
   "$defs": {
+    "maturityQuestions": {
+      "type": "object",
+      "description": "Questions organized by behaviour maturity level",
+      "properties": {
+        "emerging": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/question" }
+        },
+        "developing": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/question" }
+        },
+        "practicing": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/question" }
+        },
+        "role_modeling": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/question" }
+        },
+        "exemplifying": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/question" }
+        }
+      },
+      "additionalProperties": false
+    },
     "question": {
       "type": "object",
-      "required": ["id", "text", "lookingFor"],
+      "required": ["id", "text", "lookingFor", "simulationPrompts"],
       "properties": {
         "id": {
           "type": "string",
@@ -39,20 +54,32 @@
         },
         "text": {
           "type": "string",
-          "maxLength": 150,
-          "description": "The question text (second person, under 150 characters)"
+          "maxLength": 300,
+          "description": "The stakeholder scenario (second person, sets up a realistic situation)"
+        },
+        "context": {
+          "type": "string",
+          "description": "Additional context to set up the simulation scenario"
+        },
+        "simulationPrompts": {
+          "type": "array",
+          "description": "3-5 guiding prompts to steer the simulation and probe the candidate's behaviour",
+          "minItems": 2,
+          "maxItems": 5,
+          "items": { "type": "string" }
         },
         "lookingFor": {
           "type": "array",
-          "description": "2-4 bullet points of good answer indicators",
-          "minItems": 1,
+          "description": "2-4 indicators of strong behavioural response",
+          "minItems": 2,
           "maxItems": 4,
           "items": { "type": "string" }
         },
         "expectedDurationMinutes": {
           "type": "integer",
-          "minimum": 1,
-          "description": "Expected duration in minutes (default: 5 for emerging/developing, 8-10 for higher)"
+          "minimum": 10,
+          "default": 20,
+          "description": "Expected duration in minutes (default: 20 for stakeholder simulation)"
         },
         "followUps": {
           "type": "array",

package/schema/json/capability-questions.schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://www.forwardimpact.team/schema/json/capability-questions.schema.json",
+  "title": "Capability Decomposition Questions",
+  "description": "Decomposition interview questions for a capability, organized by role type (professional/management) and level. Inspired by Palantir's decomposition interview technique.",
+  "type": "object",
+  "properties": {
+    "professionalQuestions": {
+      "description": "Questions for professional/IC roles (e.g., engineers)",
+      "$ref": "#/$defs/levelQuestions"
+    },
+    "managementQuestions": {
+      "description": "Questions for management roles (e.g., engineering managers, product managers)",
+      "$ref": "#/$defs/levelQuestions"
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "levelQuestions": {
+      "type": "object",
+      "description": "Questions organized by capability level",
+      "properties": {
+        "awareness": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/question" }
+        },
+        "foundational": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/question" }
+        },
+        "working": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/question" }
+        },
+        "practitioner": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/question" }
+        },
+        "expert": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/question" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "question": {
+      "type": "object",
+      "required": ["id", "text", "lookingFor", "decompositionPrompts"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]*$",
+          "description": "Unique question identifier (format: {capability_abbrev}_{level_abbrev}_{number})"
+        },
+        "text": {
+          "type": "string",
+          "maxLength": 200,
+          "description": "The problem statement or scenario (second person, open-ended)"
+        },
+        "context": {
+          "type": "string",
+          "description": "Optional additional context to set up the scenario"
+        },
+        "decompositionPrompts": {
+          "type": "array",
+          "description": "3-5 guiding questions to help the candidate structure their thinking",
+          "minItems": 2,
+          "maxItems": 5,
+          "items": { "type": "string" }
+        },
+        "lookingFor": {
+          "type": "array",
+          "description": "2-4 indicators of a strong decomposition approach",
+          "minItems": 2,
+          "maxItems": 4,
+          "items": { "type": "string" }
+        },
+        "expectedDurationMinutes": {
+          "type": "integer",
+          "minimum": 5,
+          "default": 15,
+          "description": "Expected duration in minutes (default: 15 for decomposition)"
+        },
+        "followUps": {
+          "type": "array",
+          "description": "1-3 probing questions for deeper exploration",
+          "minItems": 1,
+          "maxItems": 3,
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/json/capability.schema.json

@@ -19,10 +19,10 @@
       "type": "string",
       "description": "Emoji for visual representation"
     },
-    "displayOrder": {
+    "ordinalRank": {
       "type": "integer",
       "minimum": 1,
-      "description": "Order for display in UI"
+      "description": "Numeric rank for ordering capabilities (1 = first)"
     },
     "description": {
       "type": "string",
@@ -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/skill-questions.schema.json

@@ -2,32 +2,47 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://www.forwardimpact.team/schema/json/skill-questions.schema.json",
   "title": "Skill Interview Questions",
-  "description": "Interview questions for a skill, organized by level",
+  "description": "Interview questions for a skill, organized by role type (professional/management) and level",
   "type": "object",
   "properties": {
-    "awareness": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/question" }
+    "professionalQuestions": {
+      "description": "Questions for professional/IC roles (e.g., engineers)",
+      "$ref": "#/$defs/levelQuestions"
     },
-    "foundational": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/question" }
-    },
-    "working": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/question" }
-    },
-    "practitioner": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/question" }
-    },
-    "expert": {
-      "type": "array",
-      "items": { "$ref": "#/$defs/question" }
+    "managementQuestions": {
+      "description": "Questions for management roles (e.g., engineering managers, product managers)",
+      "$ref": "#/$defs/levelQuestions"
     }
   },
   "additionalProperties": false,
   "$defs": {
+    "levelQuestions": {
+      "type": "object",
+      "description": "Questions organized by skill level",
+      "properties": {
+        "awareness": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/question" }
+        },
+        "foundational": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/question" }
+        },
+        "working": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/question" }
+        },
+        "practitioner": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/question" }
+        },
+        "expert": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/question" }
+        }
+      },
+      "additionalProperties": false
+    },
     "question": {
       "type": "object",
       "required": ["id", "text", "lookingFor"],