feat(transformer): 2026-08 规范对齐并统一共享 AGENTS.md

将各 AGENTS.md producer 规范为同一份 target-neutral 规则文档，默认关闭类型速查注入，并把 Cline skills 迁到官方推荐的 .cline/skills。Claude subagent 补齐 isolation/memory/permission_mode/max_turns/preload_skills 字段，预算增加 Codex 技能清单软上限。

Author: StringKe

.agents/references/transformer-design.md

@@ -1,107 +1,71 @@
 ---
-description: stdagent transformer 包设计参考（interface / Plan / FileOp / fanout 约定）
+description: stdagent transformer、global plan、FileOp 和协议复用契约
 std-agent-type: references
 ---
 <!-- Generated by stdagent dev. Source: .stdai/standards/references/transformer-design.md. Run `stdagent sync` to regenerate. Do not edit by hand. -->
 <!-- std-agent degraded references: transformer-design -->
 <!-- Target tool "codex" does not natively support this type. Reference is background material; AI consults it only when needed, not auto-loaded. -->
 
 
-# transformer 包设计
+# Transformer design
 
-## interface
+## Contract
 
-```go
-type Transformer interface {
-    Plan(docs []*parser.Document, cfg *config.Config) (*writer.Plan, error)
-}
-```
+每个 target 实现 `Transformer` 的 `Name()` 与 `Plan(docs, cfg)`，并通过 `init()` 注册。Plan 只计算 `writer.Plan`，不读写工作区。
 
-每个 target 一个 Transformer 实例，注册到全局 `registry` map（init() 完成）。runner.Sync 调 `transformer.Get(name)` 取实例 + 调 Plan。
+`writer.FileOp` 的关键语义：
 
-## Plan 数据流
+- `Path`：项目根相对路径，内部统一 forward slash。
+- `Content`：最终字节内容。
+- `Marker`：内容是否带 stdagent marker。
+- `IsRoot`：需要 root context budget 检查。
+- `Skip` / `Reason`：不写入及其诊断。
+- `JSONMerge`：将 Content 作为 JSON fragment 深合并，不覆盖已有 scalar。
 
-```
-[]parser.Document      读取的源 docs（含 frontmatter + body）
-        |
-        v
-   Transformer.Plan
-        |
-        v
-  writer.Plan {
-      Target string
-      Files  []FileOp
-  }
-        |
-        v
-   writer.Apply -> 落盘
-```
+内容必须 deterministic；相同 source 和 config 产生字节一致的 plan。
 
-`FileOp` 字段：
-
-```go
-type FileOp struct {
-    Path    string  // 相对项目根（forward slash）
-    Content []byte
-    Marker  bool    // 是否注入 stdagent marker comment
-    IsRoot  bool    // 是否为 target 根文件（CLAUDE.md / AGENTS.md 等），runner 触发 budget root-file 检查
-    Skip    bool    // true 表示这个 op 这次不写盘（unchanged / WARN / submodule 边界）
-    Reason  string  // 诊断信息（dry-run 输出 + warn 收集）
-}
-```
+## Global planning
+
+Runner 在任何写入前完成所有 target plan：
 
-`Skip + Reason` 有三类来源：
+```text
+source -> parse -> target plans -> shared-path canonicalization
+       -> collision validation -> submodule guard -> apply -> state/prune
+```
 
-1. transformer 主动 skip（如 `copilot.go` 对 SkillFiles WARN）：`Reason` 以 "WARN" 开头
-2. submodule 边界（runner.go 内）：`Reason = "WARN: refused write into submodule ..."`
-3. writer.Apply 检测 unchanged：`Reason = "unchanged"`
+所有 `AGENTS.md` producer 共享 canonical rules：
 
-prune 逻辑只把 (2)(3) 的 path 视作"当前管理范围内"，(1) 排除（因为我们主动声明不写）。详见 `internal/runner/runner.go` 的 `current set` 构造。
+- 合并对至少一个启用 producer 生效的 root、non-root 和 nested rules。
+- commands、skills、references、subagents 保留在 target sidecar。
+- 每个 producer plan 记录相同路径和 hash。
 
-## Document.Root / NestedPath
+其他同路径 FileOp 只有在 Content 和 JSONMerge 语义一致时才允许；否则在首个写入前失败。
 
-- `Root: true`：本 doc 是项目总览，body 写到所有 target 根文件（CLAUDE.md / AGENTS.md / GEMINI.md / .github/copilot-instructions.md）的头部
-- `NestedPath: "x/y"`：本 doc 是嵌套子目录的说明文档，写到 `x/y/CLAUDE.md` 与 `x/y/AGENTS.md`，**不** 追加 manifest（嵌套位置只是说明）
+## Protocol reuse
 
-transformer 在 Plan 内要先按 Root / NestedPath 分流，再按 Type 分发到对应输出路径。
+新增 target 优先选择现有 protocol：
 
-## fanout 约定
+- `AgentsMD`
+- `ClaudeMD`
+- `Cursor`
+- `Clinerules`
+- `WindsurfStyle`
+- `Copilot`
 
-各 target 的输出路径基本规则：
+Adapter 表达根文件、原生目录、frontmatter 方言、fallback、限制和 glossary 能力。只有多个 target 共享且 adapter 无法表达的行为才进入 protocol；单 target 特性留在 target wrapper。
 
-| Type | claude-code | codex | cursor | copilot | windsurf |
-|---|---|---|---|---|---|
-| rules (Root) | CLAUDE.md（含 manifest） | AGENTS.md | （写入 .cursor/rules/<n>.mdc + 在根文件） | .github/copilot-instructions.md | .windsurf/rules/<n>.md |
-| rules（非 Root） | .claude/rules/<n>.md | 全文 inline 到 AGENTS.md（.codex/memories 已废弃，撞官方语义） | .cursor/rules/<n>.mdc | .github/instructions/<n>.instructions.md（applyTo 转 frontmatter） | .windsurf/rules/<n>.md |
-| skills | .claude/skills/<n>/SKILL.md + 子目录（frontmatter 工具字段是 allowed-tools，不是 tools） | .agents/skills/<n>/SKILL.md | .cursor/skills/<n>/SKILL.md | .github/skills/<n>/SKILL.md（2026 GA） | .windsurf/skills/<n>/SKILL.md |
-| commands | .claude/commands/<n>.md | .agents/skills/commands/<n>/SKILL.md（降级 skill） | .cursor/commands/<n>.md | .github/prompts/<n>.prompt.md | .windsurf/workflows/<n>.md |
-| subagents | .claude/agents/<n>.md | .agents/subagents/<n>.md（降级） | .cursor/agents/<n>.md（原生） | .github/agents/<n>.agent.md | （nope） |
+## Documents
 
-2026-07 规范对齐后的其他关键落点（详见 docs/sdlc/2026-07-10/spec-refresh/spec.md）：
+- `Root`：顶级项目入口。
+- `NestedPath`：同仓库目录级入口，不含顶级 manifest。
+- 其余文档按 Type fan out。
+- `FilterDocs` 在转换前应用 target whitelist 或 blacklist。
 
-- Agent Skills 原生目录已全行业铺开：gemini `.gemini/skills/`、qwen `.qwen/skills/`、
-  roo `.roo/skills/`、kilo `.kilo/skills/`、opencode `.opencode/skills/`、
-  continue `.continue/skills/`、augment `.augment/skills/`；amp / warp / antigravity /
-  kimi-code 与 codex 共享 `.agents/skills/`（SkillSupportedFields 同集保证字节一致，writer
-  unchanged 去重）。降级 skill 子目录方案只剩 cline / pi / jules 等仍在用。
-- amp 官方已移除自定义 commands（并入 skills），与 codex 相同降级为
-  `.agents/skills/commands/<n>/SKILL.md`；grok-build 同模式走 `.grok/skills/commands/`。
-- roo 原生 commands `.roo/commands/<n>.md`；kilo 原生 `.kilo/command/<n>.md`（单数）+
-  kilo.jsonc `instructions[]` 由 JSONMerge op 注册（`.kilo/rules/` 不被自动扫描）。
-- crush 项目级 skills 必须写进 crush.json `options.skills_paths`（JSONMerge op）；
-  crush 无嵌套发现，NestedSupported=false。
-- grok-build 的 references / subagents 降级物放 `.grok/docs/`——`.grok/rules/`
-  是每 session 全量加载目录，放低频资料会污染 context。
-- qwen `.qwen/rules/` 是原生 RulesDir（支持 paths 条件规则），nonRoot rules 不再
-  inline 进 QWEN.md。
+Target 原生能力优先。缺失能力使用 protocol 的隔离 fallback；不能被 target 发现或有意读取的文件不得描述为支持。
 
-完整矩阵：`docs/conversion-rules.md`。frontmatter 字段方言：`docs/format-spec.md`。
+## Evidence and tests
 
-## 编写新 transformer 时的常见坑
+Target 路径、字段、发现机制和限制以 `docs/targets/<name>.md` 的官方 URL 为依据。完整 source schema 与跨 target 原则见 `docs/format-spec.md` 和 `docs/conversion-rules.md`。
 
-1. **路径分隔符**：内部统一 forward slash；Plan.Files[].Path 不要用 `filepath.Join` 产生 OS-specific 分隔符，用 `path` 包或自己拼 `/`。
-2. **content bytes**：用 `[]byte`，不用 `string`，避免 UTF-8 BOM 处理时变成奇怪字符。
-3. **frontmatter 写入**：用 `transformer.util.go` 的工具函数（如有），保持 YAML 缩进一致；不要每个 target 自己 fmt.Sprintf 拼接。
-4. **marker 注入**：用 `writer.footer.go` 的工具，保持 deterministic（marker 内容不含 timestamp，避免每次 sync 都 diff）。
-5. **paths vs applyTo**：rulesync 风格的 `<target>.paths` 嵌套字段优先于全局 `applyTo`，参考 cursor.go / claude_code.go 的处理。
+Done means 测试覆盖 5 种 type、filter、共享路径、首次与重复 sync、关键限制及真实 rendered output，并通过 `mise run check`、strict sync、status 和 rendered budget。
 <!-- /Generated by stdagent -->

.agents/rules/commit-style.md

@@ -1,26 +1,12 @@
 ---
 trigger: model_decision
-description: Conventional Commits 1.0.0 风格
+description: Conventional Commits 和安全暂存要求
 ---
 <!-- Generated by stdagent dev. Source: .stdai/standards/rules/commit-style.md. Run `stdagent sync` to regenerate. Do not edit by hand. -->
-# Commit style
+用户要求 commit 时：
 
-Conventional Commits 1.0.0：`<type>(scope): <description>`
-
-- type：`feat` / `fix` / `docs` / `style` / `refactor` / `perf` / `test` / `build` / `ci` / `chore`
-- scope 用模块名（`writer` / `runner` / `transformer` / `cli` 等），跨多模块的写宽 scope（如 `claude-code` / `release`）
-- description 用中文或英文都行，与现有 commit 史保持一致即可
-- 破坏性变更加 `!`：`feat(api)!: 移除旧接口`，并在 body 写 `BREAKING CHANGE:` 段
-- 不要 `Co-Authored-By` / AI 署名
-
-参考既有提交风格：
-
-```
-fix(writer): 复用 h 变量比较，消除 staticcheck SA4000
-refactor(writer): marker 移除 timestamp，输出 deterministic
-fix(claude-code): 用 paths 字段而非 applyTo（官方文档要求）
-fix(release): ignore CHANGELOG_LATEST.md so goreleaser sees clean tree
-```
-
-`.env` / 密钥类文件告知用户，不自作主张提交。staged 文件用 `git add <file>` 显式列出，避免 `git add -A` 把无关文件带进去。
+- 格式为 Conventional Commits 1.0.0：`<type>(scope): <description>`；scope 与现有模块和提交历史一致。
+- breaking change 使用 `!` 和 `BREAKING CHANGE:`。
+- 只显式暂存当前任务文件；密钥或 `.env` 类文件先报告，不擅自提交。
+- 不添加 `Co-Authored-By` 或 AI 署名。
 <!-- /Generated by stdagent -->

.agents/rules/no-history-rewrite.md

@@ -1,19 +1,9 @@
 ---
 trigger: model_decision
-description: 已推送分支禁止改写历史
+description: 保护已推送分支和 release tag
 ---
 <!-- Generated by stdagent dev. Source: .stdai/standards/rules/no-history-rewrite.md. Run `stdagent sync` to regenerate. Do not edit by hand. -->
-# 已推送分支禁止改写历史
-
-违反任一条立即修复，不辩解。
-
-- FAIL：已推送分支 `git commit --amend` + `git push --force` / `--force-with-lease`
-- FAIL：已推送分支 `git rebase` + `git push --force` / `--force-with-lease`
-- FAIL：`git reset --hard <older>` + `git push --force` 到已推送分支
-
-修补已推送 commit 的唯一方式：**追加新 commit + fast-forward push**。PR 多一个 commit 不干净也比改写历史好。
-
-唯一例外：本人独占的 WIP 分支，且明确告知协作者后才 amend。`main` / 受保护分支永远不允许 force-push。
-
-发版相关：tag 一旦 push 到 origin 触发了 goreleaser 也不要删。要修复用更高 patch 版本（v0.0.X+1）覆盖。
+- 已推送分支只追加 commit 并 fast-forward push；`main` 和受保护分支永不 force-push。
+- amend 或 rebase 仅限本人独占、尚未共享的 WIP 分支。
+- 已推送并触发发布的 tag 不删除；修复使用更高 patch 版本。
 <!-- /Generated by stdagent -->

.agents/rules/references/transformer-design.md

@@ -1,107 +1,71 @@
 ---
-description: stdagent transformer 包设计参考（interface / Plan / FileOp / fanout 约定）
+description: stdagent transformer、global plan、FileOp 和协议复用契约
 std-agent-type: references
 ---
 <!-- Generated by stdagent dev. Source: .stdai/standards/references/transformer-design.md. Run `stdagent sync` to regenerate. Do not edit by hand. -->
 <!-- std-agent degraded references: transformer-design -->
 <!-- Target tool "antigravity" does not natively support this type. Reference is background material; AI consults it only when needed, not auto-loaded. -->
 
 
-# transformer 包设计
+# Transformer design
 
-## interface
+## Contract
 
-```go
-type Transformer interface {
-    Plan(docs []*parser.Document, cfg *config.Config) (*writer.Plan, error)
-}
-```
+每个 target 实现 `Transformer` 的 `Name()` 与 `Plan(docs, cfg)`，并通过 `init()` 注册。Plan 只计算 `writer.Plan`，不读写工作区。
 
-每个 target 一个 Transformer 实例，注册到全局 `registry` map（init() 完成）。runner.Sync 调 `transformer.Get(name)` 取实例 + 调 Plan。
+`writer.FileOp` 的关键语义：
 
-## Plan 数据流
+- `Path`：项目根相对路径，内部统一 forward slash。
+- `Content`：最终字节内容。
+- `Marker`：内容是否带 stdagent marker。
+- `IsRoot`：需要 root context budget 检查。
+- `Skip` / `Reason`：不写入及其诊断。
+- `JSONMerge`：将 Content 作为 JSON fragment 深合并，不覆盖已有 scalar。
 
-```
-[]parser.Document      读取的源 docs（含 frontmatter + body）
-        |
-        v
-   Transformer.Plan
-        |
-        v
-  writer.Plan {
-      Target string
-      Files  []FileOp
-  }
-        |
-        v
-   writer.Apply -> 落盘
-```
+内容必须 deterministic；相同 source 和 config 产生字节一致的 plan。
 
-`FileOp` 字段：
-
-```go
-type FileOp struct {
-    Path    string  // 相对项目根（forward slash）
-    Content []byte
-    Marker  bool    // 是否注入 stdagent marker comment
-    IsRoot  bool    // 是否为 target 根文件（CLAUDE.md / AGENTS.md 等），runner 触发 budget root-file 检查
-    Skip    bool    // true 表示这个 op 这次不写盘（unchanged / WARN / submodule 边界）
-    Reason  string  // 诊断信息（dry-run 输出 + warn 收集）
-}
-```
+## Global planning
+
+Runner 在任何写入前完成所有 target plan：
 
-`Skip + Reason` 有三类来源：
+```text
+source -> parse -> target plans -> shared-path canonicalization
+       -> collision validation -> submodule guard -> apply -> state/prune
+```
 
-1. transformer 主动 skip（如 `copilot.go` 对 SkillFiles WARN）：`Reason` 以 "WARN" 开头
-2. submodule 边界（runner.go 内）：`Reason = "WARN: refused write into submodule ..."`
-3. writer.Apply 检测 unchanged：`Reason = "unchanged"`
+所有 `AGENTS.md` producer 共享 canonical rules：
 
-prune 逻辑只把 (2)(3) 的 path 视作"当前管理范围内"，(1) 排除（因为我们主动声明不写）。详见 `internal/runner/runner.go` 的 `current set` 构造。
+- 合并对至少一个启用 producer 生效的 root、non-root 和 nested rules。
+- commands、skills、references、subagents 保留在 target sidecar。
+- 每个 producer plan 记录相同路径和 hash。
 
-## Document.Root / NestedPath
+其他同路径 FileOp 只有在 Content 和 JSONMerge 语义一致时才允许；否则在首个写入前失败。
 
-- `Root: true`：本 doc 是项目总览，body 写到所有 target 根文件（CLAUDE.md / AGENTS.md / GEMINI.md / .github/copilot-instructions.md）的头部
-- `NestedPath: "x/y"`：本 doc 是嵌套子目录的说明文档，写到 `x/y/CLAUDE.md` 与 `x/y/AGENTS.md`，**不** 追加 manifest（嵌套位置只是说明）
+## Protocol reuse
 
-transformer 在 Plan 内要先按 Root / NestedPath 分流，再按 Type 分发到对应输出路径。
+新增 target 优先选择现有 protocol：
 
-## fanout 约定
+- `AgentsMD`
+- `ClaudeMD`
+- `Cursor`
+- `Clinerules`
+- `WindsurfStyle`
+- `Copilot`
 
-各 target 的输出路径基本规则：
+Adapter 表达根文件、原生目录、frontmatter 方言、fallback、限制和 glossary 能力。只有多个 target 共享且 adapter 无法表达的行为才进入 protocol；单 target 特性留在 target wrapper。
 
-| Type | claude-code | codex | cursor | copilot | windsurf |
-|---|---|---|---|---|---|
-| rules (Root) | CLAUDE.md（含 manifest） | AGENTS.md | （写入 .cursor/rules/<n>.mdc + 在根文件） | .github/copilot-instructions.md | .windsurf/rules/<n>.md |
-| rules（非 Root） | .claude/rules/<n>.md | 全文 inline 到 AGENTS.md（.codex/memories 已废弃，撞官方语义） | .cursor/rules/<n>.mdc | .github/instructions/<n>.instructions.md（applyTo 转 frontmatter） | .windsurf/rules/<n>.md |
-| skills | .claude/skills/<n>/SKILL.md + 子目录（frontmatter 工具字段是 allowed-tools，不是 tools） | .agents/skills/<n>/SKILL.md | .cursor/skills/<n>/SKILL.md | .github/skills/<n>/SKILL.md（2026 GA） | .windsurf/skills/<n>/SKILL.md |
-| commands | .claude/commands/<n>.md | .agents/skills/commands/<n>/SKILL.md（降级 skill） | .cursor/commands/<n>.md | .github/prompts/<n>.prompt.md | .windsurf/workflows/<n>.md |
-| subagents | .claude/agents/<n>.md | .agents/subagents/<n>.md（降级） | .cursor/agents/<n>.md（原生） | .github/agents/<n>.agent.md | （nope） |
+## Documents
 
-2026-07 规范对齐后的其他关键落点（详见 docs/sdlc/2026-07-10/spec-refresh/spec.md）：
+- `Root`：顶级项目入口。
+- `NestedPath`：同仓库目录级入口，不含顶级 manifest。
+- 其余文档按 Type fan out。
+- `FilterDocs` 在转换前应用 target whitelist 或 blacklist。
 
-- Agent Skills 原生目录已全行业铺开：gemini `.gemini/skills/`、qwen `.qwen/skills/`、
-  roo `.roo/skills/`、kilo `.kilo/skills/`、opencode `.opencode/skills/`、
-  continue `.continue/skills/`、augment `.augment/skills/`；amp / warp / antigravity /
-  kimi-code 与 codex 共享 `.agents/skills/`（SkillSupportedFields 同集保证字节一致，writer
-  unchanged 去重）。降级 skill 子目录方案只剩 cline / pi / jules 等仍在用。
-- amp 官方已移除自定义 commands（并入 skills），与 codex 相同降级为
-  `.agents/skills/commands/<n>/SKILL.md`；grok-build 同模式走 `.grok/skills/commands/`。
-- roo 原生 commands `.roo/commands/<n>.md`；kilo 原生 `.kilo/command/<n>.md`（单数）+
-  kilo.jsonc `instructions[]` 由 JSONMerge op 注册（`.kilo/rules/` 不被自动扫描）。
-- crush 项目级 skills 必须写进 crush.json `options.skills_paths`（JSONMerge op）；
-  crush 无嵌套发现，NestedSupported=false。
-- grok-build 的 references / subagents 降级物放 `.grok/docs/`——`.grok/rules/`
-  是每 session 全量加载目录，放低频资料会污染 context。
-- qwen `.qwen/rules/` 是原生 RulesDir（支持 paths 条件规则），nonRoot rules 不再
-  inline 进 QWEN.md。
+Target 原生能力优先。缺失能力使用 protocol 的隔离 fallback；不能被 target 发现或有意读取的文件不得描述为支持。
 
-完整矩阵：`docs/conversion-rules.md`。frontmatter 字段方言：`docs/format-spec.md`。
+## Evidence and tests
 
-## 编写新 transformer 时的常见坑
+Target 路径、字段、发现机制和限制以 `docs/targets/<name>.md` 的官方 URL 为依据。完整 source schema 与跨 target 原则见 `docs/format-spec.md` 和 `docs/conversion-rules.md`。
 
-1. **路径分隔符**：内部统一 forward slash；Plan.Files[].Path 不要用 `filepath.Join` 产生 OS-specific 分隔符，用 `path` 包或自己拼 `/`。
-2. **content bytes**：用 `[]byte`，不用 `string`，避免 UTF-8 BOM 处理时变成奇怪字符。
-3. **frontmatter 写入**：用 `transformer.util.go` 的工具函数（如有），保持 YAML 缩进一致；不要每个 target 自己 fmt.Sprintf 拼接。
-4. **marker 注入**：用 `writer.footer.go` 的工具，保持 deterministic（marker 内容不含 timestamp，避免每次 sync 都 diff）。
-5. **paths vs applyTo**：rulesync 风格的 `<target>.paths` 嵌套字段优先于全局 `applyTo`，参考 cursor.go / claude_code.go 的处理。
+Done means 测试覆盖 5 种 type、filter、共享路径、首次与重复 sync、关键限制及真实 rendered output，并通过 `mise run check`、strict sync、status 和 rendered budget。
 <!-- /Generated by stdagent -->