cytrogen/loom
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
No description
21 commits 1 branch 0 tags 265 KiB
Find a file
Exact
HallowDem 897a426f18 [refactor] design-review — 切到 loom-browse + 用新 viewport / hover 命令 
allowed_tools 移除 Bash(gstack:*),加 Bash(node:*)。依赖节、Phase 1 预检、
Phase 2 截图流程、停止条件全部走 node "$LB" <subcommand>。

Phase 2 现在用真正的 viewport 命令做响应式截图(1920x1080 / 1024x768 / 375x667),
不再像旧版那样只标"应该截 3 个尺寸"无具体命令。hover 状态截图用专用
hover @ref,取代 eval 派发 MouseEvent 的 workaround。

版本 v1 → v2。
2026-04-29 01:55:25 -04:00
agents [init] repo skeleton with install scripts 2026-04-17 00:49:00 -04:00
skills [refactor] design-review — 切到 loom-browse + 用新 viewport / hover 命令 2026-04-29 01:55:25 -04:00
.gitignore [refactor] apply P1-P16 writing principles: first batch of skill fixes 2026-04-24 20:12:30 -04:00
install.ps1 [chore] 仓库正式更名 claude-shared → loom 2026-04-25 11:04:07 -04:00
install.sh [chore] 仓库正式更名 claude-shared → loom 2026-04-25 11:04:07 -04:00
README.org [feat] browse — self-contained loom-browse playwright skill (取代外部 gstack) 2026-04-29 01:54:58 -04:00

README.org

loom

把工程习惯织进 Claude Code 的 skill 编排系统。

Loom 是一套自我约束、可验证的 Claude Code skill 仓库。 19 个 skill 由 dispatcher 协调，跑在一套 P 编号的写作原则框架下。

Skill 数量超过 8 个之后，用结构化约束挡住 context rot 和文档漂移， 每一步链接仍由用户手动选。

继承自 gstack，对照 tw93 Waza 明确分歧。

这是什么

Loom 是一个 skill 仓库，通过 symlink / junction 挂载到 =~/.claude/=， 跨项目共享，单一来源（无 submodule）。

Loom 带宪法：每个 skill 都受同一套 _shared/ 原则约束， 重复模式提取到共享文件而不是各处复制。新 skill 起草时显式读 _shared/writing-style.md + ~_template/SKILL.md.tmpl~。

Loom 不是 Waza-style 的克制系统。tw93 选 8 个动词 skill 让用户记得住，所以不需要推荐；loom 选 19 个名词 skill 覆盖更宽场景，多到用户记不全，靠结构化推荐和 dispatcher 协调把认知成本接回来。

Loom 也不发明规则。每个 plan-*-review skill 都先读项目的 CLAUDE.md 和 DESIGN.md，没契约就拒绝 review，只对照项目自己声明的 invariant、角色边界、时区契约打分，不推「建议加缓存」这种 generic 套话。

哲学与来源

Loom 不从零设计，参考四个来源。

1. Anthropic — context engineering

Subagent 隔离的判据来自官方 1M context 工程博客：

"Will I need this tool output again, or just the conclusion? If just the conclusion, use a subagent."

Loom 落地：=autoplan=、~investigate~ 和 qa 在重 IO 阶段都 dispatch subagent， 父 context 只保留 JSON 结论，不保留原始代码片段、完整 review 文字或 DOM 快照。 这条原则在 loom 编号为 P10（context rot 防御）。

_shared/subagent-fallbacks.md 处理 P10 的三种失败场景：subagent 跑挂用 =[SUBAGENT FALLBACK]=、ref 验证失败用 =[UNVERIFIABLE]=、依赖 skill 不存在用 =[SKILL MISSING]=，标记降级不阻塞父流程。

2. Karpathy — failure modes

Karpathy 把 LLM agent 的头号失败模式定义为 false assumption：碰到歧义指令时 agent 不停下问，而是默默挑一个解释往下跑，等做了一阵才发现一开始就理解错了。

Loom 落地：=_shared/confusion-protocol.md= 是 P15 的标准 STOP 模板。所有 workflow 和架构类 skill 在「停止条件」节用链接指向它，而不是把内容复制到各自的 SKILL.md 里。 特别保留了负向边界来防止 protocol 过度触发，列出「以下情况不触发」：routine coding、obvious changes、完全可逆且作用范围清晰。

3. tw93 — 六层模型与锐边界

tw93 在 You Don't Know Claude Code 里把 Claude Code 拆成六层（CLAUDE.md → Tools/MCP → Skills → Hooks → Subagents → Verifiers）， 论断是：

"Use Tools and MCP to give Claude new actions, use Skills to provide reusable methods, use Subagents to isolate execution, use Hooks to enforce constraints. Blur these boundaries and the system becomes difficult to reason about."

"Wrong information is more dangerous than missing information."

"If you cannot articulate what 'done' looks like, the task is probably not ready for autonomous execution."

Loom 落地：

  • 每个 skill 末尾的 ## 验证闭环 节回答了 what does done look like
  • ## 绝对不做 节防止 /wrong information/，比如不让 Claude 用 try-catch 吞异常，也不让 subagent 内部写 fix
  • 编排器 skill（=autoplan= 和 ~safety~）都带 disable-model-invocation: true 关掉 auto-invoke，逼用户显式触发

4. gstack — 直接技术 upstream

gstack 是 loom 的直接技术 upstream。 loom 的写作原则 P11、P12、P15、P16 都来自 gstack 上游 commit 的实测发现：

原则 gstack commit 实测发现
P11 numbering = semantics b3eaffc /ship 用 3.5 或 8.75 这种分数步骤编号时，模型把这些当可选附录经常跳过；改成干净整数后跳过率显著下降
P12 explicit non-stop b3eaffc /ship 在 git push 之后直接停，后续 doc-sync 和 create-PR 被跳过 ~80%；加显式 You are NOT done 后跳过率显著下降
P15 confusion protocol b805aa0 Karpathy failure mode #1 的 inline gate；负向边界保留是关键
P16 specificity gate 2300067 「如果你无法指向具体 file:line 就是在编」，比「写得具体点」软指令强得多

loom 沿用了 gstack 的 dispatcher、=contracts.md= 渐进披露、subagent JSON 契约和 ID 前缀绑维度。

与 Waza 的关系

tw93 的 Waza README 把 gstack 和 Superpowers 列为反例：/too many skills, steep configuration curve/。Loom 是从 gstack 一脉演化出来的，所以在 Waza 视角下 loom 属于它反对的那一类。

但实测发现两个 Waza 没回答的问题：

  1. 19 个名词 skill 跑完不再推荐下一个 → 用户断链 tw93 的 skills chain manually, user decides transitions 在 Waza 8 个动词 skill 系统里能成立，因为用户记得住 /think 或者 /check 或者 /hunt~。但 loom 19 个名词 skill (=autoplan= 或者 ~plan-eng-review 或者 office-hours) 用户不会主动想到下一步该跑什么。 Loom 的回应是 P17 出口推荐：每个 skill 完成时输出 ## 下一步推荐 节， 列具体 skill 名和选择条件。仍是用户手动选，不自动派发，从而尊重 tw93 的 manual chaining 立场， 只是补上「给菜单」这层 affordance。tw93 自己说 /If you want Claude to stop and ask, give it a dedicated tool/， 出口推荐就是这个 dedicated tool 的实例化。
  2. 8 个动词 skill 维度被压扁 /check 一个 skill 同时审 CEO、eng、design、devex 四种维度时，每个维度都被压扁。 Loom 的回应：拆出 4 个独立 =plan-*-review=（CEO、eng、design、devex），各 4-9 维度专项打分，ID 前缀绑维度（CEO-NN、ENG-NN、DSG-NN、DX-NN），由 dispatcher（=autoplan=）协调四视角交叉。

*Loom 不反对 Waza*，它回答的是 Waza 没回答的问题：8 个 skill 之后怎么办。

Loom 隐喻

仓库名取自织机。loom 的核心结构都能对应到具体部件上：

织机部件 Loom 对应 文件或概念
经线 Warp — 固定纵向，地基 跨 skill 固定原则 _shared/writing-style.md=、=_shared/confusion-protocol.md=、=_shared/subagent-fallbacks.md
纬线 Weft — 横向穿织，主体 19 个 skill 本体 skills/<name>/SKILL.md
梭 Shuttle — 拉纬线穿过经线 dispatcher，把多个 skill 一次穿过 autoplan=、=safety
花本 Draft — 固定要织出的图样 JSON 契约 skills/<name>/contracts.md
综 Heddle — 控制经线升降 mode 参数，决定哪条线上来 mode=interactive vs mode=subagent
布 Cloth — 织出来的成品 整合输出 autoplan summary、investigate fix、qa report

Skill 目录

19 个 skill 按用途分组。每个 skill 一行触发条件，完整说明见 =skills/<name>/SKILL.md=。

设计与决策（实现前）

Skill 触发
think 知道要做什么但不知道怎么做时，给出 2-3 个候选方案、对比、推荐其中一个
office-hours 通过结构化提问判断功能是否值得做（interrogate 模式），或通过结构化步骤生成设计方案（brainstorm 模式）
design-shotgun 为同一个组件生成 3-5 种不同风格的实现供对比

计划审查（plan 阶段，dual-mode）

Skill 触发 维度
plan-ceo-review 从产品方向和用户价值角度评估 plan 4 种模式：扩展范围、选择性放大、收紧范围、挑战前提假设
plan-eng-review 从工程实现角度评估 plan 的可行性 9 个维度：架构、Schema、状态机、数据层、访问控制、错误处理、测试、上线回滚、性能
plan-design-review 从视觉、交互和信息架构角度评估 plan 9 个维度按 0-10 打分（目标清晰度、流程步数、错误反馈等）
plan-devex-review 评估 plan 落地后开发者维护这部分代码的难度 7 个维度 + 常见反模式清单

编排与协调（dispatcher）

Skill 触发
autoplan 依次调用 ceo、eng、design、devex 4 个 plan-*-review，整合冲突，输出统一建议
safety 在 Claude 执行破坏性命令前介入的工具；4 个子命令：careful 预检、freeze 暂停改动、unfreeze 解除暂停、guard 实时拦截

调查与质量

Skill 触发
investigate 调查 bug 的根因；分 5 阶段执行；定位不到根因之前禁止提交修复代码
qa 在真实浏览器里执行系统化测试；report 模式输出问题清单，fix 模式发现问题立即修改并 commit
design-review 用真实浏览器对已上线页面做视觉检查；按 8 个维度（Typography、颜色、间距、组件等）逐项过
browse 自包含的 headless 浏览器原语（playwright firefox/webkit），单 page daemon + 7 个 CLI 命令；qa / design-review 的底层依赖，也可独立使用做高频测试和页面查看

写作

Skill 触发
write 改稿、润色、去 AI 味；通用规则在 references/=，用户个人偏好通过 =learn 写到 memory/feedback_writing_*.md 自动加载

状态与元

Skill 触发
context-save 把当前 git 状态、决策记录、未完成工作写成可恢复快照
context-restore 从 context-save 的快照恢复；切分支并加载状态后继续工作
learn 管理 MEMORY.md 索引和 memory/*.md 文件
config-audit 审计 Claude Code 配置栈（CLAUDE.md、Skills、Hooks、MCP、Memory）；只诊断不修复
gemini Gemini CLI 的 3 种模式：review 独立审查代码、challenge 主动找设计漏洞、consult 持续咨询同一话题

写作原则索引

loom 用编号管理写作原则，下表列出当前 7 条：

编号 含义 出处 文件
P7 重复出现的内容提取到共享文件 loom 自身 _shared/
P10 用 subagent 隔离上下文，父只看 JSON 结论 Anthropic 1M context 博客 autoplan=、=investigate=、=qa
P11 必做步骤用整数编号，分数 / 字母编号会被读成可选附录 gstack b3eaffc _shared/writing-style.md
P12 在 git push 等自然停顿点后显式说「未结束」 gstack b3eaffc _shared/writing-style.md
P15 歧义场景下停下问用户，不要默默猜 gstack =b805aa0=（源 Karpathy） _shared/confusion-protocol.md
P16 任何 finding 必须能引用具体 file:line gstack 2300067 _shared/writing-style.md
P17 skill 完成后输出「下一步推荐」菜单 loom 自身 _shared/writing-style.md

_shared/ 三个文件：

  • writing-style.md — P11、P12、P16、P17 的全文和正反例
  • confusion-protocol.md — P15 的 STOP 模板和负向边界
  • subagent-fallbacks.md — [UNVERIFIABLE]=、[SUBAGENT FALLBACK]=、=[SKILL MISSING]= 三段标记的定义

_template/SKILL.md.tmpl — 起草新 skill 的骨架模板。

安装

clone 一次然后跑 installer。

git clone ssh://git@git.cytrogen.icu:22222/~cytrogen/loom <install-path>
cd <install-path>

Windows（不需要管理员权限，走 directory junction）：

powershell -ExecutionPolicy Bypass -File .\install.ps1

Linux / macOS：

./install.sh

Installer 在 ~/.claude/ 下为 skills/<name>/ 和 agents/<name>/ 分别建 symlink 或 junction。已存在的同名 entry 跳过不覆盖。=_= 开头的目录（=_shared/=、=_template/=）是 helper 不是 skill，installer 自动忽略。

更新 

cd <install-path>
git pull

不需要重装，因为 symlink/junction 指向 working tree，pull 后立即生效。只在新增 skill 或某个 skill 被重命名时才需要重跑 installer。

Windows 注意：如果某个 skill 被重命名或拆分（例如最近 checkpoint 拆成 context-save 和 context-restore=），旧 junction 会变成断链，=install.ps1 不会自动清理孤儿。需要手动删 =~/.claude/skills/<old-name>=（Linux/macOS 用 =rm=，Windows 用 =rmdir=），然后重跑 installer。

新增 skill

  1. 先读 _template/SKILL.md.tmpl 和 _shared/writing-style.md
  2. 在 skills/<name>/ 下起草，按模板填 frontmatter、何时使用、工作流、验证闭环、停止条件
  3. 如果是 dispatcher 类（要 dispatch subagent），同目录下再写 contracts.md 放 JSON 契约
  4. 本地跑 ./install.sh 把新 skill 链入 =~/.claude/skills/=，在 Claude Code 里调一下确认能触发
  5. git add skills/<name> && git commit && git push
  6. 在所有 checkout 了 loom 的机器上跑 =git pull && ./install.sh=（只链新 entry，不动旧的）

P7 提醒：如果新 skill 里出现的某段文字（fallback 行为、confusion 触发条件、反套话判据）已经在 _shared/ 里有了，那就引用别复制。

不该 commit 的文件

见 =.gitignore=。永远不要 commit：

  • =settings.local.json=（机器特定，可能含密钥）
  • =worktrees/=、=projects/=、=todos/=、=*.jsonl=（runtime 日志）