Troubleshooting¶
Installation Issues¶
pip install specsmith finds no package¶
Check your Python version (requires 3.10+) and that pip is up to date: pip install --upgrade pip.
python -m specsmith gives "No module named specsmith.main"¶
Update to the latest version: pipx upgrade specsmith (or pip install --upgrade specsmith if not using pipx).
Version Mismatch — terminal vs VS Code¶
Kairos shows a different specsmith version than specsmith --version in the terminal¶
This almost always means you have two specsmith binaries on PATH and they resolve differently between Kairos and your shell.
Diagnose:
Get-Command specsmith -All # Windows: lists all binaries in PATH order
which -a specsmith # macOS/Linux
Fix: consolidate to a single pipx install:
pipx install specsmith # canonical install
pipx inject specsmith anthropic # + Claude
Then remove any duplicate installs (e.g. pip uninstall specsmith in any
other Python environment that has it).
specsmith --version shows an old version even after upgrading¶
Your shell PYTHONPATH may include a dev source directory
(...specsmith/src) that leaks an egg-info with an older version into
every Python process. Check:
$env:PYTHONPATH # Windows
echo $PYTHONPATH # macOS/Linux
If it points to a specsmith src/ directory, clear it for normal use:
Remove-Item Env:PYTHONPATH
For development, scope PYTHONPATH to the workspace only via
.vscode/settings.json (terminal.integrated.env.windows) rather than
a global shell export.
Import Issues¶
Import detects the wrong project type¶
Override during import — when prompted "Proceed with these settings?" answer n, then select the correct type from the list. Or override language: you'll be prompted for it.
Import doesn't detect my build system¶
Currently detected: pyproject.toml, Cargo.toml, go.mod, package.json, CMakeLists.txt, west.yml, build.gradle.kts, pubspec.yaml, *.csproj, Makefile. If yours isn't listed, file an issue.
Import overwrote my AGENTS.md¶
Without --force, import never overwrites existing files. If you used --force, that's the intended behavior. Re-create your AGENTS.md or restore from git.
Audit Issues¶
"REQ(s) without test coverage"¶
Your REQUIREMENTS.md has requirement IDs (e.g., REQ-CLI-001) that don't appear in any Covers: line in TESTS.md. Add Covers: REQ-CLI-001 references to your test entries.
"CI config missing expected tools"¶
Your CI config doesn't reference the tools expected for your project type. Run specsmith audit --fix to regenerate CI from the tool registry, or manually add the missing tools.
CI Issues¶
Generated CI fails: tool not found¶
The CI config assumes tools are installed in the CI environment. For example, ruff needs pip install ruff in the CI step. Check that the setup step installs the tool. specsmith generates these install steps, but if you've modified the CI, they may be missing.
Dependabot config has wrong ecosystem¶
The ecosystem is inferred from language in scaffold.yml, not from the project type. If your config says language: python but you need npm, update the language field.
Doctor Issues¶
"No scaffold.yml found"¶
Doctor requires scaffold.yml. Run specsmith import --project-dir . to generate one, or create it manually.
Tool shows as "not found" but it's installed¶
Doctor checks shutil.which() — the tool must be on your PATH. Virtual environments, conda environments, or tools installed in non-standard locations may not be found. Activate your environment first.
Template Issues¶
"'tools' is undefined" error in diff/upgrade¶
Upgrade to the latest version: pip install --upgrade specsmith.
General¶
How do I start over with governance?¶
specsmith import --project-dir . --force
How do I see what specsmith would generate without creating files?¶
There's no dry-run mode yet. Use a temporary directory:
mkdir /tmp/test && specsmith init --config scaffold.yml --output-dir /tmp/test --no-git