get2knowio / get2knowio/devcontainer-features

ai-clis: specifyCli's uv-managed Python is undiscoverable, so Spec Kit's agent-context hook always skips

Open
#77 0 comments 0 reactions 0 assignees View on GitHub
bug
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.