Diagnose Installation Problems

When Spec Kitty stops working -- skills go missing, slash commands vanish, or the runtime reports errors -- use this guide to identify the problem and recover.

Run the diagnostic command

Start every investigation with verify-setup:

spec-kitty verify-setup

The output is divided into three sections:

Installed tools -- lists every supported AI agent CLI and marks each as found or missing. A missing tool is only a problem if you intend to use that agent.
Project health -- checks .kittify/config.yaml, the skills manifest, and agent directories. Errors here block normal operation.
Feature context -- if a feature is active, verifies that its kitty-specs/ artifacts are present and well-formed.

Reading the output

Symbol	Meaning
Green checkmark	Check passed
Yellow warning	Non-blocking issue (e.g., optional tool not installed)
Red cross	Blocking error that must be resolved

To get machine-readable output for scripting or agent consumption:

spec-kitty verify-setup --json

For extended diagnostics including dashboard health:

spec-kitty verify-setup --diagnostics

Common failure patterns

Below are the nine most frequent failure states, each with its symptoms, root cause, and recovery steps.

1. Missing skill root

Symptoms:

Agent reports "skill not found" when running slash commands.
spec-kitty verify-setup lists missing skill files.

Cause: The skill root directory for your agent was deleted, or spec-kitty init ran before the current skill pack was available.

Recovery:

spec-kitty init . --ai <your-agent>

This regenerates the skill root and all skill files from the canonical registry.

2. Missing wrapper root

Symptoms:

Slash commands like /spec-kitty.implement are not recognized by the agent.
The agent's command palette shows no spec-kitty.* entries.

Cause: The agent's wrapper directory (e.g., .claude/commands/) was deleted or spec-kitty init was interrupted before wrapper files were written.

Recovery:

spec-kitty agent config sync --create-missing

This regenerates wrapper files for every configured agent.

3. Manifest drift

Symptoms:

spec-kitty verify-setup reports one or more "drifted" skill files.
Hash mismatches appear in the verification output.

Cause: Managed skill files under .kittify/skills-manifest.json were edited by hand after installation. This can also happen when merge conflicts leave partially resolved content in skill files.

Recovery:

spec-kitty upgrade

This overwrites drifted files with canonical content and updates the manifest hashes. Any local edits will be lost -- if you have intentional customizations, back them up first.

4. Runtime not found

Symptoms:

spec-kitty verify-setup reports .kittify/ is missing.
Errors like "next is blocked" or "runtime can't find missions" appear.

Cause: The .kittify/ directory was deleted, the repo was freshly cloned without running init, or the shell is in a subdirectory rather than the repository root.

Recovery:

Navigate to the repository root:
```
cd "$(git rev-parse --show-toplevel)"
```
Re-initialize:
```
spec-kitty init . --ai <your-agent>
```

5. Dashboard not starting

Symptoms:

The dashboard URL is unreachable after initialization.
Browser shows "connection refused" or the request times out.

Cause: Another process is using the dashboard port, the dashboard process crashed, or the dashboard was never started.

Recovery:

spec-kitty dashboard

If the port is already in use, the dashboard reports the conflict. Stop the conflicting process or let the dashboard auto-select an available port.

6. Stale agent configuration

Symptoms:

spec-kitty agent config status shows "Orphaned" directories (present on disk but not listed in config.yaml).
Configured agents show "Missing" directories.

Cause: Agents were added or removed by directly editing the filesystem instead of using spec-kitty agent config add / remove.

Recovery:

# Inspect current state
spec-kitty agent config status

# Sync the filesystem with config.yaml
spec-kitty agent config sync

See the safety warning about --remove-orphaned below before running sync with orphan removal.

7. Corrupted config file

Symptoms:

Any spec-kitty command fails with a YAML parse error referencing .kittify/config.yaml.

Cause: The config file was hand-edited and now contains invalid YAML, or a write operation was interrupted mid-file.

Recovery:

Back up the corrupted file:

cp .kittify/config.yaml .kittify/config.yaml.bak

Remove the corrupt file and re-initialize:

rm .kittify/config.yaml
spec-kitty init . --ai <your-agent>

If you had custom settings (e.g., a non-default agent list), restore them from the backup by comparing .kittify/config.yaml.bak with the freshly generated file.

8. Worktree linkage broken

Symptoms:

spec-kitty implement fails with "worktree not found".
git worktree list shows entries pointing to directories that no longer exist.

Cause: A worktree directory was moved or deleted without running git worktree remove. The stale metadata in .git/worktrees/ confuses both Git and Spec Kitty.

Recovery:

# List current worktrees and identify stale entries
git worktree list

# Prune stale references
git worktree prune

# Re-create the worktree if needed
spec-kitty agent action implement WP01 --agent <name>

9. Shared package imports resolve as a namespace package

Symptoms:

pytest fails during collection before any tests run.

The traceback contains an error like:

ImportError: cannot import name 'normalize_event_id' from 'spec_kitty_events' (unknown location)

The affected package reports __file__ as None:

python -c 'import spec_kitty_events as e; print(repr(getattr(e, "__file__", None))); print(e.__path__)'

Broken output looks like:

None _NamespacePath([.../site-packages/spec_kitty_events])

Cause: Python is resolving spec_kitty_events as a PEP 420 implicit namespace package instead of a normal package. This usually means an earlier install was partially removed: submodule files remain on disk, but spec_kitty_events/__init__.py or the matching .dist-info/ metadata is missing, stale, or mismatched. In that state, top-level re-exports such as normalize_event_id are unavailable even when the installed wheel normally provides them.

Recovery:

For a project virtual environment managed by uv, reinstall the dependency:

uv sync --reinstall-package spec-kitty-events

For the affected Python interpreter, remove the stale package directory and metadata before reinstalling:

python -m pip uninstall -y spec-kitty-events

python - <<'PY'
from pathlib import Path
import site

for root in map(Path, site.getsitepackages()):
    for path in root.glob("spec_kitty_events*"):
        print(path)
PY

Inspect the printed paths. They should be under the affected interpreter's site-packages. Then remove the stale package directory and metadata:

rm -rf /path/to/site-packages/spec_kitty_events \
       /path/to/site-packages/spec_kitty_events-*.dist-info
python -m pip install --force-reinstall spec-kitty-events==5.1.0

Re-run the diagnostic check. Healthy output includes a real __init__.py path:

'.../site-packages/spec_kitty_events/__init__.py' [...]

Do not work around this by changing Spec Kitty imports to spec_kitty_events.models. The CLI intentionally consumes the public top-level spec_kitty_events surface, and the consumer contract tests pin that surface.

Safety warning: --remove-orphaned and shared directories

The spec-kitty agent config sync --remove-orphaned command (which is the default behavior of sync) deletes the entire parent directory of an orphaned agent, not just the agent subdirectory.

This is dangerous for agents whose directory is shared with other tools:

Agent	Agent subdirectory	Parent directory	Also used by
GitHub Copilot	`.github/prompts/`	`.github/`	CI workflows, issue templates, dependabot config

Example of the hazard:

If copilot is orphaned (not in config.yaml but .github/ exists on disk), running sync --remove-orphaned deletes the entire .github/ directory -- including your GitHub Actions workflows, issue templates, and any other .github/ contents.

Safe alternatives:

Manually delete only the agent subdirectory instead of using --remove-orphaned:
```
rm -rf .github/prompts/
```
Keep the orphaned directory by passing --keep-orphaned:
```
spec-kitty agent config sync --keep-orphaned
```
Add the agent to your config so it is no longer considered orphaned:
```
spec-kitty agent config add copilot
```

Always run spec-kitty agent config status first to see which directories would be affected before executing a sync with orphan removal.

Quick-reference recovery table

Problem	Recovery command
Missing skill files	`spec-kitty agent config sync --create-missing`
Missing wrapper root	`spec-kitty agent config sync --create-missing`
Missing skill root	`spec-kitty init . --ai <your-agent>`
Manifest drift	`spec-kitty upgrade`
Runtime not found	`cd "$(git rev-parse --show-toplevel)" && spec-kitty init . --ai <your-agent>`
Dashboard not starting	`spec-kitty dashboard`
Stale agent config	`spec-kitty agent config sync`
Corrupted config	`cp .kittify/config.yaml .kittify/config.yaml.bak && rm .kittify/config.yaml && spec-kitty init . --ai <your-agent>`
Broken worktree	`git worktree prune && spec-kitty agent action implement WP01 --agent <name>`

Table of Contents

Diagnose Installation Problems

Run the diagnostic command

Reading the output

Common failure patterns

1. Missing skill root

2. Missing wrapper root

3. Manifest drift

4. Runtime not found

5. Dashboard not starting

6. Stale agent configuration

7. Corrupted config file

8. Worktree linkage broken

9. Shared package imports resolve as a namespace package

Safety warning: --remove-orphaned and shared directories

Quick-reference recovery table

See Also