/sdd-run

name: sdd-run
description: Explicit command with namespaced subcommands covering all SDD functionality.

/sdd-run

The explicit command for all SDD operations. Each namespace maps to a specific domain — use this when you know exactly what you want to do.

Usage

/sdd-run <namespace> <action> [args] [options]

Global Options

| Option | Description | |--------|-------------| | `--json` | Output in JSON format | | `--verbose` | Enable verbose logging | | `--help` | Show help for namespace/action |

---

When Called Without Arguments (or with `help`)

When invoked without a namespace, or with `help`, display the full namespace reference:

SDD Run — Explicit command interface

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

CORE NAMESPACES:
  change        Manage the full change lifecycle (create, approve, implement, verify)
  init          Initialize or upgrade an SDD project
  permissions   Configure Claude Code permissions for SDD
  version       Show installed and project plugin versions

TECH PACK NAMESPACES:
  (Loaded from active tech packs — run /sdd-run help for current list)

GLOBAL OPTIONS:
  --json        Output in JSON format
  --verbose     Enable verbose logging
  --help        Show help for namespace/action

EXAMPLES:
  /sdd-run change create --type feature --name user-auth
  /sdd-run init
  /sdd-run version

TIP: Use /sdd for guided, context-aware assistance.
     Use /sdd-help to learn SDD concepts and methodology.

---

Pre-Execution Checks

Two checks run **before executing any namespace**: argument validation and destructive action confirmation.

Argument Validation — Sub-Help

Validate that sufficient arguments are provided. If not, display the namespace-specific sub-help instead of running the command.

**Rules:** 1. **No namespace** → show the full namespace reference (above) 2. **Namespace provided, action missing** → show that namespace's sub-help 3. **Namespace + action provided, required args missing** → show action-specific help

For **core orchestrated namespaces** (change, init, version), the orchestrator skill handles insufficient arguments — INVOKE the skill and let it display its own sub-help.

For **core pass-through namespaces** (permissions), validate arguments **before** calling `system-run.sh`. Display the sub-help blocks defined in each namespace section below.

For **tech pack namespaces** (any namespace not recognized as core), route to the tech pack command router — it handles its own argument validation and sub-help.

Destructive Action Confirmation

Some actions destroy data, remove deployments, or reset progress. These **must not execute without explicit user authorization**.

**Severity levels:**

| Level | Meaning | Required | |-------|---------|----------| | `🔴 destructive` | Irreversible data loss or removal | Warning + explicit "yes" confirmation | | `🟡 caution` | Overwrites data or resets progress, but recoverable | Warning + confirmation |

**Destructive actions (core):**

| Namespace | Action | Level | What it affects | |-----------|--------|-------|-----------------| | `change` | `regress` | 🟡 | Rolls workflow back to an earlier phase — plan or implementation work is archived but progress is reset | | `change` | `request-changes` | 🟡 | Resets implementation status from complete to in-progress, requiring rework |

Tech packs may define additional destructive actions. The tech pack's command router provides its own destructive action table.

**Warning format:**

⚠ <LEVEL>: <action description>

This will <specific consequence>.

Target: <component/cluster/change being affected>
Environment: <env if applicable>

Confirm? (yes/no)

**NEVER** skip this confirmation, even if the user seems to expect immediate execution. The cost of accidental data loss far outweighs the friction of one confirmation prompt.

---

Namespace Routing

`change` — Manage the full change lifecycle

Read and follow `./core/skills/orchestrators/change-orchestration/SKILL.md` with:

action: <action>
args: <remaining args>

**Actions:** `create`, `status`, `continue`, `list`, `approve spec`, `approve plan`, `plan`, `implement`, `verify`, `review`, `answer`, `assume`, `regress`, `request-changes`

**When to use:** You're building a feature, fixing a bug, or refactoring — any work that follows the spec-driven lifecycle. This is the primary namespace most users interact with.

**Scenario:** You've been asked to add user authentication. You create a change (`change create --type feature --name user-auth`), iterate on the spec with your stakeholder, approve it (`change approve spec user-auth-1`), plan the implementation (`change plan user-auth-1`), approve the plan, implement, verify, and review. If open questions come up during spec review, you answer them (`change answer user-auth-1 O1 "Use token-based auth"`). If the spec needs rework after planning, you regress (`change regress user-auth-1 --to soliciting`).

---

`init` — Initialize or upgrade an SDD project

Read and follow `./core/skills/orchestrators/init-orchestration/SKILL.md`.

No arguments — runs the full 7-phase workflow.

**When to use:** You're starting a new project from scratch, or you've upgraded the plugin and need to reconcile settings with the new version.

**Scenario:** You create a new directory for your project, open Claude Code, and run `/sdd-run init`. It detects the project name, verifies your environment (permissions), registers tech packs, verifies tech-pack-specific prerequisites, scaffolds the minimal config structure, and commits. On an existing project after a plugin upgrade, it detects the version mismatch, reconciles settings, and reports what changed.

---

`permissions` — Configure Claude Code permissions for SDD

Pass-through to system CLI:

<plugin-root>/core/system/system-run.sh permissions configure

**Actions:** `configure`

**When to use:** After installing or upgrading the plugin