Skill: sdd-init
Invocation
/sdd-init <slug> [notion-url] [--mode standard|auto]
Arguments:
<slug>— kebab-case identifier for the feature (e.g.user-invitation,supplier-csv-import)[notion-url]— optional Notion page URL to fetch and archive as source material[--mode standard|auto]— workflow mode (default:standard)standard: engineer-led — AI assists, human drives decisionsauto: AI-led — suitable for non-engineers; AI asks questions and makes decisions autonomously
Purpose
Initialize a spec directory for a new feature under .claude/specs/<slug>/. This is always the first step in the SDD workflow. It creates the directory structure, optionally fetches a Notion page as source material, and records the chosen mode in progress.md.
Execution Steps
Step 1: Validate inputs
- Confirm
<slug>is kebab-case (lowercase letters, digits, hyphens only). - If
--modeis not provided, default tostandard. - Announce to the user: "Initializing spec for
<slug>in--mode <mode>."
Step 2: Create directory structure
Create the following empty directories and files under .claude/specs/<slug>/:
.claude/specs/<slug>/
├── progress.md ← created in this step
├── requirements.md ← placeholder (created by sdd-requirements)
├── design.md ← placeholder (created by sdd-design)
├── tasks.md ← placeholder (created by sdd-tasks)
└── review.md ← placeholder (created by review skills)
Write placeholder files with a single comment line:
<!-- Artifact not yet generated. Run the corresponding sdd-* skill. -->
Step 3: Fetch Notion page (if notion-url provided)
If a Notion URL is given:
- Extract the page ID from the URL (last 32-character hex segment, with or without hyphens).
- Call
mcp__claude_ai_Notion__notion-fetchwith the page ID. - Write the raw Markdown content to
.claude/specs/<slug>/source-notion.md. - If the fetch fails, warn the user and continue without the source file.
If no Notion URL is given, skip this step.
Step 4: Write progress.md
Write .claude/specs/<slug>/progress.md with the following structure:
# Spec Progress: <slug>
**Mode**: <standard|auto>
**Initialized**: <YYYY-MM-DD>
**Notion source**: <notion-url or "none">
## Phase Status
| Phase | Skill | Status |
| ----- | ----------------------- | -------------- |
| 1 | sdd-requirements | ⬜ not started |
| 2 | sdd-review-requirements | ⬜ not started |
| 3 | sdd-design | ⬜ not started |
| 4 | sdd-tasks | ⬜ not started |
| 5 | sdd-review-plan | ⬜ not started |
| 6 | sdd-impl | ⬜ not started |
| 7 | sdd-review | ⬜ not started |
| 8 | sdd-pr | ⬜ not started |
## Change Log
| Date | Phase | Note |
| ------------ | ----- | -------------------------- |
| <YYYY-MM-DD> | init | Initialized spec directory |
Step 5: Print confirmation
Print a summary of what was created, including:
- Directory path
- Mode recorded
- Whether a Notion source was fetched
- The next step to take
Mode Behavior Summary
| Aspect | --mode standard |
--mode auto |
|---|---|---|
| Who drives | Engineer | AI |
| AI role | Assist + review | Ask + decide |
| Notion fetch | Optional | Optional |
| Next skill | /sdd-requirements <slug> |
/sdd-requirements <slug> |
Notes
- The
progress.mdfile is the single source of truth for the mode. Subsequent skills MUST read mode fromprogress.mdrather than accepting a--modeflag themselves. - If
.claude/specs/<slug>/already exists, warn the user and ask whether to overwrite or abort. Do NOT silently overwrite. - The
slugis used as-is in all file paths. Choose descriptive, stable slugs.
== PHASE COMPLETE: sdd-init == Artifact: .claude/specs//progress.md Summary:
- Created spec directory structure under .claude/specs//
- Recorded mode (standard|auto) in progress.md
- Fetched Notion source (if URL provided) → source-notion.md
- All placeholder artifacts initialized
⏸ WAITING FOR CONFIRMATION
Type CONFIRM sdd-requirements to proceed. Or describe changes needed.