CodeVetter · Repo Unpack evidence
github/spec-kit
github.com/github/spec-kit ↗ · 714 files · 10.0 MB
🌱 Spec Kit Build with a spec, fix a bug, or assess an idea — with your coding agent.
Overview
Spec Kit is GitHub's toolkit for Spec-Driven Development (SDD): the Python package `specify-cli` ships a `specify` CLI that scaffolds a `.specify/` project directory containing prompt templates, helper scripts (bash/PowerShell/Python), workflows, and per-agent 'integration' files so that ~40 supported AI coding agents (Copilot, Claude, Gemini, Codex, ...) expose `/speckit.*` commands such as specify → plan → tasks → implement. Beyond init, the CLI manages a full package ecosystem — integrations, extensions, presets, workflows, and bundles — resolved through local and remote catalogs, plus a YAML workflow engine and an agent-native event/hook dispatcher. Distinctively, the wheel bundles all assets into `specify_cli/core_pack/` so `specify init` works fully offline, and every installed file is tracked by SHA-256 manifest so uninstall never clobbers user edits.
System map
The system is a single Python CLI (`specify`, entrypoint `specify_cli:main`) built on Typer/Rich. The root app in `src/specify_cli/__init__.py` wires together command groups that each own a subpackage: init/check/version/self, integration, extension, preset, workflow, bundle, artifact, and event. All distributable content (templates, scripts, extensions, workflows, presets, catalogs) is bundled into the wheel via hatchling force-include as `core_pack`, with a repo-root fallback for source checkouts. State is stored inside each target project under `.specify/` (init-options.json, integration.json, extensions.yml, manifests, workflow run state). External integrations are limited to HTTPS downloads (GitHub API/releases, catalog JSON, extension archives) and subprocess invocation of agent CLIs.
- The console script `specify` maps to `specify_cli:main`; `main()` forces UTF-8 stdout/stderr on Windows then invokes the root Typer `app` defined in `src/specify_cli/__init__.py`.
- The root Typer app registers every command group centrally: `init` via `commands/init.py`, `check`/`version`/`self` locally, plus `extension`, `integration`, `event`, `preset`, `artifact`, `bundle`, and `workflow` groups imported from their `_commands.py`/`commands/*.py` modules and attached via `register(app)` calls.
- The wheel bundles all runtime assets into `specify_cli/core_pack/` via `[tool.hatch.build.targets.wheel.force-include]`: page templates, `templates/commands`, bash/powershell/python scripts, bundled extensions (git, agent-context, assess, bug), workflows (speckit, bugfix, assess), presets (lean, constitution-sync), and bundle catalog snapshots — making `specify init` work without network access.
- `_assets.py` is the stdlib-only base of the dependency graph: `_locate_core_pack()` finds the wheel-bundled `core_pack/` directory and `_repo_root()` falls back to the source checkout; `_locate_bundled_extension|workflow|preset` check core_pack first, then `extensions/`, `workflows/`, `presets/` under the repo root.
- `INTEGRATION_REGISTRY` in `integrations/__init__.py` is the single source of truth for AI-agent integrations; `_register_builtins()` instantiates and registers ~40 integrations (claude, copilot, gemini, codex, kilocode, cursor-agent, kiro-cli, generic, ...) in alphabetical order, with duplicate or empty keys rejected.
- Command-group layout is codified in `design/cli.md`: each real CLI command lives in `command_<name>.py`, private phases in `_command_<name>_<phase>.py`, group registration in `_commands.py`, and nested CLI namespaces (e.g. `extension catalog add`) map to matching subdirectories — `extensions/` is the reference implementation.
- The workflow subsystem pairs `workflows/engine.py` (WorkflowDefinition parsing, `validate_workflow`, WorkflowEngine orchestration, RunState persistence) with `workflows/__init__.py`'s `STEP_REGISTRY`, which registers 11 built-in step types: command, shell, prompt, gate, if, init, slot, switch, while, do-while, fan-out, fan-in.
- Authentication is opt-in and registry-based: `AUTH_REGISTRY` holds GitHubAuth and AzureDevOpsAuth providers; credentials are only sent when the user creates `~/.specify/auth.json` mapping hosts to providers, and `_github_http.py` restricts `Authorization` headers (from GITHUB_TOKEN/GH_TOKEN) to a fixed GITHUB_HOSTS allowlist.
- Project-scoped commands resolve the project root through `_require_specify_project()`, which requires a `.specify/` directory in the cwd unless the `SPECIFY_INIT_DIR` env var overrides it — this single chokepoint applies uniformly to integration, extension, preset, workflow, bundle, and artifact subcommands.
- The package targets Python >=3.11 with deps typer, click, rich, platformdirs, readchar, pyyaml, packaging, pathspec, json5; tests run under pytest (`testpaths = ["tests"]`) and CI exercises Linux/macOS/Windows on Python 3.13/3.14.
- Distribution is a PyPI wheel (`specify-cli`) typically installed via `uv tool install specify-cli`; releases are cut by pushing `v*` tags which trigger `.github/workflows/release.yml` to build notes and create the GitHub release.
- Self-version reporting uses `importlib.metadata.version("specify-cli")` first and falls back to reading `pyproject.toml` from the repo root, returning "unknown" when neither works.
Feature catalog
The CLI surface splits into project bootstrapping (`init`, `check`, `version`, `self check|upgrade`), four parallel package managers (`integration`, `extension`, `preset`, `bundle`) each with add/remove/list/info/search/enable/disable/update and nested `catalog` commands, a workflow engine front-end (`workflow run/resume/status/...` plus `step` and `overlay` groups), a read-only `artifact` introspection group, and an `event run` target used by generated hook dispatchers. On the content side it ships ten core SDD command templates, four bundled extensions, three bundled workflows, and four repo presets.
- `specify init [NAME]|.|--here` scaffolds a project with flags `--script sh|ps|py`, `--integration <key>`, `--integration-options`, `--preset`, repeatable `--extension` (bundled name, local path, or HTTPS URL), `--trust-extension-urls`, `--force`, `--non-interactive`, `--ignore-agent-tools`; several legacy flags (`--skip-tls`, `--github-token`, `--offline`, `--debug`) remain as hidden no-ops.
- `specify check` iterates `AGENT_CONFIG` and runs `check_tool` (shutil.which-style probe) for each `requires_cli` agent, marks IDE-based agents as skipped, and also probes `code`/`code-insiders`.
- `specify version` prints a Rich info panel; `--features` emits stable capability flags (e.g. `workflow_catalog`, `integration_upgrade_command`) and `--json` requires `--features`. `specify self check|upgrade` lives in `_version.py` and compares the installed distribution version against the latest GitHub release tag.
- `specify integration` is a command group (app `integration_app`) with command modules for install, uninstall, list, status, switch, use, upgrade, info, search, scaffold, plus a nested `catalog` group (add/list/remove).
- `specify extension add` supports `--dev` (local directory), `--from <url>` (external archive with an HTTPS-or-localhost check and a default-deny trust prompt), `--force`, and `--priority`; the group also has remove, list, info, search, enable, disable, set-priority, update, and `catalog` subcommands.
- `specify preset` manages template-override packs with the same verb set (add/remove/list/info/search/enable/disable/set-priority/update) plus `resolve` (shows the composed resolution stack) and a nested `catalog` group.
- `specify workflow` exposes run, resume, status, list, add, remove, update, enable, disable, search, info, resolve plus nested `catalog`, `step` (with its own `catalog`), and `overlay` groups; `workflow run` accepts an installed workflow ID or a local YAML path.
- `specify bundle` packages/installs role-based bundles with verbs init, add, install, build, validate, list, info, search, remove, update and a nested `catalog` group; bundled catalog JSON ships `bugfix` and `assess` first-party bundles.
- `specify artifact list|info` is a thin read-only introspection group over `ArtifactCatalog` (commands/templates/scripts/hooks), emitting strict JSON envelopes on stdout/stderr and documented in `docs/reference/artifacts.md`.
- `specify event run <command_name> <event_name> [timeout]` is the dispatcher target for agent-native hooks: it reads a JSON payload from stdin capped at 1 MiB (counting encoded bytes via `sys.stdin.buffer`), then calls `resolve_and_run_event_command` from `events.py`.
- Ten core SDD command templates ship under `templates/commands/`: specify, plan, tasks, implement, converge, analyze, clarify, constitution, checklist, taskstoissues — mirrored by `SKILL_DESCRIPTIONS` in the package root.
- Bundled first-party content: extensions `git` (branch workflow + hooks), `agent-context` (manages CLAUDE.md/AGENTS.md sections), `assess` (idea triage), `bug` (assess→fix→test), plus `template`/`selftest` scaffolds; workflows `speckit` (specify→plan→tasks→implement with gates), `bugfix`, `assess`; presets `lean`, `constitution-sync`, `scaffold`, `self-test`.
Data flow
Inputs enter through Typer commands or content manifests (extension.yml, preset.yml, workflow.yml, bundle.yml, catalog JSON). `specify init` resolves an integration from `INTEGRATION_REGISTRY`, writes `.specify/init-options.json`, renders command templates with per-agent placeholders into the agent's config directory, and copies shared scripts/templates into `.specify/` — every written file hash-recorded in an `IntegrationManifest`. Extensions and presets layer on top via `CommandRegistrar` rendering and a priority-resolved template stack; hooks land in `.specify/extensions.yml`. Workflow runs persist resumable state under `.specify/workflows/runs/<run_id>/`. Outbound data is confined to HTTPS downloads with byte caps and optional SHA-256 pins, and subprocess calls to agent CLIs.
- `specify init` persists the user's choices to `.specify/init-options.json` via `save_init_options`; `load_init_options`/`is_ai_skills_enabled`/`resolve_active_agent_for_registration` read it back and distinguish missing-file (legacy fallback) from malformed-file (fail closed) via the `MISSING_INIT_OPTIONS_FILE` sentinel.
- Core command templates declare per-script-type helper invocations in `scripts:` frontmatter (`sh`, `ps`, `py` entries) and carry placeholders (`{SCRIPT}`, `$ARGUMENTS`, `__SPECKIT_COMMAND_<NAME>__`) that integrations resolve at install time through `process_template()` using the integration's `invoke_separator` (`.` for markdown agents, `-` for skills agents).
- Every file an integration installs is recorded with a SHA-256 in `.specify/integrations/<key>.manifest.json` via `IntegrationManifest.record_file`/`record_existing`; `teardown()` delegates to `manifest.uninstall()` which deletes only files whose current hash still matches (skipping user-modified files) unless `--force`.
- Shared infrastructure (`_install_shared_infra_impl` in `shared_infra.py`) copies `.specify/scripts/<variant>/` and `.specify/templates/` from core_pack or the repo root, resolves `__SPECKIT_COMMAND_*__` placeholders, tracks files in `speckit.manifest.json`, and writes a managed `.specify/.gitignore` covering `feature.json` and per-machine `extensions/*/local-config.yml`.
- Workflow run state is persisted under `.specify/workflows/runs/<run_id>/` as atomically-written `state.json` + `inputs.json` plus an appended `log.jsonl`; `RunState.load` validates `run_id` against a strict pattern before building the path, and `workflow resume` reloads the persisted workflow copy and merges new inputs over persisted ones.
- Extension installs parse `extension.yml` into an `ExtensionManifest` (validating `provides.commands` names against `^speckit\.<ns>\.<name>$`, hooks, events, templates, scripts), copy files via `ExtensionManager.install_from_directory`/`install_from_zip`, and merge `hooks` entries into `.specify/extensions.yml` through `register_hooks`.
- Remote content (catalog JSON, extension/preset/workflow archives) is fetched with hard byte ceilings — `MAX_DOWNLOAD_BYTES` 50 MiB, `MAX_JSON_METADATA_BYTES` 1 MiB, `MAX_JSON_CATALOG_BYTES` 8 MiB, per-entry and total zip caps — via `read_response_limited`/`safe_extract_archive`; catalog-declared `sha256` pins are verified with `hmac.compare_digest` before install.
- The events flow generates a self-contained `.specify/events.py` dispatcher plus native hook config per integration; the dispatcher resolves the event's command template and runs its script confined under the project root (`EVENT_SCRIPT_PATH_CONFINEMENT = True`), with `specify event run` as the fallback entry point that accepts a ≤1 MiB stdin payload.
- `CommandRegistrar` (agents.py) lazily derives `AGENT_CONFIGS` from `INTEGRATION_REGISTRY` `registrar_config` dicts (propagating `invoke_separator` and `dev_no_symlink`), then renders commands into each agent's directory/format for extensions and presets — so the registry is the single metadata source for both the integration layer and the registrar.
- Skills-mode installs branch on the persisted `ai_skills` flag: `resolve_active_skills_dir` maps the project to `<agent_folder>/skills` (with symlink/containment checks via `_ensure_safe_shared_directory`), special-cases `generic` (no static folder → disabled) and `kimi` (native-skills fallback when flag unset).
- The workflow engine resolves the dispatch integration by layered fallback — step `integration:` → workflow default → `.specify/integration.json` project default — with `"auto"` meaning the project-recorded integration, then `CommandStep.execute` builds the agent CLI argv via `build_exec_args` and streams output to the terminal.
- Catalog stacks (`CatalogStackBase` + per-domain subclasses) merge an ordered list of catalog sources, each entry carrying `url`, `priority`, and `install_allowed`; catalog entries from discovery-only catalogs are treated as untrusted — e.g. `_command_safe_id` refuses to interpolate non-`[a-z0-9-]` IDs into suggested shell commands.
Behavior traces
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.
Testing signals
Testing is pytest-based (~253 files under `tests/`) with coverage configured in pyproject. The suite mirrors the CLI command surface under `tests/specify_cli/` per `design/cli.md`, has one file per integration under `tests/integrations/`, parity tests proving bash↔python↔powershell script equivalence, contract tests for wheel bundling and catalog/manifest schemas, and workflow/overlay/engine suites. CI runs a 3-OS × 2-Python pytest matrix plus ruff, markdownlint, a dependency security audit, and CodeQL.
- pytest is configured in pyproject with `testpaths=["tests"]`, strict markers, and short tracebacks; the `test` extra adds `pytest` and `pytest-cov`, and `[tool.coverage]` scopes coverage to `src/`.
- Command tests mirror the source layout exactly — `src/specify_cli/extensions/command_add.py` ↔ `tests/specify_cli/extensions/test_command_add.py`, `catalog/command_add.py` ↔ `tests/specify_cli/extensions/catalog/test_command_add.py` — a convention mandated by `design/cli.md`.
- Every registered integration has a dedicated test file `tests/integrations/test_integration_<key>.py` (hyphens→underscores), plus base-class suites (`test_integration_base_markdown/toml/yaml/skills`) and registry-level tests (`test_base`, `test_cli`, `test_events`).
- tests/conftest.py provides the shared harness: `_has_working_bash()` probes for a real bash (rejecting the WSL launcher on Windows, override `SPECKIT_TEST_BASH=1`), autouse fixtures isolate `~/.specify/auth.json` and strip inherited `SPECIFY_*`/`SPECKIT_INTEGRATION_*` env vars, and argv0 fixtures fake uv-tool/pipx/uvx install locations for self-upgrade tests.
- Script parity is enforced by dedicated tests — `test_setup_plan_python_parity.py`, `test_create_new_feature_python_parity.py`, `test_resolve_template_python_parity.py`, `test_check_prerequisites_python_parity.py`, `test_setup_tasks_python_parity.py` — matching the AGENTS.md rule that all `scripts:` frontmatter entries must be behaviorally equivalent across sh/ps/py.
- Contract tests under `tests/contract/` pin the wheel's bundled payload and schemas: `test_wheel_core_pack_scripts.py`, `test_wheel_bundled_presets.py`, `test_wheel_bundled_workflows.py`, `test_catalog_schema.py`, `test_manifest_schema.py`, `test_firstparty_bundle_catalog_consistency.py`.
- Workflow coverage lives in `tests/workflows/` (bundled speckit/bugfix/assess workflow validation, overlay composer/merge/schema/security, slot step, resolver integration) plus top-level `test_workflows.py` and `test_workflow_run_without_project.py`.
- Security-focused suites exist for the risky paths: `test_download_security.py` (bounded reads/extraction), `test_registrar_path_traversal.py`, `test_command_add_path_traversal.py`, `test_security_workflow.py`, and `test_authentication.py`.
- CI: `.github/workflows/test.yml` runs ruff (`uvx ruff@0.15.0 check src tests`) then pytest on ubuntu/windows/macos × Python 3.13/3.14; `lint.yml` adds `git diff --check` and markdownlint-cli2; `security.yml` runs a dependency audit script; `codeql.yml` runs CodeQL.
- The suite is heavily fixture/monkeypatch-driven (tmp_path projects, faked argv0, stubbed catalogs) rather than spawning real agent CLIs; `_has_working_bash` auto-skips shell-dependent tests when bash is absent, so script-level coverage can silently thin out on under-provisioned runners. (inferred)
- Extension behavior has both legacy consolidated suites (`tests/test_extensions.py`, `tests/test_presets.py`) and newer per-command mirrored suites; `design/cli.md` explicitly allows the consolidated domain suites to remain until separately reorganized, so coverage is duplicated across both styles rather than missing.
Risk map
The highest-risk surface is remote-code paths the CLI intentionally supports: project-local custom workflow steps are imported and executed, URL-based extension/bundle installs download and extract archives, and generated event dispatchers + workflow `shell`/`command` steps run subprocesses with user privileges. These are hardened with HTTPS-only rules, byte caps, zip-slip defenses, SHA-256 pins, trust prompts, and path confinement — but the security posture is defense-in-depth around inherently dangerous features. Secondary risks: three giant modules concentrate blast radius, compatibility shims create fragile monkeypatch coupling, and a few silent-fallback paths can hide breakage.
- `load_custom_steps` dynamically imports and executes `__init__.py` from every package under `.specify/workflows/steps/` — arbitrary code execution by design for community step types. Mitigations: symlink rejection on every path component, sanitized synthetic module names, sys.modules cleanup on failure — but any file dropped into that directory runs with user privileges.
- Workflow `shell` and `command` steps run subprocesses with the user's full privileges; the engine explicitly documents that `requires:` (and any hypothetical `permissions:` key — which is rejected by validation) is advisory and 'NOT a security boundary'.
- URL installs (`--extension <url>`, `extension add --from`, catalog downloads) fetch remote archives: hardened by `is_https_or_localhost_http`, `is_safe_download_redirect`, `read_response_limited` byte caps, `safe_extract_archive` (entry count/size/path limits, Windows reserved names), and optional `sha256` catalog pins — but a missing pin means integrity rests on HTTPS alone.
- The generated `.specify/events.py` dispatcher runs event-mapped scripts inside agent hooks; `EVENT_SCRIPT_PATH_CONFINEMENT = True` exists because an older stale dispatcher would otherwise run unconfined script tokens — i.e. this code path was previously exploitable and is now gated by a version sentinel.
- Three files concentrate enormous blast radius: `presets/__init__.py` (6259 LOC), `extensions/__init__.py` (5481 LOC), `workflows/_commands.py` (3901 LOC) — each mixes domain logic, validation, and CLI plumbing, so a bad edit can break an entire command group.
- Fragile test-coupling pattern: `_commands.py` modules keep thin forwarders that re-fetch helpers (`_require_specify_project`, `load_init_options`, …) from the package root at call time purely so existing monkeypatch paths keep working; renaming or moving the root helpers silently breaks tests and commands.
- Subprocess policy is enforced by lint rather than review: ruff `extend-select` enables S602/S604/S605 so any `shell=True`/`os.system`/`popen2` reintroduction needs an explicit noqa, but other subprocess invocations (agent CLIs, scripts) are unrestricted list-form exec.
- `specify init --here --force` (and `--force` on existing dirs) merges/overwrites into non-empty directories; the confirmation/EOF handling is intricate (Abort vs EOFError distinction) and a scripting mistake there writes into a user's existing project.
- Deprecated hidden flags (`--skip-tls`, `--github-token`, `--offline`, `--debug`) are accepted as silent no-ops — scripts relying on the old behavior get no warning that TLS verification or offline mode semantics changed.
- Custom step loading swallows every exception (`except Exception # noqa: BLE001` → `continue`), so a broken or maliciously-aborting step package fails invisibly; same silent-skip posture applies to malformed `step.yml`.
- Credential handling: `~/.specify/auth.json` maps hosts to providers and `_github_http.py` attaches GITHUB_TOKEN/GH_TOKEN only to a fixed host allowlist (github.com, api.github.com, raw.githubusercontent.com, codeload.github.com) — correct, but the file is user-managed with no permission checks enforced in the registry layer.
- `_load_core_command_names` falls back to a hardcoded `_FALLBACK_CORE_COMMAND_NAMES` frozenset when neither core_pack nor the repo templates are readable; if the bundled template set drifts from the fallback, extension command-name validation silently uses stale data (a previous `.parent`-counting bug already broke this once, per the docstring).
Extension points
The repo is essentially a plugin framework. Five registration seams exist: (1) `INTEGRATION_REGISTRY` for AI agents via small class-attr subclasses of four base classes; (2) `STEP_REGISTRY`/`StepBase` for workflow step types, including project-local dynamically-loaded custom steps; (3) extension packages (`extension.yml`) adding commands/hooks/events/config; (4) presets (`preset.yml`) overriding templates via priority-resolved `replaces:` entries; (5) bundles (`bundle.yml`) packaging all of the above. All five are discoverable/installable through per-domain catalog stacks that users can extend with custom catalog URLs.
- New AI-agent integrations plug in via `INTEGRATION_REGISTRY`: create `src/specify_cli/integrations/<pkg>/__init__.py` with a class setting `key`, `config`, `registrar_config`, then add one import + one `_register()` call (both alphabetical) in `_register_builtins()`; package dirs use underscores while `key` keeps the hyphenated CLI name.
- Four integration base classes cover the output formats — `MarkdownIntegration`, `TomlIntegration`, `YamlIntegration`, `SkillsIntegration`, or `IntegrationBase` for fully custom setup (e.g. Copilot's dual skills/commands layouts) — with documented override points: `setup()`, `teardown()`, `command_filename()`, `options()`, `post_process_command_content()`, `effective_invoke_separator()`.
- Per-integration CLI flags are declared via `IntegrationOption` entries returned from `options()` and consumed through `--integration-options` (e.g. codex `--skills`, copilot `--commands`, generic `--commands-dir`); `options()` auto-adds `--events` when the integration declares `CANONICAL_TO_NATIVE` + `events_config_file`.
- `specify integration scaffold` generates a new integration subpackage from templates (`command_scaffold.py` + `_command_scaffold_generation.py`), giving a code-level entry point for the documented 'add an integration in 5 steps' flow.
- Workflow step types plug into `STEP_REGISTRY` (`type_key` → `StepBase` subclass); beyond the 11 builtins, `load_custom_steps` imports project-local step packages from `.specify/workflows/steps/<pkg>/` defined by `step.yml` (`step.type_key`) + `__init__.py` (`StepBase` subclass).
- Extensions are self-contained packages declared by `extension.yml` (`schema_version`, `extension` metadata, `requires`, `provides.commands|config|templates|scripts`, `hooks.<before|after>_<command>`, `events`, `config.defaults`) — validated by `ExtensionManifest` and installed by `ExtensionManager`; `extensions/template/` is the starter scaffold.
- Presets override core behavior declaratively: `preset.yml` `provides.templates` entries with `replaces: "speckit.<cmd>"` substitute command/template/script artifacts, and `PresetResolver` composes the stack by priority (lower number wins) — e.g. `lean` replaces the five core commands with minimal variants.
- Bundles (`bundle.yml`) compose extensions, presets, workflows, and step types into one installable unit (`specify bundle install`); first-party `bugfix` and `assess` bundles plus a community catalog JSON ship in the wheel for offline discovery.
- Every domain (integrations, extensions, presets, workflows, bundles) supports user-added remote catalogs through `catalog add/list/remove` commands backed by `CatalogStackBase` entries with `url`, `priority`, and `install_allowed` flags — so organizations can host private catalogs.
- Workflow overlays (`workflows/overlays/` composer + `workflow overlay` command group) let projects layer modifications onto installed workflows without forking them — merge, layer_sources, and schema modules define the overlay pipeline.
- Agent-native runtime events plug in per-integration: a class declaring `CANONICAL_TO_NATIVE` (canonical snake_case events → native hook names) and `events_config_file` automatically gets `--events` support and native hook emission via `install_integration_events`; canonical events are session_start, pre_tool_use, post_tool_use, session_end, user_prompt_submit, stop.
- The `agent-context` extension owns all context-file (CLAUDE.md/AGENTS.md) management as a fully opt-in, generic component driven by `agent-context-config.yml` markers — deliberately keeping context-file knowledge out of the CLI/registry so new integrations add nothing for it.
Contributor handoff
This repo is engineered for agent contributors: AGENTS.md gives a 5-step integration quickstart and design/cli.md defines a strict file-naming contract (`command_<name>.py`, `_command_<name>_<phase>.py`, `_commands.py`, mirrored tests). The safe-edit boundary is the registry/declarative layer — prefer adding a subpackage, extension.yml, preset.yml, or workflow.yml over touching the three giant domain modules. Non-negotiables: all installed files go through manifest recording, no `shell=True`, preserve root-level re-exports and `_commands` forwarders (tests monkeypatch them), honor the dual core_pack/repo-root asset lookup, and keep sh/ps/py script behavior identical.
- Read `AGENTS.md` first — it is the authoritative guide for adding integrations (base-class table, required class attrs, registry insertion, context-file ownership by the agent-context extension, test file naming), and `design/cli.md` before adding or moving any CLI command.
- Module naming contract: real CLI commands live in `command_<name>.py` (the only files that may register handlers), private phases in `_command_<name>_<phase>.py`, group apps/registration in `_commands.py`, nested CLI namespaces get matching directories — tests mirror under `tests/specify_cli/` as `test_command_<name>.py`.
- Build/test commands: `uv sync --extra test` then `uv run pytest`; lint with `uvx ruff check src tests`; markdown via markdownlint-cli2; CI matrix is ubuntu/windows/macos × Python 3.13/3.14 — keep tests passing on Windows (no POSIX-only assumptions).
- Never introduce `shell=True`, `os.system`, or `popen2` — ruff rules S602/S604/S605 are extended-selected specifically to make any deviation require a visible `# noqa`.
- Route every file an integration writes through `manifest.record_file()`/`record_existing()` in `setup()` — files not recorded are invisible to uninstall, and files written directly bypass the hash-check that protects user modifications.
- Preserve compatibility surfaces: root-package re-exports (`workflow_add`, `check_tool`, `load_init_options`, `_require_specify_project`, …) and `_commands.py` call-time forwarders exist because tests monkeypatch `specify_cli.<name>`; removing them breaks the suite without breaking imports.
- Asset lookups must handle both layouts: wheel installs have `specify_cli/core_pack/` (force-included at build time) while source checkouts/edits do not — always go through `_locate_core_pack()`/`_repo_root()`/`_locate_bundled_*` rather than `Path(__file__).parent` arithmetic (a past regression broke command discovery this way).
- `init-options.json` has tri-state semantics — missing file (legacy fallback to detect-all-agents), malformed/empty `ai` (fail closed, register nothing), valid string key — use `resolve_active_agent_for_registration`/`load_init_options`/`is_ai_skills_enabled` rather than reading the JSON ad hoc; a dangling symlink must fail closed, not fall back.
- Path safety helpers already exist — reuse them instead of rolling new checks: `_validate_rel_path`/`_ensure_safe_manifest_*` (manifest), `_ensure_safe_shared_directory`/`_ensure_safe_shared_destination`/`_write_shared_*` (shared_infra), `relative_extension_path_violation` (_utils), symlink-component checks in workflows/_commands.
- Every new integration needs `tests/integrations/test_integration_<key>.py` (hyphens→underscores in the filename); multi-install-safe integrations must use static unique dirs, and registry tests enforce those invariants — run the focused file plus `tests/test_agent_config_consistency.py`.
- Env-var surface an agent must know: `SPECIFY_INIT_DIR` retargets every project-scoped command; `SPECKIT_INTEGRATION_DEFAULT` changes the non-interactive init default; `SPECKIT_INTEGRATION_<KEY>_EXECUTABLE`/`_EXTRA_ARGS` and `SPECKIT_WORKFLOW_RUN_ID` exist — tests strip all `SPECIFY_*`/`SPECKIT_INTEGRATION_*` vars via conftest, so set them explicitly in tests.
- Command templates must stay tri-script: any `templates/commands/*.md` change that references a helper script needs behaviorally equivalent `sh`/`ps`/`py` entries in `scripts:` frontmatter and the parity tests (`test_*_python_parity.py`) pin the stdout contract (`FEATURE_DIR:`, `AVAILABLE_DOCS:`, `--json` shapes).
Languages
| Language | Files | Share of source |
|---|---|---|
| Python | 457 | 97% |
| Markdown | 152 | docs/config |
| YAML | 51 | docs/config |
| JSON | 17 | docs/config |
| Shell | 12 | 3% |
| CSS | 1 | docs/config |
| TOML | 1 | 0% |
Start reading here
Probable source entrypoint: pyproject.toml — inferred from the directory tree and manifest, not the upstream docs.
Source roots
src/ (191 files)
Repository structure
| Top-level path | Files |
|---|---|
tests/ | 257 |
src/ | 191 |
extensions/ | 59 |
docs/ | 45 |
.github/ | 41 |
presets/ | 29 |
scripts/ | 18 |
templates/ | 16 |
Docs found: AGENTS.mdCONTRIBUTING.mdREADME.mddocs/README.mddocs/community/bundles.mddocs/community/extensions.mddocs/community/friends.mddocs/community/overview.mddocs/community/presets.mddocs/community/walkthroughs.md
Package
pyproject.toml — specify-cli v1.0.10.dev0, 4 declared dependencies.
testpytest>=7.0"pytest-cov>=4.0"]
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructions.github/workflows/release-trigger.yml— GitHub Actions workflow.github/workflows/release.yml— GitHub Actions workflow.github/workflows/security.yml— GitHub Actions workflow.github/workflows/add-community-extension.lock.yml— GitHub Actions workflow.github/workflows/catalog-assign.yml— GitHub Actions workflow.github/workflows/lint.yml— GitHub Actions workflow.github/workflows/feature-assess.lock.yml— GitHub Actions workflow.github/workflows/test.yml— GitHub Actions workflow
Structural health signals
Average score 6.7/10 across 96 analyzed source files; 31 hotspots surfaced.
extensions/git/scripts/python/create_new_feature_branch.py— 641 lines, score 5.2 (Large file, Deep nesting)src/specify_cli/events.py— 1140 lines, score 5.4 (Large file, Deep nesting)src/specify_cli/integrations/base.py— 1263 lines, score 5.4 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
175adbcd826b2026-09-22 — refactor: reorganize bundle CLI commands (#4663)b9e7389d14142026-09-21 — refactor: organize integration CLI commands (#4662)c0d041dfa08e2026-09-21 — refactor: organize preset CLI commands (#4657)0aae991b805a2026-09-22 — fix(integrations): declare OpencodeIntegration multi_install_safe (#4620) (#4625)06de4ff529002026-09-21 — [preset] Update Autonomous Run Governance preset to v0.4.4 (#4586)