spec-driven-init

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

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

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.
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
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.
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.
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

spec-driven-init

NPX Install

SKILL.md Content

Prerequisites

Steps

Rules