CodeVetter · Repo Unpack · Behavior traces
github/spec-kit
Three flows traced end-to-end: `specify init` (bootstrap), `specify workflow run` (primary automation), and extension install plus agent-side command execution (persistence and runtime paths). Self-upgrade and the event-dispatch path were also walked. Each flow funnels through `_require_specify_project` or asset-resolution helpers before touching the filesystem, and all writes go through hash-tracked manifests or safe-write helpers.
- `specify init` ordered trace: `show_banner` → `get_integration` validation → `--here`/directory-exists handling (`--force` merge vs confirmation prompt vs non-interactive error) → agent selection (`select_with_arrows` or non-interactive default via `SPECKIT_INTEGRATION_DEFAULT`/copilot) → `check_tool` when `requires_cli` → script-type selection → `StepTracker`+`Live` phases: `IntegrationManifest` → `resolved_integration.setup()` → `_install_shared_infra_or_exit` → `ensure_executable_scripts` → `ensure_constitution_from_template` → bundled workflow install → `_install_extension_during_init` per `--extension` → `save_init_options`.
- URL-based `--extension` installs during init are resolved for trust BEFORE the Rich `Live` display starts: `_confirm_extension_url_trust` shows an 'Untrusted Source' panel per URL, defaults to deny (and auto-denies when non-interactive), with `--trust-extension-urls` as the pre-authorization override.
- `specify workflow run <src>` trace: decide file-source vs installed-ID → `_require_specify_project()` (or cwd for file sources) → `_reject_unsafe_workflow_storage` → `load_custom_steps(project_root)` → `WorkflowEngine.load_workflow` → `validate` → `_parse_input_values` → `engine.execute` → `_execute_steps` dispatches each step by `type` through `STEP_REGISTRY` → results recorded to `RunState` → exit code from `_run_outcome_exit_code`; paused runs print a `workflow resume <run_id>` hint.
- A `command` step resolves `integration` (step → workflow default → project `.specify/integration.json`, `"auto"` → recorded key) and `model`, evaluates `{{ }}` expressions in `input`/`options`, guards every non-string value with a per-step FAILED result (rather than crashing the run), then invokes the agent CLI via `build_exec_args`, streaming output live.
- `specify extension add git` trace: `_require_specify_project` → `ExtensionManager(project_root)` → `--dev` local dir / `--from` URL (HTTPS check + trust prompt) / bundled lookup / catalog download → `install_from_directory` or `install_from_zip` validates `extension.yml`, copies artifacts, records files, and `register_hooks` merges `hooks:` into `.specify/extensions.yml` → `_refresh_events_and_warn` refreshes native hook config.
- `specify self check` trace: `_get_installed_version` (importlib.metadata, 'unknown' sentinel) → `_fetch_latest_release_tag` does exactly one `open_url` call to `api.github.com/repos/github/spec-kit/releases/latest` with a 5 s timeout and a 1 MiB JSON cap → `_normalize_tag` → `_is_newer` PEP 440 compare; failures categorize as offline/rate-limited/HTTP <code> without a catch-all.
- Agent-side `/speckit.specify` execution trace (what the installed command file instructs the agent to do): read `.specify/extensions.yml` for `hooks.before_specify` (mandatory hooks emitted as EXECUTE_COMMAND and awaited; optional hooks as prompts) → generate a 2-4 word short name → run the `create-new-feature` helper script which returns a `FEATURE_DIR`/`BRANCH_NAME` JSON contract → render `spec.md` from `spec-template.md` under `specs/NNN-<short-name>/`.
- Agent-native event trace: the agent's hook config (emitted by `install_integration_events` during `setup()`) invokes the generated `.specify/events.py` dispatcher → dispatcher resolves the event's command template and confines the script token under the project root → or falls back to `specify event run <cmd> <event> <timeout>` → `resolve_and_run_event_command` executes the script with the stdin payload.
- Uninstall trace: `IntegrationBase.teardown` → `remove_events` (strips Specify-authored native hook entries) → `manifest.uninstall(project_root, force=...)` removes only files whose on-disk SHA-256 still equals the recorded hash, returning `(removed, skipped)` lists so user-modified files survive.
- `specify integration uninstall`/shared-infra refresh respects a three-tier overwrite policy: `force=True` overwrites everything (still skipping symlinks), `refresh_managed=True` overwrites only files whose hash matches the manifest (user edits preserved with a warning + caller-supplied remediation hint), default adds only missing files.