Validate and Update the Standard

You need to update your agent-aligned engineering standard -- add a skill, adjust a level description, rename a behaviour -- and confirm the result is structurally sound before anyone else sees it.

Prerequisites

Complete the Authoring Agent-Aligned Engineering Standards guide first -- this page assumes you have a working standard that already passes validation.

Edit the YAML

Open the file for the entity you want to change. The table below shows where each entity lives:

Entity	Location
Level	`data/pathway/levels.yaml`
Capability	`data/pathway/capabilities/`
Discipline	`data/pathway/disciplines/`
Track	`data/pathway/tracks/`
Behaviour	`data/pathway/behaviours/`
Driver	`data/pathway/drivers.yaml`

Skills are defined inside capability files, not in their own directory.

Make your change. For example, to add a new skill to an existing capability:

# data/pathway/capabilities/delivery.yaml
skills:
  - id: task_execution
    name: Task Execution
    human:
      description: Breaking down and completing engineering work
      proficiencyDescriptions:
        awareness: Follows guidance to complete assigned tasks
        foundational: Breaks work into steps with minimal guidance
        working: Independently plans and delivers work
        practitioner: Leads delivery across multiple workstreams
        expert: Defines delivery practices that scale across the organization

  - id: release_management
    name: Release Management
    human:
      description: Coordinating and shipping production releases
      proficiencyDescriptions:
        awareness: Follows release checklists with guidance
        foundational: Runs standard releases with minimal guidance
        working: Independently manages release cycles
        practitioner: Designs release processes across multiple products
        expert: Defines release strategy at the organizational level

Every skill requires proficiencyDescriptions at all five levels (awareness, foundational, working, practitioner, expert). Missing levels cause a schema error.

Run validation

After editing, run Map validation against your data directory:

npx fit-map validate

A passing run prints the data summary:

Validation passed

Data Summary
  Skills       -- 3
  Behaviours   -- 1
  Disciplines  -- 1
  Tracks       -- 2
  Levels       -- 2
  Drivers      -- 3

Check the Skills count -- it should reflect the skill you added or removed.

Fix validation errors

If validation fails, the output names the error type and location:

Validation failed

Errors
  - SCHEMA_VALIDATION: must have required property 'foundational' (capabilities/delivery.yaml/skills/1/human/proficiencyDescriptions)

Common error types and what they mean:

Error type	Cause	Fix
`SCHEMA_VALIDATION`	A YAML file does not match the JSON schema	Check required fields and allowed values
`INVALID_REFERENCE`	An entity references an ID that does not exist	Correct the ID or create the missing entity
`DUPLICATE_ID`	Two entities share the same ID	Rename one of the duplicates
`MISSING_REQUIRED`	A required entity type has no entries	Add at least one entry for that entity type

After fixing, run npx fit-map validate again. Repeat until validation passes.

Assign the new skill to a discipline

Skip this step if you did not add a new skill.

If you added a skill, it needs to appear in at least one discipline's tier arrays. Otherwise Pathway cannot place it in a role. Open the relevant discipline file and add the skill ID to coreSkills, supportingSkills, or broadSkills:

# data/pathway/disciplines/software_engineering.yaml
coreSkills:
  - architecture_design
  - code_quality
  - full_stack_development
  - release_management        # newly added

Run validation again -- Map checks that every skill ID referenced in a discipline exists in your capability files:

npx fit-map validate

A misspelled skill ID produces an INVALID_REFERENCE error:

Errors
  - INVALID_REFERENCE: Discipline 'software_engineering' references unknown skill 'release_managment' (disciplines/software_engineering)

Preview the result

Once validation passes, preview the rendered standard to confirm the change looks right:

npx fit-pathway dev

Browse the local development server and check that the updated entity appears where you expect it -- correct proficiency levels, correct discipline placement, correct track modifiers applied.

Verify

The update is complete when all three conditions are true:

npx fit-map validate passes with no errors.
The Data Summary counts match what you expect (e.g., one more skill than before).
npx fit-pathway dev renders the change correctly in the browser.

For the full field reference -- required vs. optional fields, ID patterns, and allowed values -- see the YAML Schema Reference.