From spec-first
Builds and verifies local CRG graph index from repository source files for query-first evidence in code navigation, impact analysis, reviews, and lifecycle hooks.
npx claudepluginhub sunrain520/spec-firstThis skill uses the workspace's default tool permissions.
`spec-graph-bootstrap` 的目标是把当前仓库准备成 **CRG query-first** 状态:
Builds or incrementally updates the repository code knowledge graph for review. Use for initial setup, after refactors or branch switches; supports Python, TypeScript/JS, Go; SQLite storage.
Generates and queries codebase knowledge graphs for architecture-aware task decomposition, dependency discovery, and context reduction in multi-module projects with 20+ files.
Queries code graph database via Bash to find callers, callees, dependencies, serializers, and associations. Use proactively after reading files, searching code, or assessing change impacts.
Share bugs, ideas, or general feedback.
spec-graph-bootstrap 的目标是把当前仓库准备成 CRG query-first 状态:
source files
-> spec-first crg build
-> graph.db + graph-quality.json + graph-index-status.json + code-navigation.json + repo-topology.json + graph-operations.jsonl
-> locate / path / explain / impact / review-context / lifecycle hooks
-> LLM reads evidence and decides
边界必须保持清晰:
$spec-graph-bootstrap [target-repo-path]
target-repo-path 省略时使用当前工作目录。宿主 workflow 入口是 /spec:graph-bootstrap 或 $spec-graph-bootstrap;package CLI 入口是 spec-first crg <subcommand>,不是 spec-first graph-bootstrap。
如果 target 是父目录 workspace(父目录下有多个独立 git repo),先运行 workspace preflight,而不是对父目录执行 repo-local build:
spec-first crg workspace scan --root=<workspace>
spec-first crg workspace status --root=<workspace>
spec-first crg workspace context --root=<workspace> --task="<task>"
workspace 层只生成 .spec-first/workspace/workspace-index.json 和 workspace-status.json 这类轻量事实;不得创建父目录 .spec-first/graph/graph.db。workspace context 的 candidates 是 advisory input,LLM/user 选择 child repo 后,才运行 repo-local 命令:
spec-first crg workspace build --root=<workspace> --repo=<child-slug-or-path>
spec-first crg hook before-plan --repo=<child-repo> --task="<task>"
如果任务跨多个 child repos,先拆成显式的顺序 repo-local runs;Phase 1 不执行一个隐藏的 combined workspace work-run。
host-setup.json 的 readiness ledger v1:
overall_statusbaseline_readytools.<tool>.host_config_statustools.<tool>.project_statuscrg.cli_statuscrg.native_modules_statusnext_actions[]fallback-active 只表示 host config 可用但可能由 fallback scope 提供;它不等于项目 graph 已 ready。CRG probe:
spec-first crg --help
spec-first crg stats --repo=<target>
Ledger 中的 crg.* 字段是上一轮 setup 写入的 host fact,只能作为提示。当前轮是否能继续,应以本地 CRG probe 和后续 build / stats / query 命令的实际结果为准。若 ledger 报 crg.native_modules_status=missing,但本地 spec-first crg ... 命令可正常执行,只报告 ledger 可能 stale,不要要求用户先修 native modules,也不要停留在 MCP setup 环节反复确认。
判定:
stats ready 且 node count > 0:进入 Phase 2。直接执行图构建:
spec-first crg build --repo=<target>
用户显式进入 $spec-graph-bootstrap / /spec:graph-bootstrap 后,repo-local graph build 是该 workflow 的核心动作,不需要再二次确认。仅在 target 是父级 workspace 且 child repo 选择不明确、或命令将写入非目标 repo 时,才停下来让 LLM/user 选择明确的 child repo。
构建成功后必须确认 control-plane 产物:
.spec-first/graph/graph-index-status.json
.spec-first/graph/code-navigation.json
.spec-first/graph/graph-quality.json
.spec-first/graph/repo-topology.json
.spec-first/graph/graph-operations.jsonl
graph.db 是代码事实真源;graph-quality.json 是当前 active generation 的质量投影,用于暴露 parser coverage、unresolved edge rate、confidence distribution、community/flow 限制等 advisory facts;其他 JSON 文件提供状态、导航、topology 和审计线索。若 operation log 写入失败,不得阻断 graph build 主产出。
至少执行一组低成本查询,确认 query-first 面可用:
spec-first crg workflow-context --stage=plan --repo=<target>
spec-first crg locate --repo=<target> --query="<task or area>" --limit=5
spec-first crg explain --repo=<target> --node="<node-or-file-id>"
如果没有具体任务,locate query 可使用仓库入口、主要模块、测试入口等中性问题。查询结果只作为候选事实,不要把第一个候选当最终答案。
完成 bootstrap 后,把后续工作引导到 CRG lifecycle hooks:
spec-first crg hook before-plan --repo=<target> --task="<task>"
spec-first crg hook before-work --repo=<target> --plan=<plan.md>
spec-first crg hook after-work --repo=<target> --work-run=<id>
spec-first crg hook before-review --repo=<target> --since=<base>
Hook 内部会读取 stage-specific workflow context,并建议后续 locate / path / explain / review-context 查询。LLM 必须结合计划、diff、本地源码和测试结果做最终判断。
当 graph unavailable:
direct_repo_reads。当 query 输出不足:
完成本 workflow 时应向用户报告:
graph-quality.json 是否存在;若存在,报告 parser coverage、unresolved edge count/rate、top limitations;若缺失,说明 workflow 仍可继续但质量摘要不可用。