Governance

治理

Ensure the host project's agent context file contains the swain governance rules. This skill is idempotent — run it every session; it only writes on first use.

确保宿主项目的Agent上下文文件包含swain治理规则。该Skill具有幂等性——可在每次会话中运行；仅在首次使用时写入内容。

Session-start check

会话启动检查

Detect the agent platform and locate the context file:
Platform Context file Detection
Claude Code
CLAUDE.md
(project root) Default — use if no other platform detected
Cursor
.cursor/rules/swain-governance.mdc
.cursor/
directory exists
Check whether governance rules are already present:
bash
```
grep -l "swain governance" CLAUDE.md .cursor/rules/swain-governance.mdc 2>/dev/null
```
If any file matches, governance is already installed. Proceed to Legacy cleanup, then stop.
If no match, run Legacy cleanup, then proceed to First-use setup.

Platform	Context file	Detection
Claude Code	`CLAUDE.md` (project root)	Default — use if no other platform detected
Cursor	`.cursor/rules/swain-governance.mdc`	`.cursor/` directory exists

检测Agent平台并定位上下文文件：

平台	上下文文件	检测方式
Claude Code	`CLAUDE.md` （项目根目录）	默认选项——若未检测到其他平台则使用此文件
Cursor	`.cursor/rules/swain-governance.mdc`	检测 `.cursor/` 目录是否存在

检查治理规则是否已存在：
bash
```
grep -l "swain governance" CLAUDE.md .cursor/rules/swain-governance.mdc 2>/dev/null
```
若任一文件匹配，则说明治理规则已安装。执行遗留内容清理后停止运行。
若未匹配到，先执行遗留内容清理，再进行首次使用设置。

Legacy cleanup

遗留内容清理

Remove pre-rename skill directories that are superseded by the current

swain-*

names. Check for each of these in

.claude/skills/

and delete any that exist:

bash

rm -rf .claude/skills/governance .claude/skills/spec-management .claude/skills/execution-tracking .claude/skills/release 2>/dev/null

Only delete a legacy directory if its

swain-*

replacement is already present — if somehow only the old names exist, leave them alone (the update likely didn't complete).

Next, check whether the governance block in the context file references old skill names (

spec-management

,

execution-tracking

). If it does, delete the entire block between

<!-- swain governance -->

and

<!-- end swain governance -->

(inclusive) and re-inject via First-use setup so the block picks up the current names. This is safe because the block is machine-managed — user customizations live outside the markers.

移除已被当前

swain-*

命名取代的重命名前Skill目录。检查

.claude/skills/

下的以下目录，若存在则删除：

bash

rm -rf .claude/skills/governance .claude/skills/spec-management .claude/skills/execution-tracking .claude/skills/release 2>/dev/null

仅当对应的

swain-*

替代目录已存在时，才删除遗留目录——若仅存在旧命名目录（说明更新可能未完成），则保留它们。

接下来，检查上下文文件中的治理块是否引用了旧Skill名称（

spec-management

、

execution-tracking

）。若存在，删除

<!-- swain governance -->

和

<!-- end swain governance -->

之间的整个块（包含标记），并通过首次使用设置重新注入，使块内容更新为当前名称。此操作是安全的，因为该块由机器管理——用户自定义内容需放在标记之外。

First-use setup

首次使用设置

When governance rules are not found, inject them into the appropriate context file.

当未检测到治理规则时，将其注入到对应的上下文文件中。

Claude Code

Append the following block to

CLAUDE.md

in the project root. If

CLAUDE.md

does not exist, create it.

markdown

<!-- swain governance — do not edit this block manually -->

将以下块追加到项目根目录的

CLAUDE.md

中。若

CLAUDE.md

不存在，则创建该文件。

markdown

<!-- swain governance — do not edit this block manually -->

Skill routing

When the user wants to create, plan, write, update, transition, or review any documentation artifact (Vision, Journey, Epic, Story, Agent Spec, Spike, ADR, Persona, Runbook, Bug) or their supporting docs (architecture overviews, competitive analyses, journey maps), always invoke the swain-design skill. This includes requests like "write a spec", "let's plan the next feature", "create an ADR for this decision", "move the spike to Active", "add a user story", "create a runbook", "file a bug", or "update the architecture overview." The skill contains the artifact types, lifecycle phases, folder structure conventions, relationship rules, and validation procedures — do not improvise artifact creation outside the skill.

For all task tracking and execution progress, use the swain-do skill instead of any built-in todo or task system. This applies whether tasks originate from swain-design (implementation plans) or from standalone work. The swain-do skill bootstraps and operates the external task backend — it will install the CLI if missing, manage fallback if installation fails, and translate abstract operations (create plan, add task, set dependency) into concrete commands. Do not use built-in agent todos when this skill is available.

When the user wants to create, plan, write, update, transition, or review any documentation artifact (Vision, Journey, Epic, Story, Agent Spec, Spike, ADR, Persona, Runbook, Bug) or their supporting docs (architecture overviews, competitive analyses, journey maps), always invoke the swain-design skill. This includes requests like "write a spec", "let's plan the next feature", "create an ADR for this decision", "move the spike to Active", "add a user story", "create a runbook", "file a bug", or "update the architecture overview." The skill contains the artifact types, lifecycle phases, folder structure conventions, relationship rules, and validation procedures — do not improvise artifact creation outside the skill.

For all task tracking and execution progress, use the swain-do skill instead of any built-in todo or task system. This applies whether tasks originate from swain-design (implementation plans) or from standalone work. The swain-do skill bootstraps and operates the external task backend — it will install the CLI if missing, manage fallback if installation fails, and translate abstract operations (create plan, add task, set dependency) into concrete commands. Do not use built-in agent todos when this skill is available.

Pre-implementation protocol (MANDATORY)

Implementation of any SPEC artifact (Epic, Story, Agent Spec, Spike) requires a swain-do plan before writing code. Invoke the swain-design skill — it enforces the full workflow.

Issue Tracking

This project uses bd (beads) for all issue tracking. Do NOT use markdown TODOs or task lists. Invoke the swain-do skill for all bd operations — it provides the full command reference and workflow.

undefined

This project uses bd (beads) for all issue tracking. Do NOT use markdown TODOs or task lists. Invoke the swain-do skill for all bd operations — it provides the full command reference and workflow.

undefined

Cursor

Write the governance rules to

.cursor/rules/swain-governance.mdc

. Create the directory if needed.

markdown

---
description: "swain governance — skill routing, pre-implementation protocol, issue tracking"
globs:
alwaysApply: true
---

<!-- swain governance — do not edit this block manually -->

将治理规则写入

.cursor/rules/swain-governance.mdc

。若目录不存在则创建。

markdown

---
description: "swain governance — skill routing, pre-implementation protocol, issue tracking"
globs:
alwaysApply: true
---

<!-- swain governance — do not edit this block manually -->

Skill routing

When the user wants to create, plan, write, update, transition, or review any documentation artifact (Vision, Journey, Epic, Story, Agent Spec, Spike, ADR, Persona, Runbook, Bug) or their supporting docs (architecture overviews, competitive analyses, journey maps), always invoke the swain-design skill. This includes requests like "write a spec", "let's plan the next feature", "create an ADR for this decision", "move the spike to Active", "add a user story", "create a runbook", "file a bug", or "update the architecture overview." The skill contains the artifact types, lifecycle phases, folder structure conventions, relationship rules, and validation procedures — do not improvise artifact creation outside the skill.

For all task tracking and execution progress, use the swain-do skill instead of any built-in todo or task system. This applies whether tasks originate from swain-design (implementation plans) or from standalone work. The swain-do skill bootstraps and operates the external task backend — it will install the CLI if missing, manage fallback if installation fails, and translate abstract operations (create plan, add task, set dependency) into concrete commands. Do not use built-in agent todos when this skill is available.

When the user wants to create, plan, write, update, transition, or review any documentation artifact (Vision, Journey, Epic, Story, Agent Spec, Spike, ADR, Persona, Runbook, Bug) or their supporting docs (architecture overviews, competitive analyses, journey maps), always invoke the swain-design skill. This includes requests like "write a spec", "let's plan the next feature", "create an ADR for this decision", "move the spike to Active", "add a user story", "create a runbook", "file a bug", or "update the architecture overview." The skill contains the artifact types, lifecycle phases, folder structure conventions, relationship rules, and validation procedures — do not improvise artifact creation outside the skill.

For all task tracking and execution progress, use the swain-do skill instead of any built-in todo or task system. This applies whether tasks originate from swain-design (implementation plans) or from standalone work. The swain-do skill bootstraps and operates the external task backend — it will install the CLI if missing, manage fallback if installation fails, and translate abstract operations (create plan, add task, set dependency) into concrete commands. Do not use built-in agent todos when this skill is available.

Pre-implementation protocol (MANDATORY)

Implementation of any SPEC artifact (Epic, Story, Agent Spec, Spike) requires a swain-do plan before writing code. Invoke the swain-design skill — it enforces the full workflow.

Issue Tracking

This project uses bd (beads) for all issue tracking. Do NOT use markdown TODOs or task lists. Invoke the swain-do skill for all bd operations — it provides the full command reference and workflow.

undefined

This project uses bd (beads) for all issue tracking. Do NOT use markdown TODOs or task lists. Invoke the swain-do skill for all bd operations — it provides the full command reference and workflow.

undefined

After injection

注入完成后

Tell the user:

Governance rules installed in
<file>
. These rules ensure swain-design, swain-do, and swain-release skills are routable. You can customize the rules — just keep the

markers so this skill can detect them on future sessions.

告知用户：

治理规则已安装在
<file>
中。这些规则确保swain-design、swain-do和swain-release Skill可被路由调用。您可以自定义规则——请保留

标记，以便此Skill在未来会话中能检测到它们。

Governance content reference

治理内容参考

The canonical governance rules are embedded in the First-use setup section above. If the upstream rules change in a future swain release, update the embedded blocks and bump the skill version. Consumers who want the updated rules can delete the

<!-- swain governance -->

block from their context file and re-run this skill.

标准治理规则嵌入在上方的首次使用设置部分。若swain后续版本中上游规则发生变更，请更新嵌入的块并升级Skill版本。想要获取更新后规则的用户，可从其上下文文件中删除

<!-- swain governance -->

块，然后重新运行此Skill。

swain-config

Original

Translation

Governance

治理

Session-start check

会话启动检查

Legacy cleanup

遗留内容清理

First-use setup

首次使用设置

Claude Code

Claude Code

Skill routing

Skill routing

Pre-implementation protocol (MANDATORY)

Pre-implementation protocol (MANDATORY)

Issue Tracking

Issue Tracking

Cursor

Cursor

Skill routing

Skill routing

Pre-implementation protocol (MANDATORY)

Pre-implementation protocol (MANDATORY)

Issue Tracking

Issue Tracking

After injection

注入完成后

Governance content reference

治理内容参考