# Spec Driven Init

> Initialize a .spec-driven/ directory in a project. Creates config.yaml, roadmap/, and specs/ scaffold, then guides the user to fill in project context.

- Skill: `kw12121212/spec-driven-init` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kw12121212/spec-driven-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kw12121212/spec-driven-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: kw12121212 (https://skillmd.com/u/kw12121212)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kw12121212/spec-driven-init

---


You are helping the user initialize the spec-driven workflow in a project.

## This Skill's Commands

If you cannot remember the exact command used by this skill, look it up here
before running anything. Do not guess.

```yaml
init: node {{SKILL_DIR}}/scripts/spec-driven.js init [path]
```

## Prerequisites

The target project directory must be accessible from the current environment.
Before proceeding, verify the path you plan to initialize exists and is the
intended project root.

## Steps

1. **Confirm the target project** — ask which project to initialize. If the user is already in the project root, use the current directory. Accept either `.` or an explicit path.

2. **Run init** — run:
   ```
   node {{SKILL_DIR}}/scripts/spec-driven.js init [path]
   ```
   Pass the path only if it differs from the current directory.
   - If `.spec-driven/` does not exist, this bootstraps it from scratch,
     including `roadmap/`, `specs/`, and `changes/`
   - If `.spec-driven/` already exists, this repairs any missing scaffold files
     and regenerates `specs/INDEX.md` without overwriting existing files

3. **Draft context** — read any existing project files that describe the project (`README.md`, `AGENTS.md`, `CLAUDE.md`, `package.json`, `pom.xml`, etc.). Draft a `context` value of 3–5 sentences covering:
   - What the project does
   - Tech stack and language(s)
   - Key conventions or constraints worth noting

   Write the draft into the `context` field of `.spec-driven/config.yaml`, then show it to the user and ask if they want to adjust anything.

4. **Capture existing behavior** — ask: "Does this project already have behavior worth documenting?" If yes, help the user write initial spec files under `.spec-driven/specs/<category>/` using the standard format:
   - Group by domain area (e.g. `auth/`, `api/`, `core/`)
   - Use `### Requirement: <name>` headings with RFC 2119 keywords
   - Describe what the system currently does, not what it should do
   - Add an entry for each new file to `.spec-driven/specs/INDEX.md`

   This step is important for existing projects — without initial specs, `propose` has nothing to read and cannot detect conflicts.

5. **Confirm** — show the user what was created and suggest running `/roadmap-plan` to shape the roadmap or `/spec-driven-propose` to create the first change.

## Rules
- Do not create any changes — initialization only
- Keep the context field concise: 3–5 sentences is enough for the AI to work from
- If `.spec-driven/` already exists, do not overwrite existing files — repair missing scaffold files only