/spec-runtime-setup

name: spec-runtime-setup
description: Install, configure, verify, and refresh required harness runtime readiness facts for spec-first workflows on Claude Code, Codex, Cursor, Kiro, Qoder, or OpenCode.
argument-hint: "[bare auto setup] [--check|--verify-only|--plan|--project-config] [--only codegraph,graphify] [--workspace-graph|--workspace-graph-status|--workspace-graph-clean] [--repos <a,b>] [--json] [--repair-host-config] [--refresh] [--repo <git-root>|--folder <project-folder>] [--requirement-workspace <target-relative-path>]"

Runtime Setup

`spec-runtime-setup` is the canonical runnable entrypoint for the Runtime Setup workflow across supported hosts (Claude/Qoder command spelling `runtime-setup`). Host-specific setup spellings are not separate products. Runtime Setup prepares deterministic host/runtime facts for spec-first workflows. It installs or verifies required MCP servers and baseline helper tooling, diagnoses manual helpers such as `agent-browser`, writes setup-owned project facts, and reports concrete next actions. It does not provide code-understanding authority; downstream workflows use bounded direct source reads, `rg`, ast-grep, git diff, tests/logs, and user-provided evidence.

Contract Summary

| Field | Contract | | --- | --- | | When to use | Host runtime setup, MCP setup, helper-tool readiness, missing runtime assets, or project-local setup fact refresh. | | When not to use | Ordinary planning, implementation, review, debugging, or code impact questions that can proceed from direct source evidence. | | 输入 | 当前 host、repo target、已加载 skill 共置的 `setup-registry.json`、host config 状态、git/workspace target facts 与项目 instruction。 | | Outputs | Readiness ledger v2, provider readiness v2 facts, generated runtime manifest freshness, setup scenario fingerprint, project-local config bootstrap status, optional project setup facts under `.spec-first/config/`, and a grouped status block. | | Artifacts | `.spec-first/config/tool-facts.json`, `.spec-first/config/runtime-capabilities.json`, `.spec-first/config.local.example.yaml`, `.spec-first/config.local.yaml` when explicitly created, `.gitignore` local-config safety rule when explicitly ensured, and `.spec-first/workspace/scenario-fingerprint-setup.json` when applicable. | | Failure modes | Missing dependencies, host config write failure, ambiguous parent workspace target, symlink escape, invalid registry schema, helper install failure, or unsupported host. | | Downstream consumers | `using-spec-first`, plan/work/review/debug workflows, doctor/update guidance, and humans repairing setup. |

核心边界：Node module 准备确定性的 readiness facts；LLM workflow 决定如何使用这些事实。Setup 不得判断代码理解的语义充分性，也不得要求普通工作必须先依赖外部分析服务。CodeGraph/Graphify readiness 准备完成后，setup 可以建议将 `spec-rule-miner` 作为基于证据生成项目 AI coding rule 的后续步骤，但不得自行调用 rule mining、合成 rule 或写入 `docs/ai/project-rules.md`。

Scenario Capability

Follows `docs/contracts/workflows/scenario-capability-matrix.md` (default). Overrides: none

Source Of Truth

Canonical package source-of-truth 是 `skills/spec-runtime-setup/setup-registry.json`，由共置的 `setup-registry.schema.json` 校验，schema version 为 `setup-registry.v10`。Generated host 从已加载 skill 目录消费共置的 registry projection；该 projection 是 generated runtime，不是第二个 source。当前完整 Runtime Setup 必备项包括 `sequential-thinking`、`context7`、ffmpeg、CodeGraph 与 Graphify；CodeGraph/Graphify first generation 和真实 query probe 属于标准 setup completion，而不是长期可跳过的 optional tail。`--only codegraph` / `--only graphify` 仅用于高级子集修复，不改变完整 setup 的必备定义。

Generated host runtime mirrors and host-local MCP config files are projections or outputs, not source. If setup prose or scripts change, update source first and use `spec-first init` only for runtime regeneration.

Required Harness Runtime

`setup-registry.json` 负责必需 MCP definition、helper readiness 与 install safety、required Provider metadata、external dependency pin、host target、artifact contract 和 platform override。Loader 针对当前 host/platform 确定性展开 registry default，不判断 Provider readiness 或语义充分性。当前 helper 检查包括 ffmpeg、`agent-browser` 与 ast-grep capability detection；ffmpeg 是 setup completion 的 baseline-blocking helper，`agent-browser` 仍保持 report-only/non-blocking。对 `agent-browser`，`dependency_status: ready` 只表示 CLI/runtime/global skill 安装完整，不等于 `execution_readiness: ready`；exact-origin capability 缺口必须保留其 canonical reason、`conformance_status`、`repair_scope` 与 `next_action`。

所有可执行 setup 行为均由共置的 Node 入口及 `scripts/` 下的 module 负责。不得在 workflow prose 中重新实现 registry query、host config 写入、Provider 命令或 facts reconciliation。

Loaded Skill 入口

从当前已加载的 `spec-runtime-setup/SKILL.md` 所在目录解析 `SKILL_DIR`。每次 runtime 调用都必须使用该目录中的共置 Node 入口：

node "$SKILL_DIR/scripts/setup.cjs" <mode-and-target-arguments>

绝不能从项目 cwd 或 source checkout 路径解析该命令。Generated command surface 使用其 companion support root 作为 `SKILL_DIR`。进入支持 mutation 的 mode 前，通过执行工具的 per-call environment overlay 传入 `MCP_SETUP_HOST=claude|codex|cursor|kiro|opencode|qoder|zcode`；只读诊断可以报告 advisory host candidate，但不能把它们转换为 write authority。

`scripts/check-health` 是带 Node shebang 的 compatibility shim，委托给 `setup.cjs --check`。Windows 直接调用 `node <loaded-skill-root>/scripts/setup.cjs --check`，不存在 platform-specific companion entry。

Optional provider readiness is reported through `provider_readiness[]` (`provider-readiness.v2`). Setup may populate lifecycle display bits such as `installed`, `configured`, `indexed`, `server_reachable`, and `query_verified`, plus setup-owned runtime metadata such as `native_interfaces`, `first_generation`, `steady_state`, and `usage_note`. Graphify may add `first_generation.scope_provenance` to separate requested scope from the scope verified by a contained receipt bound to the current `graph.json`; receipt missing/mismatch/invalid keeps first-generation status `unknown` for that request. A missing legacy receipt leaves core readiness `unknown` and the graph advisory-only; a mismatched or invalid receipt sets `readiness_status=degraded`, so selected setup/verify cannot