get2knowio / get2knowio/devcontainer-features
ai-clis: specifyCli's uv-managed Python is undiscoverable, so Spec Kit's agent-context hook always skips
- Dominant language
- Shell
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
`ai-clis` installs Specify CLI with `uv tool install` (`src/ai-clis/install.sh:148`), which places it in an isolated uv venv. Spec Kit's bundled `agent-context` extension then can't find a Python that can `import yaml`, so the hook silently no-ops in every container this feature builds.
## Root cause
Spec Kit's own docs (`.specify/extensions/agent-context/README.md`) state the assumption:
> PyYAML ships with the `specify` CLI and is normally available via the same `python3` interpreter.
That holds when `specify` is pip-installed into the system Python. It does **not** hold for `uv tool install`, which creates an isolated venv — PyYAML lands where the system `python3` can never see it.
The hook script (`.specify/extensions/agent-context/scripts/bash/update-agent-context.sh`) probes `$SPECKIT_PYTHON`, then `python3`, then `python`, requiring `import yaml` to succeed. None match, so it prints `Python 3 with PyYAML not found on PATH; skipping update` and exits 0. Because it exits 0, nothing surfaces as a failure — `CLAUDE.md` / agent context files just never get refreshed after `/speckit-specify` or `/speckit-plan`.
## Adding a Python feature dependency does not fix this
Worth stating up front, since it's the intuitive fix. A container built from `node-agentic` plus `ghcr.io/devcontainers/features/python:1` **and** `get2knowio/devcontainer-features/python-tools`:
```console
$ command -v python3
/usr/local/python/current/bin/python3
$ python3 -c "import yaml"
ModuleNotFoundError: No module named 'yaml'
```
The uv venv is isolated regardless of what else is installed. A `dependsOn`/`installsAfter` on a Python feature adds build time and changes nothing. The interpreter isn't missing — uv already provides one with PyYAML 6.0.3 in it. It's just not discoverable.
## Suggested fix
Two pieces in `src/ai-clis`:
**1. Wrapper script**, written by `install.sh` inside the `if [ "${SPECIFYCLI}" = "true" ]` block, after `uv tool install` succeeds:
```sh
# Expose the uv-managed interpreter (which has PyYAML) under a fixed path so
# Spec Kit's agent-context hook can find it. Must be an exec wrapper, NOT a
# symlink -- see below.
cat > /usr/local/bin/speckit-python <
Contributor guide
Research direction
Start with src/ai-clis/install.sh:148 and the specifyCli installation block, then inspect the feature's devcontainer-feature.json. Add the fixed SPECKIT_PYTHON environment path and wrapper described in the issue, preserving the uv-managed interpreter. Verify by running .specify/extensions/agent-context/scripts/bash/update-agent-context.sh and confirming that agent context is updated when specifyCli is enabled and skipped cleanly when it is omitted.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, shell
- Domain
- devops, tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 76/100