specture

Specture System

Specture 是一个规范驱动的开发系统。持久化的设计记录保存在 specs/ 目录树下的 SPEC.md 文件中。临时的 Agent 交接信息保存在规范文件旁边或其下级目录中的可选 PLAN.md 文件中。

使用 CLI 执行确定性的文件创建、查询和验证。使用此技能做出工作流决策并编辑文件。

从这里开始

• 设计或完善规范：阅读 references/design-workflow.md。
• 将现有规范拆分为父规范和子规范：阅读 references/split-workflow.md。
• 实现规范：更改代码前阅读 references/implementation-workflow.md，并将任何相关的 PLAN.md 纳入执行上下文。
• 验证规范或计划编辑：阅读 references/validation-workflow.md。
• 引导搭建或迁移规范目录树：阅读 references/migration-workflow.md。
• 创建或编辑 SPEC.md：阅读 references/spec-format.md。
• 创建或编辑 PLAN.md：阅读 references/plan-format.md。
• 配置纳入版本控制的规范文件：阅读 references/specs-gitignore-format.md。

核心规则

• 使用 specture list 查找规范；如果 CLI 能回答问题，就不要手动扫描规范目录树。
• 使用 specture list --assignee "Name" 查找分配给某个人的规范。查询多位负责人时，传入以逗号分隔的完整姓名；匹配时不区分大小写。
• 开始实现前，先阅读相关的 SPEC.md。
• 实现任何规范前，先阅读 references/implementation-workflow.md；不要将单独的 PLAN.md 视为充分的工作流指导。
• 实现期间，每完成一个经过验证的独立工作块，就先提交，再开始下一个工作块。
• 除非用户明确要求，否则不要将多个计划中的 PR 工作块合并到一个尚未提交的工作区中。
• 不要将实现进度写入 SPEC.md；使用 PLAN.md 记录执行交接信息和任务拆分。
• 只添加用户明确讨论或确认过的设计内容；不要臆造缺失的目标、要求或决策。
• 用户要求拆分现有规范时，可以在无需再次确认的情况下，将该规范中的既有内容重新分配到子规范；遵循 references/split-workflow.md。
• 拆分规范时，绝不要推断子规范的边界；先与用户讨论拟议的子规范，并在创建前获得明确确认。
• 父规范仅包含简要说明、目标和子规范链接索引；设计决策应放在子规范中。
• 未经用户明确许可，不要编辑规范中的设计决策或说明。
• 使用通俗易懂的 Markdown 标题；不要为标题编号。
• 跨规范引用必须使用指向目标 SPEC.md 的行内 Markdown 仓库根目录相对链接。
• 迁移规范或编辑 SPEC.md/PLAN.md 文件后，运行 specture validate。

CLI 快速参考

specture list
specture list -p 1.4
specture list -p 1.4 -d 1
specture list -d all
specture list --status draft,approved
specture list --assignee "Alice Example"
specture list --assignee "Alice Example,Bob Builder"
specture list -f json
specture validate
specture validate --spec 11
specture new --title "Feature name"
specture new --title "Child feature" --parent 11

• specture list -p/--parent 将输出范围限定为某个父级规范的子项。
• specture list -d/--depth 控制递归深度。默认值为 all（完整树）。使用 -d 1 仅显示直接子项，或使用 -d 0 / -d all 表示不限制深度。
• specture list --assignee 会在去除首尾空格后，以不区分大小写的方式匹配完整的受派人姓名；不会进行姓名部分匹配。如果需要包含已完成的任务分配，请将其与 --status all 配合使用。
• 仅当至少有一个显示的规范已分配给受派人时，文本输出才会显示 ASSIGNEE。JSON 输出始终包含一个 assignee 字符串，未分配时使用 ""。
• specture new --parent 会在父级规范下创建下一个子规范。它没有简写标志 -p。

需要了解 Specture 的行为或可用标志时，请先运行 specture help 或特定命令的 --help。只有在 CLI 无法回答问题时，才使用 ls specs/ 之类的原始 shell 目录列表命令。