sf-intake

name	sf-intake
description	为新请求创建或整理 SpecForge 工作项；用于用户提出新需求、bug、issue、重构、预研、低风险小改或边界不清的工作，需要分类工作流、决定是否需要产品需求文档、校准组件标记，并写出可支撑下一步的简报时。

sf-intake

运行目录

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

运行模式检测

1. 当前目录向上存在 .specforge/ 且有 active work item：Embedded 模式，按 artifact graph 写入正式 work item。
2. 存在 .specforge/ 但无 active work item：Lightweight 模式，可以创建 work item；如果用户只想先整理想法，则输出 specforge-import-ready.md 格式内容。
3. 不存在 .specforge/：Standalone 模式，不要运行 .specforge/... 命令；用对话完成 intake 分类和 brief 草稿，输出 specforge-import-ready.md 格式内容，后续可在初始化后导入。

sf-intake 是分诊入口：判断工作项类型、工作流、是否需要产品需求文档、是否需要预研、影响面标记、是否需要拆分，并识别是否需要进入 sf-brainstorm。它负责分诊，不负责写完整产品需求文档、需求规格、设计或实现代码。

必读

• references/routing.md：工作流分类、头脑风暴分流、产品需求文档决策、后续问题和组件标记。
• .specforge/skills/sf-discovery/stages/discovery/SKILL.md：discovery / research 输入输出和停止条件。
• .specforge/skills/sf-brainstorm/stages/brainstorm/SKILL.md：需要用户参与式取舍时的阶段说明。
• .specforge/core/standards/workflow.md：上下文加载、工作流分类、范围、命名和门禁边界。
• .specforge/core/standards/product.md：分析深度、产品需求文档决策、功能候选池、澄清和需求可测试性。
• .specforge/core/standards/ai-toolkit.md：工作流轻重分流、AI 工具链计划、人工确认和输出预算。
• .specforge/core/skills/code-intelligence/SKILL.md：当请求触碰现有代码但 Wiki 入口不足时，用于 change-focused 定位模块、API、数据或风险范围；不在 intake 做全仓项目画像。

启动扫描

1. 读取 .specforge/AGENTS.md。
2. 读取 .specforge/registry.yaml。
3. 先读取 .specforge/wiki/00-index.md，再读取和请求相关的 .specforge/wiki/ 长期事实；只读相关文件。
4. 运行 node .specforge/core/scripts/status.mjs，确认 active work item 数量。
5. 如果是已有代码项目或用户请求触碰既有模块，先判断 wiki 是否能给出相关模块、入口、API、数据、运行或风险线索。只有 wiki 缺基线、过期、冲突或无法覆盖本次请求时，才读取 code-intelligence 能力包，运行 node .specforge/core/scripts/codebase-index.mjs --json 做 bounded 定位，并考虑路由 sf-steering。

执行序列

A. 先分诊

1. 按 references/routing.md#分诊顺序 判断活跃工作项、拆分、类型、工作流、存量项目前置、产品需求文档、组件标记和下一步。
2. 多个 active work item 时先让用户指定，不猜。
3. 混合请求先拆分，不创建万能 work item。
4. 已完成或 archive work item 的后续问题，按 follow-up 新建，并保留 parent/relation。

A1. Workflow 协作选择

Workflow 类型由 AI 和用户共同确认，不由 AI 单方面决定：

1. 根据 references/routing.md#Workflow 分类表 推断最可能的 workflow 类型。
2. 向用户展示推荐结果和理由，格式：
   • 推荐：<workflow> — 一句话理由
   • 备选：<workflow> — 适用条件
3. 等待用户确认或纠正；用户说"你来定"时，写明授权内容和风险，再继续。
4. 用户确认后才写入 work.yaml，不提前创建。

B. 再创建或整理 work item

没有 active work item 时创建：

node .specforge/core/scripts/create-work.mjs --workflow <workflow> "Work item title"

可在创建时直接声明已知影响面：

node .specforge/core/scripts/create-work.mjs --workflow feature --has-ui true --has-api true --has-db false "Work item title"

如果是已完成 work item 的后续问题，带上关联：

node .specforge/core/scripts/create-work.mjs --workflow issue --kind issue --parent <previous-work-id> --relation follow_up "排查提交审批失败"

C. 写 intake 产物

写清：

• 00-intake/original-request.md
• 00-intake/brief.md

brief.md 必须包含：

• 背景和目标。
• AI 工具链计划：本 work item 每个阶段使用哪些 AI / 验证 / 可视化能力、产出什么证据、何处需要人工确认。
• 产品需求文档决策：是否需要产品需求文档、深度、原因和下一步。
• Brainstorm 决策：skip / light / deep、原因和阻断项。
• 分析深度、代码库探索、外部研究或跳过理由、澄清记录和分析综合。
• Wiki 上下文入口：本次读取的 wiki 文件、入口路径、相关模块、上游 / 下游和需要补证的缺口。
• 现有代码上下文：如使用 code-intelligence，记录 provider/fallback、查询范围、graph freshness、定位到的模块 / API / 数据候选，以及是否需要 sf-steering 刷新 Wiki。
• 候选功能池、推荐最小可行版本、用户已确认选择和明确延后项。
• 本次负责 / 不负责。
• 影响面矩阵：UI、frontend、backend、API、data、AI、integration、security、delivery、tests。
• 依赖、风险、澄清项。

D. 校准 flags 和路由

1. 更新 work.yaml 中的 workflow、kind、components 和 relations。
2. 不确定的组件 flag 保持 auto；明确无影响才写 false。
3. 运行 node .specforge/core/scripts/instructions.mjs，确认 flags 和 workflow 已正确写入。

判定表

条件	状态
多个 active work item，且用户未指定	停止：先请用户指定
需求边界不清，无法判断 workflow	停止：提一个关键澄清问题
产品 / 页面 / 全栈应用的最小可行版本功能组合尚未确认，且无法安全默认	停止：需先完成方向取舍
已有代码项目缺少 wiki 基线	停止：需先建立 wiki
需求触碰既有模块但 wiki 没有入口或明显过期	停止：路由 sf-steering 补齐项目画像
intake 需要靠全仓扫描才能判断范围	停止：改用 sf-steering 或让用户提供模块 / 业务域 / 报错路径
产品型工作项需要产品需求文档，但缺少核心产品决策	停止：需先澄清产品方向
standard / deep 缺少代码库探索证据或明确跳过原因	停止：补探索或写跳过理由
deep 缺少外部研究证据或明确跳过原因	停止：补研究或写跳过理由
存在生产、安全、权限、数据迁移风险但没有足够上下文	停止：澄清或路由 discovery

完成标准

• work item 已进入 .specforge/work/active/，或 Standalone / Lightweight 模式下输出了可导入内容。
• 简报足以支撑产品需求文档或需求规格。
• brief 已按规模选择输出预算，避免为低风险小改生成过重流程。
• brief 的 AI 工具链计划只列实际会使用的工具，并且能追溯到 artifact、验证或 wiki。
• 产品需求文档决策清楚：需要就写“是否需要产品需求文档：是”，不需要就写明跳过理由。
• Brainstorm 决策清楚：skip / light / deep 有理由。
• work.yaml 的 workflow 和 components 已与 brief 影响面矩阵一致。
• 完成后运行 node .specforge/core/scripts/instructions.mjs，将输出展示给用户，让用户知道当前 workflow 的下一步是什么。

不做

• 不直接实现。
• 不写完整产品需求文档、需求规格、界面设计或技术设计。
• 不手工绕过 artifact graph；是否跳过 ui_design / technical_design 由 components 和 workflow schema 共同决定。
• 不把 Agent 推荐方案写成用户已确认选择。