@forwardimpact/schema 0.3.0 → 0.6.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

@@ -3,6 +3,7 @@
 - id: specify
   name: Specify
   emojiIcon: "🎯"
+  summary: Defines requirements, user stories, and acceptance criteria
   description:
     Your primary task is to define WHAT users need and WHY, not how to build it.
     Gather requirements, write user stories, and define acceptance criteria.
@@ -30,6 +31,7 @@
 - id: plan
   name: Plan
   emojiIcon: "📐"
+  summary: Designs architecture, makes technology choices, and defines contracts
   description:
     Your primary task is to define HOW to build the solution. Make technology
     choices, design architecture, define contracts and data models.
@@ -60,6 +62,7 @@
 - id: code
   name: Code
   emojiIcon: "💻"
+  summary: Implements solutions, writes tests, and iterates to completion
   description:
     Your primary task is to implement the solution. Write code, write tests, and
     iterate until the implementation is complete.
@@ -83,6 +86,8 @@
 - id: review
   name: Review
   emojiIcon: "🔍"
+  summary:
+    Verifies implementation, tests acceptance criteria, and documents findings
   description:
     Your primary task is to verify the implementation works correctly. Run the
     application, test against acceptance criteria, document findings.
@@ -116,6 +121,7 @@
 - id: deploy
   name: Deploy
   emojiIcon: "🚀"
+  summary: Ships changes to production and monitors deployment workflows
   description:
     Your primary task is to ship the changes to production. Push code, monitor
     CI/CD workflows, and verify successful deployment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/schema",
-  "version": "0.3.0",
+  "version": "0.6.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",
@@ -95,7 +95,7 @@
         },
         "toolReferences": {
           "type": "array",
-          "description": "Recommended tools for this skill",
+          "description": "Required tools for this skill",
           "items": { "$ref": "#/$defs/toolReference" }
         }
       },

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"],

package/schema/json/stages.schema.json

@@ -27,7 +27,11 @@
         },
         "description": {
           "type": "string",
-          "description": "Description of the stage's purpose"
+          "description": "Description of the stage's purpose (second-person, for agent body)"
+        },
+        "summary": {
+          "type": "string",
+          "description": "Third-person summary for metadata, listings, and sub-agent descriptions"
         },
         "handoffs": {
           "type": "array",

package/schema/rdf/behaviour-questions.ttl

@@ -7,7 +7,10 @@
 # =============================================================================
 # Behaviour Questions Schema
 # =============================================================================
-# Interview questions for assessing behaviours.
+# Stakeholder simulation interview questions for assessing behaviours,
+# organized by role type (professional/management) and maturity level.
+# Each question presents a realistic stakeholder scenario with simulation
+# prompts to guide the interview panel.
 # =============================================================================
 
 # -----------------------------------------------------------------------------
@@ -26,6 +29,12 @@ fit:atMaturity a rdf:Property ;
     rdfs:domain fit:Question ;
     rdfs:range fit:BehaviourMaturity .
 
+fit:simulationPrompts a rdf:Property ;
+    rdfs:label "simulationPrompts"@en ;
+    rdfs:comment "Guiding prompts to steer the stakeholder simulation and probe the candidate's behaviour"@en ;
+    rdfs:domain fit:Question ;
+    rdfs:range xsd:string .
+
 # =============================================================================
 # SHACL SHAPES
 # =============================================================================
@@ -48,27 +57,42 @@ fit:BehaviourQuestionShape a sh:NodeShape ;
     sh:property [
         sh:path fit:text ;
         sh:datatype xsd:string ;
-        sh:maxLength 150 ;
+        sh:maxLength 300 ;
         sh:minCount 1 ;
         sh:maxCount 1 ;
         sh:name "text" ;
-        sh:description "The question text (under 150 characters)" ;
+        sh:description "The stakeholder scenario (under 300 characters)" ;
+    ] ;
+    sh:property [
+        sh:path fit:context ;
+        sh:datatype xsd:string ;
+        sh:maxCount 1 ;
+        sh:name "context" ;
+        sh:description "Additional context to set up the simulation scenario" ;
+    ] ;
+    sh:property [
+        sh:path fit:simulationPrompts ;
+        sh:datatype xsd:string ;
+        sh:minCount 2 ;
+        sh:maxCount 5 ;
+        sh:name "simulationPrompts" ;
+        sh:description "3-5 guiding prompts to steer the simulation" ;
     ] ;
     sh:property [
         sh:path fit:lookingFor ;
         sh:datatype xsd:string ;
-        sh:minCount 1 ;
+        sh:minCount 2 ;
         sh:maxCount 4 ;
         sh:name "lookingFor" ;
-        sh:description "2-4 bullet points of good answer indicators" ;
+        sh:description "2-4 indicators of strong behavioural response" ;
     ] ;
     sh:property [
         sh:path fit:expectedDurationMinutes ;
         sh:datatype xsd:integer ;
-        sh:minInclusive 1 ;
+        sh:minInclusive 10 ;
         sh:maxCount 1 ;
         sh:name "expectedDurationMinutes" ;
-        sh:description "Expected duration in minutes" ;
+        sh:description "Expected duration in minutes (default: 20)" ;
     ] ;
     sh:property [
         sh:path fit:followUps ;
@@ -93,4 +117,12 @@ fit:BehaviourQuestionShape a sh:NodeShape ;
         sh:maxCount 1 ;
         sh:name "atMaturity" ;
         sh:description "The behaviour maturity this question is for" ;
+    ] ;
+    sh:property [
+        sh:path fit:forRoleType ;
+        sh:in ( fit:professional fit:management ) ;
+        sh:minCount 1 ;
+        sh:maxCount 1 ;
+        sh:name "forRoleType" ;
+        sh:description "The role type this question is for" ;
     ] .

package/schema/rdf/capability.ttl

@@ -85,7 +85,7 @@ fit:implementationReference a rdf:Property ;
 
 fit:toolReferences a rdf:Property ;
     rdfs:label "toolReferences"@en ;
-    rdfs:comment "Recommended tools for this skill"@en ;
+    rdfs:comment "Required tools for this skill"@en ;
     rdfs:domain fit:Skill ;
     rdfs:range fit:ToolReference .
 
@@ -197,12 +197,12 @@ fit:CapabilityShape a sh:NodeShape ;
         sh:description "Emoji for visual representation" ;
     ] ;
     sh:property [
-        sh:path fit:displayOrder ;
+        sh:path fit:ordinalRank ;
         sh:datatype xsd:integer ;
         sh:minInclusive 1 ;
         sh:maxCount 1 ;
-        sh:name "displayOrder" ;
-        sh:description "Order for display in UI" ;
+        sh:name "ordinalRank" ;
+        sh:description "Numeric rank for ordering capabilities (1 = first)" ;
     ] ;
     sh:property [
         sh:path fit:description ;
@@ -288,7 +288,7 @@ fit:SkillShape a sh:NodeShape ;
         sh:path fit:toolReferences ;
         sh:node fit:ToolReferenceShape ;
         sh:name "toolReferences" ;
-        sh:description "Recommended tools for this skill" ;
+        sh:description "Required tools for this skill" ;
     ] .
 
 # -----------------------------------------------------------------------------

package/schema/rdf/defs.ttl

@@ -134,9 +134,9 @@ fit:emojiIcon a rdf:Property ;
     rdfs:comment "Emoji for visual representation"@en ;
     rdfs:range xsd:string .
 
-fit:displayOrder a rdf:Property ;
-    rdfs:label "displayOrder"@en ;
-    rdfs:comment "Order for display in UI"@en ;
+fit:ordinalRank a rdf:Property ;
+    rdfs:label "ordinalRank"@en ;
+    rdfs:comment "Numeric rank for ordering (1 = first)"@en ;
     rdfs:range xsd:integer .
 
 fit:ordinal a rdf:Property ;