What does a 'match' indicate?

Installed and project versions are the same.

What should I do if the project is outdated?

The project version is older than the installed version; reconcile by updating the project to the installed version or run claude plugins update sdd, then re-check.

What if there is no SDD project detected?

The report shows 'Project: (no SDD project detected)'; initialize a new project with /sdd to proceed.

version-orchestration

npx machina-cli add skill LiorCohen/sdd/version-orchestration --openclaw

Files (1)

SKILL.md

2.2 KB

Version Orchestration

Display the installed SDD plugin version and the project's plugin version, highlighting when the project is outdated.

Input

Invoked by sdd-run.md with no arguments.

Preconditions

Plugin is loaded (agent has access to plugin root path)

Flow

Read the installed plugin version from <plugin-root>/.claude-plugin/plugin.json → version field
Check if sdd/sdd-settings.yaml exists in the current directory
If it exists, read the project plugin version from sdd.updated_by_plugin_version (with fallback to legacy sdd.plugin_version for pre-reconciliation files)
Optionally read sdd.initialized_by_plugin_version for context (the version that first created the project)
Compare versions using semver:
- Match — installed and project versions are the same
- Project outdated — project version is older than installed version (the common case after a plugin upgrade)
- Project newer — project version is newer than installed (unusual — may indicate a downgraded plugin)
Display the version report

Output Scenarios

When versions match

SDD Plugin

  Installed:       6.5.0
  Project:         6.5.0  ✓ match
  Originally from: 6.2.0

When project is outdated (installed is newer)

SDD Plugin

  Installed:       6.5.0
  Project:         6.2.0  ⚠ outdated
  Originally from: 6.0.0

The project settings were last reconciled with an older plugin version.
  /sdd I want to initialize a new project

When project is newer than installed (unusual)

SDD Plugin

  Installed:       6.3.0
  Project:         6.5.0  ⚠ installed plugin is older than project
  Originally from: 6.0.0

The installed plugin is older than what this project expects.
Run: claude plugins update sdd

When not inside an SDD project

SDD Plugin

  Installed:  6.5.0
  Project:    (no SDD project detected)

NEXT STEPS:
  /sdd I want to initialize a new project

project-settings skill - Owns the sdd-settings.yaml schema

Output

Returns the version report as formatted text.

Source

git clone https://github.com/LiorCohen/sdd/blob/main/plugin/core/skills/orchestrators/version-orchestration/SKILL.mdView on GitHub

Overview

Version Orchestration reports the installed SDD plugin version and the project’s version, highlighting mismatches. It helps teams detect when a project is out of sync after upgrades or configuration changes.

How This Skill Works

It reads the installed version from <plugin-root>/.claude-plugin/plugin.json, then reads the project version from sdd/sdd-settings.yaml via sdd.updated_by_plugin_version (with a fallback to the legacy sdd.plugin_version) and can include sdd.initialized_by_plugin_version for context. It compares the two using semver and prints a version report showing match, outdated, or newer statuses.

When to Use It

After upgrading the SDD plugin to verify the project still matches.
When a project appears outdated after a plugin upgrade.
If the project version is newer than the installed plugin (unusual) to diagnose.
When you are in a project directory and need to confirm a valid SDD project version.
When not inside an SDD project to check environment status.

Quick Start

Step 1: Ensure the plugin is loaded and you are in the project directory so sdd-settings.yaml can be located.
Step 2: Run the version-orchestration check (invoked by sdd-run.md with no arguments) to produce the version report.
Step 3: Review the Installed vs Project lines and the status (match, outdated, or newer) to decide next steps.

Best Practices

Ensure the agent/plugin is loaded and has access to the plugin root.
Run the check in the project directory so sdd-settings.yaml is found.
Prefer sdd.updated_by_plugin_version with a fallback to sdd.plugin_version for legacy files.
Use the 'Originally from' version to understand historical reconciliation.
If the installed plugin is older than the project, run plugin update (e.g., claude plugins update sdd) and re-check.

Example Use Cases

Match: Installed 6.5.0 vs Project 6.5.0 (match); Originally from 6.2.0.
Outdated: Installed 6.5.0, Project 6.2.0 (outdated); Originally from 6.0.0.
Project newer: Installed 6.3.0, Project 6.5.0 (project newer than installed).
Not in a project: Installed 6.5.0, Project shows (no SDD project detected).
Unusual upgrade note: The installed plugin is older than the project; run: claude plugins update sdd.

Frequently Asked Questions

Add this skill to your agents