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 claude plugins update sdd If no: Continue with current version

3.4 .claude/settings.json Verification

Check the project's .claude/settings.json for required entries:

{
  "extraKnownMarketplaces": {
    "sdd": {
      "source": {
        "source": "github",
        "repo": "LiorCohen/sdd"
      }
    }
  },
  "enabledPlugins": {
    "sdd@sdd": true
  }
}

If missing: create or merge the required entries (preserve existing settings).

3.5 Permissions Check

Checking permissions...

  ⚠ SDD permissions not configured

Would you like me to configure recommended permissions automatically? (yes/no)

If yes: Run <plugin-root>/system/system-run.sh permissions configure to merge SDD permissions into .claude/settings.local.json.

If no:

You can configure permissions later:
  /sdd I want to configure permissions

This will merge SDD recommended permissions into your .claude/settings.local.json

Note: permissions written to .claude/settings.local.json do NOT take effect mid-session. The session restart requirement is communicated in Phase 6.

3.6 Settings Reconciliation (Existing Projects Only)

Skip this step if: this is a new project (no existing sdd/sdd-settings.yaml), or if versions already match.

If this is an existing project with a version mismatch (detected in Phase 1):

1. Run <plugin-root>/core/system/system-run.sh settings reconcile to migrate settings to the latest schema
2. Display the command output (it prints a summary of changes and any directory warnings)
3. Skip Phase 5 and Phase 6 — structure already exists, git already initialized
4. Jump to Phase 7 with upgrade-specific messaging

---

Phase 4: Tech Pack Registration + Prerequisites

Auto-register internal tech packs. Scan <plugin-root>/ for directories containing techpack.yaml. For each found:

1. Validate the manifest: <plugin-root>/core/system/system-run.sh tech-pack validate <tech-pack-path> --json
2. If valid, register in sdd/sdd-settings.yaml under techpacks:

   techpacks:
     <namespace>:
       path: <relative-path-to-tech-pack>
       version: <from manifest>
   

3. Build the tech pack system CLI if needed:
   • Check <tech-pack-path>/system/dist/ exists
   • If missing: run npm install && npm run build in <tech-pack-path>/system/

Tech-pack-specific prerequisite verification:

After registration, delegate tool/environment checks to each registered tech pack:

INVOKE techpacks.routeCommand with:
  namespace: <tech-pack-namespace>
  command: check-prerequisites

Each tech pack defines its own required tools and verification logic. Display results per tech pack:

Tech pack: <tech-pack-name>
  ✓ All prerequisites met

If any tech pack prerequisites fail, display the tech pack's install hints and wait for the user to resolve before proceeding.

---

Phase 5: Create Minimal Structure

Skip this phase for existing projects (upgrade/repair mode skips to Phase 7).

INVOKE the project-scaffolding skill with:

mode: minimal
project_name: <from Phase 2>
target_dir: <current directory>

---

Phase 6: Git Init + Commit

Initialize git repository (if not already in one):

git init

Stage and commit all created files following the commit-standards skill.

---

Phase 7: Completion Message

═══════════════════════════════════════════════════════════════
 PROJECT INITIALIZED: my-app
═══════════════════════════════════════════════════════════════

Location: /path/to/my-app

ENVIRONMENT:
  ✓ Plugin v7.0.0 (up to date)
  ✓ Tech packs registered
  ✓ Prerequisites verified
  ✓ Permissions configured

WHAT'S INCLUDED:
  ✓ SDD configuration (sdd/sdd-settings.yaml)
  ✓ Initial components (per tech pack)
  ✓ Spec registry (specs/INDEX.md)

TECH PACKS:
  ✓ <tech-pack-name> v<version>

IMPORTANT: Start a new Claude session before using SDD commands.
  Settings and permissions configured during init require a session restart to take effect.

NEXT STEPS:

  Start with a feature idea:
    /sdd I want to create a new feature

  Or import an existing spec:
    /sdd I want to import an external spec

  Available component types are defined by the active tech pack.
  Components are scaffolded during implementation when the plan includes them.

Important Notes

Zero Session Context

All workflow state is persisted. A new session can resume at any point by reading the files - no conversation history needed.

Two-Stage Approval

Implementation cannot begin until both SPEC.md and PLAN.md are explicitly approved:

1. Spec created → spec_review → user approves → plan created
2. Plan created → plan_review → user approves → implementation enabled

Checkpoint Commits

All state changes create checkpoint commits on feature branches:

• Checkpoints use --no-verify to skip hooks
• Checkpoints can be squashed into final commit
• Enables recovery from any interruption

Change IDs

• Format: <name>-<seq> (e.g., user-auth-1)
• Derived from the workflow's user-chosen name
• Unique across concurrent workflows (different names = different prefixes)
• Displayed in all status output
• Used for all commands that operate on a specific change

Output

Returns the Phase 7 completion message or an error if any hard blocker is encountered.