# System map — github/spec-kit

> Canonical page: https://codevetter.com/unpack/spec-kit/system-map

# System map — github/spec-kit

Scanned commit 175adbcd826befdccce8c60faa07ae3d8bbc8d87 (2026-09-22). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

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`. — [pyproject.toml#L19-20](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/pyproject.toml#L19-L20) [src/specify_cli/__init__.py#L602-617](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/src/specify_cli/__init__.py#L602-L617)
- 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. — [src/specify_cli/__init__.py#L392-600](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/src/specify_cli/__init__.py#L392-L600) [src/specify_cli/commands/init.py#L259-343](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/src/specify_cli/commands/init.py#L259-L343)
- 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. — [pyproject.toml#L26-57](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/pyproject.toml#L26-L57)
- `_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. — [src/specify_cli/_assets.py#L13-101](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/src/specify_cli/_assets.py#L13-L101)
- `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. — [src/specify_cli/integrations/__init__.py#L28-150](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/src/specify_cli/integrations/__init__.py#L28-L150) [AGENTS.md](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/AGENTS.md)
- 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. — [design/cli.md#L30-160](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/design/cli.md#L30-L160) [src/specify_cli/extensions/_commands.py#L1-47](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/src/specify_cli/extensions/_commands.py#L1-L47) [src/specify_cli/extensions/catalog/command_add.py](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/src/specify_cli/extensions/catalog/command_add.py)
- 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. — [src/specify_cli/workflows/engine.py#L34-145](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/src/specify_cli/workflows/engine.py#L34-L145) [src/specify_cli/workflows/__init__.py#L45-82](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/src/specify_cli/workflows/__init__.py#L45-L82)
- 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. — [src/specify_cli/authentication/__init__.py#L1-50](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/src/specify_cli/authentication/__init__.py#L1-L50) [src/specify_cli/_github_http.py#L1-40](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/src/specify_cli/_github_http.py#L1-L40)
- 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. — [src/specify_cli/__init__.py#L541-562](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/src/specify_cli/__init__.py#L541-L562) [src/specify_cli/_project.py](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/src/specify_cli/_project.py)
- 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. — [pyproject.toml#L6-17,65-74](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/pyproject.toml#L6-17,65-L74) [.github/workflows/test.yml](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/.github/workflows/test.yml)
- 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. — [README.md#L39-47](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/README.md#L39-L47) [.github/workflows/release.yml#L1-30](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/.github/workflows/release.yml#L1-L30)
- 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. — [src/specify_cli/_assets.py#L104-121](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/src/specify_cli/_assets.py#L104-L121) [src/specify_cli/_version.py#L55-75](https://github.com/github/spec-kit/blob/175adbcd826befdccce8c60faa07ae3d8bbc8d87/src/specify_cli/_version.py#L55-L75)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)