[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6CWJA3083C01ZDDWN5KHDT5":3,"skill-same:01M6CWJA3083C01ZDDWN5KHDT5":365},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":28,"publishedAt":49,"linkOnly":50,"markdownContent":51,"markdownBody":52,"frontMatter":53,"refName":55,"commitSha":56,"skillDirectory":57,"forksCount":58,"repositoryHtmlUrl":59,"repositoryHomepageUrl":60,"ownerHtmlUrl":61,"ownerBlogUrl":6,"ownerDescription":62,"updatedAt":63,"install":64,"resources":77},"01M6CWJA3083C01ZDDWN5KHDT5","spec-runtime-setup",null,"Install, configure, verify, and refresh required harness runtime readiness facts for spec-first workflows on Claude Code, Codex, Cursor, Kiro, Qoder, or OpenCode.","leo-kuang-ai\u002Fspec-first","leo-kuang-ai","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F8476392?v=4","01M6CWDM2YRT5M8C3G3QC3YGR5","leokuang","01M6CWDM6X46EFBXT1M1GDB5XC",111,"MIT","https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48],"spec runtime setup","setup","spec","configure","qoder","kiro","project","clean","opencode","only","auto","install","plan","graphify","git","code","status","repos","config","workflows","2026-11-10 10:12:30",false,"---\nname: spec-runtime-setup\ndescription: Install, configure, verify, and refresh required harness runtime readiness facts for spec-first workflows on Claude Code, Codex, Cursor, Kiro, Qoder, or OpenCode.\nargument-hint: \"[bare auto setup] [--check|--verify-only|--plan|--project-config] [--only codegraph,graphify] [--workspace-graph|--workspace-graph-status|--workspace-graph-clean] [--repos \u003Ca,b>] [--json] [--repair-host-config] [--refresh] [--repo \u003Cgit-root>|--folder \u003Cproject-folder>] [--requirement-workspace \u003Ctarget-relative-path>]\"\n---\n\n# Runtime Setup\n\n`spec-runtime-setup` is the canonical runnable entrypoint for the Runtime Setup workflow across supported hosts (Claude\u002FQoder command spelling `runtime-setup`). Host-specific setup spellings are not separate products. Runtime Setup prepares deterministic host\u002Fruntime 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\u002Flogs, and user-provided evidence.\n\n## Contract Summary\n\n| Field | Contract |\n| --- | --- |\n| When to use | Host runtime setup, MCP setup, helper-tool readiness, missing runtime assets, or project-local setup fact refresh. |\n| When not to use | Ordinary planning, implementation, review, debugging, or code impact questions that can proceed from direct source evidence. |\n| 输入 | 当前 host、repo target、已加载 skill 共置的 `setup-registry.json`、host config 状态、git\u002Fworkspace target facts 与项目 instruction。 |\n| 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\u002Fconfig\u002F`, and a grouped status block. |\n| Artifacts | `.spec-first\u002Fconfig\u002Ftool-facts.json`, `.spec-first\u002Fconfig\u002Fruntime-capabilities.json`, `.spec-first\u002Fconfig.local.example.yaml`, `.spec-first\u002Fconfig.local.yaml` when explicitly created, `.gitignore` local-config safety rule when explicitly ensured, and `.spec-first\u002Fworkspace\u002Fscenario-fingerprint-setup.json` when applicable. |\n| Failure modes | Missing dependencies, host config write failure, ambiguous parent workspace target, symlink escape, invalid registry schema, helper install failure, or unsupported host. |\n| Downstream consumers | `using-spec-first`, plan\u002Fwork\u002Freview\u002Fdebug workflows, doctor\u002Fupdate guidance, and humans repairing setup. |\n\n核心边界：Node module 准备确定性的 readiness facts；LLM workflow 决定如何使用这些事实。Setup 不得判断代码理解的语义充分性，也不得要求普通工作必须先依赖外部分析服务。CodeGraph\u002FGraphify readiness 准备完成后，setup 可以建议将 `spec-rule-miner` 作为基于证据生成项目 AI coding rule 的后续步骤，但不得自行调用 rule mining、合成 rule 或写入 `docs\u002Fai\u002Fproject-rules.md`。\n\n## Scenario Capability\n\nFollows `docs\u002Fcontracts\u002Fworkflows\u002Fscenario-capability-matrix.md` (default).\nOverrides: none\n\n## Source Of Truth\n\nCanonical package source-of-truth 是 `skills\u002Fspec-runtime-setup\u002Fsetup-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\u002FGraphify first generation 和真实 query probe 属于标准 setup completion，而不是长期可跳过的 optional tail。`--only codegraph` \u002F `--only graphify` 仅用于高级子集修复，不改变完整 setup 的必备定义。\n\nGenerated 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.\n\n## Required Harness Runtime\n\n`setup-registry.json` 负责必需 MCP definition、helper readiness 与 install safety、required Provider metadata、external dependency pin、host target、artifact contract 和 platform override。Loader 针对当前 host\u002Fplatform 确定性展开 registry default，不判断 Provider readiness 或语义充分性。当前 helper 检查包括 ffmpeg、`agent-browser` 与 ast-grep capability detection；ffmpeg 是 setup completion 的 baseline-blocking helper，`agent-browser` 仍保持 report-only\u002Fnon-blocking。对 `agent-browser`，`dependency_status: ready` 只表示 CLI\u002Fruntime\u002Fglobal skill 安装完整，不等于 `execution_readiness: ready`；exact-origin capability 缺口必须保留其 canonical reason、`conformance_status`、`repair_scope` 与 `next_action`。\n\n所有可执行 setup 行为均由共置的 Node 入口及 `scripts\u002F` 下的 module 负责。不得在 workflow prose 中重新实现 registry query、host config 写入、Provider 命令或 facts reconciliation。\n\n## Loaded Skill 入口\n\n从当前已加载的 `spec-runtime-setup\u002FSKILL.md` 所在目录解析 `SKILL_DIR`。每次 runtime 调用都必须使用该目录中的共置 Node 入口：\n\n```bash\nnode \"$SKILL_DIR\u002Fscripts\u002Fsetup.cjs\" \u003Cmode-and-target-arguments>\n```\n\n绝不能从项目 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。\n\n`scripts\u002Fcheck-health` 是带 Node shebang 的 compatibility shim，委托给 `setup.cjs --check`。Windows 直接调用 `node \u003Cloaded-skill-root>\u002Fscripts\u002Fsetup.cjs --check`，不存在 platform-specific companion entry。\n\nOptional 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\u002Fmismatch\u002Finvalid 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\u002Fverify cannot report completion for an unproved requested scope. `steady_state` may include project-local hook readiness facts for optional provider refresh setup, such as Graphify `hook_installed`, `hook_verified`, `hook_status=blocked`, and `refresh_mode=manual-only`. Downstream decision health is still driven by `readiness_status`; lifecycle, first-generation, provenance, and hook fields explain boundaries and next actions, not semantic truth. Graphify hook blocked\u002Ffailed\u002Fskipped 不得单独把 package、host integration、artifact integrity 与 query probe 的成功结果改写为 Provider `degraded`。The human status table may derive `readiness_scope` and `probe_status` from existing lifecycle bits to separate install\u002Findex readiness from real server\u002Fquery probes; these display columns are not new machine schema fields. Provider self-reported `fresh` maps to `unknown`; provider self-reported `stale` may map to `stale` because it is conservative. `query_verified=true` is reserved for a real probe or explicit real-environment signal, not for package installation alone. A `false` or missing `server_reachable` \u002F `query_verified` display value means the probe is not verified in this setup run unless a failure reason says otherwise; it must not be summarized as confirmed provider query availability.\n\n## Project Preflight \u002F Local Setup\n\nProject-local setup has two separate surfaces:\n\n1. Setup-owned facts: `.spec-first\u002Fconfig\u002Ftool-facts.json`, `.spec-first\u002Fconfig\u002Fruntime-capabilities.json`, and when applicable `.spec-first\u002Fworkspace\u002Fscenario-fingerprint-setup.json`.\n2. Local config bootstrap: `.spec-first\u002Fconfig.local.example.yaml`, local override state for `.spec-first\u002Fconfig.local.yaml`, and `.gitignore` coverage for `.spec-first\u002F*.local.yaml`. Missing local override means `defaults-active`，不是“未处理的可选项”。\n\nThe readiness ledger and runtime capabilities include `generated_runtime_manifest.status` (`current`, `stale`, `missing`, or `unknown`) based only on `state.manifestVersion` versus the bundled manifest version; this is a deterministic freshness fact, not proof that generated prose is semantically correct. Missing\u002Fstale remediation is emitted as structured `next_action_command={cwd,command,args}` plus `next_action_headless_command`; `next_action` is explanation only and must never contain an executable `cd ... && ...` compound string. Scenario fingerprint wrapper failures are warn-and-continue: report `scenario_fingerprint_setup` status and keep the rest of setup actionable instead of blocking ordinary direct-evidence workflows.\n\nLocal config bootstrap is a first-class Runtime Setup capability, but it remains project-local and local-only. It checks and can explicitly refresh `.spec-first\u002Fconfig.local.example.yaml`, explicitly create `.spec-first\u002Fconfig.local.yaml`, and explicitly ensure `.spec-first\u002F*.local.yaml` is ignored. It reports legacy project config signals for manual review, but it does not copy legacy files, translate old key names, or treat old defaults as spec-first truth.\n\n## Three-Stage Setup Flow\n\n即使内部 Node module 执行多项检查，Runtime Setup 仍应将面向用户的流程保持为三个阶段：\n\n### Stage 1: Diagnose Target And Readiness\n\nResolve the project target first. `--repo \u003Cpath>` selects an exact Git root; `--folder \u003Cpath>` selects that exact logical project directory whether it is nested inside a Git worktree or has no Git boundary at all. With no target flag, a pure non-Git directory with no child repos becomes the single folder target, while a non-Git parent with discovered child repos keeps the bounded all-repos behavior. Provider artifacts and setup facts stay in the exact target; generated host runtime health uses the enclosing Git root when one exists, otherwise the folder itself. Then inspect:\n\n- host runtime identity and write authority;\n- required MCP\u002Fhelper dependency readiness;\n- generated runtime manifest freshness;\n- project-local config status for `.spec-first\u002Fconfig.local.example.yaml`, `.spec-first\u002Fconfig.local.yaml`, and `.gitignore` coverage;\n- legacy project config signals;\n- required CodeGraph\u002FGraphify readiness；`--only` 时只执行选定子集，但不得把子集成功表述为完整 setup 完成。\n\nThis stage is read-only except for diagnostic facts written by verify-only paths that are already setup-owned. Missing required Provider\u002Fhelper capability blocks Runtime Setup completion；它仍不阻止能够使用 direct source evidence 的普通 plan\u002Fwork\u002Freview\u002Fdebug workflow。\n\n### Stage 2: Apply Authorized Setup Actions\n\nApply only actions authorized by the selected mode:\n\n- project-local config actions: refresh example config, create local override, ensure ignore coverage, and optionally delete obsolete legacy markdown only after explicit approval;\n- host config action：只能通过共置 Node 入口与显式 host authority 写入 MCP\u002Fruntime config；\n- helper\u002Fprovider actions: standard bare workflow 安装或验证 required baseline，并默认运行 CodeGraph\u002FGraphify bounded first-generation\u002Fquery verification；`--only codegraph`、`--only graphify` 或 `--only codegraph,graphify` 仅收窄为高级子集修复。\n\nProject-local config actions never install providers or edit host config. Host\u002Fprovider actions never migrate local config keys. Legacy project config is a manual-review signal unless the user chooses a documented cleanup action.\n\n### Stage 3: Summarize Facts And Next Action\n\nRender a grouped final status that separates:\n\n- dependency\u002Fruntime readiness;\n- generated runtime freshness;\n- project-local config status;\n- project setup facts;\n- host configured dependencies;\n- helper\u002Fprovider readiness and install safety;\n- next actions.\n\nThe summary must make skipped, declined, optional, degraded, and action-required rows visible. Do not collapse these boundaries into a single \"setup complete\" statement.\n\n## Setup Posture And Project Conventions\n\nRuntime Setup follows an `Explore -> Present -> Decide -> Write` posture, with **fast-path execution for bare invocations**:\n\n1. **Explore** host, target repo, generated runtime manifest, existing setup facts, `.spec-first\u002Fconfig.local.yaml`, verification profile visibility, provider artifacts, and project instructions.\n2. **Present & Decide**:\n   - **Bare invocation** (default `spec-runtime-setup`): After exploration, present a consolidated single summary of all pending operations (missing dependencies, config changes, provider installations) and request **one confirmation** before batch execution. The user approves the entire setup plan with a single response.\n   - **Explicit modes**: `--check` and `--plan` are read-only. `--verify-only` is a facts-only mutation mode: it may write setup-owned facts, scenario fingerprints, and ledgers only, without requesting confirmation for those bounded writes.\n   - **Subset repairs** (`--only ...`, `--refresh`): Execute the narrowed scope immediately after exploration; subset authorization is implicit in the flag itself.\n3. **Decide** only where the runtime setup workflow has authority: install\u002Fverify helper tools, configure host MCP\u002Fruntime wiring, refresh setup-owned facts, or choose a documented degraded path. Team workflow conventions and semantic project decisions remain LLM\u002Fowner judgment in downstream workflows.\n4. **Write** only setup-owned facts, supported local config examples, host runtime config through documented targets, and generated runtime refreshes through `spec-first init`. Do not write team-shared tracker policy, label vocabulary, external PR request-surface policy, issue acceptance decisions, or durable rejected-scope decisions from setup.\n\n`.spec-first\u002Fconfig.local.yaml` is a local-only override file, not team-shared source of truth. Current active local config consumers are:\n\n- `verification_profile_path`, read by the verification profile loader as a local execution preference;\n- `feedback_sources` and `sweep_*`, read and written by `spec-sweep`;\n- `pulse_*`, read and written by `spec-product-pulse`;\n- `spec_promote_spiral_optout`, read and written by `spec-promote`;\n- `plan_skip_scoping_confirm`, exposed for downstream planning workflows that support persisted scoping-confirmation preference;\n- `plan_output`, `brainstorm_output` 和 `ideate_output`，分别由 `spec-plan`、`spec-brainstorm` 和 `spec-ideate` 读取。\n\n`plan_output`、`brainstorm_output` 和 `ideate_output` 都是 active local rendering preferences。对应 consumer 只读取未注释且有效的 `md` \u002F `html` 值；缺失、无效或仍被注释的值分别回退到 `spec-plan=md`、`spec-brainstorm=md`、`spec-ideate=html`。Pipeline override 仍由各 consumer 自己决定。Runtime Setup 只暴露并保护这些 key，不调用对应 workflow，也不把本地 rendering preference 提升为 runtime authority。没有真实 reader 的 CE\u002Flocal delegation key 不进入本地 config surface。Setup must not auto-delegate, skip scoping confirmation, or change host model\u002Fruntime behavior merely because a key exists. Missing local config is not a blocker; defaults remain advisory and must not be reported as repo truth.\n\nIf setup later reports project convention facts, they must be deterministic existence facts only, such as whether `CONTEXT.md`, `CONTEXT-MAP.md`, `docs\u002Fadr\u002F`, or a project guidance index exists. Setup must not judge whether terminology is correct, an ADR applies, a proposed issue\u002FPR should be accepted or rejected, an out-of-scope concept matches, or implementation satisfies a request.\n\n## Host Authority And Write Safety\n\n当前唯一公开入口是 `spec-runtime-setup`（Claude\u002FQoder 命令拼写 `runtime-setup`）；不提供 `spec-mcp-setup` \u002F `mcp-setup` 兼容别名。调用它的 host runtime surface 是权威 host evidence。Generated host-specific runtime surface 必须在调用支持 mutation 的 Node mode 前，通过 per-call environment 固定 `MCP_SETUP_HOST=\u003Chost>`。缺少显式 canonical `MCP_SETUP_HOST=claude|codex|cursor|kiro|opencode|qoder|zcode` 时，`setup.cjs` 必须 fail closed；不得根据 `PATH`、generated runtime 目录、旧 `.spec-first\u002Fconfig\u002F*` facts 或其他平台的 host config 文件推断 mutation target。只读诊断可以展示 advisory host candidate，但这些 candidate 不具备 write authority。\n\n在写入任何 host config 或刷新 setup-owned facts 前，workflow 必须让 `setup.cjs` 从显式 entrypoint host pin 解析 host authority 与 effective registry target。旧 setup facts 只能作为 drift comparison evidence：若其与当前 entrypoint host 不一致，应报告 host-marker drift，并为当前 host 刷新 setup-owned facts，不得把旧 host 当作当前 host。绝不能仅依据 prose 手动选择 `.kiro\u002Fsettings\u002Fmcp.json`、`.qoder\u002Fsettings.local.json`、`.cursor\u002Fmcp.json`、Codex TOML 或 Claude managed\u002Fuser config。\n\n不得使用 Write、Update、Edit 等 host file-edit 工具修改 `.spec-first\u002Fconfig\u002Ftool-facts.json`、`.spec-first\u002Fconfig\u002Fruntime-capabilities.json` 或 host MCP config 文件。只有 authority、target、containment、conflict 与 verification gate 全部通过后，`setup.cjs` 及其确定性的 host-config\u002Ffacts module 才能执行这些写入。\n\n## Workflow Modes\n\n- `--check`: inspect current dependency\u002Fruntime status only; do not write setup facts, host config, or install tools.\n- `--verify-only` \u002F `--refresh-facts`: verify readiness and refresh setup-owned facts. `--verify-only` is a facts-only mutation mode and may write setup-owned facts, scenario fingerprints, and ledgers only; it must not install providers, edit host config, bootstrap project config, or refresh generated runtime.\n- `--plan`: render install\u002Fconfig operations and safety results; do not write setup facts, host config, or install tools.\n- `--project-config`：仅执行 project-local config bootstrap。按请求刷新 example，仅在显式 action 后创建 local override，按请求确保 `.spec-first\u002F*.local.yaml` ignore coverage，并报告 legacy project config signal 而不迁移它们。该 mode 不安装 MCP server、不配置 host runtime，也不执行 helper\u002FProvider first generation。\n- Bare invocation (`spec-runtime-setup` in the current host): default full setup workflow. Resolve target，运行默认 required-provider plan；无 blocker 时执行等价的 `--only codegraph,graphify` apply、验证 baseline\u002FProvider\u002Fruntime\u002Fproject status，并写 setup facts。Bare workflow invocation 本身已授权自动修复 selected target 中 registry 管理的 `host-config-conflict`，不需要二次确认；它不授权绕过 higher-precedence、unsafe path、unreadable config、symlink\u002Fpath escape 或 literal secret gate。\n- `--only \u003Cids>`: advanced headless\u002Fsubset repair path. `--only codegraph`, `--only graphify`, or `--only codegraph,graphify` narrows provider execution and does not require a confirmation prompt；子集结果必须标记为 partial scope，不能声称完整 setup ready。\n- `--repair-host-config`：显式授权 setup 仅替换 registry 管理且已确认冲突的 MCP 条目；保留同一 host config 中的其他用户字段和 server，并执行事务回滚与 post-write verification。Bare full setup 由 workflow 自动携带该 flag 处理 selected-target managed drift；显式 subset\u002Frepair 调用则必须由用户提供。可单独用于 baseline host config repair，也可与 `--only ...` 组合，在修复后继续 Provider install-init。没有该 flag 时，显式 `--plan` 必须在 package\u002Fprovider mutation 前报告 `host-config-conflict` 并阻断；高优先级 target 冲突、不可读配置、symlink\u002Fpath escape 和 literal secret 不能通过该 flag 绕过。\n- `--refresh`: Graphify 显式刷新路径。已有 `graphify-out\u002F` 时，与 `--only graphify` 一起使用；setup 调用官方 `graphify update \u003Cworkspace>` 更新现有 code graph，并在更新后重新执行完整性与裸 query probe，再原子写入与当前 `graph.json` SHA-256 绑定的 scope provenance receipt。它不创建 spec-first 顶层 staging\u002Fbackup；若只有旧版适配目录 `.graphify\u002F`，普通 setup 会先将其原子迁移为 `graphify-out\u002F`，两个 artifact root 同时存在则 fail closed。它是 `manual-only` steady state 的按需更新方式，不是修复项目外 `core.hooksPath` 的动作，也不代表完整 semantic extraction。普通 setup 或 `--verify-only` 返回 core-ready `readiness_status=unknown` 时，不得仅因 unknown 自动追加或执行 `--refresh`；unknown 表示缺少当轮 currentness evidence，不表示 query probe 失败或 required setup 未完成。\n- `--requirement-workspace \u003Ctarget-relative-path>`: optional Graphify input-scope override. Omit it for normal project-workspace setup; default input scope is the resolved execution root. This flag narrows Graphify input only; it does not change the CodeGraph root, setup facts owner, or the Provider-native `graphify-out\u002F` artifact owner.\n- `--repo \u003Cpath>` must resolve to the exact Git repository root. A nested path is invalid and fails closed instead of being promoted to an ancestor root; use `--folder` when the nested directory is the intended logical project.\n- `--folder \u003Cpath>` selects the exact logical project directory and does not require Git. CodeGraph writes `.codegraph\u002F`, Graphify writes `graphify-out\u002F`, and setup writes `.spec-first\u002Fconfig\u002F` under that folder. If it is nested inside a Git repository, generated spec-first runtime readiness is checked at the enclosing Git root so setup does not request a duplicate child `.agents\u002Fskills`; a standalone non-Git folder uses itself as the runtime projection root. Missing\u002Fstale runtime returns a structured interactive action rooted at that projection plus a headless variant containing `-y -u \u003Cname> --lang \u003Czh|en>`; the folder is never passed to Git-only `init --repo`. Git health remains an additional fact and never rewrites the folder target. Graphify commit hooks and Git HEAD baselines are skipped as `not-applicable` for `target_kind=non-git-folder`, including a nested folder whose parent is a Git repo, while first generation, query, explicit refresh, and CodeGraph indexing remain supported.\n- `--user-scope`：Kiro\u002FQoder\u002FCursor\u002FOpenCode 写入 user-level MCP config 的 opt-in。缺少该 flag 时，即使由 generated host skill\u002Fcommand 间接调用，setup 也只为 Kiro 写 workspace `.kiro\u002Fsettings\u002Fmcp.json`、为 Qoder 写 local `.qoder\u002Fsettings.local.json`、为 Cursor 写 project `.cursor\u002Fmcp.json`，或为 OpenCode 写 project `opencode.json`。OpenCode user scope 解析 `${XDG_CONFIG_HOME}\u002Fopencode\u002Fopencode.json`；project\u002Fuser scope 任一存在更高优先级 JSONC sibling 时都以 `host-config-jsonc-precedence-blocked` 阻断 JSON mutation。\n\nOpenCode host config mutation 把 MCP entry 与 `opencode-governed-assets-v1` permission policy 视为同一 bounded transaction。Permission policy 只允许当前 projected runtime state 中的精确 governed skill names，禁止 wildcard\u002Fglobal allow，并让 `bash`、`edit`、`task`、`webfetch`、`websearch` 等危险工具保持 `ask`；遇到 conflicting user rule、unsafe last-match ordering 或 post-write verification failure 时 fail closed \u002F rollback。Uninstall 只删除仍与 expected value 精确匹配的 managed entries，不删除整份 `opencode.json`，也不覆盖 unrelated user fields。\n\nGraphify setup 使用受控 Provider route；标准 bare workflow 默认选择 Graphify，`--only graphify` 是高级子集修复入口。当前 pin 是 PyPI `graphifyy@0.9.29`，要求 Python `>=3.10`。Setup 只使用已安装的 uv（优先）或 pipx，将 release-reviewed direct wheel 安装到隔离 tool environment；uv 禁止 managed Python download，缺少兼容 Python 或 tool manager 时返回 action-required，不自动 bootstrap，也不回退 plain pip。Package readiness 同时验证 distribution identity、version、CLI version、absolute launcher 与 interpreter。显式 Graphify mutation setup 只有在 Python package\u002Fartifact\u002Fquery\u002Fhost 都 verified，且 Git 项目中的 project-local hook 也 verified（非 Git 项目不适用）时，才默认卸载已确认的全局 `@sentropic\u002Fgraphify`，并只删除仍保持原 target 且解析到该 npm package 的旧 symlink。External\u002Funsafe hook target 下不执行 incumbent cleanup；未知命令、普通文件和其他 symlink 一律不改。\n\nGraphify Provider只接受PyPI `graphifyy` dependency。失败恢复使用固定wheel重装、contained artifact backup恢复与Python readiness复验。\n\n缺少 `--requirement-workspace` 时使用已解析 project workspace，并直接采用 Provider 原生默认目录 `graphify-out\u002F` 作为唯一 current artifact，不注入 `GRAPHIFY_OUT`。首次生成固定运行 `graphify extract . --code-only`，不探测 API key、不触发 semantic backend；支持代码文件非空但生成零节点时 fail closed。已有 `graphify-out\u002F` 且未提供 `--refresh` 时只验证 package、host integration、裸 query，以及当前项目授权域内可用时的 optional hook，不修改 current graph。`graphify-out` 已存在但不是非 symlink 真实目录时，以 `graphify-artifact-root-unsafe` 在任何 host\u002Fruntime mutation 前阻断；仅有旧版 `.graphify\u002F` 时原子迁移目录而不重建图；`.graphify\u002F` 与 `graphify-out\u002F` 同时存在时以 `graphify-artifact-root-conflict` 阻断，避免双 source-of-truth。显式 `--refresh` 使用官方 `graphify update \u003Cworkspace>` 在现有图上更新代码索引，复用 Provider 自带的 repo lock、临时 graph、shrink guard 与未变节点保留能力；spec-first 不再为日常刷新创建顶层 `.graphify.staging-*`、`.graphify.backup-*` 或 migration journal。旧版本遗留 journal 仅保留兼容恢复，不是新 refresh 的回滚机制。Apply\u002Frefresh 当轮有生成与 query 证据时可为 `fresh`；只读 verify 没有当轮 currentness 证据时为 `unknown`。\n\nClaude、Codex、Cursor、Kiro 使用 Python Provider 的真实 project install surface；setup 只在 recognized Provider-owned skill\u002Freference\u002Frule\u002Fsteering 与 `## graphify` section 内规范化 `graphify-out\u002F`，并将 Claude\u002FCodex host hook command绑定 verified launcher。Qoder 不调用不存在的 `--platform qoder`，由 spec-first-owned Qoder instruction提供 direct CLI\u002Ffallback adapter。Graphify Git hook 是 project-local optional auto-refresh：setup 先用 `git rev-parse --git-path hooks` 解析有效 hooks root，只有 lexical containment 与 no-follow symlink containment 均证明目标位于当前项目内时，才以进程级 `core.hooksPath` pin 运行 hook install\u002Funinstall\u002Fstatus，并在命令后重新解析目标。共享 worktree\u002Fsubmodule metadata、resolve failure 或 symlink escape 下，不运行 hook 命令、不读取外部 hook 内容、不修改 local\u002Fglobal `core.hooksPath`、不复制或串联全局 hooks；返回 `blocked + manual-only`，但不阻断已经通过的 Graphify 核心 readiness。有效 hooks root 位于项目外（如全局 `core.hooksPath`）时，setup 只读 `post-commit`\u002F`post-checkout` 两个普通文件，检测 Provider marker 与会重新生成 legacy root 的 `GRAPHIFY_OUT=.graphify` override；绝不 write\u002Fexecute\u002F`hook status`，也不修改 `core.hooksPath` 或串联全局 hooks。只有 `post-commit` marker 存在且两个文件均无 legacy override 时才报告 `hook_status=verified-external` + `refresh_mode=commit-hook-external-verified`；只有 post-checkout marker、marker 缺失或文件不可读时返回 `blocked + manual-only`，legacy override 则使用 `graphify-external-hook-legacy-artifact-override` 明确阻断。这里的 `manual-only`\u002F`verified-external` 只描述 spec-first 只读可验证的 external commit-time posture，不是 project-owned `verified`（`hook_installed`\u002F`hook_verified` 保持 false）。不得声称外部 hook 不存在、不会执行或“安装失败”；external execution 始终是 unverified。Project-local verified hook 仍要求 post-commit 与 post-checkout 各有唯一 Provider marker block、verified interpreter和允许的 `_rebuild_code`命令；spec-first 会移除旧版 `GRAPHIFY_OUT=.graphify` 注入，确保 hook 使用 Provider 原生默认目录。Marker 外用户内容保持不变，也不会被默认 smoke执行。Setup 不编辑 shell profile、不启动 watch、不安装 `graphifyy[mcp]`，也不把 Graphify candidate提升为 confirmed truth。\n\nCodeGraph setup 使用受控 MCP\u002FProvider route。被选中后，setup 安装 `setup-registry.json` 声明的 pinned CodeGraph dependency，使用 `codegraph serve --mcp` 配置 host MCP，运行 `codegraph init`，并探测 `codegraph status`。若 status 报告 `Pending Changes` 或要求 `codegraph index -f`，setup 先执行一次 bounded `codegraph sync`，再运行 `codegraph status`；仍存在 pending change 或 sync 失败时，返回带 diagnostic 的 action-required。若 post-sync status 仍要求 `codegraph index -f`，setup 执行一次 bounded full reindex 并复查 status。索引 ready 后必须运行 bounded `codegraph query __spec_first_readiness_probe__ --limit 1 --json` real query probe；只有命令真实成功才设置 `query_verified=true`，失败则报告 `codegraph-query-probe-failed` degraded readiness。Full reindex 或 query probe 失败时保留现有 `.codegraph\u002F` artifact，报告 degraded\u002Factionable readiness，不删除 index。这些一次性的 sync\u002Freindex 分支属于 install-init repair，不代表 spec-first 接管 steady-state ownership。\n\n## Default Full Setup Flow\n\nFor bare `spec-runtime-setup`, execute with **batch authorization and single confirmation**:\n\n1. Resolve the project target. Use `--repo \u003Cgit-root>` for an exact Git repository or `--folder \u003Cproject-folder>` for an exact logical directory, including a fully non-Git project. With no flag, a pure non-Git directory becomes the folder target unless bounded child repos are discovered. An invalid nested `--repo` stops before plan, host, provider, or facts work; the same path is valid through `--folder`.\n2. Run the read-only check。若 example config missing\u002Foutdated 或 local-config ignore rule missing，先运行 `--project-config --refresh-example --ensure-gitignore`；`.spec-first\u002Fconfig.local.yaml` 缺失保持 `defaults-active`，不创建空 override。\n3. Run `node \"$SKILL_DIR\u002Fscripts\u002Fsetup.cjs\" --plan --repo \u003Cresolved-git-root>` for a Git target or `node \"$SKILL_DIR\u002Fscripts\u002Fsetup.cjs\" --plan --folder \u003Cresolved-folder>` for a folder target. For the default parent-workspace batch, preview every discovered child with its own `--repo \u003Cchild>` target before the shared apply. Plan 默认选择 registry 中 `setup_required=true` 的 CodeGraph\u002FGraphify，并同时预览 baseline MCP\u002Fhelper、host config、Provider artifact、hook 与 facts writes。计划必须分别显示 absolute execution root、runtime projection root、Graphify input scope 和 absolute artifact root；input scope 变窄或 runtime 复用都不改变 artifact ownership。\n4. If the plan reports an unresolved target, higher-precedence conflict, unsafe path, unreadable config, or unsupported install path, stop with the exact blocker. If it reports a selected-target `host-config-conflict`, show config path\u002Fkey\u002Fdrift fields。Bare workflow invocation 本身已授权自动修复 selected target 中 registry 管理的 `host-config-conflict`：自动携带 `--repair-host-config` 重新 preview 并继续 apply，不再请求用户二次确认。\n5. **Present consolidated setup summary and request single confirmation**: Show all pending operations in one grouped summary (missing dependencies, config changes, provider installations). Ask exactly one yes\u002Fno confirmation for the whole batch, using the platform's blocking question tool when available (e.g. `AskUserQuestion` in Claude Code, `request_user_input` in Codex) and falling back to a plain-text yes\u002Fno prompt in chat when no blocking tool exists in the harness. Never ask a second confirmation per item. On approval, immediately proceed to step 6. On decline, exit with the diagnostic summary and no mutation.\n6. Plan 无 blocker 且用户确认后，批量执行 apply：Git 目标使用 `--repo \u003Cresolved-git-root>`，folder 目标使用 `--folder \u003Cresolved-folder>`；默认 parent-workspace batch 则从 parent 运行且不带 target flag，由 resolver 对全部 discovered child 执行。所有路径都携带已授权的 repair\u002Ftarget\u002Fworkspace flags。\n7. Apply 必须完成 ffmpeg\u002Fbaseline helper、CodeGraph init\u002Findex\u002Fquery、Graphify package\u002Fhost integration\u002Fgraph\u002Fquery、host config、project status 和 facts verification。Graphify hook 只在有效目标位于项目内时作为 optional auto-refresh enhancement 安装并验证；blocked\u002Fskipped\u002Ffailed 必须显式展示 steady-state limitation，但不得单独把 core-ready 完整 setup 改为 action-required。任一真正 required item 未 ready 时，完整 setup 返回 action-required；不得以 direct-source fallback 把 setup 本身报告为 complete。\n\n## Subset \u002F Repair Flow\n\nUse `--only codegraph`, `--only graphify`, `--only codegraph,graphify`, or Graphify `--refresh` for advanced subset repair:\n\n1. 运行带相同 selection 的 plan，再执行 apply；`--only` 自身就是该子集 mutation 的授权。\n2. Host conflict 仍需独立 `--repair-host-config` 授权；higher-precedence、unsafe path、unreadable config 和 literal secret 永远 fail closed。\n3. 子集成功只证明所选 scope ready。最终完整 setup readiness 仍以 `spec-runtime-setup --verify-only` 对全部 required items 的结果为准。\n\n## Per-Requirement Workspace Graph (Multi-Repo)\n\n从一个**非 Git 的需求文件夹**(多仓父目录,内含多个独立 clone 的子 Git 仓)运行 setup 时,先分清两条路径:\n\n1. **子仓 provider\u002FMCP setup**(各 child 的 CodeGraph\u002FGraphify\u002Fhost config):父目录无 target 参数时默认 all-repos；`--repo \u003Cchild>` 收窄到单仓，`--all-repos` 可用于显式表达同一批处理范围。\n2. **父目录双层图**(per-child CodeGraph + workspace Graphify merge):`--workspace-graph --repos a,b,...` 或 `.spec-first\u002Fworkspace.yaml` manifest。  \n   **不要**写 `--workspace-graph --all-repos`——`--all-repos` 只服务子仓 batch,不是 workspace-graph 的仓集确认。\n\n### 从子仓开始时的轻量引导\n\n这是一段静态引导，不会自动声明 workspace membership、CodeGraph 已安装，或 workspace graph 已构建：\n\n- 问题只涉及当前子仓时，如 Provider 可用，以当前子仓作为 `projectPath` 使用 CodeGraph；结果只是导航候选，重要结论仍由源码、测试、diff 或日志确认。\n- 问题跨多个子仓时，回到非 Git 的需求父工作区。仅当 workspace graph 状态和目标仓范围均已确认时才使用 Graphify；随后直接检查候选子仓。\n- 不要假设 workspace graph 存在或仍然 current，不要从该引导推断成员关系，也不要把任一 Provider 输出当作语义证明。\n\n本轮不向 child `AGENTS.md` \u002F `CLAUDE.md` 注入独立受管 marker，也不提供对应的 clean 生命周期；父目录 routing block 仍由显式 workspace graph lifecycle 管理。\n\n首次接入 requirement workspace 时先运行 `spec-first init --all-repos`（或逐仓 `spec-first init --repo \u003Cchild>`）让所选宿主的 child projection current，再运行 `spec-runtime-setup --only codegraph,graphify --workspace-graph`。Projection current 后，workspace graph 命令会为该 workspace 建立两层代码图：\n\n1. **每子仓战术图**:`codegraph init` 生成 `工程N\u002F.codegraph\u002Fcodegraph.db`;`.codegraph\u002F` 写入该子仓 `.git\u002Finfo\u002Fexclude`(经 `git rev-parse --git-path` 解析,正确处理 `.git`-as-file\u002Fworktree,并做 realpath+containment 校验)以保持子仓 `git status` 干净;CodeGraph MCP server 全局 install 一次,跨仓查询通过 `projectPath`。Build、refresh-only 与 status 均只把 contained、stable、非 symlink、非空的 canonical DB 视为 artifact ready；目录中的日志、锁文件或空 DB 不构成完成证据。\n2. **workspace 跨仓宏观图**:Graphify `extract --code-only` 每子仓子图 + `merge-graphs` 合并图,全部 out-of-tree 写到 `需求文件夹\u002Fgraphify-out\u002F`(子仓物理零侵入)。单\u002F零子仓分别产出 single-source \u002F not-applicable。所有 Graphify JSON 在 promotion\u002Fstatus 前通过 no-follow stable descriptor 做任意大小的完整流式语法校验，不以非空、首尾括号或 Provider 零退出替代 artifact 完整性。构建结果原子写入 `graphify-out\u002Fworkspace-graph-state.json`;`workspace-graph-state.v3` 保留 source snapshot、merged artifact SHA-256、repo\u002Fmerge artifact promotion cleanup pending 与可为 null 的 `refresh_hook`。异步模式的 `workspace-child-hook-contract.v2` receipt 包含 canonical managed-block SHA-256、绝对 Node\u002Fasync\u002Fsetup\u002FCodeGraph\u002FGraphify 路径、runtime host 与 bundled version。status 保留主要 build reason，并把 cleanup pending 作为独立 limitation 暴露；只有在最近构建 complete、无 cleanup pending、repo 集合与 source snapshot 未变化、两个 hook 内容\u002F执行位\u002Fruntime path\u002Fversion 均符合 receipt，且 CodeGraph\u002FGraphify artifacts、非 symlink 合并图与路由块均存在时才报告 ready。旧 v1\u002Fv2 state、v1 hook receipt 或缺少 `refresh_hook` 的 state 不自动迁移；升级后需显式重跑 workspace build，以原子替换 state 和 managed hooks。\n\nCodeGraph 1.5.0 的 MCP watcher 只绑定 server 默认项目，通过 `projectPath` 打开的其他子仓不会各自启动 watcher。Graphify 0.9.x 原生 child hook 只重建 child 默认 output，也不能更新上述 out-of-tree 子图并重收敛 merged graph。因此 workspace 模式使用 spec-first 自有 contained `post-commit` \u002F `post-checkout` managed hook：显式 build 先通过现有 Provider resolver 确认绝对 CodeGraph 与 Graphify launcher，只有两个 launcher、当前 host 与 bundled version 都完整时才固化进 hook；managed block 放在 shell shebang 后、用户正文前，避免既有 `exit` \u002F `exec` \u002F `set -e` 令刷新不可达，malformed block 在 install\u002Fclean 时均 fail closed。上下文不完整时不安装 PATH-dependent hook并降级为 explicit。Status 依据 receipt 重建 canonical block digest，检查两个 hook 的内容、POSIX 执行位、记录的 runtime files 可用性与当前 bundled version；漂移时统一将 workspace status 降为 partial、effective refresh mode 降为 explicit，并保留 per-child `workspace-child-hook-*` reason code。Git 事件 detached 触发 refresh-only setup，它必须同时携带 internal marker、两个 pinned launcher 与有效 lifecycle credential；在 lifecycle lease 内对全部 confirmed child 运行 bounded `codegraph sync \u003Crepo>`，再执行 Graphify `extract` \u002F `merge-graphs`，不得再次执行 CodeGraph global install\u002Finit、managed exclude、routing injection 或 hook installation。Refresh-only 期间保留上一份 completed state，由 async\u002Flifecycle facts 表达 in-flight，最终再原子发布新 state，避免并发 Git 事件被 active-state gate 丢弃。`graphify-out\u002Fworkspace-async-refresh.lock` 只负责 event single-flight\u002Fcoalesce\u002Frelease handoff；`.spec-first\u002Fworkspace-graph-lifecycle.lock` 独占所有后台 build、显式 build、clean 与 status writer，async setup child 只能校验 wrapper 继承的 token。显式 build\u002Fclean 抢锁失败时必须在 provider、图、routing、hook、state mutation 前返回 `workspace-graph-lifecycle-busy`；活 PID 但 start marker 无法确认时保持 busy，不按年龄抢占，successor release 会清理已失去 canonical ownership 的 quarantine residue。clean 删除 state 后，旧 hook\u002Fworker 会在 trigger 与获得 lifecycle lease 后复核 enablement 并停止。可恢复的 provider partial 允许下一次 Git 事件重试；需要 owner 确认、路由写入失败或 runtime\u002Fhook contract 漂移保持显式修复。status receipt 带 `attempt_id`，成功 build 只清除开始时观察到的 generation。与其他 provider mutation 相同，workspace build 在 selected child 的当前 host projection 缺失或过期时必须于 mutation 前阻断。hook 不可安全安装、非 Git 变化或需要即时刷新时，重新运行同一 `--workspace-graph --repos ...` 命令。不得把 watcher、hook marker、派发成功或最近一次 success receipt 表述成 workspace freshness 保证；消费侧仍以 source snapshot\u002Fstatus 为准。\n\n仓集来源是 `需求文件夹\u002F.spec-first\u002Fworkspace.yaml` manifest 与 `--repos \u003Ca,b>` 的并集；manifest 先处理，同仓重复声明时保留 manifest alias\u002Fentry，CLI 只增补其他 confirmed 仓。自动发现仅作候选，需确认后才建。自动发现只扫描需求根的直接子目录；重复 alias 或嵌套仓根会返回 `workspace-targets-ambiguous` 并阻止 build\u002Fclean，必须先由 owner 消除歧义。\n\n`workspace.yaml` 是为六宿主 projected runtime 保持零依赖的**严格 YAML 子集**，不是通用 YAML：支持顶层 `schema_version`、`repos`、`exclusions`，2 空格列表缩进、`repos` 下 4 空格的 `path`\u002F可选 `alias`、普通或单\u002F双引号字符串和行尾注释。禁止 tab、flow collection (`[]`\u002F`{}`)、anchor\u002Ftag、block scalar、多行值及未声明字段；不符合时返回 `workspace-manifest-unparseable` 或 `workspace-manifest-schema-invalid`，不得猜测或静默忽略。可用格式：\n\n```yaml\nschema_version: workspace-manifest.v1\nrepos:\n  - path: api # workspace-relative\n  - path: 'web client'\n    alias: web\nexclusions:\n  - vendor\n```\n\n相关 flag(同一 workspace-graph 域):\n\n| Flag | 作用 |\n| --- | --- |\n| `--workspace-graph` | 在 child projection current 后，一次性建双层图 + 写 state receipt + 安装 contained child async refresh hook + 注入六宿主入口路由块；hook 不可用、非 Git 变化或需即时刷新时显式重跑 |\n| `--workspace-graph-status` | 只读汇总各 child\u002Fworkspace 图状态、state\u002Fsource freshness、hook digest\u002Fruntime\u002Fversion\u002F执行位、merged artifact containment\u002FSHA-256、default `projectPath` containment(advisory)、路由块是否已注入;不调用 provider 二进制 |\n| `--workspace-graph-clean` | 幂等清理:先独占 lifecycle lease；busy 时零 mutation 返回失败。成功持锁后删子仓 `.codegraph\u002F`、只移除 spec-first managed exclude\u002Fhook 块、删需求父目录的 current `graphify-out\u002F` 与 legacy `.graphify\u002F`、剥离路由 managed block；任一 child\u002Frouting 清理失败时保留两个 workspace graph root 供重试，不强制 kill CodeGraph daemon。宿主级等价入口:`spec-first clean --workspace-graph [--repos a,b] [--dry-run]`(不碰 host runtime mirror) |\n\nMachine contract:\n\n| operation status | mutation exit code | 含义 |\n| --- | ---: | --- |\n| `complete` | 0 | 请求的 mutation 全部完成 |\n| `partial` \u002F `failed` | 1 | 至少一个确定性步骤失败;读取 `reason_code` 与 per-repo 状态 |\n| `needs-confirmation` | 2 | 自动发现仅是候选;用 JSON 中的 `pending_confirm[]` 生成 `--repos` 重试命令 |\n\n`--json` 输出完整 envelope;自动化消费者必须同时读取 `status`、`reason_code`、`pending_confirm[]`、state\u002Ffreshness 与 per-repo 字段,不能只检查文件存在或进程是否打印成功文本。显式 `--workspace-graph-status` 是只读诊断,即使对象 absent\u002Fpartial 也可 exit 0,由 envelope 表达 readiness。\n\n**边界(per-需求 隔离)**:每个需求文件夹自成一体,不复用其它需求的图,不写机器级 global graph;`projectPath` 解析限定当前 workspace 根内;discovery 与所有 Git-metadata 写入均 symlink-contained;图输出是 advisory candidate,结论回子仓源码确认。删除需求文件夹即清空其图(无机器级残留)。\n\n从当前 Git repo(非父 workspace)运行 `--workspace-graph*` 会被跳过(该能力面向非 Git 多仓父目录)。\n\n## Workflow\n\n1. Identify the current host from the generated host-specific runtime surface invoking the unified `spec-runtime-setup` entrypoint.\n2. If invoked from a non-Git parent workspace, resolve all discovered supported child repos by default; `--repo \u003Cchild>` narrows the run. Writes must stay within each resolved child target.\n3. 运行共置 Node 入口，使其加载 `setup-registry.v10`、校验 schema，并展开 effective host\u002Fplatform registry。\n4. 让 `setup.cjs` 按所选 mode 诊断或安装必需的 package-backed MCP tool；standard workflow 默认选择 registry required Provider，`--only` 只用于高级子集修复；host config 只能通过 registry target 写入，并记录结构化 execution facts。\n5. 让同一 Node 入口验证 baseline helper 与 required Provider。`agent-browser` 保持 diagnostic\u002Fmanual-command only，并通过 sibling `spec-test-browser` canonical wrapper 读取 capability facts；安装完整但 exact-origin execution blocked 时报告 degraded 而非重复安装，且不影响 baseline completion。ffmpeg、CodeGraph 与 Graphify 核心能力必须进入完整 setup completion。Provider first generation 与 project-local auto-refresh setup 只能通过静态 Provider module 与 bounded argv-array process runner 执行。若默认 project-root scope 中的 `graphify extract .` 失败，setup 可以先尝试 code-only `graphify update .`，再返回 failed readiness。若 Graphify 已安装但不在用户原始 `PATH` 中可见，报告 manual visibility action，不编辑 shell profile。Graphify hook 仅在有效 hooks root 位于项目内时允许 bounded repair；blocked\u002Ffailed hook 记录 `next_actions` 与 `manual-only` limitation，不得标记 hook refresh 已验证，也不得单独把已通过的核心 Provider readiness 改为 `degraded`。\n6. Run project-local config bootstrap where the selected mode authorizes it. Bare setup reports example\u002Flocal\u002Fgitignore\u002Flegacy status；missing local override 记为 `defaults-active`。Explicit project-config actions may refresh the example, create the local override, and ensure ignore coverage. Do not auto-delete legacy project config or migrate legacy keys.\n7. 使用 `setup.cjs --verify-only` 写入 readiness ledger、reconcile host pointer facts、写入 project setup facts，并渲染分组 status block。必须分别读取 `generated_runtime_manifest.status` 与 `baseline_ready`；`baseline_ready=true` 不能掩盖 stale generated runtime。状态为 `stale` 或 `missing` 时，按 topology 消费 setup 返回的结构化 runtime init action：当前 repo\u002Ffolder\u002Fparent 使用 action 自带的 projection `cwd`，单个 child 或 all-repos 使用 workspace verify 返回的对应 argv；交互式 action 不带 `-y`，headless action 必须显式提供 developer name 与 language。不得把 cwd\u002Fpath 拼成 shell compound command；随后重新验证。若刚运行 `spec-first update` 后状态仍 stale，应将其视为 degraded refresh evidence，并展示相同 fallback action，不得报告 runtime freshness 为 ready。\n8. Report the status exactly enough for the user to act: ready rows need no action; action-required rows name the missing dependency\u002Fconfig\u002Ftarget step; generated runtime manifest rows name the init refresh command when stale or missing.\n\n## Output Shape\n\nThe final setup output should contain:\n\n- `Execution result`: separate `Required MCP\u002Fhelper dependencies` and `Generated runtime manifest` rows; report `baseline_ready` as dependency readiness and `generated_runtime_manifest.status` as generated runtime freshness.\n- `MCP servers`: required baseline MCP tool dependency\u002Fhost\u002Fproject readiness、CodeGraph host config readiness 和 next action；`--only` subset 必须显式标注 scope。\n- `Helper tools`: helper install and readiness status.\n- `Provider tools`: provider readiness status, derived `readiness_scope` \u002F `probe_status`, and lifecycle display bits when present. Summaries must distinguish install\u002Findex readiness from server\u002Fquery verification.\n- `Host configured dependencies`: configured MCP\u002Fhooks\u002Fallowlist\u002Fsetup\u002Fverification command facts.\n- `Install safety`: helper install source, risk, review, and mirror provenance.\n- `Project local config`: example config, local override, gitignore safety rule, legacy markdown config signal, and retired legacy local config status. Human labels and machine fields should be de-branded; active setup facts must use `.spec-first` local config paths and neutral legacy field names.\n- `Project setup facts`: status for `tool-facts.json` and `runtime-capabilities.json`.\n- `Verification profile`: current verification profile visibility placeholder; full profile execution is v1.13 scope.\n- `Next steps`: either fix action-required rows, narrow to an explicit child repo when a single-repo retry is needed, continue to the user-intent workflow, or suggest `spec-rule-miner` as a separate follow-up after CodeGraph\u002FGraphify readiness is prepared. This suggestion is advisory; setup must not treat rule-miner output as setup readiness and must not call `spec-rule-miner` automatically.\n\n### Readiness Handoff\n\n- Render the first-task handoff only when the full setup outcome is ready and every required dependency plus generated runtime manifest is ready. 按用户语言输出最多 3 行非空输出，并提供可直接替换内容的任务模板：中文为 `请基于当前项目处理这个任务：\u003C描述你的需求或问题>。`；英文为 `Please handle this task based on the current project: \u003Cdescribe your requirement or problem>.`。\n- 对 action-required、degraded、failed 或其他未就绪结果，不得展示上述首次任务模板；要求用户执行报告的 next action 后重新运行 `spec-runtime-setup`。不得把 `spec-first doctor` 或额外 `--verify-only` 作为正常 ready 路径的第二道验证。\n- 既有 direct source evidence fallback 仍可供下游 workflow 在证据足够时降级执行，但它不改变本次完整 setup 的状态，也不得把完整 setup 报告为 ready。\n\n`tool-facts.json` records setup-owned tool and helper readiness:\n\n```json\n{\n  \"schema_version\": \"tool-facts.v2\",\n  \"tools\": {},\n  \"helper_tools\": {},\n  \"items\": [],\n  \"configured_dependencies\": [],\n  \"schema_capabilities\": [\n    \"items\",\n    \"configured_dependencies\",\n    \"tool-existence\",\n    \"provider-readiness-generic\"\n  ],\n  \"source\": {\n    \"repo_status\": \"git-repo\"\n  }\n}\n```\n\n`runtime-capabilities.json` should record direct evidence posture instead of provider capabilities:\n\n```json\n{\n  \"schema_version\": \"runtime-capabilities.v1\",\n  \"direct_evidence\": {\n    \"bounded_source_reads\": true,\n    \"ripgrep\": true,\n    \"ast_grep\": true,\n    \"git_diff\": true,\n    \"tests_and_logs\": true\n  }\n}\n```\n\n## Boundaries\n\nSetup does:\n\n- verify Node\u002Fnpm\u002Fnpx and required helper dependencies;\n- 按 `setup-registry.json` 配置 warm package-backed MCP server；\n- write host MCP config through managed\u002Fuser host targets;\n- replace only an authorized conflicting managed MCP entry through `--repair-host-config`; bare full setup supplies this authorization for selected-target registry-managed drift, while explicit subset\u002Frepair calls require the flag, unrelated host config is preserved, and higher-precedence or unsafe targets remain blocked;\n- write Kiro MCP config to workspace `.kiro\u002Fsettings\u002Fmcp.json` by default, and to `~\u002F.kiro\u002Fsettings\u002Fmcp.json` only after explicit user-scope opt-in;\n- write Qoder MCP config to local `.qoder\u002Fsettings.local.json` by default, and to `~\u002F.qoder\u002Fsettings.json` only after explicit user-scope opt-in;\n- write Cursor MCP config to project `.cursor\u002Fmcp.json` by default, and to `~\u002F.cursor\u002Fmcp.json` only after explicit user-scope opt-in;\n- write project-local setup facts;\n- refresh `.spec-first\u002Fconfig.local.example.yaml`, create `.spec-first\u002Fconfig.local.yaml`, and ensure `.spec-first\u002F*.local.yaml` ignore coverage only through explicit project-local config bootstrap actions;\n- report the legacy project markdown signal for manual review and the retired legacy local config status without migrating either;\n- perform explicit provider-native first generation for approved providers when the target workspace is resolved, or verify Graphify install readiness without regenerating the graph when a project-root Graphify artifact already exists and no explicit `--refresh` was requested;\n- perform bounded provider-native setup repair where deterministic and documented, such as Graphify provider-native `update` for explicit `--refresh`, one `codegraph sync` after pending\u002Ffull-rebuild status, or one `codegraph index -f` after sync cannot clear the full-rebuild advisory;\n- perform provider-native project-local auto-refresh setup only when the Git-native effective hooks root is contained by the current project, such as Graphify `graphify hook install`, followed by bounded marker-owned artifact\u002Finterpreter normalization and structural verification; otherwise report a non-mutating `blocked + manual-only` steady state;\n- classify parent workspace target ambiguity and foreign residual indicators as advisory facts.\n\nSetup does not:\n\n- start watchers or long-running daemons;\n- install the optional Graphify MCP server;\n- run provider first generation from `--check`, `--plan`, `--verify-only`, or invalid explicit workspace override paths;\n- treat provider indexes or query probes as semantic code evidence;\n- treat setup facts as semantic code evidence;\n- invoke `spec-rule-miner`, synthesize project rules, or write `docs\u002Fai\u002Fproject-rules.md`;\n- treat `.spec-first\u002Fconfig.local.yaml` as team-shared workflow policy;\n- silently copy or translate legacy project config into `.spec-first\u002Fconfig.local.yaml`;\n- decide issue\u002FPR category, state, scope, accept\u002Freject status, or implementation truth;\n- hand-edit generated runtime mirrors as source;\n- block ordinary plan\u002Fwork\u002Freview\u002Fdebug when direct source evidence is sufficient.\n\n## Verification\n\nFocused setup changes should run the narrowest relevant checks:\n\n```bash\nnode \"$SKILL_DIR\u002Fscripts\u002Fsetup.cjs\" --check\nnode \"$SKILL_DIR\u002Fscripts\u002Fsetup.cjs\" --plan\nnpm run test:runtime-setup\nnode --check \"$SKILL_DIR\u002Fscripts\u002Fsetup.cjs\"\n```\n\nFor cross-host changes, also run `npm run typecheck`, `npm run test:unit`, `npm run test:smoke`, and `spec-first init` after source validation.\n","# Runtime Setup\n\n`spec-runtime-setup` is the canonical runnable entrypoint for the Runtime Setup workflow across supported hosts (Claude\u002FQoder command spelling `runtime-setup`). Host-specific setup spellings are not separate products. Runtime Setup prepares deterministic host\u002Fruntime 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\u002Flogs, and user-provided evidence.\n\n## Contract Summary\n\n| Field | Contract |\n| --- | --- |\n| When to use | Host runtime setup, MCP setup, helper-tool readiness, missing runtime assets, or project-local setup fact refresh. |\n| When not to use | Ordinary planning, implementation, review, debugging, or code impact questions that can proceed from direct source evidence. |\n| 输入 | 当前 host、repo target、已加载 skill 共置的 `setup-registry.json`、host config 状态、git\u002Fworkspace target facts 与项目 instruction。 |\n| 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\u002Fconfig\u002F`, and a grouped status block. |\n| Artifacts | `.spec-first\u002Fconfig\u002Ftool-facts.json`, `.spec-first\u002Fconfig\u002Fruntime-capabilities.json`, `.spec-first\u002Fconfig.local.example.yaml`, `.spec-first\u002Fconfig.local.yaml` when explicitly created, `.gitignore` local-config safety rule when explicitly ensured, and `.spec-first\u002Fworkspace\u002Fscenario-fingerprint-setup.json` when applicable. |\n| Failure modes | Missing dependencies, host config write failure, ambiguous parent workspace target, symlink escape, invalid registry schema, helper install failure, or unsupported host. |\n| Downstream consumers | `using-spec-first`, plan\u002Fwork\u002Freview\u002Fdebug workflows, doctor\u002Fupdate guidance, and humans repairing setup. |\n\n核心边界：Node module 准备确定性的 readiness facts；LLM workflow 决定如何使用这些事实。Setup 不得判断代码理解的语义充分性，也不得要求普通工作必须先依赖外部分析服务。CodeGraph\u002FGraphify readiness 准备完成后，setup 可以建议将 `spec-rule-miner` 作为基于证据生成项目 AI coding rule 的后续步骤，但不得自行调用 rule mining、合成 rule 或写入 `docs\u002Fai\u002Fproject-rules.md`。\n\n## Scenario Capability\n\nFollows `docs\u002Fcontracts\u002Fworkflows\u002Fscenario-capability-matrix.md` (default).\nOverrides: none\n\n## Source Of Truth\n\nCanonical package source-of-truth 是 `skills\u002Fspec-runtime-setup\u002Fsetup-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\u002FGraphify first generation 和真实 query probe 属于标准 setup completion，而不是长期可跳过的 optional tail。`--only codegraph` \u002F `--only graphify` 仅用于高级子集修复，不改变完整 setup 的必备定义。\n\nGenerated 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.\n\n## Required Harness Runtime\n\n`setup-registry.json` 负责必需 MCP definition、helper readiness 与 install safety、required Provider metadata、external dependency pin、host target、artifact contract 和 platform override。Loader 针对当前 host\u002Fplatform 确定性展开 registry default，不判断 Provider readiness 或语义充分性。当前 helper 检查包括 ffmpeg、`agent-browser` 与 ast-grep capability detection；ffmpeg 是 setup completion 的 baseline-blocking helper，`agent-browser` 仍保持 report-only\u002Fnon-blocking。对 `agent-browser`，`dependency_status: ready` 只表示 CLI\u002Fruntime\u002Fglobal skill 安装完整，不等于 `execution_readiness: ready`；exact-origin capability 缺口必须保留其 canonical reason、`conformance_status`、`repair_scope` 与 `next_action`。\n\n所有可执行 setup 行为均由共置的 Node 入口及 `scripts\u002F` 下的 module 负责。不得在 workflow prose 中重新实现 registry query、host config 写入、Provider 命令或 facts reconciliation。\n\n## Loaded Skill 入口\n\n从当前已加载的 `spec-runtime-setup\u002FSKILL.md` 所在目录解析 `SKILL_DIR`。每次 runtime 调用都必须使用该目录中的共置 Node 入口：\n\n```bash\nnode \"$SKILL_DIR\u002Fscripts\u002Fsetup.cjs\" \u003Cmode-and-target-arguments>\n```\n\n绝不能从项目 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。\n\n`scripts\u002Fcheck-health` 是带 Node shebang 的 compatibility shim，委托给 `setup.cjs --check`。Windows 直接调用 `node \u003Cloaded-skill-root>\u002Fscripts\u002Fsetup.cjs --check`，不存在 platform-specific companion entry。\n\nOptional 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\u002Fmismatch\u002Finvalid 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\u002Fverify cannot report completion for an unproved requested scope. `steady_state` may include project-local hook readiness facts for optional provider refresh setup, such as Graphify `hook_installed`, `hook_verified`, `hook_status=blocked`, and `refresh_mode=manual-only`. Downstream decision health is still driven by `readiness_status`; lifecycle, first-generation, provenance, and hook fields explain boundaries and next actions, not semantic truth. Graphify hook blocked\u002Ffailed\u002Fskipped 不得单独把 package、host integration、artifact integrity 与 query probe 的成功结果改写为 Provider `degraded`。The human status table may derive `readiness_scope` and `probe_status` from existing lifecycle bits to separate install\u002Findex readiness from real server\u002Fquery probes; these display columns are not new machine schema fields. Provider self-reported `fresh` maps to `unknown`; provider self-reported `stale` may map to `stale` because it is conservative. `query_verified=true` is reserved for a real probe or explicit real-environment signal, not for package installation alone. A `false` or missing `server_reachable` \u002F `query_verified` display value means the probe is not verified in this setup run unless a failure reason says otherwise; it must not be summarized as confirmed provider query availability.\n\n## Project Preflight \u002F Local Setup\n\nProject-local setup has two separate surfaces:\n\n1. Setup-owned facts: `.spec-first\u002Fconfig\u002Ftool-facts.json`, `.spec-first\u002Fconfig\u002Fruntime-capabilities.json`, and when applicable `.spec-first\u002Fworkspace\u002Fscenario-fingerprint-setup.json`.\n2. Local config bootstrap: `.spec-first\u002Fconfig.local.example.yaml`, local override state for `.spec-first\u002Fconfig.local.yaml`, and `.gitignore` coverage for `.spec-first\u002F*.local.yaml`. Missing local override means `defaults-active`，不是“未处理的可选项”。\n\nThe readiness ledger and runtime capabilities include `generated_runtime_manifest.status` (`current`, `stale`, `missing`, or `unknown`) based only on `state.manifestVersion` versus the bundled manifest version; this is a deterministic freshness fact, not proof that generated prose is semantically correct. Missing\u002Fstale remediation is emitted as structured `next_action_command={cwd,command,args}` plus `next_action_headless_command`; `next_action` is explanation only and must never contain an executable `cd ... && ...` compound string. Scenario fingerprint wrapper failures are warn-and-continue: report `scenario_fingerprint_setup` status and keep the rest of setup actionable instead of blocking ordinary direct-evidence workflows.\n\nLocal config bootstrap is a first-class Runtime Setup capability, but it remains project-local and local-only. It checks and can explicitly refresh `.spec-first\u002Fconfig.local.example.yaml`, explicitly create `.spec-first\u002Fconfig.local.yaml`, and explicitly ensure `.spec-first\u002F*.local.yaml` is ignored. It reports legacy project config signals for manual review, but it does not copy legacy files, translate old key names, or treat old defaults as spec-first truth.\n\n## Three-Stage Setup Flow\n\n即使内部 Node module 执行多项检查，Runtime Setup 仍应将面向用户的流程保持为三个阶段：\n\n### Stage 1: Diagnose Target And Readiness\n\nResolve the project target first. `--repo \u003Cpath>` selects an exact Git root; `--folder \u003Cpath>` selects that exact logical project directory whether it is nested inside a Git worktree or has no Git boundary at all. With no target flag, a pure non-Git directory with no child repos becomes the single folder target, while a non-Git parent with discovered child repos keeps the bounded all-repos behavior. Provider artifacts and setup facts stay in the exact target; generated host runtime health uses the enclosing Git root when one exists, otherwise the folder itself. Then inspect:\n\n- host runtime identity and write authority;\n- required MCP\u002Fhelper dependency readiness;\n- generated runtime manifest freshness;\n- project-local config status for `.spec-first\u002Fconfig.local.example.yaml`, `.spec-first\u002Fconfig.local.yaml`, and `.gitignore` coverage;\n- legacy project config signals;\n- required CodeGraph\u002FGraphify readiness；`--only` 时只执行选定子集，但不得把子集成功表述为完整 setup 完成。\n\nThis stage is read-only except for diagnostic facts written by verify-only paths that are already setup-owned. Missing required Provider\u002Fhelper capability blocks Runtime Setup completion；它仍不阻止能够使用 direct source evidence 的普通 plan\u002Fwork\u002Freview\u002Fdebug workflow。\n\n### Stage 2: Apply Authorized Setup Actions\n\nApply only actions authorized by the selected mode:\n\n- project-local config actions: refresh example config, create local override, ensure ignore coverage, and optionally delete obsolete legacy markdown only after explicit approval;\n- host config action：只能通过共置 Node 入口与显式 host authority 写入 MCP\u002Fruntime config；\n- helper\u002Fprovider actions: standard bare workflow 安装或验证 required baseline，并默认运行 CodeGraph\u002FGraphify bounded first-generation\u002Fquery verification；`--only codegraph`、`--only graphify` 或 `--only codegraph,graphify` 仅收窄为高级子集修复。\n\nProject-local config actions never install providers or edit host config. Host\u002Fprovider actions never migrate local config keys. Legacy project config is a manual-review signal unless the user chooses a documented cleanup action.\n\n### Stage 3: Summarize Facts And Next Action\n\nRender a grouped final status that separates:\n\n- dependency\u002Fruntime readiness;\n- generated runtime freshness;\n- project-local config status;\n- project setup facts;\n- host configured dependencies;\n- helper\u002Fprovider readiness and install safety;\n- next actions.\n\nThe summary must make skipped, declined, optional, degraded, and action-required rows visible. Do not collapse these boundaries into a single \"setup complete\" statement.\n\n## Setup Posture And Project Conventions\n\nRuntime Setup follows an `Explore -> Present -> Decide -> Write` posture, with **fast-path execution for bare invocations**:\n\n1. **Explore** host, target repo, generated runtime manifest, existing setup facts, `.spec-first\u002Fconfig.local.yaml`, verification profile visibility, provider artifacts, and project instructions.\n2. **Present & Decide**:\n   - **Bare invocation** (default `spec-runtime-setup`): After exploration, present a consolidated single summary of all pending operations (missing dependencies, config changes, provider installations) and request **one confirmation** before batch execution. The user approves the entire setup plan with a single response.\n   - **Explicit modes**: `--check` and `--plan` are read-only. `--verify-only` is a facts-only mutation mode: it may write setup-owned facts, scenario fingerprints, and ledgers only, without requesting confirmation for those bounded writes.\n   - **Subset repairs** (`--only ...`, `--refresh`): Execute the narrowed scope immediately after exploration; subset authorization is implicit in the flag itself.\n3. **Decide** only where the runtime setup workflow has authority: install\u002Fverify helper tools, configure host MCP\u002Fruntime wiring, refresh setup-owned facts, or choose a documented degraded path. Team workflow conventions and semantic project decisions remain LLM\u002Fowner judgment in downstream workflows.\n4. **Write** only setup-owned facts, supported local config examples, host runtime config through documented targets, and generated runtime refreshes through `spec-first init`. Do not write team-shared tracker policy, label vocabulary, external PR request-surface policy, issue acceptance decisions, or durable rejected-scope decisions from setup.\n\n`.spec-first\u002Fconfig.local.yaml` is a local-only override file, not team-shared source of truth. Current active local config consumers are:\n\n- `verification_profile_path`, read by the verification profile loader as a local execution preference;\n- `feedback_sources` and `sweep_*`, read and written by `spec-sweep`;\n- `pulse_*`, read and written by `spec-product-pulse`;\n- `spec_promote_spiral_optout`, read and written by `spec-promote`;\n- `plan_skip_scoping_confirm`, exposed for downstream planning workflows that support persisted scoping-confirmation preference;\n- `plan_output`, `brainstorm_output` 和 `ideate_output`，分别由 `spec-plan`、`spec-brainstorm` 和 `spec-ideate` 读取。\n\n`plan_output`、`brainstorm_output` 和 `ideate_output` 都是 active local rendering preferences。对应 consumer 只读取未注释且有效的 `md` \u002F `html` 值；缺失、无效或仍被注释的值分别回退到 `spec-plan=md`、`spec-brainstorm=md`、`spec-ideate=html`。Pipeline override 仍由各 consumer 自己决定。Runtime Setup 只暴露并保护这些 key，不调用对应 workflow，也不把本地 rendering preference 提升为 runtime authority。没有真实 reader 的 CE\u002Flocal delegation key 不进入本地 config surface。Setup must not auto-delegate, skip scoping confirmation, or change host model\u002Fruntime behavior merely because a key exists. Missing local config is not a blocker; defaults remain advisory and must not be reported as repo truth.\n\nIf setup later reports project convention facts, they must be deterministic existence facts only, such as whether `CONTEXT.md`, `CONTEXT-MAP.md`, `docs\u002Fadr\u002F`, or a project guidance index exists. Setup must not judge whether terminology is correct, an ADR applies, a proposed issue\u002FPR should be accepted or rejected, an out-of-scope concept matches, or implementation satisfies a request.\n\n## Host Authority And Write Safety\n\n当前唯一公开入口是 `spec-runtime-setup`（Claude\u002FQoder 命令拼写 `runtime-setup`）；不提供 `spec-mcp-setup` \u002F `mcp-setup` 兼容别名。调用它的 host runtime surface 是权威 host evidence。Generated host-specific runtime surface 必须在调用支持 mutation 的 Node mode 前，通过 per-call environment 固定 `MCP_SETUP_HOST=\u003Chost>`。缺少显式 canonical `MCP_SETUP_HOST=claude|codex|cursor|kiro|opencode|qoder|zcode` 时，`setup.cjs` 必须 fail closed；不得根据 `PATH`、generated runtime 目录、旧 `.spec-first\u002Fconfig\u002F*` facts 或其他平台的 host config 文件推断 mutation target。只读诊断可以展示 advisory host candidate，但这些 candidate 不具备 write authority。\n\n在写入任何 host config 或刷新 setup-owned facts 前，workflow 必须让 `setup.cjs` 从显式 entrypoint host pin 解析 host authority 与 effective registry target。旧 setup facts 只能作为 drift comparison evidence：若其与当前 entrypoint host 不一致，应报告 host-marker drift，并为当前 host 刷新 setup-owned facts，不得把旧 host 当作当前 host。绝不能仅依据 prose 手动选择 `.kiro\u002Fsettings\u002Fmcp.json`、`.qoder\u002Fsettings.local.json`、`.cursor\u002Fmcp.json`、Codex TOML 或 Claude managed\u002Fuser config。\n\n不得使用 Write、Update、Edit 等 host file-edit 工具修改 `.spec-first\u002Fconfig\u002Ftool-facts.json`、`.spec-first\u002Fconfig\u002Fruntime-capabilities.json` 或 host MCP config 文件。只有 authority、target、containment、conflict 与 verification gate 全部通过后，`setup.cjs` 及其确定性的 host-config\u002Ffacts module 才能执行这些写入。\n\n## Workflow Modes\n\n- `--check`: inspect current dependency\u002Fruntime status only; do not write setup facts, host config, or install tools.\n- `--verify-only` \u002F `--refresh-facts`: verify readiness and refresh setup-owned facts. `--verify-only` is a facts-only mutation mode and may write setup-owned facts, scenario fingerprints, and ledgers only; it must not install providers, edit host config, bootstrap project config, or refresh generated runtime.\n- `--plan`: render install\u002Fconfig operations and safety results; do not write setup facts, host config, or install tools.\n- `--project-config`：仅执行 project-local config bootstrap。按请求刷新 example，仅在显式 action 后创建 local override，按请求确保 `.spec-first\u002F*.local.yaml` ignore coverage，并报告 legacy project config signal 而不迁移它们。该 mode 不安装 MCP server、不配置 host runtime，也不执行 helper\u002FProvider first generation。\n- Bare invocation (`spec-runtime-setup` in the current host): default full setup workflow. Resolve target，运行默认 required-provider plan；无 blocker 时执行等价的 `--only codegraph,graphify` apply、验证 baseline\u002FProvider\u002Fruntime\u002Fproject status，并写 setup facts。Bare workflow invocation 本身已授权自动修复 selected target 中 registry 管理的 `host-config-conflict`，不需要二次确认；它不授权绕过 higher-precedence、unsafe path、unreadable config、symlink\u002Fpath escape 或 literal secret gate。\n- `--only \u003Cids>`: advanced headless\u002Fsubset repair path. `--only codegraph`, `--only graphify`, or `--only codegraph,graphify` narrows provider execution and does not require a confirmation prompt；子集结果必须标记为 partial scope，不能声称完整 setup ready。\n- `--repair-host-config`：显式授权 setup 仅替换 registry 管理且已确认冲突的 MCP 条目；保留同一 host config 中的其他用户字段和 server，并执行事务回滚与 post-write verification。Bare full setup 由 workflow 自动携带该 flag 处理 selected-target managed drift；显式 subset\u002Frepair 调用则必须由用户提供。可单独用于 baseline host config repair，也可与 `--only ...` 组合，在修复后继续 Provider install-init。没有该 flag 时，显式 `--plan` 必须在 package\u002Fprovider mutation 前报告 `host-config-conflict` 并阻断；高优先级 target 冲突、不可读配置、symlink\u002Fpath escape 和 literal secret 不能通过该 flag 绕过。\n- `--refresh`: Graphify 显式刷新路径。已有 `graphify-out\u002F` 时，与 `--only graphify` 一起使用；setup 调用官方 `graphify update \u003Cworkspace>` 更新现有 code graph，并在更新后重新执行完整性与裸 query probe，再原子写入与当前 `graph.json` SHA-256 绑定的 scope provenance receipt。它不创建 spec-first 顶层 staging\u002Fbackup；若只有旧版适配目录 `.graphify\u002F`，普通 setup 会先将其原子迁移为 `graphify-out\u002F`，两个 artifact root 同时存在则 fail closed。它是 `manual-only` steady state 的按需更新方式，不是修复项目外 `core.hooksPath` 的动作，也不代表完整 semantic extraction。普通 setup 或 `--verify-only` 返回 core-ready `readiness_status=unknown` 时，不得仅因 unknown 自动追加或执行 `--refresh`；unknown 表示缺少当轮 currentness evidence，不表示 query probe 失败或 required setup 未完成。\n- `--requirement-workspace \u003Ctarget-relative-path>`: optional Graphify input-scope override. Omit it for normal project-workspace setup; default input scope is the resolved execution root. This flag narrows Graphify input only; it does not change the CodeGraph root, setup facts owner, or the Provider-native `graphify-out\u002F` artifact owner.\n- `--repo \u003Cpath>` must resolve to the exact Git repository root. A nested path is invalid and fails closed instead of being promoted to an ancestor root; use `--folder` when the nested directory is the intended logical project.\n- `--folder \u003Cpath>` selects the exact logical project directory and does not require Git. CodeGraph writes `.codegraph\u002F`, Graphify writes `graphify-out\u002F`, and setup writes `.spec-first\u002Fconfig\u002F` under that folder. If it is nested inside a Git repository, generated spec-first runtime readiness is checked at the enclosing Git root so setup does not request a duplicate child `.agents\u002Fskills`; a standalone non-Git folder uses itself as the runtime projection root. Missing\u002Fstale runtime returns a structured interactive action rooted at that projection plus a headless variant containing `-y -u \u003Cname> --lang \u003Czh|en>`; the folder is never passed to Git-only `init --repo`. Git health remains an additional fact and never rewrites the folder target. Graphify commit hooks and Git HEAD baselines are skipped as `not-applicable` for `target_kind=non-git-folder`, including a nested folder whose parent is a Git repo, while first generation, query, explicit refresh, and CodeGraph indexing remain supported.\n- `--user-scope`：Kiro\u002FQoder\u002FCursor\u002FOpenCode 写入 user-level MCP config 的 opt-in。缺少该 flag 时，即使由 generated host skill\u002Fcommand 间接调用，setup 也只为 Kiro 写 workspace `.kiro\u002Fsettings\u002Fmcp.json`、为 Qoder 写 local `.qoder\u002Fsettings.local.json`、为 Cursor 写 project `.cursor\u002Fmcp.json`，或为 OpenCode 写 project `opencode.json`。OpenCode user scope 解析 `${XDG_CONFIG_HOME}\u002Fopencode\u002Fopencode.json`；project\u002Fuser scope 任一存在更高优先级 JSONC sibling 时都以 `host-config-jsonc-precedence-blocked` 阻断 JSON mutation。\n\nOpenCode host config mutation 把 MCP entry 与 `opencode-governed-assets-v1` permission policy 视为同一 bounded transaction。Permission policy 只允许当前 projected runtime state 中的精确 governed skill names，禁止 wildcard\u002Fglobal allow，并让 `bash`、`edit`、`task`、`webfetch`、`websearch` 等危险工具保持 `ask`；遇到 conflicting user rule、unsafe last-match ordering 或 post-write verification failure 时 fail closed \u002F rollback。Uninstall 只删除仍与 expected value 精确匹配的 managed entries，不删除整份 `opencode.json`，也不覆盖 unrelated user fields。\n\nGraphify setup 使用受控 Provider route；标准 bare workflow 默认选择 Graphify，`--only graphify` 是高级子集修复入口。当前 pin 是 PyPI `graphifyy@0.9.29`，要求 Python `>=3.10`。Setup 只使用已安装的 uv（优先）或 pipx，将 release-reviewed direct wheel 安装到隔离 tool environment；uv 禁止 managed Python download，缺少兼容 Python 或 tool manager 时返回 action-required，不自动 bootstrap，也不回退 plain pip。Package readiness 同时验证 distribution identity、version、CLI version、absolute launcher 与 interpreter。显式 Graphify mutation setup 只有在 Python package\u002Fartifact\u002Fquery\u002Fhost 都 verified，且 Git 项目中的 project-local hook 也 verified（非 Git 项目不适用）时，才默认卸载已确认的全局 `@sentropic\u002Fgraphify`，并只删除仍保持原 target 且解析到该 npm package 的旧 symlink。External\u002Funsafe hook target 下不执行 incumbent cleanup；未知命令、普通文件和其他 symlink 一律不改。\n\nGraphify Provider只接受PyPI `graphifyy` dependency。失败恢复使用固定wheel重装、contained artifact backup恢复与Python readiness复验。\n\n缺少 `--requirement-workspace` 时使用已解析 project workspace，并直接采用 Provider 原生默认目录 `graphify-out\u002F` 作为唯一 current artifact，不注入 `GRAPHIFY_OUT`。首次生成固定运行 `graphify extract . --code-only`，不探测 API key、不触发 semantic backend；支持代码文件非空但生成零节点时 fail closed。已有 `graphify-out\u002F` 且未提供 `--refresh` 时只验证 package、host integration、裸 query，以及当前项目授权域内可用时的 optional hook，不修改 current graph。`graphify-out` 已存在但不是非 symlink 真实目录时，以 `graphify-artifact-root-unsafe` 在任何 host\u002Fruntime mutation 前阻断；仅有旧版 `.graphify\u002F` 时原子迁移目录而不重建图；`.graphify\u002F` 与 `graphify-out\u002F` 同时存在时以 `graphify-artifact-root-conflict` 阻断，避免双 source-of-truth。显式 `--refresh` 使用官方 `graphify update \u003Cworkspace>` 在现有图上更新代码索引，复用 Provider 自带的 repo lock、临时 graph、shrink guard 与未变节点保留能力；spec-first 不再为日常刷新创建顶层 `.graphify.staging-*`、`.graphify.backup-*` 或 migration journal。旧版本遗留 journal 仅保留兼容恢复，不是新 refresh 的回滚机制。Apply\u002Frefresh 当轮有生成与 query 证据时可为 `fresh`；只读 verify 没有当轮 currentness 证据时为 `unknown`。\n\nClaude、Codex、Cursor、Kiro 使用 Python Provider 的真实 project install surface；setup 只在 recognized Provider-owned skill\u002Freference\u002Frule\u002Fsteering 与 `## graphify` section 内规范化 `graphify-out\u002F`，并将 Claude\u002FCodex host hook command绑定 verified launcher。Qoder 不调用不存在的 `--platform qoder`，由 spec-first-owned Qoder instruction提供 direct CLI\u002Ffallback adapter。Graphify Git hook 是 project-local optional auto-refresh：setup 先用 `git rev-parse --git-path hooks` 解析有效 hooks root，只有 lexical containment 与 no-follow symlink containment 均证明目标位于当前项目内时，才以进程级 `core.hooksPath` pin 运行 hook install\u002Funinstall\u002Fstatus，并在命令后重新解析目标。共享 worktree\u002Fsubmodule metadata、resolve failure 或 symlink escape 下，不运行 hook 命令、不读取外部 hook 内容、不修改 local\u002Fglobal `core.hooksPath`、不复制或串联全局 hooks；返回 `blocked + manual-only`，但不阻断已经通过的 Graphify 核心 readiness。有效 hooks root 位于项目外（如全局 `core.hooksPath`）时，setup 只读 `post-commit`\u002F`post-checkout` 两个普通文件，检测 Provider marker 与会重新生成 legacy root 的 `GRAPHIFY_OUT=.graphify` override；绝不 write\u002Fexecute\u002F`hook status`，也不修改 `core.hooksPath` 或串联全局 hooks。只有 `post-commit` marker 存在且两个文件均无 legacy override 时才报告 `hook_status=verified-external` + `refresh_mode=commit-hook-external-verified`；只有 post-checkout marker、marker 缺失或文件不可读时返回 `blocked + manual-only`，legacy override 则使用 `graphify-external-hook-legacy-artifact-override` 明确阻断。这里的 `manual-only`\u002F`verified-external` 只描述 spec-first 只读可验证的 external commit-time posture，不是 project-owned `verified`（`hook_installed`\u002F`hook_verified` 保持 false）。不得声称外部 hook 不存在、不会执行或“安装失败”；external execution 始终是 unverified。Project-local verified hook 仍要求 post-commit 与 post-checkout 各有唯一 Provider marker block、verified interpreter和允许的 `_rebuild_code`命令；spec-first 会移除旧版 `GRAPHIFY_OUT=.graphify` 注入，确保 hook 使用 Provider 原生默认目录。Marker 外用户内容保持不变，也不会被默认 smoke执行。Setup 不编辑 shell profile、不启动 watch、不安装 `graphifyy[mcp]`，也不把 Graphify candidate提升为 confirmed truth。\n\nCodeGraph setup 使用受控 MCP\u002FProvider route。被选中后，setup 安装 `setup-registry.json` 声明的 pinned CodeGraph dependency，使用 `codegraph serve --mcp` 配置 host MCP，运行 `codegraph init`，并探测 `codegraph status`。若 status 报告 `Pending Changes` 或要求 `codegraph index -f`，setup 先执行一次 bounded `codegraph sync`，再运行 `codegraph status`；仍存在 pending change 或 sync 失败时，返回带 diagnostic 的 action-required。若 post-sync status 仍要求 `codegraph index -f`，setup 执行一次 bounded full reindex 并复查 status。索引 ready 后必须运行 bounded `codegraph query __spec_first_readiness_probe__ --limit 1 --json` real query probe；只有命令真实成功才设置 `query_verified=true`，失败则报告 `codegraph-query-probe-failed` degraded readiness。Full reindex 或 query probe 失败时保留现有 `.codegraph\u002F` artifact，报告 degraded\u002Factionable readiness，不删除 index。这些一次性的 sync\u002Freindex 分支属于 install-init repair，不代表 spec-first 接管 steady-state ownership。\n\n## Default Full Setup Flow\n\nFor bare `spec-runtime-setup`, execute with **batch authorization and single confirmation**:\n\n1. Resolve the project target. Use `--repo \u003Cgit-root>` for an exact Git repository or `--folder \u003Cproject-folder>` for an exact logical directory, including a fully non-Git project. With no flag, a pure non-Git directory becomes the folder target unless bounded child repos are discovered. An invalid nested `--repo` stops before plan, host, provider, or facts work; the same path is valid through `--folder`.\n2. Run the read-only check。若 example config missing\u002Foutdated 或 local-config ignore rule missing，先运行 `--project-config --refresh-example --ensure-gitignore`；`.spec-first\u002Fconfig.local.yaml` 缺失保持 `defaults-active`，不创建空 override。\n3. Run `node \"$SKILL_DIR\u002Fscripts\u002Fsetup.cjs\" --plan --repo \u003Cresolved-git-root>` for a Git target or `node \"$SKILL_DIR\u002Fscripts\u002Fsetup.cjs\" --plan --folder \u003Cresolved-folder>` for a folder target. For the default parent-workspace batch, preview every discovered child with its own `--repo \u003Cchild>` target before the shared apply. Plan 默认选择 registry 中 `setup_required=true` 的 CodeGraph\u002FGraphify，并同时预览 baseline MCP\u002Fhelper、host config、Provider artifact、hook 与 facts writes。计划必须分别显示 absolute execution root、runtime projection root、Graphify input scope 和 absolute artifact root；input scope 变窄或 runtime 复用都不改变 artifact ownership。\n4. If the plan reports an unresolved target, higher-precedence conflict, unsafe path, unreadable config, or unsupported install path, stop with the exact blocker. If it reports a selected-target `host-config-conflict`, show config path\u002Fkey\u002Fdrift fields。Bare workflow invocation 本身已授权自动修复 selected target 中 registry 管理的 `host-config-conflict`：自动携带 `--repair-host-config` 重新 preview 并继续 apply，不再请求用户二次确认。\n5. **Present consolidated setup summary and request single confirmation**: Show all pending operations in one grouped summary (missing dependencies, config changes, provider installations). Ask exactly one yes\u002Fno confirmation for the whole batch, using the platform's blocking question tool when available (e.g. `AskUserQuestion` in Claude Code, `request_user_input` in Codex) and falling back to a plain-text yes\u002Fno prompt in chat when no blocking tool exists in the harness. Never ask a second confirmation per item. On approval, immediately proceed to step 6. On decline, exit with the diagnostic summary and no mutation.\n6. Plan 无 blocker 且用户确认后，批量执行 apply：Git 目标使用 `--repo \u003Cresolved-git-root>`，folder 目标使用 `--folder \u003Cresolved-folder>`；默认 parent-workspace batch 则从 parent 运行且不带 target flag，由 resolver 对全部 discovered child 执行。所有路径都携带已授权的 repair\u002Ftarget\u002Fworkspace flags。\n7. Apply 必须完成 ffmpeg\u002Fbaseline helper、CodeGraph init\u002Findex\u002Fquery、Graphify package\u002Fhost integration\u002Fgraph\u002Fquery、host config、project status 和 facts verification。Graphify hook 只在有效目标位于项目内时作为 optional auto-refresh enhancement 安装并验证；blocked\u002Fskipped\u002Ffailed 必须显式展示 steady-state limitation，但不得单独把 core-ready 完整 setup 改为 action-required。任一真正 required item 未 ready 时，完整 setup 返回 action-required；不得以 direct-source fallback 把 setup 本身报告为 complete。\n\n## Subset \u002F Repair Flow\n\nUse `--only codegraph`, `--only graphify`, `--only codegraph,graphify`, or Graphify `--refresh` for advanced subset repair:\n\n1. 运行带相同 selection 的 plan，再执行 apply；`--only` 自身就是该子集 mutation 的授权。\n2. Host conflict 仍需独立 `--repair-host-config` 授权；higher-precedence、unsafe path、unreadable config 和 literal secret 永远 fail closed。\n3. 子集成功只证明所选 scope ready。最终完整 setup readiness 仍以 `spec-runtime-setup --verify-only` 对全部 required items 的结果为准。\n\n## Per-Requirement Workspace Graph (Multi-Repo)\n\n从一个**非 Git 的需求文件夹**(多仓父目录,内含多个独立 clone 的子 Git 仓)运行 setup 时,先分清两条路径:\n\n1. **子仓 provider\u002FMCP setup**(各 child 的 CodeGraph\u002FGraphify\u002Fhost config):父目录无 target 参数时默认 all-repos；`--repo \u003Cchild>` 收窄到单仓，`--all-repos` 可用于显式表达同一批处理范围。\n2. **父目录双层图**(per-child CodeGraph + workspace Graphify merge):`--workspace-graph --repos a,b,...` 或 `.spec-first\u002Fworkspace.yaml` manifest。  \n   **不要**写 `--workspace-graph --all-repos`——`--all-repos` 只服务子仓 batch,不是 workspace-graph 的仓集确认。\n\n### 从子仓开始时的轻量引导\n\n这是一段静态引导，不会自动声明 workspace membership、CodeGraph 已安装，或 workspace graph 已构建：\n\n- 问题只涉及当前子仓时，如 Provider 可用，以当前子仓作为 `projectPath` 使用 CodeGraph；结果只是导航候选，重要结论仍由源码、测试、diff 或日志确认。\n- 问题跨多个子仓时，回到非 Git 的需求父工作区。仅当 workspace graph 状态和目标仓范围均已确认时才使用 Graphify；随后直接检查候选子仓。\n- 不要假设 workspace graph 存在或仍然 current，不要从该引导推断成员关系，也不要把任一 Provider 输出当作语义证明。\n\n本轮不向 child `AGENTS.md` \u002F `CLAUDE.md` 注入独立受管 marker，也不提供对应的 clean 生命周期；父目录 routing block 仍由显式 workspace graph lifecycle 管理。\n\n首次接入 requirement workspace 时先运行 `spec-first init --all-repos`（或逐仓 `spec-first init --repo \u003Cchild>`）让所选宿主的 child projection current，再运行 `spec-runtime-setup --only codegraph,graphify --workspace-graph`。Projection current 后，workspace graph 命令会为该 workspace 建立两层代码图：\n\n1. **每子仓战术图**:`codegraph init` 生成 `工程N\u002F.codegraph\u002Fcodegraph.db`;`.codegraph\u002F` 写入该子仓 `.git\u002Finfo\u002Fexclude`(经 `git rev-parse --git-path` 解析,正确处理 `.git`-as-file\u002Fworktree,并做 realpath+containment 校验)以保持子仓 `git status` 干净;CodeGraph MCP server 全局 install 一次,跨仓查询通过 `projectPath`。Build、refresh-only 与 status 均只把 contained、stable、非 symlink、非空的 canonical DB 视为 artifact ready；目录中的日志、锁文件或空 DB 不构成完成证据。\n2. **workspace 跨仓宏观图**:Graphify `extract --code-only` 每子仓子图 + `merge-graphs` 合并图,全部 out-of-tree 写到 `需求文件夹\u002Fgraphify-out\u002F`(子仓物理零侵入)。单\u002F零子仓分别产出 single-source \u002F not-applicable。所有 Graphify JSON 在 promotion\u002Fstatus 前通过 no-follow stable descriptor 做任意大小的完整流式语法校验，不以非空、首尾括号或 Provider 零退出替代 artifact 完整性。构建结果原子写入 `graphify-out\u002Fworkspace-graph-state.json`;`workspace-graph-state.v3` 保留 source snapshot、merged artifact SHA-256、repo\u002Fmerge artifact promotion cleanup pending 与可为 null 的 `refresh_hook`。异步模式的 `workspace-child-hook-contract.v2` receipt 包含 canonical managed-block SHA-256、绝对 Node\u002Fasync\u002Fsetup\u002FCodeGraph\u002FGraphify 路径、runtime host 与 bundled version。status 保留主要 build reason，并把 cleanup pending 作为独立 limitation 暴露；只有在最近构建 complete、无 cleanup pending、repo 集合与 source snapshot 未变化、两个 hook 内容\u002F执行位\u002Fruntime path\u002Fversion 均符合 receipt，且 CodeGraph\u002FGraphify artifacts、非 symlink 合并图与路由块均存在时才报告 ready。旧 v1\u002Fv2 state、v1 hook receipt 或缺少 `refresh_hook` 的 state 不自动迁移；升级后需显式重跑 workspace build，以原子替换 state 和 managed hooks。\n\nCodeGraph 1.5.0 的 MCP watcher 只绑定 server 默认项目，通过 `projectPath` 打开的其他子仓不会各自启动 watcher。Graphify 0.9.x 原生 child hook 只重建 child 默认 output，也不能更新上述 out-of-tree 子图并重收敛 merged graph。因此 workspace 模式使用 spec-first 自有 contained `post-commit` \u002F `post-checkout` managed hook：显式 build 先通过现有 Provider resolver 确认绝对 CodeGraph 与 Graphify launcher，只有两个 launcher、当前 host 与 bundled version 都完整时才固化进 hook；managed block 放在 shell shebang 后、用户正文前，避免既有 `exit` \u002F `exec` \u002F `set -e` 令刷新不可达，malformed block 在 install\u002Fclean 时均 fail closed。上下文不完整时不安装 PATH-dependent hook并降级为 explicit。Status 依据 receipt 重建 canonical block digest，检查两个 hook 的内容、POSIX 执行位、记录的 runtime files 可用性与当前 bundled version；漂移时统一将 workspace status 降为 partial、effective refresh mode 降为 explicit，并保留 per-child `workspace-child-hook-*` reason code。Git 事件 detached 触发 refresh-only setup，它必须同时携带 internal marker、两个 pinned launcher 与有效 lifecycle credential；在 lifecycle lease 内对全部 confirmed child 运行 bounded `codegraph sync \u003Crepo>`，再执行 Graphify `extract` \u002F `merge-graphs`，不得再次执行 CodeGraph global install\u002Finit、managed exclude、routing injection 或 hook installation。Refresh-only 期间保留上一份 completed state，由 async\u002Flifecycle facts 表达 in-flight，最终再原子发布新 state，避免并发 Git 事件被 active-state gate 丢弃。`graphify-out\u002Fworkspace-async-refresh.lock` 只负责 event single-flight\u002Fcoalesce\u002Frelease handoff；`.spec-first\u002Fworkspace-graph-lifecycle.lock` 独占所有后台 build、显式 build、clean 与 status writer，async setup child 只能校验 wrapper 继承的 token。显式 build\u002Fclean 抢锁失败时必须在 provider、图、routing、hook、state mutation 前返回 `workspace-graph-lifecycle-busy`；活 PID 但 start marker 无法确认时保持 busy，不按年龄抢占，successor release 会清理已失去 canonical ownership 的 quarantine residue。clean 删除 state 后，旧 hook\u002Fworker 会在 trigger 与获得 lifecycle lease 后复核 enablement 并停止。可恢复的 provider partial 允许下一次 Git 事件重试；需要 owner 确认、路由写入失败或 runtime\u002Fhook contract 漂移保持显式修复。status receipt 带 `attempt_id`，成功 build 只清除开始时观察到的 generation。与其他 provider mutation 相同，workspace build 在 selected child 的当前 host projection 缺失或过期时必须于 mutation 前阻断。hook 不可安全安装、非 Git 变化或需要即时刷新时，重新运行同一 `--workspace-graph --repos ...` 命令。不得把 watcher、hook marker、派发成功或最近一次 success receipt 表述成 workspace freshness 保证；消费侧仍以 source snapshot\u002Fstatus 为准。\n\n仓集来源是 `需求文件夹\u002F.spec-first\u002Fworkspace.yaml` manifest 与 `--repos \u003Ca,b>` 的并集；manifest 先处理，同仓重复声明时保留 manifest alias\u002Fentry，CLI 只增补其他 confirmed 仓。自动发现仅作候选，需确认后才建。自动发现只扫描需求根的直接子目录；重复 alias 或嵌套仓根会返回 `workspace-targets-ambiguous` 并阻止 build\u002Fclean，必须先由 owner 消除歧义。\n\n`workspace.yaml` 是为六宿主 projected runtime 保持零依赖的**严格 YAML 子集**，不是通用 YAML：支持顶层 `schema_version`、`repos`、`exclusions`，2 空格列表缩进、`repos` 下 4 空格的 `path`\u002F可选 `alias`、普通或单\u002F双引号字符串和行尾注释。禁止 tab、flow collection (`[]`\u002F`{}`)、anchor\u002Ftag、block scalar、多行值及未声明字段；不符合时返回 `workspace-manifest-unparseable` 或 `workspace-manifest-schema-invalid`，不得猜测或静默忽略。可用格式：\n\n```yaml\nschema_version: workspace-manifest.v1\nrepos:\n  - path: api # workspace-relative\n  - path: 'web client'\n    alias: web\nexclusions:\n  - vendor\n```\n\n相关 flag(同一 workspace-graph 域):\n\n| Flag | 作用 |\n| --- | --- |\n| `--workspace-graph` | 在 child projection current 后，一次性建双层图 + 写 state receipt + 安装 contained child async refresh hook + 注入六宿主入口路由块；hook 不可用、非 Git 变化或需即时刷新时显式重跑 |\n| `--workspace-graph-status` | 只读汇总各 child\u002Fworkspace 图状态、state\u002Fsource freshness、hook digest\u002Fruntime\u002Fversion\u002F执行位、merged artifact containment\u002FSHA-256、default `projectPath` containment(advisory)、路由块是否已注入;不调用 provider 二进制 |\n| `--workspace-graph-clean` | 幂等清理:先独占 lifecycle lease；busy 时零 mutation 返回失败。成功持锁后删子仓 `.codegraph\u002F`、只移除 spec-first managed exclude\u002Fhook 块、删需求父目录的 current `graphify-out\u002F` 与 legacy `.graphify\u002F`、剥离路由 managed block；任一 child\u002Frouting 清理失败时保留两个 workspace graph root 供重试，不强制 kill CodeGraph daemon。宿主级等价入口:`spec-first clean --workspace-graph [--repos a,b] [--dry-run]`(不碰 host runtime mirror) |\n\nMachine contract:\n\n| operation status | mutation exit code | 含义 |\n| --- | ---: | --- |\n| `complete` | 0 | 请求的 mutation 全部完成 |\n| `partial` \u002F `failed` | 1 | 至少一个确定性步骤失败;读取 `reason_code` 与 per-repo 状态 |\n| `needs-confirmation` | 2 | 自动发现仅是候选;用 JSON 中的 `pending_confirm[]` 生成 `--repos` 重试命令 |\n\n`--json` 输出完整 envelope;自动化消费者必须同时读取 `status`、`reason_code`、`pending_confirm[]`、state\u002Ffreshness 与 per-repo 字段,不能只检查文件存在或进程是否打印成功文本。显式 `--workspace-graph-status` 是只读诊断,即使对象 absent\u002Fpartial 也可 exit 0,由 envelope 表达 readiness。\n\n**边界(per-需求 隔离)**:每个需求文件夹自成一体,不复用其它需求的图,不写机器级 global graph;`projectPath` 解析限定当前 workspace 根内;discovery 与所有 Git-metadata 写入均 symlink-contained;图输出是 advisory candidate,结论回子仓源码确认。删除需求文件夹即清空其图(无机器级残留)。\n\n从当前 Git repo(非父 workspace)运行 `--workspace-graph*` 会被跳过(该能力面向非 Git 多仓父目录)。\n\n## Workflow\n\n1. Identify the current host from the generated host-specific runtime surface invoking the unified `spec-runtime-setup` entrypoint.\n2. If invoked from a non-Git parent workspace, resolve all discovered supported child repos by default; `--repo \u003Cchild>` narrows the run. Writes must stay within each resolved child target.\n3. 运行共置 Node 入口，使其加载 `setup-registry.v10`、校验 schema，并展开 effective host\u002Fplatform registry。\n4. 让 `setup.cjs` 按所选 mode 诊断或安装必需的 package-backed MCP tool；standard workflow 默认选择 registry required Provider，`--only` 只用于高级子集修复；host config 只能通过 registry target 写入，并记录结构化 execution facts。\n5. 让同一 Node 入口验证 baseline helper 与 required Provider。`agent-browser` 保持 diagnostic\u002Fmanual-command only，并通过 sibling `spec-test-browser` canonical wrapper 读取 capability facts；安装完整但 exact-origin execution blocked 时报告 degraded 而非重复安装，且不影响 baseline completion。ffmpeg、CodeGraph 与 Graphify 核心能力必须进入完整 setup completion。Provider first generation 与 project-local auto-refresh setup 只能通过静态 Provider module 与 bounded argv-array process runner 执行。若默认 project-root scope 中的 `graphify extract .` 失败，setup 可以先尝试 code-only `graphify update .`，再返回 failed readiness。若 Graphify 已安装但不在用户原始 `PATH` 中可见，报告 manual visibility action，不编辑 shell profile。Graphify hook 仅在有效 hooks root 位于项目内时允许 bounded repair；blocked\u002Ffailed hook 记录 `next_actions` 与 `manual-only` limitation，不得标记 hook refresh 已验证，也不得单独把已通过的核心 Provider readiness 改为 `degraded`。\n6. Run project-local config bootstrap where the selected mode authorizes it. Bare setup reports example\u002Flocal\u002Fgitignore\u002Flegacy status；missing local override 记为 `defaults-active`。Explicit project-config actions may refresh the example, create the local override, and ensure ignore coverage. Do not auto-delete legacy project config or migrate legacy keys.\n7. 使用 `setup.cjs --verify-only` 写入 readiness ledger、reconcile host pointer facts、写入 project setup facts，并渲染分组 status block。必须分别读取 `generated_runtime_manifest.status` 与 `baseline_ready`；`baseline_ready=true` 不能掩盖 stale generated runtime。状态为 `stale` 或 `missing` 时，按 topology 消费 setup 返回的结构化 runtime init action：当前 repo\u002Ffolder\u002Fparent 使用 action 自带的 projection `cwd`，单个 child 或 all-repos 使用 workspace verify 返回的对应 argv；交互式 action 不带 `-y`，headless action 必须显式提供 developer name 与 language。不得把 cwd\u002Fpath 拼成 shell compound command；随后重新验证。若刚运行 `spec-first update` 后状态仍 stale，应将其视为 degraded refresh evidence，并展示相同 fallback action，不得报告 runtime freshness 为 ready。\n8. Report the status exactly enough for the user to act: ready rows need no action; action-required rows name the missing dependency\u002Fconfig\u002Ftarget step; generated runtime manifest rows name the init refresh command when stale or missing.\n\n## Output Shape\n\nThe final setup output should contain:\n\n- `Execution result`: separate `Required MCP\u002Fhelper dependencies` and `Generated runtime manifest` rows; report `baseline_ready` as dependency readiness and `generated_runtime_manifest.status` as generated runtime freshness.\n- `MCP servers`: required baseline MCP tool dependency\u002Fhost\u002Fproject readiness、CodeGraph host config readiness 和 next action；`--only` subset 必须显式标注 scope。\n- `Helper tools`: helper install and readiness status.\n- `Provider tools`: provider readiness status, derived `readiness_scope` \u002F `probe_status`, and lifecycle display bits when present. Summaries must distinguish install\u002Findex readiness from server\u002Fquery verification.\n- `Host configured dependencies`: configured MCP\u002Fhooks\u002Fallowlist\u002Fsetup\u002Fverification command facts.\n- `Install safety`: helper install source, risk, review, and mirror provenance.\n- `Project local config`: example config, local override, gitignore safety rule, legacy markdown config signal, and retired legacy local config status. Human labels and machine fields should be de-branded; active setup facts must use `.spec-first` local config paths and neutral legacy field names.\n- `Project setup facts`: status for `tool-facts.json` and `runtime-capabilities.json`.\n- `Verification profile`: current verification profile visibility placeholder; full profile execution is v1.13 scope.\n- `Next steps`: either fix action-required rows, narrow to an explicit child repo when a single-repo retry is needed, continue to the user-intent workflow, or suggest `spec-rule-miner` as a separate follow-up after CodeGraph\u002FGraphify readiness is prepared. This suggestion is advisory; setup must not treat rule-miner output as setup readiness and must not call `spec-rule-miner` automatically.\n\n### Readiness Handoff\n\n- Render the first-task handoff only when the full setup outcome is ready and every required dependency plus generated runtime manifest is ready. 按用户语言输出最多 3 行非空输出，并提供可直接替换内容的任务模板：中文为 `请基于当前项目处理这个任务：\u003C描述你的需求或问题>。`；英文为 `Please handle this task based on the current project: \u003Cdescribe your requirement or problem>.`。\n- 对 action-required、degraded、failed 或其他未就绪结果，不得展示上述首次任务模板；要求用户执行报告的 next action 后重新运行 `spec-runtime-setup`。不得把 `spec-first doctor` 或额外 `--verify-only` 作为正常 ready 路径的第二道验证。\n- 既有 direct source evidence fallback 仍可供下游 workflow 在证据足够时降级执行，但它不改变本次完整 setup 的状态，也不得把完整 setup 报告为 ready。\n\n`tool-facts.json` records setup-owned tool and helper readiness:\n\n```json\n{\n  \"schema_version\": \"tool-facts.v2\",\n  \"tools\": {},\n  \"helper_tools\": {},\n  \"items\": [],\n  \"configured_dependencies\": [],\n  \"schema_capabilities\": [\n    \"items\",\n    \"configured_dependencies\",\n    \"tool-existence\",\n    \"provider-readiness-generic\"\n  ],\n  \"source\": {\n    \"repo_status\": \"git-repo\"\n  }\n}\n```\n\n`runtime-capabilities.json` should record direct evidence posture instead of provider capabilities:\n\n```json\n{\n  \"schema_version\": \"runtime-capabilities.v1\",\n  \"direct_evidence\": {\n    \"bounded_source_reads\": true,\n    \"ripgrep\": true,\n    \"ast_grep\": true,\n    \"git_diff\": true,\n    \"tests_and_logs\": true\n  }\n}\n```\n\n## Boundaries\n\nSetup does:\n\n- verify Node\u002Fnpm\u002Fnpx and required helper dependencies;\n- 按 `setup-registry.json` 配置 warm package-backed MCP server；\n- write host MCP config through managed\u002Fuser host targets;\n- replace only an authorized conflicting managed MCP entry through `--repair-host-config`; bare full setup supplies this authorization for selected-target registry-managed drift, while explicit subset\u002Frepair calls require the flag, unrelated host config is preserved, and higher-precedence or unsafe targets remain blocked;\n- write Kiro MCP config to workspace `.kiro\u002Fsettings\u002Fmcp.json` by default, and to `~\u002F.kiro\u002Fsettings\u002Fmcp.json` only after explicit user-scope opt-in;\n- write Qoder MCP config to local `.qoder\u002Fsettings.local.json` by default, and to `~\u002F.qoder\u002Fsettings.json` only after explicit user-scope opt-in;\n- write Cursor MCP config to project `.cursor\u002Fmcp.json` by default, and to `~\u002F.cursor\u002Fmcp.json` only after explicit user-scope opt-in;\n- write project-local setup facts;\n- refresh `.spec-first\u002Fconfig.local.example.yaml`, create `.spec-first\u002Fconfig.local.yaml`, and ensure `.spec-first\u002F*.local.yaml` ignore coverage only through explicit project-local config bootstrap actions;\n- report the legacy project markdown signal for manual review and the retired legacy local config status without migrating either;\n- perform explicit provider-native first generation for approved providers when the target workspace is resolved, or verify Graphify install readiness without regenerating the graph when a project-root Graphify artifact already exists and no explicit `--refresh` was requested;\n- perform bounded provider-native setup repair where deterministic and documented, such as Graphify provider-native `update` for explicit `--refresh`, one `codegraph sync` after pending\u002Ffull-rebuild status, or one `codegraph index -f` after sync cannot clear the full-rebuild advisory;\n- perform provider-native project-local auto-refresh setup only when the Git-native effective hooks root is contained by the current project, such as Graphify `graphify hook install`, followed by bounded marker-owned artifact\u002Finterpreter normalization and structural verification; otherwise report a non-mutating `blocked + manual-only` steady state;\n- classify parent workspace target ambiguity and foreign residual indicators as advisory facts.\n\nSetup does not:\n\n- start watchers or long-running daemons;\n- install the optional Graphify MCP server;\n- run provider first generation from `--check`, `--plan`, `--verify-only`, or invalid explicit workspace override paths;\n- treat provider indexes or query probes as semantic code evidence;\n- treat setup facts as semantic code evidence;\n- invoke `spec-rule-miner`, synthesize project rules, or write `docs\u002Fai\u002Fproject-rules.md`;\n- treat `.spec-first\u002Fconfig.local.yaml` as team-shared workflow policy;\n- silently copy or translate legacy project config into `.spec-first\u002Fconfig.local.yaml`;\n- decide issue\u002FPR category, state, scope, accept\u002Freject status, or implementation truth;\n- hand-edit generated runtime mirrors as source;\n- block ordinary plan\u002Fwork\u002Freview\u002Fdebug when direct source evidence is sufficient.\n\n## Verification\n\nFocused setup changes should run the narrowest relevant checks:\n\n```bash\nnode \"$SKILL_DIR\u002Fscripts\u002Fsetup.cjs\" --check\nnode \"$SKILL_DIR\u002Fscripts\u002Fsetup.cjs\" --plan\nnpm run test:runtime-setup\nnode --check \"$SKILL_DIR\u002Fscripts\u002Fsetup.cjs\"\n```\n\nFor cross-host changes, also run `npm run typecheck`, `npm run test:unit`, `npm run test:smoke`, and `spec-first init` after source validation.\n",{"name":5,"description":7,"argument-hint":54},"[bare auto setup] [--check|--verify-only|--plan|--project-config] [--only codegraph,graphify] [--workspace-graph|--workspace-graph-status|--workspace-graph-clean] [--repos \u003Ca,b>] [--json] [--repair-host-config] [--refresh] [--repo \u003Cgit-root>|--folder \u003Cproject-folder>] [--requirement-workspace \u003Ctarget-relative-path>]","master","74655dc86b1270bb52239e0f8bc9517de7a7071c","skills\u002Fspec-runtime-setup",13,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first","http:\u002F\u002Fspec-first.cn\u002F","https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai","作为一个初学者或者进阶者，这并没有什么错。当一个有能力的程序员而不是领导者，这也没有什么错。真正的错误是，当你知道应该如何去提高时仍然选择做一名初学者。","2026-11-05 13:30:55",{"source":8,"skillName":5,"commands":65,"prompt":75,"zipAvailable":76},[66,69,72],{"tool":67,"command":68},"npx","npx skills add leo-kuang-ai\u002Fspec-first --skill spec-runtime-setup",{"tool":70,"command":71},"bunx","bunx skills add leo-kuang-ai\u002Fspec-first --skill spec-runtime-setup",{"tool":73,"command":74},"pnpm","pnpm dlx skills add leo-kuang-ai\u002Fspec-first --skill spec-runtime-setup","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002FSKILL.md",true,[78,84,88,92,96,100,104,110,114,118,122,126,130,134,138,142,146,150,154,158,162,166,170,174,178,182,186,190,194,198,202,206,210,214,218,222,226,230,234,238,242,246,250,254,258,262,266,270,274,278,281,285,289,293,297,301,305,309,313,317,321,325,329,333,337,341,345,349,353,357,361],{"path":79,"resourceType":80,"resourceTypeDesc":81,"sizeBytes":82,"sourceHtmlUrl":83},"evals\u002Fcases\u002Fsemantic-question-not-setup.yaml","REFERENCE","参考文档",745,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fevals\u002Fcases\u002Fsemantic-question-not-setup.yaml",{"path":85,"resourceType":80,"resourceTypeDesc":81,"sizeBytes":86,"sourceHtmlUrl":87},"evals\u002Fcases\u002Fverify-only-readonly.yaml",763,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fevals\u002Fcases\u002Fverify-only-readonly.yaml",{"path":89,"resourceType":80,"resourceTypeDesc":81,"sizeBytes":90,"sourceHtmlUrl":91},"evals\u002Feval.yaml",368,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fevals\u002Feval.yaml",{"path":93,"resourceType":80,"resourceTypeDesc":81,"sizeBytes":94,"sourceHtmlUrl":95},"evals\u002Fexamples.json",3295,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fevals\u002Fexamples.json",{"path":97,"resourceType":80,"resourceTypeDesc":81,"sizeBytes":98,"sourceHtmlUrl":99},"evals\u002Ffixtures\u002Frepos\u002Fmini-ledger\u002Fpackage.json",96,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fevals\u002Ffixtures\u002Frepos\u002Fmini-ledger\u002Fpackage.json",{"path":101,"resourceType":80,"resourceTypeDesc":81,"sizeBytes":102,"sourceHtmlUrl":103},"evals\u002Ffixtures\u002Frepos\u002Fmini-ledger\u002FREADME.md",365,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fevals\u002Ffixtures\u002Frepos\u002Fmini-ledger\u002FREADME.md",{"path":105,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":108,"sourceHtmlUrl":109},"evals\u002Ffixtures\u002Frepos\u002Fmini-ledger\u002Fsrc\u002Fserver.js","SCRIPT","脚本",665,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fevals\u002Ffixtures\u002Frepos\u002Fmini-ledger\u002Fsrc\u002Fserver.js",{"path":111,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":112,"sourceHtmlUrl":113},"evals\u002Ffixtures\u002Fscripts\u002Fasks-a-question.sh",1232,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fevals\u002Ffixtures\u002Fscripts\u002Fasks-a-question.sh",{"path":115,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":116,"sourceHtmlUrl":117},"evals\u002Ffixtures\u002Fscripts\u002Fcheck-not-setup-scope.sh",552,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fevals\u002Ffixtures\u002Fscripts\u002Fcheck-not-setup-scope.sh",{"path":119,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":120,"sourceHtmlUrl":121},"evals\u002Ffixtures\u002Fscripts\u002Fcheck-readonly-verify.sh",696,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fevals\u002Ffixtures\u002Fscripts\u002Fcheck-readonly-verify.sh",{"path":123,"resourceType":80,"resourceTypeDesc":81,"sizeBytes":124,"sourceHtmlUrl":125},"evals\u002FREADME.md",401,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fevals\u002FREADME.md",{"path":127,"resourceType":80,"resourceTypeDesc":81,"sizeBytes":128,"sourceHtmlUrl":129},"references\u002Fconfig-template.yaml",3310,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Freferences\u002Fconfig-template.yaml",{"path":131,"resourceType":80,"resourceTypeDesc":81,"sizeBytes":132,"sourceHtmlUrl":133},"references\u002Fsupported-mcp-tools.md",3718,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Freferences\u002Fsupported-mcp-tools.md",{"path":135,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":136,"sourceHtmlUrl":137},"scripts\u002Fcheck-health",141,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Fcheck-health",{"path":139,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":140,"sourceHtmlUrl":141},"scripts\u002Fcontracts\u002Fworkspace-graph-state.schema.json",3824,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Fcontracts\u002Fworkspace-graph-state.schema.json",{"path":143,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":144,"sourceHtmlUrl":145},"scripts\u002Fcontracts\u002Fworkspace-manifest.schema.json",1820,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Fcontracts\u002Fworkspace-manifest.schema.json",{"path":147,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":148,"sourceHtmlUrl":149},"scripts\u002Flib\u002Fargs.cjs",4513,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fargs.cjs",{"path":151,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":152,"sourceHtmlUrl":153},"scripts\u002Flib\u002Fbaseline-policy.cjs",225,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fbaseline-policy.cjs",{"path":155,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":156,"sourceHtmlUrl":157},"scripts\u002Flib\u002Fconfigured-dependencies.cjs",12901,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fconfigured-dependencies.cjs",{"path":159,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":160,"sourceHtmlUrl":161},"scripts\u002Flib\u002Ffacts.cjs",29205,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Ffacts.cjs",{"path":163,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":164,"sourceHtmlUrl":165},"scripts\u002Flib\u002Fgit-path.cjs",1782,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fgit-path.cjs",{"path":167,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":168,"sourceHtmlUrl":169},"scripts\u002Flib\u002Fhost-authority.cjs",7218,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fhost-authority.cjs",{"path":171,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":172,"sourceHtmlUrl":173},"scripts\u002Flib\u002Fhost-config.cjs",53210,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fhost-config.cjs",{"path":175,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":176,"sourceHtmlUrl":177},"scripts\u002Flib\u002Fhuman-output.cjs",7840,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fhuman-output.cjs",{"path":179,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":180,"sourceHtmlUrl":181},"scripts\u002Flib\u002Finstallation-executor.cjs",20060,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Finstallation-executor.cjs",{"path":183,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":184,"sourceHtmlUrl":185},"scripts\u002Flib\u002Fmode-policy.cjs",5833,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fmode-policy.cjs",{"path":187,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":188,"sourceHtmlUrl":189},"scripts\u002Flib\u002Fopencode-permissions.cjs",16865,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fopencode-permissions.cjs",{"path":191,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":192,"sourceHtmlUrl":193},"scripts\u002Flib\u002Fpath-safety.cjs",3511,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fpath-safety.cjs",{"path":195,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":196,"sourceHtmlUrl":197},"scripts\u002Flib\u002Fpreflight.cjs",7254,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fpreflight.cjs",{"path":199,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":200,"sourceHtmlUrl":201},"scripts\u002Flib\u002Fprocess-runner.cjs",16693,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fprocess-runner.cjs",{"path":203,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":204,"sourceHtmlUrl":205},"scripts\u002Flib\u002Fprocess-utils.cjs",452,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fprocess-utils.cjs",{"path":207,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":208,"sourceHtmlUrl":209},"scripts\u002Flib\u002Fproject-config.cjs",18421,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fproject-config.cjs",{"path":211,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":212,"sourceHtmlUrl":213},"scripts\u002Flib\u002Fproject-target.cjs",12407,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fproject-target.cjs",{"path":215,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":216,"sourceHtmlUrl":217},"scripts\u002Flib\u002Fregistry.cjs",23396,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fregistry.cjs",{"path":219,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":220,"sourceHtmlUrl":221},"scripts\u002Flib\u002Fregular-file-publication.cjs",1030,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fregular-file-publication.cjs",{"path":223,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":224,"sourceHtmlUrl":225},"scripts\u002Flib\u002Fregular-file-snapshot.cjs",4161,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fregular-file-snapshot.cjs",{"path":227,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":228,"sourceHtmlUrl":229},"scripts\u002Flib\u002Frenderer.cjs",14251,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Frenderer.cjs",{"path":231,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":232,"sourceHtmlUrl":233},"scripts\u002Flib\u002Fruntime-executor.cjs",35819,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fruntime-executor.cjs",{"path":235,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":236,"sourceHtmlUrl":237},"scripts\u002Flib\u002Fruntime-remediation.cjs",1188,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fruntime-remediation.cjs",{"path":239,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":240,"sourceHtmlUrl":241},"scripts\u002Flib\u002Fscenario-fingerprint.cjs",8166,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fscenario-fingerprint.cjs",{"path":243,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":244,"sourceHtmlUrl":245},"scripts\u002Flib\u002Ftoml-section-editor.cjs",21414,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Ftoml-section-editor.cjs",{"path":247,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":248,"sourceHtmlUrl":249},"scripts\u002Flib\u002Fworkspace-async-refresh.cjs",38210,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-async-refresh.cjs",{"path":251,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":252,"sourceHtmlUrl":253},"scripts\u002Flib\u002Fworkspace-child-hook.cjs",24748,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-child-hook.cjs",{"path":255,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":256,"sourceHtmlUrl":257},"scripts\u002Flib\u002Fworkspace-exec.cjs",618,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-exec.cjs",{"path":259,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":260,"sourceHtmlUrl":261},"scripts\u002Flib\u002Fworkspace-executor.cjs",28733,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-executor.cjs",{"path":263,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":264,"sourceHtmlUrl":265},"scripts\u002Flib\u002Fworkspace-git-exclude.cjs",5753,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-git-exclude.cjs",{"path":267,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":268,"sourceHtmlUrl":269},"scripts\u002Flib\u002Fworkspace-graph-artifacts.cjs",12003,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-graph-artifacts.cjs",{"path":271,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":272,"sourceHtmlUrl":273},"scripts\u002Flib\u002Fworkspace-graph-build.cjs",22735,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-graph-build.cjs",{"path":275,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":276,"sourceHtmlUrl":277},"scripts\u002Flib\u002Fworkspace-graph-clean.cjs",13549,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-graph-clean.cjs",{"path":279,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":276,"sourceHtmlUrl":280},"scripts\u002Flib\u002Fworkspace-graph-executor.cjs","https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-graph-executor.cjs",{"path":282,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":283,"sourceHtmlUrl":284},"scripts\u002Flib\u002Fworkspace-graph-lifecycle-lease.cjs",21756,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-graph-lifecycle-lease.cjs",{"path":286,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":287,"sourceHtmlUrl":288},"scripts\u002Flib\u002Fworkspace-graph-refresh.cjs",2679,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-graph-refresh.cjs",{"path":290,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":291,"sourceHtmlUrl":292},"scripts\u002Flib\u002Fworkspace-graph-scope.cjs",3077,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-graph-scope.cjs",{"path":294,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":295,"sourceHtmlUrl":296},"scripts\u002Flib\u002Fworkspace-graph-state.cjs",9022,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-graph-state.cjs",{"path":298,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":299,"sourceHtmlUrl":300},"scripts\u002Flib\u002Fworkspace-graph-status.cjs",20927,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-graph-status.cjs",{"path":302,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":303,"sourceHtmlUrl":304},"scripts\u002Flib\u002Fworkspace-manifest.cjs",4628,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-manifest.cjs",{"path":306,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":307,"sourceHtmlUrl":308},"scripts\u002Flib\u002Fworkspace-parent-diagnostic.cjs",6488,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-parent-diagnostic.cjs",{"path":310,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":311,"sourceHtmlUrl":312},"scripts\u002Flib\u002Fworkspace-provider-runners.cjs",3155,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-provider-runners.cjs",{"path":314,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":315,"sourceHtmlUrl":316},"scripts\u002Flib\u002Fworkspace-refresh-contract.cjs",1502,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-refresh-contract.cjs",{"path":318,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":319,"sourceHtmlUrl":320},"scripts\u002Flib\u002Fworkspace-routing-inject.cjs",5207,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-routing-inject.cjs",{"path":322,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":323,"sourceHtmlUrl":324},"scripts\u002Flib\u002Fworkspace-routing-instruction.cjs",7660,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-routing-instruction.cjs",{"path":326,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":327,"sourceHtmlUrl":328},"scripts\u002Flib\u002Fworkspace-runtime-preflight.cjs",7151,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-runtime-preflight.cjs",{"path":330,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":331,"sourceHtmlUrl":332},"scripts\u002Flib\u002Fworkspace-target.cjs",9616,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworkspace-target.cjs",{"path":334,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":335,"sourceHtmlUrl":336},"scripts\u002Flib\u002Fworktree-health.cjs",4722,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Flib\u002Fworktree-health.cjs",{"path":338,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":339,"sourceHtmlUrl":340},"scripts\u002Fproviders\u002Fcodegraph.cjs",16608,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Fproviders\u002Fcodegraph.cjs",{"path":342,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":343,"sourceHtmlUrl":344},"scripts\u002Fproviders\u002Fcommon.cjs",5259,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Fproviders\u002Fcommon.cjs",{"path":346,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":347,"sourceHtmlUrl":348},"scripts\u002Fproviders\u002Fgraphify.cjs",113793,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Fproviders\u002Fgraphify.cjs",{"path":350,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":351,"sourceHtmlUrl":352},"scripts\u002Fproviders\u002Fregistry.cjs",117,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Fproviders\u002Fregistry.cjs",{"path":354,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":355,"sourceHtmlUrl":356},"scripts\u002Fsetup.cjs",33783,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fscripts\u002Fsetup.cjs",{"path":358,"resourceType":80,"resourceTypeDesc":81,"sizeBytes":359,"sourceHtmlUrl":360},"setup-registry.json",59362,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fsetup-registry.json",{"path":362,"resourceType":80,"resourceTypeDesc":81,"sizeBytes":363,"sourceHtmlUrl":364},"setup-registry.schema.json",16987,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-runtime-setup\u002Fsetup-registry.schema.json",[366,393,414,428,441,460],{"skillNo":367,"name":368,"nameZh":6,"description":369,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":370,"categories":371,"keywords":374,"publishedAt":49},"01M6CWKQCYJXDCW4MEF3FSJE26","using-spec-first","Standalone entry governor for spec-first. Use before substantial work in a spec-first repo or when the user asks what to run next; choose one public `spec-*` workflow, standalone skill, terminal command, or Direct Lane. Do not use to reroute active public workflows or bounded workers, or for lightweight facts, current-context explanations, narrow lookups, user-supplied single-document cleanup, or clearly scoped low-risk edits.","https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fusing-spec-first\u002FSKILL.md",[372,373],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},[31,375,376,377,378,379,380,381,382,383,384,385,386,387,388,389,390,391,48,392],"first","using spec first","terminal","work","active","next","do","use","context","command","repo","choose","direct","risk","lane","run","cleanup","workflow",{"skillNo":394,"name":395,"nameZh":6,"description":396,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":397,"categories":398,"keywords":400,"publishedAt":49},"01M6CWKK43ZJKQXKVJB3BWWPR1","spec-write-tasks","Public workflow entrypoint (spec-write-tasks): compile a settled local spec-plan into an optional derived task pack for spec-work, or validate an existing local task pack before execution. Use for explicit plan-splitting\u002Ftask-doc requests or high-complexity work suitability; do not use for plan authoring, implementation execution, unresolved scope, small low-risk plans, progress\u002Fapproval state, remote\u002Fgeneric task lists, or generated runtime mirror edits. Keep the plan as single source of truth; tasks are derived and optional.","https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-write-tasks\u002FSKILL.md",[399],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[31,401,402,403,404,405,381,406,407,382,408,378,41,409,388,410,411,412,392,413],"tasks","write","spec write tasks","local","task","complexity","plan authoring","generated","doc","execution","compile","validate","state",{"skillNo":415,"name":416,"nameZh":6,"description":417,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":418,"categories":419,"keywords":421,"publishedAt":49},"01M6CWKEK6CVPQW8EMCNSDPHBJ","spec-write-skill","公开 workflow：创建、修改或迁移项目拥有的 Agent Skill package，或对现有\u002F外部 package 做用户明确要求、零执行的只读验证与 readiness 报告时使用；也用于按已接受的 audit finding 修复 source skill。不要用于一次性回答、解释\u002F总结\u002F翻译、普通代码 review、第三方 Skill 纯安装或导入、跨仓批量修改，或直接修补 generated runtime mirrors。","https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-write-skill\u002FSKILL.md",[420],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[422,31,402,423,424,408,425,426,392,427],"spec write skill","write skill","audit","翻译","package","review",{"skillNo":429,"name":430,"nameZh":6,"description":431,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":432,"categories":433,"keywords":434,"publishedAt":49},"01M6CWKBDEZ7QFF1ZH3DP52SHA","spec-worktree","Internal helper for caller-owned git worktree isolation. Governed callers are spec-dogfood and spec-work; every caller must provide the forward invocation and intake contract.","https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-worktree\u002FSKILL.md",[],[31,435,436,437,43,438,439,378,440],"worktree","spec worktree","intake","Bash","dogfood","git worktree",{"skillNo":442,"name":443,"nameZh":6,"description":444,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":445,"categories":446,"keywords":448,"publishedAt":49},"01M6CWK5W4VREMNXGQQKXXSQ3N","spec-work","Execute a settled plan, validated task pack, spec path, or concrete implementation request end-to-end. Use spec-debug for open-ended bugs; stop when target repo, scope, source ownership, or required authorization is unresolved. Not for explicitly requested GitHub PR-review-feedback handling — route those to spec-resolve-pr-feedback.","https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-work\u002FSKILL.md",[447],{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},[378,449,31,450,451,452,453,454,405,455,456,39,382,385,457,458,41,459,409,427],"spec work","stop","github","to spec","debug","route","github pr","implementation","pr","feedback","open",{"skillNo":461,"name":462,"nameZh":6,"description":463,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":464,"categories":465,"keywords":471,"publishedAt":49},"01M6CWK1MFTSNV9MYD4C8WGB8B","spec-test-xcode","Build and test iOS apps on simulator using XcodeBuildMCP. Use after making iOS code changes, before creating a PR, or when verifying app behavior and checking for crashes on simulator.","https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-test-xcode\u002FSKILL.md",[466,469,470],{"categoryNo":467,"categoryName":468,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},[31,472,473,457,44,474,475,476,382,477,478],"test","spec test xcode","ios","build and test","behavior","default","build"]