SpecForge requirements 主能力包。用于把 brief、brainstorm、PRD、research、gap report、wiki 当前事实和用户确认转成可测试、可追踪、可交给 UI / technical design / tasking / verification 的 REQ / AC / NFR / 边界 / handoff 行为契约。

2026-06-222

sf-requirements

huangrx6/SpecForge

生成或更新 SpecForge 工作项的需求规格；用于活跃工作项的 ready artifact 为 requirements，或需要把产品需求文档 / 简报转成可测试行为、边界、用户故事、验收标准和影响面标记时。

2026-06-222

requirements

huangrx6/SpecForge

SpecForge 内部需求技能。用于为 work item 生成清晰、可测试的功能需求、非功能需求、范围边界、不在范围内和验收标准。

2026-06-222

code-intelligence

huangrx6/SpecForge

SpecForge 跨阶段代码智能能力包。用于任何阶段需要 Wiki-first 定位现有代码范围、选择 CodeGraph / MCP / SCIP / Repomix / rg、检查 provider freshness、归一 graph_facts、分析影响面 / affected tests 或生成 Wiki 回写候选时必读；不要只在 sf-steering 中使用。

2026-06-222

test-engineering

huangrx6/SpecForge

SpecForge 测试工程主能力包。用于 sf-verify 在验证前把 requirements、tasks、UI、technical design 和 code review 风险转成可解析 TC/PW 用例、runtime runbook、auth strategy、自动化计划和可归档 evidence。

2026-06-222

code-review

huangrx6/SpecForge

SpecForge 本地代码审查主能力包。用于 sf-code-review 执行 code_review gate 前，对照 approved spec、tasks、implementation report、changed-files、真实 git diff 和验证证据审查实现是否可批准；每次使用前读取本入口，并按风险读取 references。

2026-06-222

name	sf-steering
description	为存量项目或大型代码库建立 SpecForge 项目画像；用于新需求或 bugfix 前理解现有架构、刷新 wiki、生成后续 work item 的上下文基线。

sf-steering

运行目录

执行任何 node .specforge/... 命令或读取 .specforge/... 文件前，必须先定位宿主项目根：项目根是“包含 .specforge/ 目录的业务项目目录”，不是 .specforge/ 目录本身。若当前目录是 .specforge/ 或其任意子目录，先 cd .. 回到宿主项目根；若当前目录是 frontend/、backend/ 等子目录，也先向上回到包含 .specforge/ 的项目根，除非该子目录就是独立仓库根。禁止从 .specforge/ 内执行 node .specforge/core/scripts/...，否则会形成 .specforge/.specforge/... 的错误路径。

sf-steering 用来理解存量项目。它不写业务代码，也不创建普通需求产物；它先建立可复用的项目画像，并把稳定事实回写到 .specforge/wiki/*.md。后续 sf-intake、sf-requirements、sf-tech-design、sf-implement 才能基于这些事实做新需求、bugfix 或重构。

Steering 的产出必须能降低后续 token 成本：wiki 不只写“项目是什么”，还要写“下次从哪里开始查”。架构、模块、API、数据和运维文件都要尽量包含入口路径、关键符号 / 路由、上游下游、测试位置、运行命令和推荐检索词。

何时触发

已有项目刚接入 SpecForge，.specforge/wiki/03-architecture.md 仍是空模板。
用户说“先理解这个项目 / 扫描项目 / 项目画像 / 架构地图 / 存量项目 / 老项目”。
新需求或 bugfix 会触碰既有模块，但 wiki 中没有对应模块、API、数据或运行事实。
项目较大，不能靠一次性读取所有文件来理解。
wiki 明显过期，和当前代码实现冲突。

启动检查

node .specforge/core/scripts/doctor.mjs
node .specforge/core/scripts/codebase-index.mjs --json

Steering 需要代码智能时，先读取跨阶段能力包：

.specforge/core/skills/code-intelligence/SKILL.md

正式建立项目画像时，先生成可审查的中间证据报告：

node .specforge/core/scripts/codebase-index.mjs --write-report

有 active work item 时，默认写入：

.specforge/work/active/<work-item>/00-steering/codebase-intelligence.md

没有 active work item 时，默认写入：

.specforge/work/inbox/codebase-intelligence.md

wiki 写入或刷新完成后运行：

node .specforge/core/scripts/wiki-hydrate.mjs --from <codebase-intelligence.md> --mode steering --write
node .specforge/core/scripts/wiki-quality.mjs --mode steering

FAIL 必须修复；WARN 必须补齐当前事实、source work、owner、更新时间，或在 08-risks.md 写明缺口、影响和下一步证据来源。

读取内部阶段说明：

.specforge/skills/sf-steering/stages/steering/SKILL.md

codebase-index.mjs 会检测 code intelligence provider，并在内部运行 codebase-map.mjs 生成 bootstrap map，还会输出 normalized_context、wiki_seed 和 provider 执行 / 查询计划。codebase-map.mjs 只是 fallback scanner，不等于符号级理解。结论必须来自代码、配置、测试、CI、现有文档、provider 查询结果或用户确认。CodeGraph 安装、接入、freshness、query、affected tests 和 graph_facts[] 归一化细节统一以 .specforge/core/skills/code-intelligence/ 为准。

工作模式

按代码规模和用户目标选择模式：

模式	适用场景	处理方式
`baseline-lite`	小项目，代码量少，模块清晰	读取入口、配置、主要模块、测试和部署文件，直接更新核心 wiki
`baseline-standard`	中型项目或普通存量项目首接入	`codebase-index` + `rg`，必要时用 Repomix 打包目标模块，再更新项目概览、架构、数据、运行、风险
`baseline-deep`	大型项目、单体遗留系统、多服务仓库	必须优先使用图谱 / MCP / SCIP 类 provider；无 provider 且无目标模块时暂停
`change-focused`	用户已有明确新需求	只理解相关模块和上下游，输出“本次变更上下文基线”，再路由 `sf-intake`
`bug-focused`	用户已有异常或 bug	先理解复现路径、调用链、相关模块、日志和测试，再路由 `sf-intake` 或 `sf-discovery`

大项目策略

不要把大型仓库直接打包进上下文。采用 provider 优先策略：

扫描模式决策层：运行 codebase-index.mjs --json，先读取 scan_modes、scan_mode_decision、dependency_decision 和 bootstrap.scale。
- 如果顶层 status=scan_mode_required，立即停止后续扫描，只展示扫描模式并等待用户选择。
- 不要在未选模式时解析 bootstrap.languages、bootstrap.source_roots 或启动 Explore agents。
- 需要摘要时优先读取 JSON 的 summary 字段。
小项目：内置 bootstrap map + rg + 关键文件阅读足够。
中型项目：bootstrap map + rg；有明确模块时可用 Repomix 生成模块上下文包，不打包全仓。
大型项目：优先使用 CodeGraph、codebase-memory-mcp、CodeGraphContext 或同类图谱 / MCP / SCIP provider 查询模块、符号、调用链、依赖和入口关系。
无扫描模式选择：暂停全仓理解，先让用户选择 baseline-lite、baseline-standard、baseline-deep、change-focused 或 bug-focused。
无 provider 的大型深度扫描：用户选择 baseline-deep 后，再让用户选择自己安装 provider、Agent 辅助安装、改选 provider 或改选扫描模式。
任务上下文层：针对后续需求或 bug，只加载相关 wiki + 相关文件，不重新扫描全仓库。

成熟开源工具的做法可以作为参考：Aider 的 repo map、Repomix/Gitingest 的代码打包、CodeGraph / CodeGraphContext / codebase-memory-mcp 的图谱与 MCP 检索、RepoAgent 的文档生成。但在 SpecForge 中，外部工具输出只能作为证据来源，最终必须改写成 .specforge/wiki/*.md 的当前事实。

代码智能能力包

sf-steering 不再内置全部 CodeGraph 细节。检测到 codegraph CLI、用户明确启用 CodeGraph，或扫描模式需要 graph provider 时，按顺序读取：

.specforge/core/skills/code-intelligence/references/workflow-playbook.md
.specforge/core/skills/code-intelligence/references/provider-and-freshness.md
.specforge/core/skills/code-intelligence/references/graph-facts-contract.md
.specforge/core/skills/code-intelligence/references/wiki-and-output-contract.md

Steering 只负责项目画像和 Wiki 回写；provider 的安装 / 接入 / 初始化 / 同步 / query / affected tests 规则由 code-intelligence 能力包统一维护。

写入 wiki

先读取 codebase-intelligence.md 报告，再用 wiki-hydrate --mode steering --write 把其中的 wiki_seed 和已验证当前事实归一写入 wiki。不要把 provider 原始输出、Repomix 包或报告全文直接复制进 wiki。

根据实际发现更新这些文件；不需要的文件保持不动：

文件	写入内容
`.specforge/wiki/01-project-overview.md`	项目目标、主要用户、核心能力、边界、常见任务入口
`.specforge/wiki/03-architecture.md`	架构形态、服务/模块划分、入口、关键依赖、主要追踪路径
`.specforge/wiki/module-<name>.md`	单个模块职责、入口、依赖、关键文件、测试位置、推荐检索词
`.specforge/wiki/api-<domain>.md`	API 域、路由、请求响应、鉴权、错误约定、实现路径和调用方
`.specforge/wiki/external-interfaces.md`	对外接口总览：API、Webhook、CLI、SDK、文件导入导出、第三方调用、事件消息
`.specforge/wiki/config-env.md`	配置源、环境变量、secret、feature flag 和配置风险
`.specforge/wiki/security-auth.md`	认证、授权、权限和敏感数据边界
`.specforge/wiki/jobs-events.md`	后台任务、队列、事件、定时任务、retry / DLQ
`.specforge/wiki/04-data-model.md`	当前数据权威、当前实体 / 表、迁移初始化、历史 / 未受信 SQL、数据生命周期
`.specforge/wiki/05-operations.md`	本地启动、构建、测试、部署、CI、环境变量、验证入口
`.specforge/wiki/06-decisions.md`	已确认的架构或产品决策
`.specforge/wiki/07-glossary.md`	领域术语、缩写、系统内命名
`.specforge/wiki/08-risks.md`	技术债、风险点、未知区、需用户确认项
`.specforge/wiki/00-index.md`	当前 wiki 索引和摘要

Wiki 只保留当前事实。不要按日期、版本或 work item 复制多份同类文档。

Wiki 完整度要求

存量项目画像不能只写“这是一个前后端项目”这类概述。写入前必须按 .specforge/core/standards/wiki.md#最低完整度 自检。

重点补扫：

不完整表现	必须补扫
架构只有技术栈，没有模块边界	source roots、package / build 配置、入口、路由、服务目录、部署文件
API 只有“有接口”	route / controller / OpenAPI / SDK / test / caller，先更新 `external-interfaces.md`，必要时创建 `api-<domain>.md`
数据模型只有“使用数据库”	schema / model / migration / repository / runtime config / fixture / test，先确认当前数据权威；历史 SQL 只能进入历史 / 未受信 SQL 章节
模块只有目录名	入口、职责、上游、下游、数据读写、测试位置，必要时创建 `module-<name>.md`
运维只有启动命令	env、构建、测试、DB 初始化、任务、部署、回滚、日志监控

如果补扫后仍无法确认，不要略过：在目标 wiki 写 未确认，并在 08-risks.md 记录“缺口 / 已扫范围 / 下一步证据来源”。

关联标准

.specforge/core/standards/code-intelligence.md：provider 优先级、规模策略和大型项目停止条件。
.specforge/core/standards/wiki.md：wiki 单文件当前态、事实回写和未知项记录。
.specforge/core/standards/workflow.md：上下文加载、暂停条件和下一步路由。

输出给用户

完成后输出：

本次选择的模式。
代码库规模判断：small / medium / large。
已更新的 wiki 文件。
codebase intelligence 证据报告路径。
wiki-quality.mjs 结果和剩余缺口。
已确认的关键模块和入口。
尚未确认的业务含义或风险。
下一步建议路由：通常是 sf-intake；如果用户只是要求项目画像，则停在这里。

停止条件

codebase-index.mjs 显示 scan_mode_required，且用户尚未选择扫描模式。
dependency_decision.status=install_required，且用户尚未选择自己安装、Agent 辅助安装、改选模式或指定目标范围。
代码事实和现有 wiki / 文档冲突，无法判断哪个是当前事实。
需要业务 owner 确认术语、权限、流程或上线规则。
发现安全、数据迁移、生产配置风险，但没有足够权限或证据继续判断。

完成标准

.specforge/wiki/ 至少包含当前项目概览和架构概览。
大型项目至少有相关模块级 wiki，而不是只有笼统总结。
03-architecture.md、04-data-model.md、05-operations.md、external-interfaces.md 和必要的 api-<domain>.md / module-<name>.md 达到最低完整度；缺口进入 08-risks.md。
后续 sf-intake 能引用 wiki 判断影响面，不必重新理解全仓库。
未确认内容写入 08-risks.md 或在输出中列为待确认，不混入当前事实。
wiki-hydrate --mode steering --write 已执行，wiki_seed 已回写或记录缺口。
wiki-quality.mjs --mode steering 无 FAIL；WARN 已修复或在 08-risks.md 中记录 owner、影响和下一步证据来源。

不做

不直接实现新需求或修 bug。
不创建 PRD、requirements、technical_design 或 tasks。
不把外部工具生成的大段原文直接写入 wiki。
不因为扫描到文件就推断业务含义；无法确认就标为未知。