/init-orchestration

name: init-orchestration
description: Orchestrates SDD project initialization — version detection, environment verification, scaffolding, and git setup.
user-invocable: false

Init Orchestration

Initialize a new spec-driven project with minimal structure. Components are scaffolded during implementation when the plan includes a scaffolding phase.

Input

Invoked by `sdd-run.md` with no arguments. Project name is derived from the current directory.

Workflow

This skill follows an approval-based workflow that verifies environment, creates minimal structure, and prepares for change-driven development.

| Phase | Purpose | |-------|---------| | 1 | Version detection + plugin build (if existing project with version mismatch) | | 2 | Detect project name from current directory (or load from existing settings) | | 3 | Environment verification (plugin, settings, permissions, reconciliation) | | 4 | Tech pack registration + tech-specific prerequisite verification | | 5 | Create minimal structure (config component only) — skipped for existing projects | | 6 | Git init + commit — skipped for existing projects | | 7 | Completion message |

---

Phase Tracking (CRITICAL)

**You MUST complete ALL phases before declaring initialization complete.** Use this checklist to track progress:

[ ] Phase 1: Version check completed (or skipped for new projects)
[ ] Phase 2: Project name detected and confirmed
[ ] Phase 3: Environment verified (plugin, settings, permissions, reconciliation)
[ ] Phase 4: Tech packs registered and prerequisites verified
[ ] Phase 5: Minimal structure created (or skipped for existing projects)
[ ] Phase 6: Git repository initialized and committed (or skipped for existing projects)
[ ] Phase 7: Completion report displayed

**DO NOT:**

• Stop after environment verification without completing structure creation
• Declare "initialization complete" until Phase 6 is finished
• Ask the user "should I continue?" between phases - just proceed

---

Phase 1: Version Detection & Plugin Build

**This phase runs BEFORE any other logic.** If plugin code has changed, all subsequent logic (validation, reconciliation, CLI commands) would run against stale built code.

1. Check if `sdd/sdd-settings.yaml` exists 2. If it exists, raw-parse the YAML and read version from `sdd.updated_by_plugin_version` (or legacy `sdd.plugin_version` for pre-reconciliation files) 3. Read current plugin version from `<plugin-root>/.claude-plugin/plugin.json` → `version` field 4. If versions differ:

• Run `npm install` in `<plugin-root>/system/`
• Run `npm run build` in `<plugin-root>/system/`
• Only proceed once plugin is built with current code

5. If no settings file exists, this is a new project — skip version check, proceed to Phase 2

---

Phase 2: Detect Project Name

**If `sdd/sdd-settings.yaml` exists** (existing project):

• Load `project.name` from the settings file
• **Do NOT prompt** for project name — it's already configured
• Switch to **upgrade/repair mode** (see below)

**If new project** (no settings file): Derive project name from the current directory:

Initializing SDD project...

Detected project name: my-app (from current directory)
Is this correct? (yes/no)

**Project Name Rules:**

• Derived from `basename(pwd)` (current directory name)
• Validated: lowercase letters, numbers, hyphens only
• Spaces/special chars: prompt user to provide a valid name
• Empty directory name: prompt user to provide a name

If user says no: Ask for project name interactively.

**Existing Project — Upgrade/Repair Mode:**

Existing SDD project detected: <project-name>

Running environment check...
  ✓ Plugin v6.5.0 (up to date)
  ✓ All required tools available
  ✓ Permissions configured

Checking project structure...
  ✓ sdd/sdd-settings.yaml exists
  ✓ specs/INDEX.md exists
  ⚠ Required components missing (per tech pack)

Would you like to add missing components? (yes/no)

If yes: Add only missing pieces, **never overwrite existing files**. If no: Exit gracefully.

**Running init multiple times is always safe.**

---

Phase 3: Environment Verification

3.1 Platform Check (HARD BLOCKER)

The SDD plugin requires a Unix environment. Check the runtime platform. If unsupported (native Windows without WSL), **STOP** immediately:

SDD requires a Unix environment (macOS or Linux).
On Windows, use WSL (Windows Subsystem for Linux): https://learn.microsoft.com/en-us/windows/wsl/install

3.2 Plugin Installation Verification (HARD BLOCKER)

This must pass before any other checks. The agent knows the plugin's absolute path from its Claude Code plugin context.

1. Use the known plugin path from your plugin context. If the plugin path cannot be determined, fall back to searching `~/.claude/plugins` recursively for the SDD plugin (look for `plugin.json` marker files). If neither finds the plugin: **STOP** — display installation instructions and exit. 2. Verify the plugin path exists and contains expected marker files (`plugin.json`) 3. Check core system build readiness:

• `<plugin-root>/core/system/dist/` exists (core system built)
• `<plugin-root>/core/system/node_modules/` exists (dependencies installed)

4. If `dist/` exists: core system is ready (this is the normal case for installed plugins) 5. If `dist/` missing but `core/system/package.json` exists: run `npm install && npm run build` in `<plugin-root>/core/system/` (development mode) 6. If repairs fail: **STOP** — display error details and exit

**This is a hard blocker.** If the plugin is not installed, not built, or not functional after repair attempts, do NOT continue to other phases.

3.3 Plugin Update Check

Checking for plugin updates...

Current version: 5.11.0
Latest version:  5.12.0

A newer version is available. It's recommended to upgrade before initializing.
Would you like to stop and upgrade? (yes/no)

If yes: Exit with instructions to run `cl