Speckit Install

---
name: speckit-install
description: "Install the SpecKit CLI and initialize the current repository for one or both coding-agent integrations (Claude Code, Codex CLI). Use when the operator says: 'install speckit', 'set up speckit', 'initialize speckit in this repo', 'add speckit to this project', 'specify init for me', 'install spec-kit', '$speckit-pro:speckit-install', or has a repo with no .specify/ directory and wants to start using Spec-Driven Development. Detects existing installs and hands off to $speckit-pro:speckit-upgrade rather than overwriting. Safe to run on any repo. Not for upgrading an existing speckit install ($speckit-pro:speckit-upgrade), not for scaffolding a new spec on an already-installed repo ($speckit-pro:speckit-scaffold-spec), and not for installing this plugin's own bundled Codex subagents (use $speckit-pro:install for that)."
---

# SpecKit Install

Install the official SpecKit CLI (https://github.com/github/spec-kit)
if missing, then initialize this repository to use it with Claude
Code, Codex CLI, or both. Safe to run on any repo — detects an
existing `.specify/` directory and hands off to
`$speckit-pro:speckit-upgrade` rather than overwriting it.

This skill is **mutation-heavy** (it writes files to the repo and
to `~/.local/share/uv/tools/specify-cli/` if installing the CLI).
It runs only on explicit operator request and never auto-fires from
other skills.

## Scope Boundaries — Not For

- Upgrading an existing SpecKit install. That is `$speckit-pro:speckit-upgrade`.
  This skill hands off to it when `.specify/` is present.
- Scaffolding a new spec from the technical roadmap. That is
  `$speckit-pro:speckit-scaffold-spec`.
- Installing this plugin's own bundled Codex subagent TOML files
  (`autopilot-fast-helper.toml`, `phase-executor.toml`, etc.) into
  `$CODEX_HOME/agents/` (default `~/.codex/agents/`). That is
  `$speckit-pro:install`.
- Methodology coaching. That is `$speckit-pro:speckit-coach`.

## Invocation

```text
$speckit-pro:speckit-install                    # interactive — asks which integrations
$speckit-pro:speckit-install claude             # claude only
$speckit-pro:speckit-install codex              # codex only
$speckit-pro:speckit-install claude codex       # both (dual-integration)
```

If the operator does not specify, ask before proceeding.

## What to Do

### 1. Ensure the SpecKit CLI is available

The runner owns the pinned Spec Kit version. Invoke
`[resolved_python, "-m", "speckit_pro_runner"]` with this request on
stdin, parse `data.stdout.text` as JSON, and read its `spec_kit` object
(`status`, `installed_version`, `pinned_version`, `install_argv`, `cli_argv`):

```json
{"schema_version":"1.0","request_id":"install-spec-kit-pin","helper_id":"check-prerequisites","operation":"check-prerequisites","mode":"read_only","inputs":{"workflow_file":""}}
```

Use `spec_kit.cli_argv` as the executable prefix for every Spec Kit command
below, including health checks, extensions, presets and upgrade handoffs.
Append the listed arguments and launch the resulting array with `shell=False`.
The runner supplies the verified absolute path; preserve it even if PATH,
the current directory or a discovery link changes. If `cli_argv` is empty, STOP
before any Spec Kit command; offer the pinned install, then verify again.
Re-run `check-prerequisites` after any CLI install or replacement and pass the
new `spec_kit` object to subsequent steps and handoffs. A declined version
repair permits continuation only with a nonempty `cli_argv`.

- If it is found, record `installed_version`. When `status` is `match`,
  move on. When it is `older`, `newer` or `unreadable`, tell the
  operator the installed version and the pinned one, and ask before
  running `install_argv` (it replaces the CLI).
- If the CLI is missing (`status` is `missing`):
  - Look up `uv` the same way.
  - If `uv` is present, install the pinned CLI by invoking
    `install_argv` with argv-only execution.
  - If `uv` is missing, STOP and tell the operator to install `uv`
    from the official Astral documentation, then re-run
    `$speckit-pro:speckit-install`. SpecKit CLI is distributed as a `uv` tool.

Do not attempt other install methods (pipx, manual git clone) unless
the operator explicitly requests it.

### 2. Detect existing-install state

Use a filesystem directory check for `.specify/` and record the state
as `PRESENT` or `ABSENT`.

If `.specify/` is **PRESENT**:

1. Invoke `spec_kit.cli_argv + ["integration", "list"]` with argv-only execution and
   capture stdout and stderr to see which integrations are installed.
2. Tell the operator: "This repo already has SpecKit installed
   (integrations: `<list>`). The right tool for this state is
   `$speckit-pro:speckit-upgrade` (handles diff-aware upgrades and
   slash-command-to-skills migration safely)."
3. Ask whether to (a) hand off to `$speckit-pro:speckit-upgrade`, (b) add a new
   integration alongside the existing ones (e.g., adding `codex` to a
   `claude`-only repo), or (c) abort.
4. On (a): STOP this skill and invoke `$speckit-pro:speckit-upgrade`.
5. On (b): go directly to Step 4 with only the new integration(s) the
   operator wants to add, and skip its bootstrap `spec_kit.cli_argv + ["init"]`.
6. On (c): STOP.

If `.specify/` is **ABSENT**: continue to Step 3.

### 3. Ask which integrations to install

If the operator passed integration keys as arguments, use those.
Otherwise ask:

> Which coding-agent integrations should this project support?
>
> - `claude` — Claude Code (installs skills at `.claude/skills/speckit-*/`)
> - `codex`  — Codex CLI (installs skills at `.agents/skills/speckit-*/`; skills mode is the default)
> - `both`   — dual-integration (`claude` AND `codex` side-by-side)

Both `claude` and `codex` are declared "Multi-install Safe" by the
SpecKit CLI, so dual-integration is officially supported in a single
project. The plugin's own skills work in both runtimes.

If the operator's request is ambiguous (e.g., "install for codex but
also leave Claude alone"), ask one clarifying question — do NOT
infer.

### 4. Initialize the repository

Every `specify` call passes `--script sh`, the script flavor the
runner's setup-contract check reads, and which avoids the CLI's script
prompt.

For a **fresh install** (Step 2 said ABSENT):

1. Pick the operator's first integration key as the bootstrap key.
2. Run `spec_kit.cli_argv + ["init", "--here", "--integration", "<first-key>", "--script", "sh"]` to
   scaffold `.specify/` (templates, scripts, constitution placeholder)
   AND install the first integration. For Codex, skills mode is the
   default and writes `.agents/skills/speckit-*/`, so no extra option
   is needed.
3. For each additional integration the operator chose, run
   `spec_kit.cli_argv + ["integration", "install", "<key>", "--script", "sh"]`.

For **adding to an existing install** (Step 2 said PRESENT, operator
chose option (b)):

- Skip the bootstrap `spec_kit.cli_argv + ["init"]`. For each new integration the
  operator chose, run `spec_kit.cli_argv + ["integration", "install", "<key>", "--script", "sh"]`.

If any command returns non-zero, STOP. Do not retry or "fix" without
operator input — the CLI's error message is the operator's signal.

When `claude` was installed, use the resolved Python 3.11+ interpreter to run
`<resolved_python> <plugin-root>/scripts/agent-memory-ignore.py --mode apply --repo-root <repository-root>`
with argv-only execution before any memory-enabled plugin agent runs. Include
the resulting `.gitignore` change in the setup commit before clean-worktree-gated
helpers. If the command reports tracked memory or an ineffective nested
override, stop and report its paths; never remove memory automatically.

For every install, also use the resolved Python 3.11+ interpreter to run
`<resolved_python> <plugin-root>/scripts/agent-memory-ignore.py --mode apply --target worktrees --repo-root <repository-root>`
with argv-only execution. It ignores `.worktrees/`, where scaffold places each
spec worktree, so the first scaffold does not stop on an unignored target.
Include the `.gitignore` change in the same setup commit. A nonzero exit means a
nested ignore rule overrides it: stop and report the output.

### 5. Offer to install the curated set of extensions and presets

speckit-pro recommends a small set of community extensions and presets
that power the autopilot's post-implementation parallel group and the
AskUserQuestion picker preset for `$speckit-clarify` and
`$speckit-checklist`.
See [presets-extensions-guide.md → The curated set](../speckit-coach/references/presets-extensions-guide.md)
for the full list and rationale.

First install the reviewability preset, which scaffold requires. Send this
request and read `reviewability_preset` in the result:

```json
{"schema_version":"1.0","request_id":"install-reviewability-preset","helper_id":"detect-presets","operation":"detect-presets","mode":"read_only","inputs":{"repo_root":"."}}
```

When `status` is `upgrade`, run `spec_kit.cli_argv + upgrade_args`, stop on
failure, then require `installed` from `detect-presets` and report the upgrade.
When `status` is `missing`, run `spec_kit.cli_argv + add_args` without asking:
it is part of the install, not a recommendation, then send the
`check-prerequisites` request again and report a failing `template_resolution`
check. When `status` is `unavailable`, report it and continue.

Compare `.specify/extensions/` and `.specify/presets/` against the entries in
`<plugin-root>/scripts/curated-set.json`.

- If every entry is present: report "Curated extensions and presets
  already installed — nothing to install." Continue to Step 6.

- Otherwise, list the missing entries and ask which to install.
  Recommended default is **all**. For each accepted entry, give the
  operator the `spec_kit.cli_argv + ["<kind>", "add", "<id>", "--from", "<archive_url>"]`
  command from the curated set (`<kind>` is `extension` or `preset`). Spec Kit
  refuses a bare `add <id>` for these entries. Run a preset command yourself after
  the operator confirms. Do not run an extension command: it stops at Spec Kit's
  trust prompt, so the operator runs it in their own terminal. The pin
  pins the bytes but does not vet them: before the operator confirms, ask them to
  review the archive's commands, scripts, and hooks.
  [The curated set](../speckit-coach/references/presets-extensions-guide.md)
  says how to vet the archive and verify the result. Skipped entries can be
  installed later with `$speckit-pro:speckit-upgrade`.

### 6. Verify

Invoke `spec_kit.cli_argv + ["check"]` and `spec_kit.cli_argv + ["integration", "list"]` with argv-only
execution, and capture stdout and stderr. Confirm:

- `spec_kit.cli_argv + ["check"]` reports the project is ready.
- Each chosen integration appears as `installed` in the integration
  list.
- For Codex, `.agents/skills/speckit-*/SKILL.md` exists. That is the
  primary Codex skills path. A legacy `.codex/skills/` directory may
  also exist from an older setup; Codex still reads it, so report it
  and leave it in place.

If verification fails, report the mismatch — do not silently
continue.

#### Research screening check

speckit-pro requires the typesafe-jev plugin, and Codex has no plugin
dependency mechanism. Run `codex plugin list` with argv-only execution. If
`typesafe-jev` is absent, print `codex plugin add
typesafe-jev@racecraft-plugins-public`, tell the user to restart Codex, and
stop this step. Otherwise run runner helper `research-broker-preflight` in
`read_only` mode with empty `inputs`.

Report `data.screening_mode` and each `data.warnings[].message` and
`data.errors[].message`. The helper never reads a key value.

- A key is optional. With no Jev key or binary, research runs in
  `sanitizer-only` mode, which is a warning, not a failure.
- With no Tavily key, `research_search` returns `search_unavailable` and
  `docs_query` still works through keyless Context7. Point the user to a free
  Tavily key in `~/.config/speckit-pro/tavily.key` (mode 0600).
- `expected_failure` means a credential or binary is configured but broken.
  Report the fix it names. Do not roll back the SpecKit install for it.
- A key held only in an environment variable is a warning: the broker runs
  as an MCP server, which may not see it. Prefer the key files.

#### Autopilot review policy check

Codex's automatic approval reviewer needs a standing policy so that a ratified
autopilot plan's ordinary actions run without a per-run question: feature-branch
pushes, the plan's pull requests and review replies, public documentation
research, and offline audits on a worker on this machine. Read the
`auto_review.extra_policy` string from the user-level `~/.codex/config.toml`,
if one exists; read that file, never write it. Run runner helper
`render-egress-authorization` in `read_only` mode with `scope=standing`, the
repository's GitHub `owner/name`, its default branch, and that string as
`installed_extra_policy`.

- When `data.installed` is true, report the standing policy as installed.
- Otherwise print `data.extra_policy_fragment` unchanged as the install text,
  and tell the operator to review it and install it once. It needs Codex 0.158
  or later. TOML allows one `[auto_review]` table, so merge it into an existing
  `extra_policy` string. It is an `extra_policy` fragment, never
  `auto_review.policy`, which replaces the default reviewer policy.
- Tell the operator that a reviewer session persists for its thread, even
  after an app restart: a new or changed policy reaches only threads started
  after the change, so start the autopilot in a new thread after installing it.
- This skill never writes the fragment into `~/.codex`, the repository's
  `.codex/`, or `AGENTS.md`: the reviewer trusts `AGENTS.md`, and a branch
  could rewrite it.
- A missing policy is a warning, not a failure. The autopilot asks for it once,
  at run start, before Phase 1, and the run starts on the operator's reply.

### 7. Report

Return a concise install summary:

```text
## SpecKit Installed

**CLI version:** specify <X.Y.Z>
**Repo init:** .specify/ scaffolded (templates, scripts, constitution placeholder)
**Integrations installed:**
- claude → .claude/skills/speckit-*/ (skills mode)
- codex  → .agents/skills/speckit-*/ (skills mode)

**Next steps:**
1. Restart your coding-agent process (Claude Code or Codex CLI) so
   the new skills load.
2. Create your project constitution:
   - Claude: `/speckit-constitution` or `/speckit-pro:speckit-coach create my project constitution`
   - Codex:  `$speckit-constitution` or `$speckit-pro:speckit-coach`
3. When you're ready to spec a feature, scaffold it from the technical
   roadmap with `/speckit-pro:speckit-scaffold-spec SPEC-ID` (Claude)
   or `$speckit-pro:speckit-scaffold-spec SPEC-ID` (Codex).
```

Do not continue into any other workflow in the same skill. Install
ends here.

## Hard Constraints

- Never run `spec_kit.cli_argv + ["init", "--here", "--force"]` from this skill. `--force`
  overwrites local customizations. Force-flagged behavior lives
  exclusively in the upgrade skill, where it is wrapped with
  backup/restore.
- Never proceed to mutation without explicit operator confirmation of
  the integration choice when there is ambiguity.
- Never mutate `.specify/memory/constitution.md` — that's the
  operator's content. If they don't have one yet, leave the SpecKit
  placeholder in place and tell them how to fill it.
- Never partially-install. If any `specify` invocation fails (e.g.,
  network error fetching templates), STOP and report the exact error.
  Do not retry silently.
- Never touch `.claude-plugin/`, `commands/`, or this plugin's
  marketplace files. Those are this plugin's own files, not the
  consumer repo's.

## Failure Handling

Stop and report — do not improvise — when:

- `uv` is missing and the operator cannot install it.
- `spec_kit.cli_argv + ["init"]` returns a non-zero exit code (network failure,
  template fetch error, etc.).
- `spec_kit.cli_argv + ["integration", "install", "<key>"]` fails (the operator may have a
  conflicting integration; surface the CLI's error message and let
  them decide).
- The repo has detached HEAD or uncommitted changes that would
  conflict with the new files. Recommend committing or stashing
  first.
- The operator declines confirmation on the integration choice.

If a partial install happened (e.g., `claude` succeeded but `codex`
failed), report exactly what landed and what did not. Recommend
running `spec_kit.cli_argv + ["integration", "list"]` to see current state.