spec-kitty init lifecycle
Who is this for (1)
- End Users — Written for end-users.
Reference description of what spec-kitty init creates, in what order, and how its options interact. For installation, see Install on macOS / Linux / Windows.
Synopsis
spec-kitty init [PROJECT_NAME] [OPTIONS]| Argument | Description |
|---|---|
PROJECT_NAME | Name of a new directory to create. Omit to initialize the current directory. |
| Option | Description |
|---|---|
--ai <keys> | Comma-separated agent keys (claude, codex, gemini, cursor, qwen, opencode, windsurf, kilocode, auggie, copilot, q, kiro, antigravity, vibe, pi, letta). Required in non-interactive mode. (roo is deprecated and rejected — Roo Code shut down 2026-05-15.) |
--non-interactive / --yes / -y | Skip all prompts. Equivalent to setting SPEC_KITTY_NON_INTERACTIVE=1. |
--help | Show full help (this page is a curated summary). |
Note:
initnever touches git. It does not rungit init, does not stage files, and does not create commits. Manage version control yourself.
What gets created
spec-kitty init materializes the following layout. Existing files are preserved; the command is idempotent and can be re-run safely.
.kittify/ — project scaffold
Holds spec-kitty’s per-project configuration and runtime state. Key contents:
| Path | Purpose |
|---|---|
.kittify/config.yaml | Single source of truth for configured agents and feature flags. |
.kittify/metadata.yaml | Project schema version, used by the upgrade gate. |
.kittify/memory/ | Long-lived memory used by the runtime. |
.kittify/command-skills-manifest.json | Tracks which agents reference each command-skill package (Codex/Vibe/Pi/Letta). |
kitty-specs/ — mission artifacts
Empty at init time. Populated by /spec-kitty.specify, /spec-kitty.plan, and /spec-kitty.tasks. Each mission becomes a subdirectory.
Agent command directories
One directory per agent selected via --ai. Spec Kitty supports 17 agents total — 12 command-surface agents and 5 command-skill agents. (Roo Code shut down on 2026-05-15 and can no longer be selected; existing .roo/ directories are preserved on upgrade.)
| Agent key | Directory created | Command surface |
|---|---|---|
claude | .claude/commands/ | /spec-kitty.* |
copilot | .github/prompts/ | /spec-kitty.* |
gemini | .gemini/commands/ | /spec-kitty.* |
cursor | .cursor/commands/ | /spec-kitty.* |
qwen | .qwen/commands/ | /spec-kitty.* |
opencode | .opencode/command/ | /spec-kitty.* |
windsurf | .windsurf/workflows/ | /spec-kitty.* |
kilocode | .kilocode/workflows/ | /spec-kitty.* |
auggie | .augment/commands/ | /spec-kitty.* |
q | .amazonq/prompts/ | /spec-kitty.* |
kiro | .kiro/prompts/ | /spec-kitty.* |
llxprt | .llxprt/commands/ | /spec-kitty.* |
codex | .agents/skills/spec-kitty-<command>/ | $spec-kitty-<command> |
vibe | .agents/skills/spec-kitty-<command>/ plus .vibe/config.toml | /spec-kitty-<command> |
pi | .agents/skills/spec-kitty-<command>/ | /skill:spec-kitty-<command> |
letta | .agents/skills/spec-kitty-<command>/ | /spec-kitty-<command> |
antigravity | .agents/skills/spec-kitty-<command>/ | /spec-kitty-<command> |
Codex, Vibe, Pi, Letta, and Antigravity share a single installation tree under .agents/skills/; Vibe also gets a .vibe/config.toml skill_paths entry pointing at that tree. Only the agents you list in --ai get directories.
Ignore files
.gitignoreis created or appended to with a# spec-kittyblock that excludes execution worktrees and ephemeral runtime files..claudeignore(and equivalent for other agents) gets matching entries so agents do not crawl generated state.
Idempotent behavior
spec-kitty init is safe to re-run:
-
Existing files are not overwritten.
-
Missing files for configured agents are recreated.
-
Agents that are not in
config.yamlare left untouched —initwill not recreate a directory you removed viaspec-kitty agent config remove. -
Re-running with a different
--ailist adds the new agents but does not remove the old ones. To remove agents, use:Terminal window spec-kitty agent config remove <key>spec-kitty agent config sync
Non-interactive mode
Non-interactive mode is triggered by any of:
- The
--non-interactiveflag. - The
--yes/-yflag. - The
SPEC_KITTY_NON_INTERACTIVE=1environment variable. - Running in a non-TTY context (CI, scripts).
In non-interactive mode, --ai is required. Example:
spec-kitty init my-project --ai claude,codex --non-interactiveHost selection
The set of installed agent directories is driven by --ai. Validate the keys you pass — invalid keys cause init to exit non-zero before touching the filesystem.
# Install only the Claude Code surfacespec-kitty init . --ai claude
# Install Claude + Codex + Cursorspec-kitty init . --ai claude,codex,cursorYou can change the agent set later without re-running init:
spec-kitty agent config add geminispec-kitty agent config remove cursorspec-kitty agent config syncExit codes
| Code | Meaning |
|---|---|
| 0 | Init succeeded (created or already-current). |
| 1 | General error (filesystem permission, invalid agent key, etc.). |
| 2 | Usage error (missing required arg, invalid flag combination). |
What init does not do
- It does not initialize a git repository.
- It does not create any commits.
- It does not run
pipx ensurepathor modify your shell PATH. - It does not contact PyPI or any other network resource.
- It does not run migrations — that is the job of
spec-kitty upgrade.
Examples
# Interactive init in current directoryspec-kitty init
# New project directory with Claudespec-kitty init my-app --ai claude
# Multiple agents, non-interactive (CI)spec-kitty init . --ai claude,codex --non-interactive
# Add Spec Kitty to an existing repo without polluting itcd /path/to/existing-repospec-kitty init . --ai claude --non-interactive