swain-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec Management

Spec管理

This skill defines the canonical artifact types, phases, and hierarchy. The ER diagram below is the relationship summary; detailed definitions and templates live in

references/

. If the host repo has an AGENTS.md, keep its artifact sections in sync with the skill's reference data.

本技能定义了标准的工件类型、阶段和层级结构。下方的ER图是关系汇总；详细定义和模板存放在

references/

目录中。若宿主仓库包含AGENTS.md文件，需确保其工件章节与本技能的参考数据保持同步。

Artifact relationship model

文档工件关系模型

mermaid

erDiagram
    VISION ||--o{ EPIC : "parent-vision"
    VISION ||--o{ JOURNEY : "parent-vision"
    EPIC ||--o{ SPEC : "parent-epic"
    EPIC ||--o{ STORY : "parent-epic"
    JOURNEY ||--|{ PAIN_POINT : "PP-NN"
    PAIN_POINT }o--o{ EPIC : "addresses"
    PAIN_POINT }o--o{ SPEC : "addresses"
    PAIN_POINT }o--o{ STORY : "addresses"
    PERSONA }o--o{ JOURNEY : "linked-personas"
    PERSONA }o--o{ STORY : "linked-stories"
    ADR }o--o{ SPEC : "linked-adrs"
    ADR }o--o{ EPIC : "linked-epics"
    SPEC }o--o{ SPIKE : "linked-research"
    SPEC ||--o| IMPL_PLAN : "seeds"
    RUNBOOK }o--o{ EPIC : "validates"
    RUNBOOK }o--o{ SPEC : "validates"
    BUG }o--o{ SPEC : "affected-artifacts"
    BUG }o--o{ EPIC : "affected-artifacts"
    BUG ||--o| IMPL_PLAN : "fix-ref"
    SPIKE }o--o{ ADR : "linked-research"
    SPIKE }o--o{ EPIC : "linked-research"
    SPIKE }o--o{ BUG : "linked-research"
    DESIGN }o--o{ EPIC : "linked-designs"
    DESIGN }o--o{ STORY : "linked-designs"
    DESIGN }o--o{ SPEC : "linked-designs"
    DESIGN }o--o{ BUG : "linked-designs"

    EPIC {
        string parent_vision FK
        list success_criteria "required"
        list depends_on "optional"
    }
    JOURNEY {
        string parent_vision FK
        list linked_personas "optional"
    }
    SPEC {
        string parent_epic FK
        list linked_research "optional"
        list linked_adrs "optional"
        list addresses "optional"
    }
    STORY {
        string parent_epic FK
        list addresses "optional"
    }
    ADR {
        list linked_epics "optional"
        list linked_specs "optional"
    }
    PERSONA {
        list linked_journeys "optional"
        list linked_stories "optional"
    }
    RUNBOOK {
        list validates "required"
        string parent_epic "optional"
        string mode "agentic or manual"
        string trigger "required"
    }
    BUG {
        string severity "critical/high/medium/low"
        list affected_artifacts "optional"
        string discovered_in "required"
        string fix_ref "optional"
    }
    SPIKE {
        string question "required"
        string gate "required"
        list depends_on "optional"
    }
    DESIGN {
        string superseded_by "optional"
        list linked_epics "optional"
        list linked_stories "optional"
        list linked_specs "optional"
        list linked_bugs "optional"
        list depends_on "optional"
    }
    IMPL_PLAN {
        string origin_ref "SPEC-NNN"
        list spec_tags "mutable"
    }

Key: Solid lines (

||--o{

) = mandatory hierarchy. Diamond lines (

}o--o{

) = informational cross-references. SPIKE can attach to any artifact type, not just SPEC. Any artifact can declare

depends-on:

blocking dependencies on any other artifact.

mermaid

erDiagram
    VISION ||--o{ EPIC : "parent-vision"
    VISION ||--o{ JOURNEY : "parent-vision"
    EPIC ||--o{ SPEC : "parent-epic"
    EPIC ||--o{ STORY : "parent-epic"
    JOURNEY ||--|{ PAIN_POINT : "PP-NN"
    PAIN_POINT }o--o{ EPIC : "addresses"
    PAIN_POINT }o--o{ SPEC : "addresses"
    PAIN_POINT }o--o{ STORY : "addresses"
    PERSONA }o--o{ JOURNEY : "linked-personas"
    PERSONA }o--o{ STORY : "linked-stories"
    ADR }o--o{ SPEC : "linked-adrs"
    ADR }o--o{ EPIC : "linked-epics"
    SPEC }o--o{ SPIKE : "linked-research"
    SPEC ||--o| IMPL_PLAN : "seeds"
    RUNBOOK }o--o{ EPIC : "validates"
    RUNBOOK }o--o{ SPEC : "validates"
    BUG }o--o{ SPEC : "affected-artifacts"
    BUG }o--o{ EPIC : "affected-artifacts"
    BUG ||--o| IMPL_PLAN : "fix-ref"
    SPIKE }o--o{ ADR : "linked-research"
    SPIKE }o--o{ EPIC : "linked-research"
    SPIKE }o--o{ BUG : "linked-research"
    DESIGN }o--o{ EPIC : "linked-designs"
    DESIGN }o--o{ STORY : "linked-designs"
    DESIGN }o--o{ SPEC : "linked-designs"
    DESIGN }o--o{ BUG : "linked-designs"

    EPIC {
        string parent_vision FK
        list success_criteria "required"
        list depends_on "optional"
    }
    JOURNEY {
        string parent_vision FK
        list linked_personas "optional"
    }
    SPEC {
        string parent_epic FK
        list linked_research "optional"
        list linked_adrs "optional"
        list addresses "optional"
    }
    STORY {
        string parent_epic FK
        list addresses "optional"
    }
    ADR {
        list linked_epics "optional"
        list linked_specs "optional"
    }
    PERSONA {
        list linked_journeys "optional"
        list linked_stories "optional"
    }
    RUNBOOK {
        list validates "required"
        string parent_epic "optional"
        string mode "agentic or manual"
        string trigger "required"
    }
    BUG {
        string severity "critical/high/medium/low"
        list affected_artifacts "optional"
        string discovered_in "required"
        string fix_ref "optional"
    }
    SPIKE {
        string question "required"
        string gate "required"
        list depends_on "optional"
    }
    DESIGN {
        string superseded_by "optional"
        list linked_epics "optional"
        list linked_stories "optional"
        list linked_specs "optional"
        list linked_bugs "optional"
        list depends_on "optional"
    }
    IMPL_PLAN {
        string origin_ref "SPEC-NNN"
        list spec_tags "mutable"
    }

说明： 实线（

||--o{

）= 强制层级关系。菱形线（

}o--o{

）= 信息性交叉引用。SPIKE可关联任意类型的工件，而非仅SPEC。任何工件均可声明

depends-on:

字段，设置对其他工件的阻塞依赖。

Stale reference watcher

过期引用监控器

The

specwatch.sh

script monitors

docs/

for stale references. It checks two things:

Markdown link paths —
```
[text](path/to/file.md)
```
links where the target no longer exists. Suggests corrections by artifact ID lookup.
Frontmatter artifact references — all
```
depends-on
```
,
```
parent-*
```
,
```
linked-*
```
,
```
addresses
```
,
```
validates
```
,
```
affected-artifacts
```
,
```
superseded-by
```
, and
```
fix-ref
```
fields. For each artifact ID, resolves to a relative file path and checks both existence and semantic coherence (target in Abandoned/Rejected state, phase mismatches where the source is significantly more advanced than the target).

Script location:

scripts/specwatch.sh

(relative to this skill)

Subcommands:

Command	What it does
`scan`	Run a full stale-reference scan (no watcher needed)
`watch`	Start background filesystem watcher (requires `fswatch` )
`stop`	Stop a running watcher
`status`	Show watcher status and log summary
`touch`	Refresh the sentinel keepalive timer

Log format: Findings are written to

.agents/specwatch.log

in a structured format. This file is a runtime artifact — add

specwatch.log

to your

.gitignore

if it isn't already.

STALE <source-file>:<line>
  broken: <relative-path-as-written>
  found: <suggested-new-path>
  artifact: <TYPE-NNN>

STALE_REF <source-file>:<line> (frontmatter)
  field: <frontmatter-field-name>
  target: <TYPE-NNN>
  resolved: NONE
  issue: unresolvable artifact ID

WARN <source-file>:<line> (frontmatter)
  field: <frontmatter-field-name>
  target: <TYPE-NNN>
  resolved: <relative-path-to-target>
  issue: <target is Abandoned | source is X but target is still Y>

specwatch.sh

脚本监控

docs/

目录下的过期引用，主要检查两项内容：

Markdown链接路径 — 检查
```
[text](path/to/file.md)
```
格式的链接是否指向已不存在的文件，并通过工件ID查找提供修正建议。
前置元数据工件引用 — 检查所有
```
depends-on
```
、
```
parent-*
```
、
```
linked-*
```
、
```
addresses
```
、
```
validates
```
、
```
affected-artifacts
```
、
```
superseded-by
```
和
```
fix-ref
```
字段。对每个工件ID，解析为相对文件路径并检查文件是否存在，以及语义一致性（如目标工件处于已废弃/已拒绝状态、源工件阶段远超前于目标工件等）。

脚本位置： 相对于本技能的

scripts/specwatch.sh

子命令：

命令	功能
`scan`	执行完整的过期引用扫描（无需监控器）
`watch`	启动后台文件系统监控器（需要 `fswatch` 依赖）
`stop`	停止运行中的监控器
`status`	显示监控器状态和日志摘要
`touch`	刷新哨兵保活计时器

日志格式： 检测结果会以结构化格式写入

.agents/specwatch.log

。该文件为运行时工件——若尚未添加至

.gitignore

，请将

specwatch.log

加入其中。

STALE <source-file>:<line>
  broken: <relative-path-as-written>
  found: <suggested-new-path>
  artifact: <TYPE-NNN>

STALE_REF <source-file>:<line> (frontmatter)
  field: <frontmatter-field-name>
  target: <TYPE-NNN>
  resolved: NONE
  issue: unresolvable artifact ID

WARN <source-file>:<line> (frontmatter)
  field: <frontmatter-field-name>
  target: <TYPE-NNN>
  resolved: <relative-path-to-target>
  issue: <target is Abandoned | source is X but target is still Y>

Post-operation scan

操作后扫描

After every artifact operation (create, edit, transition, audit), run

scripts/specwatch.sh scan

to catch any stale references introduced by the changes. If

.agents/specwatch.log

reports stale references, surface them as warnings and fix them before committing. The scan has no external dependencies — it uses only Python 3 and the filesystem.

The background

watch

mode (requires

fswatch

) is available for long-running sessions but is not part of the default workflow.

每次工件操作（创建、编辑、阶段流转、审计）完成后，需运行

scripts/specwatch.sh scan

以检测操作引入的过期引用。若

.agents/specwatch.log

报告存在过期引用，需将其作为警告提示，并在提交前修复。该扫描无外部依赖——仅需Python 3和文件系统即可运行。

后台

watch

模式（需要

fswatch

）适用于长会话场景，但不属于默认工作流。

Dependency graph

依赖图谱

The

specgraph.sh

script builds and queries the artifact dependency graph from frontmatter. It caches a JSON graph in

/tmp/

and auto-rebuilds when any

docs/*.md

file changes.

Script location:

scripts/specgraph.sh

(relative to this skill)

Subcommands:

Command	What it does
`overview`	Default. Hierarchy tree with status indicators + execution tracking
`build`	Force-rebuild graph from frontmatter
`blocks <ID>`	What does this artifact depend on? (direct dependencies)
`blocked-by <ID>`	What depends on this artifact? (inverse lookup)
`tree <ID>`	Transitive dependency tree (all ancestors)
`ready`	Active/Planned artifacts with all deps resolved
`next`	What to work on next (ready items + what they unblock, blocked items + what they need)
`mermaid`	Mermaid diagram to stdout
`status`	Summary table by type and phase

Run

blocks <ID>

before phase transitions to verify dependencies are resolved. Run

ready

to find unblocked work. Run

tree <ID>

for transitive dependency chains.

specgraph.sh

脚本通过前置元数据构建并查询工件依赖图谱，将JSON格式的图谱缓存至

/tmp/

目录，当任意

docs/*.md

文件变更时会自动重建图谱。

脚本位置： 相对于本技能的

scripts/specgraph.sh

子命令：

命令	功能
`overview`	默认命令。带状态标识的层级树 + 执行追踪信息
`build`	强制从前置元数据重建图谱
`blocks <ID>`	查询指定工件依赖的对象（直接依赖）
`blocked-by <ID>`	查询依赖指定工件的对象（反向查找）
`tree <ID>`	查询传递依赖树（所有祖先节点）
`ready`	查询所有依赖已解决的活跃/规划中工件
`next`	查询下一步工作内容（可开展项及其解锁的任务、阻塞项及其所需依赖）
`mermaid`	向标准输出输出Mermaid图
`status`	按工件类型和阶段生成汇总表格

在阶段流转前运行

blocks <ID>

以验证依赖是否已解决。运行

ready

以查找无阻塞的工作项。运行

tree <ID>

以查看完整的传递依赖链。

Lifecycle table format

生命周期表格格式

Every artifact embeds a lifecycle table tracking phase transitions:

markdown

undefined

每个工件都嵌入了一个生命周期表格，用于追踪阶段流转：

markdown

undefined

Lifecycle

生命周期

Phase	Date	Commit	Notes
Planned	2026-02-24	abc1234	Initial creation
Active	2026-02-25	def5678	Dependency X satisfied


Commit hashes reference the repo state at the time of the transition, not the commit that writes the hash stamp itself. Commit the transition first, then stamp the resulting hash into the lifecycle table and index in a second commit. This keeps the stamped hash reachable in git history.

阶段	日期	提交哈希	备注
Planned	2026-02-24	abc1234	初始创建
Active	2026-02-25	def5678	依赖项X已满足


提交哈希引用的是阶段流转时的仓库状态，而非写入该哈希戳的提交。需先提交流转变更，再将生成的哈希戳写入生命周期表格和索引，作为单独的二次提交。这种两次提交的方式可确保哈希戳在Git历史中可追溯。

Index maintenance

索引维护

Every doc-type directory keeps a single lifecycle index (

list-<type>.md

). Refreshing the index is the final step of every artifact operation — creation, content edits, phase transitions, and abandonment. No artifact change is complete until the index reflects it.

每个文档类型目录都需维护一个生命周期索引文件（

list-<type>.md

）。刷新索引是所有工件操作的最后一步——包括创建、内容编辑、阶段流转和废弃操作。只有当索引反映了工件变更时，该变更才算完成。

What "refresh" means

「刷新」的定义

Read (or create)
```
docs/<type>/list-<type>.md
```
.
Ensure one table per active lifecycle phase, plus a table for each end-of-life phase that has entries.
For the affected artifact, update its row: title, current phase, last-updated date, and commit hash of the change.
If the artifact moved phases, remove it from the old phase table and add it to the new one.
Sort rows within each table by artifact number.

读取（或创建）
```
docs/<type>/list-<type>.md
```
文件。
确保每个活跃生命周期阶段对应一个表格，且每个有工件的终结阶段也对应一个表格。
针对受影响的工件，更新其行信息：标题、当前阶段、最后更新日期和变更的提交哈希。
若工件发生阶段流转，需将其从旧阶段表格中移除，添加至新阶段表格。
每个表格内的行按工件编号排序。

When to refresh

刷新时机

Operation	Trigger
Create artifact	New row in the appropriate phase table
Edit artifact content or frontmatter	Update last-updated date and commit hash
Transition phase	Move row between phase tables
Abandon / end-of-life	Move row to the end-of-life table

This rule is referenced as the index refresh step in the workflows below. Do not skip it.

操作	触发条件
创建工件	在对应阶段表格中添加新行
编辑工件内容或前置元数据	更新最后更新日期和提交哈希
阶段流转	在阶段表格间移动行
废弃/终结	将行移至终结阶段表格

该规则在下文工作流中被称为索引刷新步骤，请勿跳过。

Auditing artifacts

工件审计

Audits touch every artifact, so always parallelize with sub-agents — serial auditing is too slow and misses the cross-cutting checks that only make sense when run together. Spawn four agents in a single turn:

Agent	Responsibility
Lifecycle auditor	Check every artifact in `docs/` for valid status field, lifecycle table with hash stamps, and matching row in the appropriate `list-<type>.md` index.
Cross-reference checker	Verify all `parent-` , `depends-on` , `linked-` , and `addresses` frontmatter values resolve to existing artifact files. Flag dangling references.
Naming & structure validator	Confirm directory/file names follow `(TYPE-NNN)-Title` convention, templates have required frontmatter fields, and folder-type artifacts contain a primary `.md` file.
Phase/folder alignment	Run `specwatch.sh phase-fix` to detect and move artifacts whose frontmatter `status:` doesn't match their phase subdirectory. Review the staged `git mv` renames and commit.
Dependency coherence auditor	Validate that `depends-on` edges are logically sound, not just syntactically valid. See checks below.

The dependency coherence auditor catches cases where the graph exists but is wrong. The cross-reference checker confirms targets resolve to real files; this agent checks whether those edges still make sense. Specific checks:

Dead-end dependencies —
```
depends-on
```
targets an Abandoned or Rejected artifact. The dependency can never be satisfied; flag it for removal or replacement.
Orphaned satisfied dependencies —
```
depends-on
```
targets a Complete/Implemented artifact but the dependent is still in Draft/Proposed. The blocker is resolved — is the dependent actually stalled for a different reason, or should it advance?
Phase-inversion — A dependent artifact is in a later lifecycle phase than something it supposedly depends on (e.g., an Implemented spec that
```
depends-on
```
a Draft spike). This suggests the edge was never cleaned up or was added in error.
Content-drift — Read both artifacts and assess whether the dependency relationship still holds given what each artifact actually describes. Artifacts evolve; an edge that made sense at creation time may no longer reflect reality. Flag edges where the content of the two artifacts has no apparent logical connection.
Missing implicit dependencies — Scan artifact bodies for references to other artifact IDs (e.g., "as decided in ADR-001" or "builds on SPIKE-003") that are not declared in
```
depends-on
```
or
```
linked-*
```
frontmatter. These are shadow dependencies that should be formalized or explicitly noted as informational.

For checks 4 and 5, the agent must actually read artifact content — frontmatter alone is not sufficient. Present findings as a table with: source artifact, target artifact, check type, evidence (quote or summary), and recommended action (remove edge, add edge, update frontmatter, or investigate).

Each agent reports gaps as a structured table with file path, issue type, and missing/invalid field. Merge the tables into a single audit report. Always include a 1-2 sentence summary of each artifact (not just its title) in result tables.

Enforce definitions, not current layout. The artifact definition files (in

references/

) are the source of truth for folder structure. If the repo's current layout diverges from the definitions (e.g., epics in a flat directory instead of phase subdirectories), the audit should flag misplaced files and propose

git mv

commands to bring them into compliance. Do not silently adopt a non-standard layout just because it already exists.

审计需覆盖所有工件，因此必须与子代理并行执行——串行审计速度过慢，且会遗漏仅在并行执行时才有意义的跨维度检查。需一次性生成四个代理：

代理	职责
生命周期审计员	检查 `docs/` 目录下所有工件的状态字段是否有效、是否包含带哈希戳的生命周期表格、以及在对应 `list-<type>.md` 索引中是否有匹配的行。
交叉引用检查器	验证所有 `parent-` 、 `depends-on` 、 `linked-` 和 `addresses` 前置元数据的值是否指向存在的工件文件，标记悬空引用。
命名与结构验证器	确认目录/文件名遵循 `(TYPE-NNN)-Title` 命名规范、模板包含必填前置元数据字段、文件夹类型的工件包含主 `.md` 文件。
阶段/文件夹对齐器	运行 `specwatch.sh phase-fix` 以检测并移动那些前置元数据 `status:` 与所在阶段子目录不匹配的工件，审阅暂存的 `git mv` 重命名操作并提交。
依赖一致性审计员	验证 `depends-on` 关联是否逻辑合理，而非仅语法有效。具体检查项见下文。

依赖一致性审计员负责捕获图谱存在但逻辑错误的情况。交叉引用检查器确认目标指向真实文件；而该代理检查这些关联是否仍然合理。具体检查项：

死胡同依赖 —
```
depends-on
```
指向已废弃或已拒绝的工件。该依赖永远无法满足，需标记为待移除或替换。
已满足的孤立依赖 —
```
depends-on
```
指向已完成/已实现的工件，但依赖方仍处于草稿/提议阶段。阻塞已解除——需确认依赖方是否因其他原因停滞，或是否应推进阶段。
阶段倒置 — 依赖方工件的生命周期阶段晚于其依赖的工件（例如，已实现的Spec依赖仍处于草稿阶段的Spike）。这表明关联未被清理或添加错误。
内容漂移 — 读取两个工件的内容，评估依赖关系是否仍符合工件实际描述。工件会不断演化，创建时合理的关联可能不再反映实际情况。标记那些内容无明显逻辑关联的工件关联。
缺失的隐式依赖 — 扫描工件内容中引用的其他工件ID（例如，"如ADR-001中所决定"或"基于SPIKE-003构建"），但这些引用未在
```
depends-on
```
或
```
linked-*
```
前置元数据中声明。这些是应被规范化或明确标记为信息性引用的影子依赖。

对于检查项4和5，代理必须实际读取工件内容——仅靠前置元数据是不够的。需将检测结果整理为包含以下内容的表格：源工件、目标工件、检查类型、证据（引用或摘要）、建议操作（移除关联、添加关联、更新前置元数据或调查）。

每个代理需以包含文件路径、问题类型和缺失/无效字段的结构化表格报告问题。将所有表格合并为一份审计报告。结果表格中需始终包含每个工件的1-2句摘要（而非仅标题）。

执行规则：严格遵循定义，而非当前布局。 工件定义文件（位于

references/

）是文件夹结构的唯一可信来源。若仓库当前布局与定义不符（例如，Epic存放在扁平目录而非阶段子目录中），审计需标记错位文件，并提议使用

git mv

命令使其符合规范。请勿因非标准布局已存在就默认接受。

Status overview

状态概览

When the user asks for status, progress, or "what's next?", default to showing both swain-design and swain-do layers unless they specifically ask for only one. The

overview

command is the single entry point.

当用户询问状态、进度或「下一步工作」时，默认同时展示swain-design和swain-do两层信息，除非用户明确要求仅展示其中一层。

overview

命令是唯一入口点。

specgraph.sh overview

(primary — use this by default)

specgraph.sh overview

（首选——默认使用该命令）

Renders a hierarchy tree in the terminal showing every artifact with its status, blocking dependencies, and swain-do progress:

  ✓ VISION-001: Personal Agent Patterns [Active]
  ├── → EPIC-007: Spec Management System [Active]
  │   ├── ✓ SPEC-001: Artifact Lifecycle [Implemented]
  │   ├── ✓ SPEC-002: Dependency Graph [Implemented]
  │   └── → SPEC-003: Cross-reference Validation [Draft]
  │         ↳ blocked by: SPIKE-002
  └── → EPIC-008: Execution Tracking [Proposed]

── Cross-cutting ──
  ├── → ADR-001: Graph Storage Format [Adopted]
  └── → PERSONA-001: Solo Developer [Validated]

── Execution Tracking ──
  (bd status output here)

Status indicators:

✓

= resolved (Complete/Implemented/Adopted/etc.),

→

= active/in-progress. Blocked dependencies show inline with

↳ blocked by:

. Cross-cutting artifacts (ADR, Persona, Runbook, Bug, Spike) appear in their own section. The swain-do tail calls

bd status

automatically.

Display rule: Present the

specgraph.sh overview

output verbatim — do not summarize, paraphrase, or reformat the tree. The script's output is already designed for human consumption. You may add a brief note after the output only if the user asked a specific question (e.g., "what should I work on next?").

在终端渲染层级树，展示所有工件的状态、阻塞依赖和swain-do进度：

  ✓ VISION-001: Personal Agent Patterns [Active]
  ├── → EPIC-007: Spec Management System [Active]
  │   ├── ✓ SPEC-001: Artifact Lifecycle [Implemented]
  │   ├── ✓ SPEC-002: Dependency Graph [Implemented]
  │   └── → SPEC-003: Cross-reference Validation [Draft]
  │         ↳ blocked by: SPIKE-002
  └── → EPIC-008: Execution Tracking [Proposed]

── Cross-cutting ──
  ├── → ADR-001: Graph Storage Format [Adopted]
  └── → PERSONA-001: Solo Developer [Validated]

── Execution Tracking ──
  (bd status output here)

状态标识：

✓

= 已解决（已完成/已实现/已采纳等），

→

= 活跃/进行中。阻塞依赖以内联方式显示为

↳ blocked by:

。跨维度工件（ADR、Persona、Runbook、Bug、Spike）显示在独立区域。swain-do会自动调用

bd status

。

展示规则： 直接呈现

specgraph.sh overview

的输出——请勿总结、改写或重新格式化该树状图。脚本输出已针对人类阅读进行优化。仅当用户提出特定问题（例如，「我下一步该做什么？」）时，才可在输出后添加简短说明。

其他只读命令

Command	When to use
`specgraph.sh status`	Flat summary table grouped by artifact type — useful for counts and phase distribution
`specgraph.sh next`	Ready items + what they'd unblock, blocked items + what they need — useful for deciding what to work on
`specgraph.sh mermaid`	Mermaid diagram to stdout — useful for documentation or visual export

命令	使用场景
`specgraph.sh status`	按工件类型分组的扁平汇总表格——适用于统计数量和阶段分布
`specgraph.sh next`	可开展项及其解锁的任务、阻塞项及其所需依赖——适用于决定下一步工作
`specgraph.sh mermaid`	向标准输出输出Mermaid图——适用于文档或可视化导出

Creating artifacts

创建工件

Error handling

错误处理

When an operation fails (missing parent, number collision, script error, etc.), consult references/troubleshooting.md for the recovery procedure. Do not improvise workarounds — the troubleshooting guide covers the known failure modes.

当操作失败（缺失父工件、编号冲突、脚本错误等）时，请参考references/troubleshooting.md中的恢复流程。请勿自行临时解决——故障排除指南已涵盖所有已知故障模式。

Workflow

工作流

Scan
```
docs/<type>/
```
(recursively, across all phase subdirectories) to determine the next available number for the prefix.
For VISION artifacts: Before drafting, ask the user whether this is a competitive product or a personal product. The answer determines which template sections to include and shapes the entire downstream decomposition. See the vision definition for details on each product type.
Read the artifact's definition file and template from the lookup table below.
Create the artifact in the correct phase subdirectory (usually the first phase — e.g.,
```
docs/epic/Proposed/
```
,
```
docs/spec/Draft/
```
). Create the phase directory with
```
mkdir -p
```
if it doesn't exist yet. See the definition file for the exact directory structure.
Populate frontmatter with the required fields for the type (see the template).
Initialize the lifecycle table with the appropriate phase and current date. This is usually the first phase (Draft, Planned, etc.), but an artifact may be created directly in a later phase if it was fully developed during the conversation (see Phase skipping).
Validate parent references exist (e.g., the Epic referenced by a new Agent Spec must already exist).
Index refresh step — update
```
list-<type>.md
```
(see Index maintenance).

扫描
```
docs/<type>/
```
目录（递归扫描所有阶段子目录），确定该前缀的下一个可用编号。
针对VISION工件： 在起草前，询问用户该工件是竞品产品还是个人产品。答案将决定模板包含的章节，并影响后续所有拆解工作。详情请参阅Vision定义中关于各产品类型的说明。
从下方查找表中读取工件的定义文件和模板。
在正确的阶段子目录中创建工件（通常为第一个阶段——例如
```
docs/epic/Proposed/
```
、
```
docs/spec/Draft/
```
）。若阶段目录不存在，使用
```
mkdir -p
```
创建。具体目录结构请参阅工件定义文件。
填充该类型工件的必填前置元数据字段（请参阅模板）。
使用对应阶段和当前日期初始化生命周期表格。通常为第一个阶段（草稿、规划等），但若工件在对话中已完全成型，也可直接创建在后期阶段（详见阶段跳过）。
验证父引用是否存在（例如，新Agent Spec引用的Epic必须已存在）。
索引刷新步骤 — 更新
```
list-<type>.md
```
（详见索引维护）。

Artifact type definitions

工件类型定义

Each artifact type has a definition file (lifecycle phases, conventions, folder structure) and a template (frontmatter fields, document skeleton). Read the definition for the artifact type you are creating or transitioning.

Type	Definition	Template
Product Vision (VISION-NNN)	references/vision-definition.md	references/vision-template.md.template
User Journey (JOURNEY-NNN)	references/journey-definition.md	references/journey-template.md.template
Epic (EPIC-NNN)	references/epic-definition.md	references/epic-template.md.template
User Story (STORY-NNN)	references/story-definition.md	references/story-template.md.template
Agent Spec (SPEC-NNN)	references/spec-definition.md	references/spec-template.md.template
Research Spike (SPIKE-NNN)	references/spike-definition.md	references/spike-template.md.template
Persona (PERSONA-NNN)	references/persona-definition.md	references/persona-template.md.template
ADR (ADR-NNN)	references/adr-definition.md	references/adr-template.md.template
Runbook (RUNBOOK-NNN)	references/runbook-definition.md	references/runbook-template.md.template
Bug (BUG-NNN)	references/bug-definition.md	references/bug-template.md.template

每种工件类型都有一个定义文件（生命周期阶段、规范、文件夹结构）和一个模板（前置元数据字段、文档框架）。在创建或流转工件前，请先阅读对应类型的定义文件。

类型	定义文件	模板
产品愿景（VISION-NNN）	references/vision-definition.md	references/vision-template.md.template
用户旅程（JOURNEY-NNN）	references/journey-definition.md	references/journey-template.md.template
Epic（EPIC-NNN）	references/epic-definition.md	references/epic-template.md.template
用户故事（STORY-NNN）	references/story-definition.md	references/story-template.md.template
Agent Spec（SPEC-NNN）	references/spec-definition.md	references/spec-template.md.template
研究Spike（SPIKE-NNN）	references/spike-definition.md	references/spike-template.md.template
用户画像（PERSONA-NNN）	references/persona-definition.md	references/persona-template.md.template
ADR（ADR-NNN）	references/adr-definition.md	references/adr-template.md.template
运行手册（RUNBOOK-NNN）	references/runbook-definition.md	references/runbook-template.md.template
Bug（BUG-NNN）	references/bug-definition.md	references/bug-template.md.template

Phase transitions

阶段流转

Phase skipping

阶段跳过

Phases listed in the artifact definition files are available waypoints, not mandatory gates. An artifact may skip intermediate phases and land directly on a later phase in the sequence. This is normal in single-user workflows where drafting and review happen conversationally in the same session.

The lifecycle table records only the phases the artifact actually occupied — one row per state it landed on, not rows for states it skipped past.
Skipping is forward-only: an artifact cannot skip backward in its phase sequence.
Abandoned is a universal end-of-life phase available from any state, including Draft. It signals the artifact was intentionally not pursued. Use it instead of deleting artifacts — the record of what was considered and why it was dropped is valuable.
Other end-of-life transitions (Sunset, Retired, Superseded, Archived, Deprecated) require the artifact to have been in an active state first — you cannot skip directly from Draft to Retired.

工件定义文件中列出的阶段是可选节点，而非强制关卡。工件可跳过中间阶段，直接进入后续阶段。在单用户工作流中，起草和评审在同一会话中完成时，这种情况很常见。

生命周期表格仅记录工件实际经历的阶段——每一行对应一个实际进入的状态，而非跳过的状态。
仅允许向前跳过：工件无法向后跳过阶段序列。
已废弃是所有状态都可进入的通用终结阶段，包括草稿状态。该状态表示工件已被主动放弃。请使用该状态而非删除工件——被考虑过的想法及其放弃原因的记录具有重要价值。
其他终结状态（已下线、已退役、已取代、已归档、已弃用）要求工件先进入活跃状态——无法直接从草稿状态跳至已退役状态。

Workflow

工作流

Validate the target phase is reachable from the current phase (same or later in the sequence; intermediate phases may be skipped).
Move the artifact to the new phase subdirectory using
```
git mv
```
(e.g.,
```
git mv docs/epic/Proposed/(EPIC-001)-Foo/ docs/epic/Active/(EPIC-001)-Foo/
```
). Every artifact type uses phase subdirectories — see the artifact's definition file for the exact directory names.
Update the artifact's status field in frontmatter to match the new phase.
Commit the transition change (move + status update).
Append a row to the artifact's lifecycle table with the commit hash from step 4.
Commit the hash stamp as a separate commit — never amend. Two distinct commits keeps the stamped hash reachable in git history and avoids interactive-rebase pitfalls.
Index refresh step — move the artifact's row to the new phase table (see Index maintenance).

验证目标阶段是否可从当前阶段到达（同阶段或后续阶段；可跳过中间阶段）。
移动工件：使用
```
git mv
```
将工件移至新阶段子目录（例如，
```
git mv docs/epic/Proposed/(EPIC-001)-Foo/ docs/epic/Active/(EPIC-001)-Foo/
```
）。所有工件类型都使用阶段子目录——具体目录名称请参阅工件定义文件。
更新工件前置元数据中的状态字段，使其与新阶段匹配。
提交流转变更（移动操作 + 状态更新）。
将步骤4的提交哈希添加至工件生命周期表格的新行中。
将哈希戳作为单独的提交提交——切勿合并提交。两次独立提交可确保哈希戳在Git历史中可追溯，并避免交互式变基的陷阱。
索引刷新步骤 — 将工件行移至新阶段表格（详见索引维护）。

Completion rules

完成规则

An Epic is "Complete" only when all child Agent Specs are "Implemented" and success criteria are met.
An Agent Spec is "Implemented" only when its implementation plan is closed (or all tasks are done in fallback mode).
An ADR is "Superseded" only when the superseding ADR is "Adopted" and links back.

仅当所有子Agent Spec都已「实现」且成功标准已满足时，Epic才算「完成」。
仅当其实施计划已关闭（或在回退模式下所有任务已完成）时，Agent Spec才算「实现」。
仅当替代ADR已「采纳」且反向关联时，ADR才算「被取代」。

Execution tracking handoff

执行追踪交接

Artifact types fall into four tracking tiers based on their relationship to implementation work:

Tier	Artifacts	Rule
Implementation	SPEC, STORY, BUG	Execution-tracking must be invoked when the artifact comes up for implementation — create a tracked plan before writing code
Coordination	EPIC, VISION, JOURNEY	Swain-design decomposes into implementable children first; swain-do runs on the children, not the container
Research	SPIKE	Execution-tracking is optional but recommended for complex spikes with multiple investigation threads
Reference	ADR, PERSONA, RUNBOOK	No execution tracking expected

根据与实施工作的关系，工件类型分为四个追踪层级：

层级	工件	规则
实施层	SPEC、STORY、BUG	当工件进入实施阶段时，必须调用执行追踪——在编写代码前创建可追踪计划
协调层	EPIC、VISION、JOURNEY	Swain-design先将其拆解为可实施的子工件；swain-do仅作用于子工件，而非父容器
研究层	SPIKE	执行追踪为可选操作，但对于包含多个调查线程的复杂Spike，建议使用
参考层	ADR、PERSONA、RUNBOOK	无需执行追踪

The

swain-do

frontmatter field

swain-do

前置元数据字段

Artifacts that need swain-do carry

swain-do: required

in their frontmatter. This field is:

Always present on SPEC, STORY, and BUG artifacts (injected by their templates)
Added per-instance on SPIKE artifacts when swain-design assesses the spike is complex enough to warrant tracked research
Never present on EPIC, VISION, JOURNEY, ADR, PERSONA, or RUNBOOK artifacts — orchestration for those types lives in the skill, not the artifact

When an agent reads an artifact with

swain-do: required

, it should invoke the swain-do skill before beginning implementation work.

需要swain-do的工件在前置元数据中包含

swain-do: required

字段。该字段：

始终存在于SPEC、STORY和BUG工件中（由模板自动注入）
按需添加于SPIKE工件中——当swain-design评估Spike足够复杂，需要追踪研究时添加
从不出现于EPIC、VISION、JOURNEY、ADR、PERSONA或RUNBOOK工件中——这些类型的编排逻辑存在于技能中，而非工件本身

当代理读取到包含

swain-do: required

的工件时，需在开始实施工作前调用swain-do技能。

What "comes up for implementation" means

「进入实施阶段」的定义

The trigger is intent, not phase transition alone. An artifact comes up for implementation when the user or workflow indicates they want to start building — not merely when its status changes. When implementation begins, the resulting plan should follow TDD methodology (see Implementation plans § TDD methodology) — tests derived from acceptance criteria are written before the code they verify.

"Let's implement SPEC-003" → invoke swain-do with TDD-structured plan
"Move SPEC-003 to Approved" → phase transition only, no tracking yet
"Fix BUG-001" → invoke swain-do (write a failing regression test first, then fix)
"Let's work on EPIC-008" → decompose into SPECs/STORYs first, then track the children

触发条件是实施意图，而非仅阶段流转。当用户或工作流表明要开始构建时，工件即进入实施阶段——而非仅当状态变更时。开始实施时，生成的计划应遵循TDD方法论（详见实施计划 § TDD方法论）——从验收标准衍生的测试需在其验证的代码之前编写。

「我们来实现SPEC-003」→ 调用swain-do生成TDD结构化计划
「将SPEC-003移至已批准状态」→ 仅进行阶段流转，暂不追踪
「修复BUG-001」→ 调用swain-do（先编写失败的回归测试，再修复）
「我们来处理EPIC-008」→ 先将其拆解为SPEC/STORY，再追踪子工件

Coordination artifact decomposition

协调工件拆解

When swain-do is requested on an EPIC, VISION, or JOURNEY:

Swain-design leads. Decompose the artifact into implementable children (SPECs, STORYs) if they don't already exist.
Swain-do follows. Create tracked plans for the child artifacts, not the container.
Swain-design monitors. The container transitions (e.g., EPIC → Complete) based on child completion per the existing completion rules.

当针对EPIC、VISION或JOURNEY请求swain-do时：

Swain-design主导：若子工件尚未存在，将父工件拆解为可实施的子工件（SPEC、STORY）。
Swain-do跟进：为子工件创建追踪计划，而非父容器。
Swain-design监控：父容器的阶段流转（例如EPIC→完成）基于子工件的完成情况，遵循现有完成规则。

STORY and SPEC coordination

STORY与SPEC的协调

Under the same parent Epic, Stories define user-facing requirements and Specs define technical implementations. They connect through shared

addresses

pain-point references and their common parent Epic. When creating swain-do plans, tag tasks with both

spec:SPEC-NNN

and

story:STORY-NNN

labels when a task satisfies both artifacts.

在同一父Epic下，Story定义用户可见的需求，Spec定义技术实现。它们通过共享的

addresses

痛点引用和共同的父Epic建立关联。创建swain-do计划时，若任务同时满足两种工件，需为任务添加

spec:SPEC-NNN

和

story:STORY-NNN

标签。

Superpowers integration

Superpowers集成

When superpowers (obra/superpowers) is installed, route implementation through its brainstorming → writing-plans pipeline to produce higher-quality plans before handing off to swain-do.

Detection: Check whether the

brainstorming

and

writing-plans

skills exist:

bash

ls .claude/skills/brainstorming/SKILL.md .claude/skills/writing-plans/SKILL.md 2>/dev/null

If both exist, superpowers is available. If either is missing, use the current direct-to-swain-do flow.

Routing when superpowers IS present:

Invoke the
```
brainstorming
```
skill with the artifact's context — pass the problem statement, acceptance criteria, and scope from the artifact's frontmatter and body.
Brainstorming produces a design and invokes
```
writing-plans
```
automatically.

writing-plans

saves a plan file to

docs/plans/YYYY-MM-DD-<feature-name>.md

After the plan file is saved, invoke swain-do's plan ingestion:

bash

python3 .claude/skills/swain-do/scripts/ingest-plan.py \
  docs/plans/<plan-file>.md <ARTIFACT-ID>

This creates a bd epic with child tasks, sequential dependencies, and spec lineage tags.

Routing when superpowers is NOT present:

Use the current flow — invoke swain-do directly for ad-hoc task breakdown.

If the user rejects the brainstorming design: Stop cleanly. No plan file is produced, no bd tasks are created. The user can either retry brainstorming or fall back to the direct flow.

Superpowers is a recommended companion, not a hard dependency. Never install it automatically or block implementation if it's missing.

当已安装superpowers（obra/superpowers）时，需通过其头脑风暴→编写计划的流程开展实施工作，以在移交至swain-do前生成更高质量的计划。

检测方式： 检查

brainstorming

和

writing-plans

技能是否存在：

bash

ls .claude/skills/brainstorming/SKILL.md .claude/skills/writing-plans/SKILL.md 2>/dev/null

若两者都存在，则superpowers可用。若任一缺失，则使用当前直接调用swain-do的流程。

当superpowers可用时的路由：

调用
```
brainstorming
```
技能并传入工件上下文——传递工件前置元数据和正文中的问题描述、验收标准和范围。
头脑风暴会生成设计，并自动调用
```
writing-plans
```
。

writing-plans

会将计划文件保存至

docs/plans/YYYY-MM-DD-<feature-name>.md

。

计划文件保存后，调用swain-do的计划导入功能：

bash

python3 .claude/skills/swain-do/scripts/ingest-plan.py \
  docs/plans/<plan-file>.md <ARTIFACT-ID>

这将创建一个bd epic，包含子任务、顺序依赖和Spec谱系标签。

当superpowers不可用时的路由：

使用当前流程——直接调用swain-do进行临时任务拆解。

若用户拒绝头脑风暴生成的设计： 干净终止流程。不生成计划文件，不创建bd任务。用户可重试头脑风暴，或回退至直接调用流程。

Superpowers是推荐的配套工具，而非强制依赖。 请勿自动安装，也不要在其缺失时阻塞实施工作。

Implementation plans

实施计划

Implementation plans bridge declarative specs (

docs/

) and execution tracking. They are not doc-type artifacts. All CLI operations are handled by the swain-do skill — invoke it to bootstrap the task backend before creating plans.

实施计划是声明式规格（

docs/

）与执行追踪之间的桥梁。它们不属于文档类型工件。所有CLI操作由swain-do技能处理——在创建计划前，需调用该技能初始化任务后端。

TDD methodology

TDD方法论

Implementation plans follow test-driven development as the default methodology. Every plan should structure tasks so that tests are written before the code they verify — the classic red-green-refactor cycle. This matters because tests written after implementation tend to confirm what was built rather than what was specified; writing tests first forces the plan to stay anchored to the acceptance criteria.

Task ordering principles:

Test first. For each functional unit, the plan should contain a test task before its implementation task. The test task writes a failing test derived from the artifact's acceptance criteria. The implementation task makes it pass.
Small cycles. Prefer many small red-green pairs over a single "write all tests" → "write all code" split. Each cycle should cover one acceptance criterion or one behavioral facet.
Refactor explicitly. When a cycle produces working but rough code, include a refactor task after the green phase. Not every cycle needs one — only when the implementation warrants cleanup.
Integration tests bookend the plan. Start with a skeleton integration test that exercises the end-to-end path (it will fail until the pieces exist). The final task verifies it passes.

When superpowers is present, the brainstorming step should produce a TDD-structured plan. When seeding manually, decompose the spec's acceptance criteria into red-green task pairs.

实施计划默认遵循测试驱动开发方法论。每个计划的任务结构应确保测试在其验证的代码之前编写——即经典的红-绿-重构循环。这一点至关重要：在实施后编写的测试往往只能验证已构建的内容，而先编写测试可确保计划始终锚定验收标准。

任务排序原则：

测试优先：对于每个功能单元，计划应包含一个测试任务，且该任务在对应的实现任务之前。测试任务需编写一个基于工件验收标准的失败测试。实现任务需使该测试通过。
小循环：优先采用多个小型红-绿循环，而非单次「编写所有测试」→「编写所有代码」的拆分。每个循环应覆盖一个验收标准或一个行为层面。
显式重构：当循环产生可运行但粗糙的代码时，需在绿阶段后添加重构任务。并非每个循环都需要重构——仅当实施需要清理时才添加。
集成测试首尾呼应：以一个覆盖端到端路径的骨架集成测试开始（在各组件完成前，该测试会失败）。最后一个任务需验证该测试通过。

当superpowers可用时，头脑风暴步骤应生成TDD结构化计划。手动生成计划时，需将规格的验收标准拆解为红-绿任务对。

Workflow

工作流

If superpowers is present, use the superpowers integration flow to author the plan. Otherwise, seed manually from the spec's "Implementation Approach" section, structuring tasks as TDD cycles derived from acceptance criteria.
Create an implementation plan linked via an origin ref (e.g.,
```
SPEC-003
```
). Create tasks with dependencies, each tagged with spec tags for originating specs. Order test-writing tasks before their corresponding implementation tasks.
When a task impacts additional specs, add spec tags and cross-plan dependencies.

若superpowers可用，使用superpowers集成流程生成计划。否则，从规格的「实施方法」章节手动生成计划，将任务结构化为基于验收标准的TDD循环。
创建一个通过源引用（例如
```
SPEC-003
```
）关联的实施计划。创建带依赖的任务，每个任务标记规格标签以关联源规格。按测试任务先于对应实现任务的顺序排序。
当任务影响多个规格时，添加规格标签和跨计划依赖。

Closing the loop

闭环

Progress lives in the execution backend, not the spec doc. Transition the spec to "Implemented" once the plan completes.
Note cross-spec tasks in each affected artifact's lifecycle entry (e.g., "Implemented — shared serializer also covers SPEC-007").
If execution reveals the spec is unworkable, the swain-do skill's escalation protocol flows control back to this skill for spec updates before re-planning.

进度信息存在于执行后端，而非规格文档。当计划完成后，将Spec流转至「已实现」状态。
在每个受影响工件的生命周期条目中记录跨规格任务（例如，「已实现——共享序列化器同时覆盖SPEC-007」）。
若执行过程中发现规格不可行，swain-do技能的升级协议会将控制权交还至本技能，以更新规格，然后重新规划。

Fallback

回退方案

If swain-do is unavailable, fall back to the agent's built-in todo system (

todo

in_progress

blocked

done

). Maintain lineage by including artifact IDs in task titles (e.g.,

[SPEC-003] Add export endpoint

若swain-do不可用，回退至代理内置的待办系统（

todo

、

in_progress

、

blocked

、

done

）。通过在任务标题中包含工件ID（例如

[SPEC-003] 添加导出端点

）来维护谱系关系。

swain-design

Original

Translation

Spec Management

Spec管理

Artifact relationship model

文档工件关系模型

Stale reference watcher

过期引用监控器

Post-operation scan

操作后扫描

Dependency graph

依赖图谱

Lifecycle table format

生命周期表格格式

Lifecycle

生命周期

Index maintenance

索引维护

What "refresh" means

「刷新」的定义

When to refresh

刷新时机

Auditing artifacts

工件审计

Status overview

状态概览

specgraph.sh overview (primary — use this by default)

specgraph.sh overview（首选——默认使用该命令）

Other read-only commands

其他只读命令

Creating artifacts

创建工件

Error handling

错误处理

Workflow

工作流

Artifact type definitions

工件类型定义

Phase transitions

阶段流转

Phase skipping

阶段跳过

Workflow

工作流

Completion rules

完成规则

Execution tracking handoff

执行追踪交接

The swain-do frontmatter field

swain-do前置元数据字段

What "comes up for implementation" means

「进入实施阶段」的定义

Coordination artifact decomposition

协调工件拆解

STORY and SPEC coordination

STORY与SPEC的协调

Superpowers integration

Superpowers集成

Implementation plans

实施计划

TDD methodology

TDD方法论

Workflow

工作流

Closing the loop

闭环

Fallback

回退方案

`specgraph.sh overview`
(primary — use this by default)

`specgraph.sh overview`
（首选——默认使用该命令）

The
`swain-do`
frontmatter field

`swain-do`
前置元数据字段