@mc-and-his-agents/loom-installer 0.1.9 → 0.1.11

package/README.md

@@ -1,5 +1,7 @@
 # @mc-and-his-agents/loom-installer
 
+Language: English | [中文版本](./README.zh-CN.md)
+
 Loom npm / npx installer.
 
 The primary install mode is the complete Loom plugin surface. Single-skill install remains available for compatibility and advanced use.
@@ -11,7 +13,7 @@ npx @mc-and-his-agents/loom-installer add plugin --host codex
 npx @mc-and-his-agents/loom-installer add plugin --host claude
 ```
 
-Single skill compatibility path:
+Single-skill compatibility path:
 
 ```bash
 npx @mc-and-his-agents/loom-installer add skill <skill-id> --host codex
@@ -35,13 +37,13 @@ Options:
 ## Requirements
 
 - Node `>=20`
-- Python `>=3.10`，推荐 `3.11+`
+- Python `>=3.10`, recommended `3.11+`
 
 ## Payload Model
 
-The published package includes a generated payload. The payload is generated from the canonical root `.codex-plugin/` and `skills/` sources during build / pack / publish.
+The published package includes a generated payload. The payload is generated from the canonical root `.codex-plugin/` and `skills/` sources during build, pack, and publish.
 
-Generated payload directories are not committed to git. The build step recreates them deterministically and `check:payload` verifies rebuild stability.
+Generated payload directories are not committed to git. The build step recreates them deterministically, and `check:payload` verifies rebuild stability.
 
 ## Release Notes
 
@@ -52,4 +54,4 @@ Release model:
 - PRs run gates but do not publish npm.
 - `main` is the only release truth source.
 - Loom repository releases and installer npm package versions are maintained separately.
-- publish 成功后再创建 `loom-installer-v<version>` git tag 与同名前缀的 GitHub Release.
+- Create the `loom-installer-v<version>` git tag and matching GitHub Release only after npm publish succeeds.

package/README.zh-CN.md

@@ -0,0 +1,57 @@
+# @mc-and-his-agents/loom-installer
+
+语言：中文 | [English version](./README.md)
+
+Loom 的 npm / npx installer。
+
+主安装模式是完整 Loom plugin surface。单 skill 安装仍然保留，用于兼容和高级场景。
+
+## Commands
+
+```bash
+npx @mc-and-his-agents/loom-installer add plugin --host codex
+npx @mc-and-his-agents/loom-installer add plugin --host claude
+```
+
+单 skill 兼容路径：
+
+```bash
+npx @mc-and-his-agents/loom-installer add skill <skill-id> --host codex
+npx @mc-and-his-agents/loom-installer add skill <skill-id> --host claude
+```
+
+也可以先固定 installer 版本：
+
+```bash
+npm install -D @mc-and-his-agents/loom-installer
+npx loom-installer add plugin --host codex
+```
+
+Options：
+
+- `--host codex|claude|auto`
+- `--target <repo-root>`
+- `--force`
+- `--json`
+
+## Requirements
+
+- Node `>=20`
+- Python `>=3.10`，推荐 `3.11+`
+
+## Payload Model
+
+发布包会包含生成出来的 payload。该 payload 会在 build、pack 和 publish 阶段，从 canonical root `.codex-plugin/` 与 `skills/` 源动态生成。
+
+生成出来的 payload 目录不会提交到 git。Build 步骤会以确定性方式重建它们，`check:payload` 会校验重建稳定性。
+
+## Release Notes
+
+发布只会从 `main` 进行。
+
+Release model：
+
+- PR 会运行 gates，但不会发布 npm。
+- `main` 是唯一 release truth source。
+- Loom 仓库 release 与 installer npm package version 分开维护。
+- 只有在 npm publish 成功后，才创建 `loom-installer-v<version>` git tag 和同名前缀的 GitHub Release。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mc-and-his-agents/loom-installer",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Node installer for Loom plugin and single-skill installation surfaces.",
   "type": "module",
   "bin": {

package/payload/manifest.json

@@ -2,9 +2,9 @@
   "schema_version": "loom-installer-payload/v1",
   "loom_version": "0.4.0",
   "source_repository": "https://github.com/MC-and-his-Agents/Loom",
-  "source_commit": "177ddf6ce8fc69cbea65bb5377d34cdb9a3b6624",
+  "source_commit": "4f6a4074d02557304018e9f063425f974d6a08cf",
   "source_ref": "main",
-  "built_at": "2026-04-24T14:51:38+08:00",
+  "built_at": "2026-04-25T11:49:46+08:00",
   "runtime": {
     "python_minimum": "3.10",
     "python_recommended": "3.11+"
@@ -363,8 +363,13 @@
     },
     {
       "path": "plugin/loom/skills/README.md",
-      "bytes": 4132,
-      "sha256": "ad5f5bf3ab9944bdd22018b5af77d8c5ab3f3e89ea282e5d5a679e65503c6e19"
+      "bytes": 4330,
+      "sha256": "907c801ec6d20ee3a4a8d90e137d432e9512aae96c765d28b055e7952e1e0dfc"
+    },
+    {
+      "path": "plugin/loom/skills/README.zh-CN.md",
+      "bytes": 3986,
+      "sha256": "90ba899919bf2329098fe72a7993edc6c5a6ba1f04ed820c2a643f89c95f65eb"
     },
     {
       "path": "plugin/loom/skills/registry.json",
@@ -623,13 +628,13 @@
     },
     {
       "path": "plugin/loom/skills/shared/scripts/loom_check.py",
-      "bytes": 248115,
-      "sha256": "9b6f6af1f63bd9af6f1b4f24356bfdf5e52edaa82bbb2b2ade040e9bff951039"
+      "bytes": 253737,
+      "sha256": "9ada27e8f88d01940e7f70112301f1c6c78ffa362f5159abba2a44ae445266ac"
     },
     {
       "path": "plugin/loom/skills/shared/scripts/loom_flow.py",
-      "bytes": 248662,
-      "sha256": "69263e7c763f45a0a4f29a2c43e12e08b2d1fffd2cf3a63dea41aec3d1543597"
+      "bytes": 259768,
+      "sha256": "f11062993fe565160cdc2910e981e9a601d0fcafcbe16dd0072d63acf39d67b0"
     },
     {
       "path": "plugin/loom/skills/shared/scripts/loom_init.py",
@@ -943,8 +948,13 @@
     },
     {
       "path": "skills/loom-adopt/.loom-runtime/README.md",
-      "bytes": 4132,
-      "sha256": "ad5f5bf3ab9944bdd22018b5af77d8c5ab3f3e89ea282e5d5a679e65503c6e19"
+      "bytes": 4330,
+      "sha256": "907c801ec6d20ee3a4a8d90e137d432e9512aae96c765d28b055e7952e1e0dfc"
+    },
+    {
+      "path": "skills/loom-adopt/.loom-runtime/README.zh-CN.md",
+      "bytes": 3986,
+      "sha256": "90ba899919bf2329098fe72a7993edc6c5a6ba1f04ed820c2a643f89c95f65eb"
     },
     {
       "path": "skills/loom-adopt/.loom-runtime/registry.json",
@@ -1203,13 +1213,13 @@
     },
     {
       "path": "skills/loom-adopt/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 248115,
-      "sha256": "9b6f6af1f63bd9af6f1b4f24356bfdf5e52edaa82bbb2b2ade040e9bff951039"
+      "bytes": 253737,
+      "sha256": "9ada27e8f88d01940e7f70112301f1c6c78ffa362f5159abba2a44ae445266ac"
     },
     {
       "path": "skills/loom-adopt/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 248662,
-      "sha256": "69263e7c763f45a0a4f29a2c43e12e08b2d1fffd2cf3a63dea41aec3d1543597"
+      "bytes": 259768,
+      "sha256": "f11062993fe565160cdc2910e981e9a601d0fcafcbe16dd0072d63acf39d67b0"
     },
     {
       "path": "skills/loom-adopt/.loom-runtime/shared/scripts/loom_init.py",
@@ -1553,8 +1563,13 @@
     },
     {
       "path": "skills/loom-handoff/.loom-runtime/README.md",
-      "bytes": 4132,
-      "sha256": "ad5f5bf3ab9944bdd22018b5af77d8c5ab3f3e89ea282e5d5a679e65503c6e19"
+      "bytes": 4330,
+      "sha256": "907c801ec6d20ee3a4a8d90e137d432e9512aae96c765d28b055e7952e1e0dfc"
+    },
+    {
+      "path": "skills/loom-handoff/.loom-runtime/README.zh-CN.md",
+      "bytes": 3986,
+      "sha256": "90ba899919bf2329098fe72a7993edc6c5a6ba1f04ed820c2a643f89c95f65eb"
     },
     {
       "path": "skills/loom-handoff/.loom-runtime/registry.json",
@@ -1813,13 +1828,13 @@
     },
     {
       "path": "skills/loom-handoff/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 248115,
-      "sha256": "9b6f6af1f63bd9af6f1b4f24356bfdf5e52edaa82bbb2b2ade040e9bff951039"
+      "bytes": 253737,
+      "sha256": "9ada27e8f88d01940e7f70112301f1c6c78ffa362f5159abba2a44ae445266ac"
     },
     {
       "path": "skills/loom-handoff/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 248662,
-      "sha256": "69263e7c763f45a0a4f29a2c43e12e08b2d1fffd2cf3a63dea41aec3d1543597"
+      "bytes": 259768,
+      "sha256": "f11062993fe565160cdc2910e981e9a601d0fcafcbe16dd0072d63acf39d67b0"
     },
     {
       "path": "skills/loom-handoff/.loom-runtime/shared/scripts/loom_init.py",
@@ -2163,8 +2178,13 @@
     },
     {
       "path": "skills/loom-init/.loom-runtime/README.md",
-      "bytes": 4132,
-      "sha256": "ad5f5bf3ab9944bdd22018b5af77d8c5ab3f3e89ea282e5d5a679e65503c6e19"
+      "bytes": 4330,
+      "sha256": "907c801ec6d20ee3a4a8d90e137d432e9512aae96c765d28b055e7952e1e0dfc"
+    },
+    {
+      "path": "skills/loom-init/.loom-runtime/README.zh-CN.md",
+      "bytes": 3986,
+      "sha256": "90ba899919bf2329098fe72a7993edc6c5a6ba1f04ed820c2a643f89c95f65eb"
     },
     {
       "path": "skills/loom-init/.loom-runtime/registry.json",
@@ -2423,13 +2443,13 @@
     },
     {
       "path": "skills/loom-init/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 248115,
-      "sha256": "9b6f6af1f63bd9af6f1b4f24356bfdf5e52edaa82bbb2b2ade040e9bff951039"
+      "bytes": 253737,
+      "sha256": "9ada27e8f88d01940e7f70112301f1c6c78ffa362f5159abba2a44ae445266ac"
     },
     {
       "path": "skills/loom-init/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 248662,
-      "sha256": "69263e7c763f45a0a4f29a2c43e12e08b2d1fffd2cf3a63dea41aec3d1543597"
+      "bytes": 259768,
+      "sha256": "f11062993fe565160cdc2910e981e9a601d0fcafcbe16dd0072d63acf39d67b0"
     },
     {
       "path": "skills/loom-init/.loom-runtime/shared/scripts/loom_init.py",
@@ -2778,8 +2798,13 @@
     },
     {
       "path": "skills/loom-merge-ready/.loom-runtime/README.md",
-      "bytes": 4132,
-      "sha256": "ad5f5bf3ab9944bdd22018b5af77d8c5ab3f3e89ea282e5d5a679e65503c6e19"
+      "bytes": 4330,
+      "sha256": "907c801ec6d20ee3a4a8d90e137d432e9512aae96c765d28b055e7952e1e0dfc"
+    },
+    {
+      "path": "skills/loom-merge-ready/.loom-runtime/README.zh-CN.md",
+      "bytes": 3986,
+      "sha256": "90ba899919bf2329098fe72a7993edc6c5a6ba1f04ed820c2a643f89c95f65eb"
     },
     {
       "path": "skills/loom-merge-ready/.loom-runtime/registry.json",
@@ -3038,13 +3063,13 @@
     },
     {
       "path": "skills/loom-merge-ready/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 248115,
-      "sha256": "9b6f6af1f63bd9af6f1b4f24356bfdf5e52edaa82bbb2b2ade040e9bff951039"
+      "bytes": 253737,
+      "sha256": "9ada27e8f88d01940e7f70112301f1c6c78ffa362f5159abba2a44ae445266ac"
     },
     {
       "path": "skills/loom-merge-ready/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 248662,
-      "sha256": "69263e7c763f45a0a4f29a2c43e12e08b2d1fffd2cf3a63dea41aec3d1543597"
+      "bytes": 259768,
+      "sha256": "f11062993fe565160cdc2910e981e9a601d0fcafcbe16dd0072d63acf39d67b0"
     },
     {
       "path": "skills/loom-merge-ready/.loom-runtime/shared/scripts/loom_init.py",
@@ -3388,8 +3413,13 @@
     },
     {
       "path": "skills/loom-pre-review/.loom-runtime/README.md",
-      "bytes": 4132,
-      "sha256": "ad5f5bf3ab9944bdd22018b5af77d8c5ab3f3e89ea282e5d5a679e65503c6e19"
+      "bytes": 4330,
+      "sha256": "907c801ec6d20ee3a4a8d90e137d432e9512aae96c765d28b055e7952e1e0dfc"
+    },
+    {
+      "path": "skills/loom-pre-review/.loom-runtime/README.zh-CN.md",
+      "bytes": 3986,
+      "sha256": "90ba899919bf2329098fe72a7993edc6c5a6ba1f04ed820c2a643f89c95f65eb"
     },
     {
       "path": "skills/loom-pre-review/.loom-runtime/registry.json",
@@ -3648,13 +3678,13 @@
     },
     {
       "path": "skills/loom-pre-review/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 248115,
-      "sha256": "9b6f6af1f63bd9af6f1b4f24356bfdf5e52edaa82bbb2b2ade040e9bff951039"
+      "bytes": 253737,
+      "sha256": "9ada27e8f88d01940e7f70112301f1c6c78ffa362f5159abba2a44ae445266ac"
     },
     {
       "path": "skills/loom-pre-review/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 248662,
-      "sha256": "69263e7c763f45a0a4f29a2c43e12e08b2d1fffd2cf3a63dea41aec3d1543597"
+      "bytes": 259768,
+      "sha256": "f11062993fe565160cdc2910e981e9a601d0fcafcbe16dd0072d63acf39d67b0"
     },
     {
       "path": "skills/loom-pre-review/.loom-runtime/shared/scripts/loom_init.py",
@@ -3998,8 +4028,13 @@
     },
     {
       "path": "skills/loom-resume/.loom-runtime/README.md",
-      "bytes": 4132,
-      "sha256": "ad5f5bf3ab9944bdd22018b5af77d8c5ab3f3e89ea282e5d5a679e65503c6e19"
+      "bytes": 4330,
+      "sha256": "907c801ec6d20ee3a4a8d90e137d432e9512aae96c765d28b055e7952e1e0dfc"
+    },
+    {
+      "path": "skills/loom-resume/.loom-runtime/README.zh-CN.md",
+      "bytes": 3986,
+      "sha256": "90ba899919bf2329098fe72a7993edc6c5a6ba1f04ed820c2a643f89c95f65eb"
     },
     {
       "path": "skills/loom-resume/.loom-runtime/registry.json",
@@ -4258,13 +4293,13 @@
     },
     {
       "path": "skills/loom-resume/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 248115,
-      "sha256": "9b6f6af1f63bd9af6f1b4f24356bfdf5e52edaa82bbb2b2ade040e9bff951039"
+      "bytes": 253737,
+      "sha256": "9ada27e8f88d01940e7f70112301f1c6c78ffa362f5159abba2a44ae445266ac"
     },
     {
       "path": "skills/loom-resume/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 248662,
-      "sha256": "69263e7c763f45a0a4f29a2c43e12e08b2d1fffd2cf3a63dea41aec3d1543597"
+      "bytes": 259768,
+      "sha256": "f11062993fe565160cdc2910e981e9a601d0fcafcbe16dd0072d63acf39d67b0"
     },
     {
       "path": "skills/loom-resume/.loom-runtime/shared/scripts/loom_init.py",
@@ -4608,8 +4643,13 @@
     },
     {
       "path": "skills/loom-retire/.loom-runtime/README.md",
-      "bytes": 4132,
-      "sha256": "ad5f5bf3ab9944bdd22018b5af77d8c5ab3f3e89ea282e5d5a679e65503c6e19"
+      "bytes": 4330,
+      "sha256": "907c801ec6d20ee3a4a8d90e137d432e9512aae96c765d28b055e7952e1e0dfc"
+    },
+    {
+      "path": "skills/loom-retire/.loom-runtime/README.zh-CN.md",
+      "bytes": 3986,
+      "sha256": "90ba899919bf2329098fe72a7993edc6c5a6ba1f04ed820c2a643f89c95f65eb"
     },
     {
       "path": "skills/loom-retire/.loom-runtime/registry.json",
@@ -4868,13 +4908,13 @@
     },
     {
       "path": "skills/loom-retire/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 248115,
-      "sha256": "9b6f6af1f63bd9af6f1b4f24356bfdf5e52edaa82bbb2b2ade040e9bff951039"
+      "bytes": 253737,
+      "sha256": "9ada27e8f88d01940e7f70112301f1c6c78ffa362f5159abba2a44ae445266ac"
     },
     {
       "path": "skills/loom-retire/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 248662,
-      "sha256": "69263e7c763f45a0a4f29a2c43e12e08b2d1fffd2cf3a63dea41aec3d1543597"
+      "bytes": 259768,
+      "sha256": "f11062993fe565160cdc2910e981e9a601d0fcafcbe16dd0072d63acf39d67b0"
     },
     {
       "path": "skills/loom-retire/.loom-runtime/shared/scripts/loom_init.py",
@@ -5218,8 +5258,13 @@
     },
     {
       "path": "skills/loom-review/.loom-runtime/README.md",
-      "bytes": 4132,
-      "sha256": "ad5f5bf3ab9944bdd22018b5af77d8c5ab3f3e89ea282e5d5a679e65503c6e19"
+      "bytes": 4330,
+      "sha256": "907c801ec6d20ee3a4a8d90e137d432e9512aae96c765d28b055e7952e1e0dfc"
+    },
+    {
+      "path": "skills/loom-review/.loom-runtime/README.zh-CN.md",
+      "bytes": 3986,
+      "sha256": "90ba899919bf2329098fe72a7993edc6c5a6ba1f04ed820c2a643f89c95f65eb"
     },
     {
       "path": "skills/loom-review/.loom-runtime/registry.json",
@@ -5478,13 +5523,13 @@
     },
     {
       "path": "skills/loom-review/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 248115,
-      "sha256": "9b6f6af1f63bd9af6f1b4f24356bfdf5e52edaa82bbb2b2ade040e9bff951039"
+      "bytes": 253737,
+      "sha256": "9ada27e8f88d01940e7f70112301f1c6c78ffa362f5159abba2a44ae445266ac"
     },
     {
       "path": "skills/loom-review/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 248662,
-      "sha256": "69263e7c763f45a0a4f29a2c43e12e08b2d1fffd2cf3a63dea41aec3d1543597"
+      "bytes": 259768,
+      "sha256": "f11062993fe565160cdc2910e981e9a601d0fcafcbe16dd0072d63acf39d67b0"
     },
     {
       "path": "skills/loom-review/.loom-runtime/shared/scripts/loom_init.py",
@@ -5828,8 +5873,13 @@
     },
     {
       "path": "skills/loom-spec-review/.loom-runtime/README.md",
-      "bytes": 4132,
-      "sha256": "ad5f5bf3ab9944bdd22018b5af77d8c5ab3f3e89ea282e5d5a679e65503c6e19"
+      "bytes": 4330,
+      "sha256": "907c801ec6d20ee3a4a8d90e137d432e9512aae96c765d28b055e7952e1e0dfc"
+    },
+    {
+      "path": "skills/loom-spec-review/.loom-runtime/README.zh-CN.md",
+      "bytes": 3986,
+      "sha256": "90ba899919bf2329098fe72a7993edc6c5a6ba1f04ed820c2a643f89c95f65eb"
     },
     {
       "path": "skills/loom-spec-review/.loom-runtime/registry.json",
@@ -6088,13 +6138,13 @@
     },
     {
       "path": "skills/loom-spec-review/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 248115,
-      "sha256": "9b6f6af1f63bd9af6f1b4f24356bfdf5e52edaa82bbb2b2ade040e9bff951039"
+      "bytes": 253737,
+      "sha256": "9ada27e8f88d01940e7f70112301f1c6c78ffa362f5159abba2a44ae445266ac"
     },
     {
       "path": "skills/loom-spec-review/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 248662,
-      "sha256": "69263e7c763f45a0a4f29a2c43e12e08b2d1fffd2cf3a63dea41aec3d1543597"
+      "bytes": 259768,
+      "sha256": "f11062993fe565160cdc2910e981e9a601d0fcafcbe16dd0072d63acf39d67b0"
     },
     {
       "path": "skills/loom-spec-review/.loom-runtime/shared/scripts/loom_init.py",

package/payload/plugin/loom/skills/README.md

@@ -1,22 +1,24 @@
 # Skills
 
+Language: English | [中文版本](./README.zh-CN.md)
+
 `skills/` is the canonical skills library for Loom.
 
-When Loom is installed through Codex native skill discovery, a host plugin, or the npm installer, this directory is the user-facing execution surface. The methodology and architecture docs stay behind this layer; users should normally enter through skills, not through internal governance documents.
+When Loom is installed through Codex native skill discovery, a host plugin, or the npm installer, this directory is the user-facing execution surface. Methodology and architecture documents stay behind this layer; users should enter through skills instead of internal governance docs.
 
-默认从 `loom-init` 开始。它是 Loom 唯一的 root entry，负责两件事：
+By default, start from `loom-init`. It is the unique root entry for Loom and is responsible for two things:
 
-- 初始化 Loom，或把 Loom retrofit 进既有仓库
-- 在没有显式指定场景 skill 时，根据任务信号把执行者导向正确场景
+- initialize Loom or retrofit Loom into an existing repository
+- route the operator to the correct scenario skill when no explicit skill was named
 
-当前 `skills/` 层消费的是新的强治理控制面，固定约束如下：
+The `skills/` layer consumes the current strong-governance control plane with these fixed constraints:
 
-- `Work Item` 是唯一正式执行入口
-- 命中 formal spec 的事项，必须先通过 `spec gate`
-- 执行放行链固定收敛为 `spec gate -> build gate -> review gate -> merge gate`
-- `status control plane` 只读取并汇总事实链与宿主控制面，不新增 authored 真相
-- profile maturity 按 `light -> standard -> strong` 升级；事项成熟度仍按治理状态机推进
-- merge 由 GitHub 或等价宿主控制面受控执行；Loom 只消费并汇总 `GitHub controlled merge` 的前置条件
+- `Work Item` is the only formal execution entry
+- tasks that hit the formal spec path must pass the `spec gate` first
+- the release chain converges on `spec gate -> build gate -> review gate -> merge gate`
+- `status control plane` only reads and summarizes fact-chain and host control-plane truth, and does not author a second source of truth
+- profile maturity upgrades through `light -> standard -> strong`, while item maturity still advances through the governance state machine
+- merge is controlled by GitHub or an equivalent host control plane; Loom only consumes and summarizes the prerequisites for GitHub controlled merge
 
 ## Skills Library
 

package/payload/plugin/loom/skills/README.zh-CN.md

@@ -0,0 +1,92 @@
+# Skills
+
+语言：中文 | [English version](./README.md)
+
+`skills/` 是 Loom 的 canonical skills library。
+
+当 Loom 通过 Codex 原生 skill discovery、宿主 plugin 或 npm installer 安装时，这个目录就是面向用户的执行表面。方法论和架构文档位于这层之后，用户通常应该从 skills 进入，而不是先读内部治理文档。
+
+默认从 `loom-init` 开始。它是 Loom 唯一的 root entry，负责两件事：
+
+- 初始化 Loom，或把 Loom retrofit 进既有仓库
+- 在没有显式指定场景 skill 时，根据任务信号把执行者导向正确场景
+
+当前 `skills/` 层消费的是新的强治理控制面，固定约束如下：
+
+- `Work Item` 是唯一正式执行入口
+- 命中 formal spec 的事项，必须先通过 `spec gate`
+- 执行放行链固定收敛为 `spec gate -> build gate -> review gate -> merge gate`
+- `status control plane` 只读取并汇总事实链与宿主控制面，不新增 authored 真相
+- profile maturity 按 `light -> standard -> strong` 升级；事项成熟度仍按治理状态机推进
+- merge 由 GitHub 或等价宿主控制面受控执行；Loom 只消费并汇总 `GitHub controlled merge` 的前置条件
+
+## Skills Library
+
+Loom 暴露一个 root entry 和八个 scenario skills：
+
+| Skill | 作用 |
+| --- | --- |
+| `loom-init` | Root entry；负责初始化和路由。 |
+| `loom-adopt` | 初始化新仓库，或把 Loom retrofit 到既有仓库。 |
+| `loom-resume` | 恢复上下文并继续执行。 |
+| `loom-pre-review` | 在正式 review 前检查 readiness。 |
+| `loom-spec-review` | 审查 formal spec 路径，并产出后续 gate 消费的 `spec gate`。 |
+| `loom-review` | 执行正式 review 并记录输出。 |
+| `loom-handoff` | 写出 handoff 点和下一步状态。 |
+| `loom-retire` | 清理或退场当前工作现场。 |
+| `loom-merge-ready` | 在 GitHub controlled merge 前执行最终 `merge gate` 汇总。 |
+
+## Entry Model
+
+Loom 支持两种入口模式：
+
+- 显式入口：用户直接指定某个场景 skill。
+- 路由入口：用户从 `loom-init` 开始，由 `loom-init` 根据任务信号选择场景。
+
+如果任务信号不完整、存在冲突，或缺少稳定执行所需的最小输入，应回退到 `loom-init`，并要求补齐最小缺失信号。稳定路由规则见 [route-matrix.md](./route-matrix.md)。
+
+路由只决定场景 skill，不替代稳定控制面：
+
+- 执行入口仍然绑定在 `Work Item`
+- gate 仍然绑定在共享 `gate chain`
+- 状态读取仍然绑定在共享 `status control plane`
+- merge 仍然由宿主平台控制面执行
+
+## Install Model
+
+主安装路径是完整 Loom skills library：
+
+```bash
+git clone https://github.com/MC-and-his-Agents/Loom.git ~/.codex/loom
+mkdir -p ~/.agents/skills
+ln -s ~/.codex/loom/skills ~/.agents/skills/loom
+```
+
+npm installer 也可以安装完整 plugin surface：
+
+```bash
+npx @mc-and-his-agents/loom-installer add plugin --host codex
+npx @mc-and-his-agents/loom-installer add plugin --host claude
+```
+
+## Advanced / Compatibility
+
+单 skill 安装保留为高级兼容路径，但不再是默认用户路径：
+
+```bash
+npx @mc-and-his-agents/loom-installer add skill <skill-id> --host codex
+npx @mc-and-his-agents/loom-installer add skill <skill-id> --host claude
+```
+
+单独安装的 skill 只会向宿主暴露该 skill 本身。除非安装的就是 `loom-init`，否则它不会暴露完整的 `loom-init` 路由面，也不应被表述成完整的 Loom 体验。
+
+## Internal Contracts
+
+以下文件属于 runtime contract，应保持稳定：
+
+- [registry.json](./registry.json)
+- [install-layout.json](./install-layout.json)
+- [upgrade-contract.json](./upgrade-contract.json)
+- [distribution-and-adapter-contract.md](./distribution-and-adapter-contract.md)
+
+共享 runtime scripts、assets 和 references 位于 [shared/](./shared/)。它们会被 scenario skills 和 release tooling 一起消费，用来生成 plugin 或 single-skill payload。