@forwardimpact/schema 0.2.0 → 0.4.0

package/examples/disciplines/data_engineering.yaml

@@ -59,18 +59,6 @@ agent:
   priority: |
     Data quality is paramount. Always validate data at ingestion points and
     document schema assumptions. Treat undocumented schemas with suspicion.
-  beforeMakingChanges:
-    - Understand the data sources and their quality characteristics
-    - Map data lineage and dependencies
-    - Consider performance implications for downstream consumers
-  delegation: |
-    When facing tasks outside your expertise, use `runSubagent` to delegate:
-    - Statistical analysis or model validation → data science subagent
-    - Application code changes → software engineering subagent
-    - Infrastructure or deployment → SRE subagent
-
-    Subagents run in isolated context. Provide clear task descriptions and
-    specify what information to return.
   constraints:
     - Ignoring data quality issues
     - Creating pipelines without proper error handling

package/examples/disciplines/engineering_management.yaml

@@ -53,10 +53,6 @@ agent:
     remove organizational friction.
 
     Your role is to support engineering judgment, not replace it.
-  beforeMakingChanges:
-    - Consider team dynamics and individual growth
-    - Think about systemic improvements over individual fixes
-    - Focus on enabling others rather than doing directly
   constraints:
     - Focus on enabling and empowering rather than doing directly
     - Consider long-term team health over short-term fixes

package/examples/disciplines/software_engineering.yaml

@@ -59,18 +59,6 @@ agent:
     Code review is more important than code generation. Every line of code
     you produce must be understood and verified. Never ship code without
     comprehensive testing.
-  beforeMakingChanges:
-    - Understand the existing architecture and patterns
-    - Identify test coverage requirements
-    - Consider backward compatibility implications
-  delegation: |
-    When facing tasks outside your expertise, use `runSubagent` to delegate:
-    - Data modeling or statistical analysis → data science subagent
-    - Security assessment or threat modeling → research subagent
-    - Complex debugging across unfamiliar systems → research subagent
-
-    Subagents run in isolated context. Provide clear task descriptions and
-    specify what information to return.
   constraints:
     - Committing code without running tests
     - Making changes without understanding the existing codebase

package/examples/framework.yaml

@@ -66,4 +66,4 @@ entityDefinitions:
     title: Tools
     emojiIcon: "🔧"
     description: |
-      Recommended tools and utilities referenced by skills for effective engineering workflows. Tools are linked to specific skills with guidance on when and how to use them, surfacing best practices directly in skill definitions.
+      Required tools and utilities referenced by skills for effective engineering workflows. Tools are linked to specific skills with guidance on when and how to use them, surfacing organizational standards directly in skill definitions.

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/examples/tracks/platform.yaml

@@ -37,11 +37,6 @@ agent:
 
     Every API change must consider developer experience. Treat breaking 
     changes with extreme caution—your consumers build on your stability.
-  beforeMakingChanges:
-    - Understand the existing architecture and patterns
-    - Identify test coverage requirements
-    - Consider backward compatibility implications
-    - Plan documentation updates
   constraints:
     - Maintain backward compatibility
     - Document breaking changes with migration guides

package/examples/tracks/sre.yaml

@@ -36,11 +36,6 @@ agent:
 
     Production stability trumps feature velocity. No change ships without
     understanding its impact on system reliability.
-  beforeMakingChanges:
-    - Understand system dependencies and failure modes
-    - Ensure observability instrumentation is in place
-    - Consider rollback procedures and blast radius
-    - Verify runbooks are updated
   constraints:
     - Never compromise on observability instrumentation
     - Document all runbooks and incident response procedures

package/lib/validation.js

@@ -750,48 +750,6 @@ function validateDiscipline(
       );
     }
 
-    // Optional: beforeMakingChanges (array of strings)
-    if (discipline.agent.beforeMakingChanges !== undefined) {
-      if (!Array.isArray(discipline.agent.beforeMakingChanges)) {
-        errors.push(
-          createError(
-            "INVALID_VALUE",
-            "Discipline agent beforeMakingChanges must be an array",
-            `${agentPath}.beforeMakingChanges`,
-            discipline.agent.beforeMakingChanges,
-          ),
-        );
-      } else {
-        discipline.agent.beforeMakingChanges.forEach((item, i) => {
-          if (typeof item !== "string") {
-            errors.push(
-              createError(
-                "INVALID_VALUE",
-                "Discipline agent beforeMakingChanges items must be strings",
-                `${agentPath}.beforeMakingChanges[${i}]`,
-                item,
-              ),
-            );
-          }
-        });
-      }
-    }
-
-    // Optional: delegation (string)
-    if (
-      discipline.agent.delegation !== undefined &&
-      typeof discipline.agent.delegation !== "string"
-    ) {
-      errors.push(
-        createError(
-          "INVALID_VALUE",
-          "Discipline agent delegation must be a string",
-          `${agentPath}.delegation`,
-          discipline.agent.delegation,
-        ),
-      );
-    }
-
     // Optional: constraints (array of strings)
     if (discipline.agent.constraints !== undefined) {
       if (!Array.isArray(discipline.agent.constraints)) {
@@ -824,7 +782,7 @@ function validateDiscipline(
       errors.push(
         createError(
           "INVALID_FIELD",
-          "Discipline agent 'coreInstructions' field is not supported. Use identity, priority, beforeMakingChanges, and delegation instead.",
+          "Discipline agent 'coreInstructions' field is not supported. Use identity, priority, and constraints instead.",
           `${agentPath}.coreInstructions`,
         ),
       );
@@ -1024,33 +982,6 @@ function validateTrack(
       );
     }
 
-    // Optional: beforeMakingChanges (array of strings)
-    if (track.agent.beforeMakingChanges !== undefined) {
-      if (!Array.isArray(track.agent.beforeMakingChanges)) {
-        errors.push(
-          createError(
-            "INVALID_VALUE",
-            "Track agent beforeMakingChanges must be an array",
-            `${agentPath}.beforeMakingChanges`,
-            track.agent.beforeMakingChanges,
-          ),
-        );
-      } else {
-        track.agent.beforeMakingChanges.forEach((item, i) => {
-          if (typeof item !== "string") {
-            errors.push(
-              createError(
-                "INVALID_VALUE",
-                "Track agent beforeMakingChanges items must be strings",
-                `${agentPath}.beforeMakingChanges[${i}]`,
-                item,
-              ),
-            );
-          }
-        });
-      }
-    }
-
     // Optional: constraints (array of strings)
     if (track.agent.constraints !== undefined) {
       if (!Array.isArray(track.agent.constraints)) {
@@ -1083,7 +1014,7 @@ function validateTrack(
       errors.push(
         createError(
           "INVALID_FIELD",
-          "Track agent 'coreInstructions' field is not supported. Use identity, priority, beforeMakingChanges, and constraints instead.",
+          "Track agent 'coreInstructions' field is not supported. Use identity, priority, and constraints instead.",
           `${agentPath}.coreInstructions`,
         ),
       );

package/package.json

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

package/schema/json/capability.schema.json

@@ -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/discipline.schema.json

@@ -111,15 +111,6 @@
           "type": "string",
           "description": "Priority guidance for the agent"
         },
-        "beforeMakingChanges": {
-          "type": "array",
-          "description": "Checklist items to consider before making changes",
-          "items": { "type": "string" }
-        },
-        "delegation": {
-          "type": "string",
-          "description": "Guidance on when and how to delegate to subagents"
-        },
         "constraints": {
           "type": "array",
           "description": "Things the agent should avoid or never do",

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/json/track.schema.json

@@ -83,11 +83,6 @@
           "type": "string",
           "description": "Priority guidance specific to this track"
         },
-        "beforeMakingChanges": {
-          "type": "array",
-          "description": "Additional checklist items to consider",
-          "items": { "type": "string" }
-        },
         "constraints": {
           "type": "array",
           "description": "Additional constraints specific to this track",

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 .
 
@@ -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/discipline.ttl

@@ -109,16 +109,6 @@ fit:priority a rdf:Property ;
     rdfs:comment "Priority guidance for the agent"@en ;
     rdfs:range xsd:string .
 
-fit:beforeMakingChanges a rdf:Property ;
-    rdfs:label "beforeMakingChanges"@en ;
-    rdfs:comment "Checklist items to consider before making changes"@en ;
-    rdfs:range xsd:string .
-
-fit:delegation a rdf:Property ;
-    rdfs:label "delegation"@en ;
-    rdfs:comment "Guidance on when and how to delegate to subagents"@en ;
-    rdfs:range xsd:string .
-
 # Modifier Properties
 fit:targetBehaviour a rdf:Property ;
     rdfs:label "targetBehaviour"@en ;
@@ -289,19 +279,6 @@ fit:DisciplineAgentSectionShape a sh:NodeShape ;
         sh:name "priority" ;
         sh:description "Priority guidance for the agent" ;
     ] ;
-    sh:property [
-        sh:path fit:beforeMakingChanges ;
-        sh:datatype xsd:string ;
-        sh:name "beforeMakingChanges" ;
-        sh:description "Checklist items to consider before making changes" ;
-    ] ;
-    sh:property [
-        sh:path fit:delegation ;
-        sh:datatype xsd:string ;
-        sh:maxCount 1 ;
-        sh:name "delegation" ;
-        sh:description "Guidance on when and how to delegate to subagents" ;
-    ] ;
     sh:property [
         sh:path fit:constraints ;
         sh:datatype xsd:string ;

package/schema/rdf/stages.ttl

@@ -33,6 +33,17 @@ fit:entryCriteria a rdf:Property ;
     rdfs:comment "Conditions that must be met before entering this stage"@en ;
     rdfs:range xsd:string .
 
+fit:exitCriteria a rdf:Property ;
+    rdfs:label "exitCriteria"@en ;
+    rdfs:comment "Conditions that must be met before leaving this stage"@en ;
+    rdfs:range xsd:string .
+
+fit:summary a rdf:Property ;
+    rdfs:label "summary"@en ;
+    rdfs:comment "Third-person summary for metadata, listings, and sub-agent descriptions"@en ;
+    rdfs:domain fit:Stage ;
+    rdfs:range xsd:string .
+
 fit:targetStage a rdf:Property ;
     rdfs:label "targetStage"@en ;
     rdfs:comment "The stage to transition to"@en ;
@@ -63,7 +74,7 @@ fit:StageShape a sh:NodeShape ;
     sh:targetClass fit:Stage ;
     sh:property [
         sh:path fit:id ;
-        sh:in ( "plan" "code" "review" ) ;
+        sh:in ( "specify" "plan" "code" "review" "deploy" ) ;
         sh:minCount 1 ;
         sh:maxCount 1 ;
         sh:name "id" ;
@@ -89,7 +100,14 @@ fit:StageShape a sh:NodeShape ;
         sh:datatype xsd:string ;
         sh:maxCount 1 ;
         sh:name "description" ;
-        sh:description "Description of the stage's purpose" ;
+        sh:description "Description of the stage's purpose (second-person, for agent body)" ;
+    ] ;
+    sh:property [
+        sh:path fit:summary ;
+        sh:datatype xsd:string ;
+        sh:maxCount 1 ;
+        sh:name "summary" ;
+        sh:description "Third-person summary for metadata, listings, and sub-agent descriptions" ;
     ] ;
     sh:property [
         sh:path fit:handoffs ;
@@ -108,6 +126,12 @@ fit:StageShape a sh:NodeShape ;
         sh:datatype xsd:string ;
         sh:name "entryCriteria" ;
         sh:description "Conditions that must be met before entering this stage" ;
+    ] ;
+    sh:property [
+        sh:path fit:exitCriteria ;
+        sh:datatype xsd:string ;
+        sh:name "exitCriteria" ;
+        sh:description "Conditions that must be met before leaving this stage" ;
     ] .
 
 # -----------------------------------------------------------------------------
@@ -118,7 +142,7 @@ fit:HandoffShape a sh:NodeShape ;
     sh:targetClass fit:Handoff ;
     sh:property [
         sh:path fit:targetStage ;
-        sh:in ( "plan" "code" "review" ) ;
+        sh:in ( "specify" "plan" "code" "review" "deploy" ) ;
         sh:minCount 1 ;
         sh:maxCount 1 ;
         sh:name "targetStage" ;

package/schema/rdf/track.ttl

@@ -166,12 +166,6 @@ fit:TrackAgentSectionShape a sh:NodeShape ;
         sh:name "priority" ;
         sh:description "Priority guidance specific to this track" ;
     ] ;
-    sh:property [
-        sh:path fit:beforeMakingChanges ;
-        sh:datatype xsd:string ;
-        sh:name "beforeMakingChanges" ;
-        sh:description "Additional checklist items to consider" ;
-    ] ;
     sh:property [
         sh:path fit:constraints ;
         sh:datatype xsd:string ;