betterspec init

Initialize betterspec in the current project. Creates the required directory structure, configuration file, and scaffolds tool-specific integrations for your AI coding assistant.

Usage

betterspec init

Options

Option	Description
`-C, --cwd <path>`	Run as if betterspec was started in the given path

What it does

Running betterspec init walks you through a 3-step interactive flow and then scaffolds everything needed for spec-driven development — including native integration with your AI tool.

Interactive Flow

Step 1: Spec Mode

Choose where specs are stored:

? Select spec mode:
  local          — Specs live inside the project only
  local+global   — Specs live in the project with global fallbacks
  global         — Specs are managed globally across projects

Step 2: Tool Selection

Choose your AI coding tool. betterspec scaffolds native integration files for the selected tool:

? Select your AI tool:
  OpenCode     — Agents, inline plugin, hooks, and skills
  Claude Code  — Subagents, hooks, CLAUDE.md context, and skills
  Gemini CLI   — Agents, GEMINI.md context, and skills
  Cursor       — Rules and skills
  Codex        — Agents and skills
  Generic      — Skills only (works with any tool)

Step 3: Skills Location

Choose where skill files are installed:

? Where should skills be installed?
  local   — Skills in betterspec/skills/ only
  global  — Skills in ~/.betterspec/skills/ only
  both    — Skills in both locations

What Each Tool Adapter Creates

OpenCode

What	Where
Agent files (Planner, Builder, Validator, Archivist)	`.opencode/agents/`
Global plugin (installed separately via opencode.json)	See OpenCode integration

Claude Code

What	Where
Subagent files (Planner, Builder, Validator, Archivist)	`.claude/agents/`
Hook scripts	`.claude/hooks/`
Hook configuration	`.claude/settings.json`
Context injection	`CLAUDE.md`

Gemini CLI

What	Where
Agent files	`.gemini/agents/`
Context injection	`GEMINI.md`

Cursor

What	Where
Rules	`.cursor/rules/betterspec.mdc`

Codex

What	Where
Context injection	`AGENTS.md` (betterspec section appended)

Generic

What	Where
Skills	`betterspec/skills/`

No tool-specific files are created. Any AI tool that reads project files can use the specs and skills directly.

Directory Structure

After running betterspec init, the core betterspec structure is created:

betterspec/
  betterspec.json
  knowledge/
  skills/

betterspec.json — Project configuration (includes tool and skills fields)
knowledge/ — Directory for project knowledge documents
skills/ — Directory for reusable skill definitions

Additional tool-specific files are created based on your selection in Step 2.

Example

$ betterspec init
? Select spec mode: local+global
? Select your AI tool: Claude Code
? Where should skills be installed? both
Created betterspec/betterspec.json
Created betterspec/knowledge/
Created betterspec/skills/
Created .claude/agents/planner.md
Created .claude/agents/builder.md
Created .claude/agents/validator.md
Created .claude/agents/archivist.md
Created .claude/hooks/betterspec-context.sh
Updated .claude/settings.json
Updated CLAUDE.md
Betterspec initialized for Claude Code.

betterspec init

On this page