Spec Kit Local Extensions

面向本地增强工作流的 Spec Kit 分发版。

这个仓库的重点不是复述基础用法，而是打包一组本地扩展和预设，让规格、架构、证据、预览、治理和多 agent 实现流程连成一条可审查的链路。

---

本地定位

这个 checkout 是一个带本地增强能力的 Spec Kit 仓库。它保留核心 specify 工作流，同时默认安装一组本地扩展和一个默认预设。

本 README 只介绍仓库中实际存在的本地内容：

• extensions/ 下的本地扩展。
• presets/ 下的本地预设。
• specify init 默认会安装的增强能力。
• 需要手动安装的可选能力。
• 扩展和预设运行后会写入的主要产物。

如果你只是想知道这个仓库相比基础流程多了什么，可以先看这三件事：

• 默认扩展：discovery、inception、intake、preview、repository-governance。
• 默认预设：workflow-preset。
• 自动上下文扩展：agent-context。

快速开始

在本仓库开发或试用时，优先从仓库地址安装 CLI：

uv tool install specify-cli --from git+https://github.com/bigsmartben/spec-kit.git

初始化一个项目：

specify init my-project --integration codex
cd my-project

在已有目录里初始化：

specify init . --integration codex --force

如果当前机器没有对应 agent CLI，但你只想生成文件：

specify init my-project --integration codex --ignore-agent-tools

初始化完成后，本地默认能力会被复制到项目的 .specify/ 目录，并注册到所选 agent 的命令或 skill 目录中。

默认安装内容

specify init 当前默认安装这些本地扩展和预设：

类型	ID	来源目录	作用
自动扩展	agent-context	extensions/agent-context	维护 AGENTS、CLAUDE、Copilot 等 agent context 文件里的 Spec Kit 受管段。
默认扩展	discovery	extensions/discovery	在正式计划前做可行性、技术选型、旧代码评估、接口理解、PoC 和场景化技术决策。
默认扩展	inception	extensions/inception	在正式 SDD 前通过对话收敛可选的产品 UC 和 wireflow；旧架构入口仅提供迁移提示。
默认扩展	intake	extensions/intake	把 PRD、设计稿、Figma、最终静态 HTML 交付、测试用例等来源归一化为 SDD 可消费的证据包。
默认扩展	preview	extensions/preview	从规格和计划生成低、中、高保真 Markdown 或自包含 HTML 预览。
默认扩展	repository-governance	extensions/repository-governance	生成仓库治理 SSOT，帮助 agent 明确目录责任、读取顺序和事实证据。
默认预设	workflow-preset	presets/workflow-preset	从 Specify 引入 UI/UX 需求，从 Plan 引入 BDD、集成与 E2E 测试设计，由 Tasks 映射为执行清单，最终交给标准 Core Implement。

默认扩展列表在 src/specify_cli/commands/init.py 的 DEFAULT_BUNDLED_EXTENSIONS 中维护。默认预设列表在同文件的 DEFAULT_BUNDLED_PRESETS 中维护。

默认扩展

inception

inception 是正式规格化之前的可选产品启动阶段。它通过对话确认产品材料，并用模板生成 inception/product/ 下的产物。

产品命令：

/speckit.inception.product

主要产物：

inception/product/uc.md
inception/product/wireflow-medium.html
inception/product/wireflow-high.html

使用建议：

• 仅在需要产品启动材料时运行 /speckit.inception.product。
• uc.md 只有在用户后续明确选择时才成为 Constitution 或 Architecture 输入。
• /speckit.inception.arch 已退役，只返回迁移提示，不读取 UC、生成架构或运行 PoC。
• inception 不生成 spec.md、plan.md、tasks.md、OpenAPI、数据库 schema、生产代码或测试套件变更。

arch

arch v3 是可选迁移扩展，不再生成项目架构。旧命令名保留为无写入入口，统一指向 workflow-preset 的 /speckit.constitution。

常用命令：

/speckit.arch.generate
/speckit.arch.reverse

使用建议：

• 新工作流直接运行 /speckit.constitution。
• /speckit.arch.generate 和 /speckit.arch.reverse 只返回 ARCH_COMMAND_RETIRED。
• 团队文档完成迁移后可以卸载 arch。

discovery

discovery 放在 /speckit.plan 之前，用来处理“不确定能不能做、怎么做更稳、旧代码到底长什么样”这类问题。

常用命令：

/speckit.discovery.feasibility
/speckit.discovery.techselect
/speckit.discovery.decision
/speckit.discovery.codebase
/speckit.discovery.codebase-api-imp
/speckit.discovery.poc

适合场景：

• 需要做 go/no-go 可行性判断。
• 需要比较多个技术方案。
• 需要在 API、性能、迁移、UX、兼容性之间做场景化决策。
• 接手旧代码，需要先评估风险、复用资产和集成边界。
• 需要解释一个已实现 API、SDK 方法、CLI 命令、消息 topic 或内部能力的真实执行路径。
• 静态判断不够，需要一个有边界的 PoC。

典型产物会写在当前 feature 的 discovery 相关文件中，例如 feasibility、tech-selection、legacy codebase risk、PoC plan/result 或 API implementation overview。

intake

intake 负责把外部输入变成可追踪证据，而不是直接替你生成需求。它的重点是保留来源、标记不确定性、做结构化归一化，让后续 /speckit.specify、/speckit.plan 能带着证据继续工作。

常用命令：

/speckit.intake.prd
/speckit.intake.visual-design
/speckit.intake.test-cases

支持来源：

• PRD、产品说明、Markdown、PDF、导出的文档。
• 图片、线框图、设计 PDF、Figma 文件、Figma 页面或节点。
• 设计稿派生的视觉 IR、操作回放、动效锚点、视口截图和最终静态 HTML 交付证据。
• 既有测试、Gherkin、手工测试用例、QA 导出、测试管理表格。

主要产物：

specs/<feature>/intake/prd/
specs/<feature>/intake/visual-design/
specs/<feature>/intake/visual-design/visual-ir/
specs/<feature>/intake/visual-design/delivery/
specs/<feature>/intake/test-cases/

这些目录中会包含 source manifest、source files、归一化 YAML、evidence packet 和 schema 校验所需材料。

preview

preview 在实现前生成评审产物。它不改应用源码，不替代实现；它用当前 feature 的规格、计划和契约生成可以讨论的自包含 HTML wireflow。

常用命令：

/speckit.preview.wireflow <low|mid|high> [design focus]

主要产物：

specs/<feature>/preview/wireflow.html

使用建议：

• 需求还早期：用 low 看主路径和分支。
• 产品、设计和工程需要一起评审：用 mid。
• 交互、状态、权限、响应式和错误反馈要确认：用 high。

repository-governance

repository-governance 生成 agent 可读的仓库治理说明。它把目录职责、SSOT 读取顺序、工具链证据、agent 平台适配和仓库事实投影到当前 agent 的上下文文件中。

常用命令：

/speckit.repository-governance.generate

它也注册了 hook，可在 constitution、plan、tasks 之后提示生成或更新治理内容。

主要产物：

.specify/memory/repository-governance.md

以及当前集成对应的 agent context 文件中的受管治理段。

使用建议：

• 多 agent 协作时使用。
• 新人或新 agent 接手仓库时使用。
• 仓库目录结构、构建工具、SSOT 或平台适配规则变化后使用。

agent-context

agent-context 是上下文维护扩展。它读取集成元数据，并更新当前 agent 的说明文件，例如 AGENTS.md、CLAUDE.md 或 .github/copilot-instructions.md。

常用命令：

/speckit.agent-context.update

它主要维护受管 Spec Kit 段，不应覆盖用户在标记之外手写的内容。

默认预设

workflow-preset

workflow-preset 是这个本地分发版的核心增强预设。它包装规格、检查、规划和任务阶段；实现阶段始终使用当前 Spec Kit core 命令。

它会增强这些命令：

/speckit.specify
/speckit.clarify
/speckit.checklist
/speckit.constitution
/speckit.analyze
/speckit.plan
/speckit.tasks

主要增强：

• /speckit.checklist 增加 BDD、NFR、视觉保真 readiness gate。
• /speckit.constitution 增加 Change Scope Granularity 治理。
• /speckit.plan 增加 Phase 0 行为投影、BDD/UIF/data fixture intent 和可选设计产物。
• /speckit.tasks 从行为契约、接口契约、research.md、quickstart.md 映射实现、验证、集成/E2E 和最终 Code Review 清单。
• /speckit.implement 不由 preset 复制或覆盖；当前 core 命令按顺序执行 tasks.md，其中 Final Code Review 是最后的强制阶段。

典型产物：

specs/<feature>/contracts/bdd/
specs/<feature>/contracts/uif/
specs/<feature>/contracts/behavior/

社区资源

上游文档站收录了社区贡献的扩展、预设、bundle、walkthrough 和相关项目：

• Extensions — commands, hooks, and capabilities
• Presets — template and terminology overrides
• Bundles — role and team stacks composed from existing components
• Walkthroughs — end-to-end SDD scenarios
• Friends — projects that extend or build on Spec Kit

贡献扩展、预设或 bundle 时，分别参考 Extension Publishing Guide、Presets Publishing Guide 和 Community Bundles guide。

Note

社区贡献由各自作者独立创建和维护。安装或使用前请审查来源与代码。

可选本地扩展

bug

bug 提供三段式 bug 工作流：评估、修复、验证。

命令：

/speckit.bug.assess
/speckit.bug.fix
/speckit.bug.test

主要产物：

.specify/bugs/<slug>/assessment.md
.specify/bugs/<slug>/fix.md
.specify/bugs/<slug>/test.md

安装：

specify extension add bug

git

git 是内置可选扩展，不在当前默认扩展列表中。它负责 Git 初始化、feature branch、branch validation、remote 检测和可配置自动提交。

命令：

/speckit.git.initialize
/speckit.git.feature
/speckit.git.validate
/speckit.git.remote
/speckit.git.commit

配置文件：

.specify/extensions/git/git-config.yml

安装：

specify extension add git

可选本地预设

lean

lean 把核心流程压缩成更轻量的命令，适合小功能、实验、低仪式感任务。

它覆盖这些命令：

/speckit.constitution
/speckit.specify
/speckit.plan
/speckit.tasks
/speckit.implement

安装：

specify preset add lean

开发和测试用本地包

这些目录主要服务扩展/预设作者或测试，不建议作为普通项目主流程：

类型	ID	来源目录	用途
扩展模板	template	extensions/template	新扩展作者复制和改造的起始模板。
扩展测试	selftest	extensions/selftest	验证扩展发现、安装和注册生命周期。
预设模板	scaffold	presets/scaffold	新预设作者复制和改造的起始模板。
预设测试	self-test	presets/self-test	覆盖核心模板和命令，用于测试 preset 解析与组合。

Bundle 能力

Bundle 把一组扩展、预设、步骤和 workflow 打包成一个版本化的角色或团队配置。它适合把产品经理、业务分析、安全研究、开发等 persona 的完整工具栈用一次安装交付给项目。

Bundle 使用手写的 bundle.yml manifest，声明组件版本，也可以指定目标 integration。未指定 integration 的 bundle 是 agnostic，会继承项目已有 integration。

常用命令：

specify bundle search [<query>]
specify bundle info <bundle-id>
specify bundle install <bundle-id>
specify bundle list
specify bundle update <bundle-id>     # or --all
specify bundle remove <bundle-id>

Bundle 从按优先级排列的 catalog stack 解析（project > user > built-in）。catalog source 可以是 install-allowed 或 discovery-only；后者可搜索和查看，但不能安装。管理 catalog 使用 specify bundle catalog list|add|remove。

作者可本地校验并打包 bundle：

specify bundle validate --path ./my-bundle
specify bundle build --path ./my-bundle

可参考 examples/bundles/ 下的 product manager、business analyst、security researcher 和 developer 示例。

目标	使用
新增一个命令或 workflow	Extension
自定义 spec、plan 或 tasks 的格式	Preset
集成外部工具或服务	Extension
强制组织级或合规标准	Preset
发布可复用领域模板	Extension 或 Preset
一次性安装完整角色工具栈	Bundle

推荐使用路径

新项目

/speckit.inception.product   # 可选
/speckit.constitution        # greenfield；用户指定输入和更新范围
/speckit.specify
/speckit.clarify
/speckit.checklist
/speckit.discovery.feasibility
/speckit.plan
/speckit.preview.wireflow mid
/speckit.tasks
/speckit.analyze
/speckit.implement

旧仓库接入

/speckit.discovery.codebase
/speckit.constitution        # brownfield；显式授权仓库证据范围
/speckit.repository-governance.generate
/speckit.specify
/speckit.checklist
/speckit.plan
/speckit.tasks
/speckit.implement

已有 PRD、设计或测试用例

/speckit.intake.prd
/speckit.intake.visual-design
/speckit.intake.test-cases
/speckit.specify
/speckit.clarify
/speckit.plan

前端和交互功能

/speckit.intake.visual-design
/speckit.specify
/speckit.preview.wireflow low
/speckit.plan
/speckit.preview.wireflow mid
/speckit.tasks
/speckit.implement

小功能或实验

specify preset add lean

然后使用轻量核心链路：

/speckit.specify
/speckit.plan
/speckit.tasks
/speckit.implement

Bug 修复

specify extension add bug

然后：

/speckit.bug.assess
/speckit.bug.fix
/speckit.bug.test

产物地图

目录或文件	来源	含义
.specify/memory/architecture.md	workflow-preset 的 /speckit.constitution	项目级边界、概念、技术证据、规划约束和缺口。
.specify/memory/repository-governance.md	repository-governance	内部仓库治理 SSOT。
inception/product/	inception	产品 UC 和 medium/high wireflow 启动设计产物。
specs/<feature>/intake/	intake	PRD、视觉设计、测试用例的结构化证据包。
specs/<feature>/preview/	preview	单一自包含 HTML wireflow 预览。
specs/<feature>/contracts/bdd/	workflow-preset	BDD 行为契约。
specs/<feature>/contracts/uif/	workflow-preset	UI flow / interface fidelity 契约。
specs/<feature>/contracts/behavior/	workflow-preset	行为场景、fixture、assertion 等正式契约。
.specify/bugs/<slug>/	bug	单个 bug 的 assess/fix/test 报告。
.specify/extensions/git/git-config.yml	git	Git 分支和自动提交配置。

本地安装和管理

查看已安装扩展：

specify extension list

安装本地内置扩展：

specify extension add bug
specify extension add git

从本地源码目录安装扩展：

specify extension add --dev extensions/preview
specify extension add --dev extensions/intake

查看已安装预设：

specify preset list

安装本地内置预设：

specify preset add lean

从本地源码目录安装预设：

specify preset add --dev presets/workflow-preset

禁用或启用扩展：

specify extension disable preview
specify extension enable preview

移除预设：

specify preset remove lean

开发验证

本仓库是 Python 项目。常用验证命令：

uv run pytest

只验证集成相关测试：

uv run pytest tests/integrations -v

验证本地扩展或预设时，优先在临时项目中使用 --dev 安装源码目录：

specify extension add --dev extensions/preview
specify extension add --dev extensions/intake
specify preset add --dev presets/workflow-preset

维护提示

• README 中的默认扩展和默认预设必须与 src/specify_cli/commands/init.py 保持一致。
• 扩展命令清单应以各自 extension.yml 为准。
• 预设覆盖关系应以各自 preset.yml 为准。
• git 是本地内置可选扩展，不应写成默认安装。
• template、selftest、scaffold、self-test 是开发/测试用途，不应包装成普通用户主路径。

许可证

本项目使用 MIT License。详见 LICENSE。