ethanreedlabs/sulde/configure-sulde

/configure-sulde — 项目配置 / 升级 / 维护 8 mode

入口 command(在 commands/sulde-*.md 定义),都走本 skill。根据用户 invoke 的 command 选 mode。

§0 Mode dispatch

任一 mode 跑完输出“结果与阻塞”段。范围内的 next steps 由 Agent 继续执行；只有缺少外部事实、 物理接入或高风险授权时才向用户询问，不输出让用户代跑的命令。

§1 Mode: init(对话式 8 步)

新项目接入 sulde-cc。步骤:

1. Detect existing .sulde-config.yaml(若有,refuse + 提示 /sulde-migrate-from-v0.1.0)
2. Q1:project name(default = dir basename)
3. Q2:role(coordinator / dev / both,default coordinator)
4. Q3:stack 多选(default [android, ios],可加 flutter / harmony)
5. Q4:design source MCP(default pencil)+ file 路径(./design/app.pen 等)
6. Q5:team(每个 frontend 至少 1 个 alias;先收集 N,后跑 add-team-member mode 加 alias)
7. Q6:enforcement_level(default balanced)+ grace_period_days(default 7)
8. Q7:lang(default auto)+ os_primary_target(default unix)
9. 生成 `.sulde-config.yaml` 写入 project root
10. 复制 `${CLAUDE_PLUGIN_ROOT}/template/_project/*` 到 project root(根级 + scripts/ + docs-hub/ 骨架)
11. 复制 `${CLAUDE_PLUGIN_ROOT}/template/<stack>/*` 到 <frontend>/ 每个 frontend(对应 stack 骨架)
12. 写 grace marker:echo '{"started_at":"<ISO>","grace_period_days":7}' > .sulde-grace-started
13. 跑各 frontend 的 `scripts/pre-commit-installer.sh` 装 git hook
14. cp `template/_project/docs-hub/design/page-relation.yaml.example` → `<docs-hub>/design/page-relation.yaml`(空骨架,首次跑 /ui-impl 阶段 0 强制读取本图谱,缺则报错)
15. 由 Agent 完成后续收尾并输出结果:

• 7 day grace period 已起,hook 强制 lenient mode 直到 .sulde-grace-ended marker
• Agent 检查运行时依赖；缺 PyYAML 时在当前环境安装并回读版本，权限或网络需要扩大时走原生确认
• 若多人协作:Agent 根据已收集的团队信息继续执行 add-team-member；缺少身份事实时一次问齐
• 若独立开发者:team: [] 留空即可(check_commit_alias.sh hook 自动 skip alias 强制,plain git commit 工作)
• 若有设计工具(Pencil / Figma MCP):Agent 继续执行 /update-design 起初版 design-truth
• 若无设计工具:.sulde-config.yaml: design_source.mcp 设为 none，Agent 根据用户提供的设计源生成 design-truth
• 首次跑 /ui-impl 前由 Agent 根据可验证页面关系填写 <docs-hub>/design/page-relation.yaml；

只有关系语义不明时才问一个自然语言问题

• 用户明确要求提前结束 grace 时，Agent 执行 /sulde-end-grace

复制实现 见 §9 跨目录 cp 权限段。

§2 Mode: migrate(v0.1.0 → v0.2.0)

老版本(v0.1.0)用户升级。步骤:

1. Read existing .sulde-config.yaml(v0.1.0 schema)
2. 显示 diff:

• frontend-a placeholder → 提示 rename(用户选 android / ios / flutter / harmony)
• 新增字段填 default(enforcement_level: balanced / lang: auto / enforcement_grace_period_days: 7 / scope_inheritance: parent / os_compatibility: {primary_target: unix, windows_shell_hint: git-bash} / build_verify: {...} / enforcement: {...})
• skill paths 从 v0.1.0 的 user-private bundle → v0.2.0 generic(假定用户没改 plugin 源)

1. Dry-run write to .sulde-config.yaml.v2-preview
2. 用户已经请求迁移且 preview 无未决语义时，Agent 备份原 file 为

.sulde-config.yaml.v0.1.0-backup 后写新 file；只有字段含义无法推断时才询问具体选择

1. 写 grace marker .sulde-grace-started(7d grace 让用户适应新 enforcement)
2. Agent 安装并回读 Python 依赖与各 frontend git hook，输出 migration report；若失败自动恢复备份。

报告保留 v0.1.0 回滚路径，但不要求用户代跑安装命令。

§3 Mode: add-frontend

Args: <name> <path> <stack>(例:/sulde-add-frontend harmony ./harmony mobile-harmony)

1. Read existing config → 检查 name 不重复
2. Append to frontends: 数组
3. 复制 ${CLAUDE_PLUGIN_ROOT}/template/<stack>/* 到 <path>/(用户可未存在该目录,创建)
4. 跑 <path>/scripts/pre-commit-installer.sh 装 git hook
5. 已提供团队身份时由 Agent 继续配置；缺少 alias/name/email 时一次问齐，不输出待用户再次触发的命令

可用 stack(v0.2.0):mobile-android / mobile-ios / mobile-flutter / mobile-harmony。

§4 Mode: add-team-member

Args: <alias> <name> <email> <frontend>(例:/sulde-add-team-member as-c Carol carol@team.com flutter)

1. Read existing config → 检查 alias 不重复
2. Append to team: 数组:

```yaml

• alias: as-c

name: Carol email: carol@team.com frontend: flutter ```

1. 创建 git alias as-<alias>:

• 写入项目 .git/config 的 [alias] section:

`` [alias] as-c = "!SULDE_COMMIT_ALIAS=as-c git -c user.name='Carol' -c user.email='carol@team.com' commit" ``

• 注:SULDE_COMMIT_ALIAS 是 sentinel,check_commit_alias.sh pre-commit hook 据此放行

1. 回读 alias 配置并报告；后续提交由 Agent 使用 git as-c commit ...。alias 是 per-repo，

新 clone 由 Agent 重新执行本 mode，不让用户手工编辑 .git/config

§5 Mode: add-sensitive-file

Args: <path>(例:/sulde-add-sensitive-file core-ui/AppRouter.kt)

委托 skills/sulde-add-sensitive-file/SKILL.md 完整执行：

1. Read existing config → append to scope_sensitivity.sensitive_files: 数组(去重)，作为 advisory/self-fix 边界。
2. 同时向项目 .claude/settings.json: permissions.deny 去重追加 Edit(<相对路径>) 与 Write(<相对路径>)，作为 harness 级 deny；保留其他键，首次修改已有 settings 前备份为 .claude/settings.json.bak-sulde。
3. 输出双保险 reminder:Dev 端 self-fix-boundary 会 block 自发改这些文件，harness 拒绝直接 Edit/Write；改动必经 task md。

§6 Mode: add-scaffold

Args: <name> [trigger-regex](例:/sulde-add-scaffold AppTopBar "TopBar|TitleBar")

1. Read <docs-hub>/scaffold-map.yaml → append:

```yaml

• name: AppTopBar

triggers: ["TopBar", "TitleBar"] contract: <docs-hub>/scaffolds/AppTopBar.md # 需协调端补 owner: coordinator ```

1. 提示协调端补 <docs-hub>/scaffolds/<name>.md 契约文档

§7 Mode: add-skill-trigger

Args: <regex> <skill> [role](例:/sulde-add-skill-trigger "pen-truth.*更新" update-design coordinator)

1. Append to .sulde-config.yaml: skill_triggers:(已是 v0.2.0 字段)

```yaml skill_triggers:

• regex: "pen-truth.*更新"

skill: update-design role: coordinator reminder: "Invoke the update-design skill..." ```

1. 输出 reminder:hook skill_trigger.py 会在 UserPromptSubmit 时合并 default + user triggers

§8 Mode: end-grace

无 args。

1. 检查 .sulde-grace-started 存在(若不存在 → "no grace period active")
2. 写 .sulde-grace-ended(空 file 即可,或 {"ended_at": "<ISO>"} 内容)
3. 输出:enforcement 立刻切回 config enforcement_level(strict / balanced / lenient)
4. 提示:.sulde-grace-* marker 已加 .gitignore(不进 git,per-machine state)

§9 跨目录 cp 权限 / 实现细节(B4 fix)

复制 template 时:

import shutil
from pathlib import Path
PLUGIN_ROOT = Path(os.environ["CLAUDE_PLUGIN_ROOT"])  # set by Claude Code
src = PLUGIN_ROOT / "template" / "_project"
dst = Path(project_root)
shutil.copytree(src, dst, dirs_exist_ok=True)
# Re-apply executable bit on scripts (Python copytree preserves mode on Unix
# but Windows file modes are limited)
for sh in dst.glob("**/*.sh"):
    sh.chmod(sh.stat().st_mode | 0o755)

权限失败:Agent 先解析精确目标并通过宿主原生权限面申请一次性写入；获准后重试并回读。 若权限仍不可用，报告精确 blocker 并保持原文件不变，禁止输出让用户代跑的 cp 命令。

跨 OS windows:

• shutil.copytree works
• .sh 在 Windows 没 executable bit,git pre-commit 会以 bash 解释器跑(via Git for Windows / WSL2)— pre-commit-installer.sh 内含 OS detect 提示

§10 default 字段写入(各 mode 共用)

写 .sulde-config.yaml 时,默认字段 + 必填字段 区分:

§11 mode 错误处理