What is change-orchestration?

It orchestrates the full lifecycle by routing actions to phase-specific sub-files and providing dispatch logic with shared validation.

How are actions dispatched?

Actions are parsed from arguments, with two-word actions like approve spec or request-changes routed to the correct sub-file (e.g., spec-review.md or planning.md).

What validations are performed before dispatch?

Change ID lookup and status checks are performed to ensure the change exists and the current status allows the requested action; errors are clearly reported if not.

change-orchestration

Scanned

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

Files (1)

SKILL.md

4.2 KB

Change Orchestration

Orchestrates the full change lifecycle: create, spec review, planning, implementation, verification, and management operations.

Input

Invoked by sdd-run.md with:

action — The change action to perform
args — Remaining arguments after the action

Action Routing

Action	Sub-file	Description
`create`	`creation.md`	Create a new change (interactive or external spec)
`approve spec`	`spec-review.md`	Approve SPEC.md, trigger PLAN.md creation
`answer`	`spec-review.md`	Answer an open question
`assume`	`spec-review.md`	Mark question as assumption
`plan`	`planning.md`	Begin planning phase (after ALL specs approved)
`approve plan`	`planning.md`	Approve PLAN.md, enable implementation
`implement`	`implementation.md`	Start implementation (requires plan_approved)
`verify`	`verification.md`	Verify implementation against spec
`review`	`verification.md`	Submit for user review
`status`	`management.md`	Show workflow state and change IDs
`list`	`management.md`	List all changes in workflow
`continue`	`management.md`	Resume workflow from persisted state
`regress`	`management.md`	Go back to earlier phase
`request-changes`	`management.md`	Request changes during review

Dispatch Logic

Parse the action from the first argument(s):
- Two-word actions: approve spec, approve plan, request-changes
- Single-word actions: everything else
Read the corresponding sub-file from this skill's directory
Follow the sub-file's instructions for the specific action

Shared Validation

Before dispatching any action, perform these common checks:

Change ID Lookup

For actions that require a <change-id>:

Read sdd/workflows/ to find the workflow containing that change
Validate the change exists
If not found: Error: Change '<change-id>' not found. Run /sdd-run change list to see all changes.

Status Checks

Each action has required statuses. If the current status doesn't match:

Error: Change '<change-id>' is in '<current-status>' status.
Action '<action>' requires status: <required-status>.

No Arguments

When invoked with no action, display usage:

⚠ Missing required action argument.

USAGE:
  /sdd-run change <action> [args] [options]

ACTIONS:
  create             Create a new change (interactive or from external spec)
  status             Show current workflow state and all change IDs
  continue           Resume current workflow from persisted state
  list               List all changes in current workflow
  approve spec       Approve SPEC.md, trigger PLAN.md creation
  approve plan       Approve PLAN.md, enable implementation
  implement          Start implementation (requires plan_approved)
  verify             Verify implementation, mark complete
  review             Submit for user review (after implementation)
  plan               Begin planning phase (after ALL specs approved)
  answer             Answer an open question
  assume             Mark question as assumption
  regress            Go back to earlier phase                   🟡 caution
  request-changes    Request changes during review              🟡 caution

COMMON WORKFLOWS:

  Start new feature:
    /sdd-run change create --type feature --name user-auth

  Import external spec:
    /sdd-run change create --spec /path/to/requirements.md

  Resume work:
    /sdd-run change continue <change-id>

  Approve and implement:
    /sdd-run change approve spec <change-id>
    /sdd-run change approve plan <change-id>
    /sdd-run change implement <change-id>

Common Output Patterns

NEXT STEPS Blocks

All output messages that suggest next actions use /sdd with natural language prompts:

NEXT STEPS:
  /sdd I want to approve the spec
  /sdd I want to start planning
  /sdd I want to start implementing

Change Links

Always render change references as clickable markdown links:

[<change-id>](changes/YYYY/MM/DD/<id>-<name>/<seq>-<slug>/)

Output

Returns the output from the dispatched sub-file action.

Source

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

Overview

Change Orchestration coordinates the entire change lifecycle, from creation through verification and management. It routes each action to phase-specific sub-files (e.g., creation.md, spec-review.md, planning.md, implementation.md, verification.md, management.md) to ensure consistent progression and validation.

How This Skill Works

The system parses the action from the first arguments, selects the corresponding phase sub-file, and follows its instructions. Before dispatch, it performs shared validation such as Change ID lookup and status checks to ensure actions are valid in the current workflow.

When to Use It

Start a new change by invoking create for a feature or external spec
Approve SPEC.md or PLAN.md to advance to planning or implementation
Begin planning after all specs are approved (plan)
Implement changes and verify them against the specification (implement, verify)
Manage and audit ongoing work with status, list, continue, regress, or request-changes

Quick Start

Step 1: Invoke a change action (e.g., /sdd-run change create --type feature --name user-auth)
Step 2: The orchestrator routes to the appropriate phase sub-file (creation.md, spec-review.md, planning.md, etc.)
Step 3: Use status, list, and continue to manage progress and resume workflows

Best Practices

Map each action to its exact phase sub-file (creation.md, spec-review.md, planning.md, etc.) to keep flows deterministic
Validate the Change ID upfront with clear error messages if not found
Use the prescribed two-word actions (e.g., approve spec, approve plan, request-changes) for precise routing
Maintain consistent statuses and persist state between steps to enable seamless resumption
Keep SPEC.md and PLAN.md in sync with implementation and verification activities

Example Use Cases

Start a new feature change: /sdd-run change create --type feature --name user-auth
Approve SPEC.md to trigger PLAN.md creation: /sdd-run change approve spec <change-id>
Approve PLAN.md to enable implementation: /sdd-run change approve plan <change-id>
Implement the change and verify against the spec: /sdd-run change implement <change-id> followed by /sdd-run change verify <change-id>
Resume or inspect workflow: /sdd-run change continue <change-id> or /sdd-run change status

Frequently Asked Questions

Add this skill to your agents