From d3be94fb9b30e7386b802625c30e6d0de039ea02 Mon Sep 17 00:00:00 2001 From: yaojingang Date: Mon, 6 Apr 2026 11:02:27 +0800 Subject: [PATCH] docs: simplify hero architecture diagram --- README.md | 50 +++++++++++--------------------------------- docs/README.fr-FR.md | 50 +++++++++++--------------------------------- docs/README.ja-JP.md | 50 +++++++++++--------------------------------- docs/README.ru-RU.md | 50 +++++++++++--------------------------------- docs/README.zh-CN.md | 50 +++++++++++--------------------------------- 5 files changed, 60 insertions(+), 190 deletions(-) diff --git a/README.md b/README.md index 473b7d2..04714c1 100644 --- a/README.md +++ b/README.md @@ -24,49 +24,23 @@ It turns rough workflows, transcripts, prompts, notes, and runbooks into reusabl ## Architecture -The system is intentionally layered so users can understand it from top to bottom: route first, choose method second, validate third, then package and govern the result. +Hero view: turn messy operational input into a governed, reusable skill package through one compact flow. ```mermaid -flowchart TD - A["Inputs
workflows / prompts / transcripts / docs / notes"] --> B["Router
SKILL.md"] - B --> C["Method Layer
references/"] - B --> D["Authoring Flow
scripts/yao.py"] - - C --> C1["Archetypes"] - C --> C2["Gate Selection"] - C --> C3["Non-Skill Decision"] - C --> C4["Operating Modes"] - C --> C5["Governance"] - C --> C6["Resource Boundaries"] - - D --> E["Create
init / template"] - D --> F["Validate
lint / boundary / governance"] - D --> G["Evaluate
trigger / suites / judge / confusion"] - D --> H["Promote
promotion policy / candidate registry"] - D --> I["Package
neutral source -> target adapters"] - D --> J["Report
history / scorecards / context / portability"] - - E --> K["Skill Package"] - F --> K - G --> L["evals/"] - H --> M["reports/"] - I --> N["dist/ or target outputs"] - - K --> K1["SKILL.md"] - K --> K2["agents/interface.yaml"] - K --> K3["manifest.json"] - K --> K4["optional references / scripts / evals / reports"] - - L --> M +flowchart LR + A["Inputs
workflow / prompt / transcript / docs / notes"] --> B["Route
SKILL.md"] + B --> C["Design
method + gates"] + C --> D["Run
create / validate / eval / promote"] + D --> E["Outputs
skill package + reports + adapters"] ``` -Read the diagram in five layers: +Read it in 10 seconds: -- **Inputs**: rough operational material becomes the source for a reusable skill package. -- **Router**: `SKILL.md` stays small and decides boundary, mode, and output contract first. -- **Method layer**: doctrine files explain whether the request should become a skill and which quality gates it deserves. -- **Authoring flow**: the unified CLI turns creation, validation, optimization, promotion, reporting, and packaging into one path. -- **Evidence and outputs**: the result is not only a skill package, but also eval artifacts, governance signals, portability outputs, and iteration history. +- **Inputs**: start from rough operational material. +- **Route**: define boundary and trigger in a lean `SKILL.md`. +- **Design**: choose the right archetype, gates, and resource split. +- **Run**: use the unified CLI to build, validate, optimize, and promote. +- **Outputs**: ship a reusable skill plus evidence, governance signals, and portability artifacts. ## Quick Start diff --git a/docs/README.fr-FR.md b/docs/README.fr-FR.md index 5f99eeb..53d0992 100644 --- a/docs/README.fr-FR.md +++ b/docs/README.fr-FR.md @@ -14,49 +14,23 @@ Il transforme des workflows bruts, des transcripts, des prompts, des notes et de ## Architecture -Le système est volontairement organisé par couches afin qu'un nouveau venu puisse le lire de haut en bas : d'abord le routage, ensuite la méthode, puis la validation, et enfin le packaging et la gouvernance. +En version hero, le système tient sur une seule ligne : transformer une entrée brouillonne en skill package gouverné et réutilisable. ```mermaid -flowchart TD - A["Entrées
workflows / prompts / transcripts / docs / notes"] --> B["Routeur
SKILL.md"] - B --> C["Couche méthode
references/"] - B --> D["Flux auteur
scripts/yao.py"] - - C --> C1["Skill Archetype"] - C --> C2["Gate Selection"] - C --> C3["Non-Skill Decision"] - C --> C4["Operating Modes"] - C --> C5["Governance"] - C --> C6["Resource Boundaries"] - - D --> E["Création
init / template"] - D --> F["Validation
lint / boundary / governance"] - D --> G["Évaluation
trigger / suites / judge / confusion"] - D --> H["Promotion
promotion policy / candidate registry"] - D --> I["Packaging
neutral source -> target adapters"] - D --> J["Rapports
history / scorecards / context / portability"] - - E --> K["Skill Package"] - F --> K - G --> L["evals/"] - H --> M["reports/"] - I --> N["dist/ ou sorties cibles"] - - K --> K1["SKILL.md"] - K --> K2["agents/interface.yaml"] - K --> K3["manifest.json"] - K --> K4["references / scripts / evals / reports optionnels"] - - L --> M +flowchart LR + A["Entrées
workflow / prompt / transcript / docs / notes"] --> B["Routage
SKILL.md"] + B --> C["Conception
méthode + garde-fous"] + C --> D["Exécution
create / validate / eval / promote"] + D --> E["Sorties
skill package + rapports + adapters"] ``` -On peut lire ce schéma en cinq couches : +Lecture en 10 secondes : -- **Couche d'entrée** : les matériaux opérationnels bruts servent de source au futur skill package. -- **Couche de routage** : `SKILL.md` reste léger et définit d'abord les frontières, le mode et le contrat de sortie. -- **Couche méthode** : les documents de doctrine déterminent si la demande mérite d'être skillifiée et quels garde-fous elle doit recevoir. -- **Couche de flux auteur** : le CLI unifié relie création, validation, optimisation, promotion, reporting et packaging. -- **Couche preuves et sorties** : le résultat n'est pas seulement un skill package, mais aussi des evals, des signaux de gouvernance, des sorties de portabilité et un historique d'itération. +- **Entrées** : on part de workflows, prompts, documents et notes dispersés. +- **Routage** : un `SKILL.md` léger définit d'abord la frontière et le déclenchement. +- **Conception** : on choisit le bon archetype, les bons gates et la bonne séparation des ressources. +- **Exécution** : la CLI unifiée construit, valide, optimise et promeut le skill. +- **Sorties** : on obtient un skill package réutilisable avec ses preuves d'évaluation, de gouvernance et de portabilité. ## Quick Start diff --git a/docs/README.ja-JP.md b/docs/README.ja-JP.md index b6f187b..4ad4218 100644 --- a/docs/README.ja-JP.md +++ b/docs/README.ja-JP.md @@ -14,49 +14,23 @@ ## アーキテクチャ -このシステムは層構造になっており、新しい利用者でも上から順に理解できます。最初に route を決め、次に method を選び、その後に検証し、最後に package と governance を扱います。 +Hero 版では、全体の流れは 1 本です。ばらばらの入力を、統制された再利用可能な skill package に変えます。 ```mermaid -flowchart TD - A["入力
workflow / prompt / transcript / docs / notes"] --> B["ルーター
SKILL.md"] - B --> C["メソッド層
references/"] - B --> D["作者フロー
scripts/yao.py"] - - C --> C1["Skill Archetype"] - C --> C2["Gate Selection"] - C --> C3["Non-Skill Decision"] - C --> C4["Operating Modes"] - C --> C5["Governance"] - C --> C6["Resource Boundaries"] - - D --> E["作成
init / template"] - D --> F["検証
lint / boundary / governance"] - D --> G["評価
trigger / suites / judge / confusion"] - D --> H["昇格
promotion policy / candidate registry"] - D --> I["パッケージ化
neutral source -> target adapters"] - D --> J["レポート
history / scorecards / context / portability"] - - E --> K["Skill Package"] - F --> K - G --> L["evals/"] - H --> M["reports/"] - I --> N["dist/ または target outputs"] - - K --> K1["SKILL.md"] - K --> K2["agents/interface.yaml"] - K --> K3["manifest.json"] - K --> K4["optional references / scripts / evals / reports"] - - L --> M +flowchart LR + A["入力
workflow / prompt / transcript / docs / notes"] --> B["ルート定義
SKILL.md"] + B --> C["設計
method + gates"] + C --> D["実行
create / validate / eval / promote"] + D --> E["出力
skill package + reports + adapters"] ``` -この図は 5 つの層として読むとわかりやすいです。 +10 秒で読むならこうです。 -- **入力層**: 断片的な運用資料を skill 化の原材料にします。 -- **ルーター層**: `SKILL.md` は軽量のまま、境界、モード、出力契約を先に決めます。 -- **メソッド層**: method 文書が、skill 化すべきか、どの quality gate が必要かを決めます。 -- **作者フロー層**: 統一 CLI が作成、検証、最適化、昇格、レポート、パッケージ化を一つの流れにします。 -- **証拠と出力層**: 最終成果は skill package だけでなく、eval 結果、governance signal、portability 出力、iteration history も含みます。 +- **入力**: workflow、prompt、文書、メモなどの粗い素材から始めます。 +- **ルート定義**: まず軽量な `SKILL.md` で境界と trigger を決めます。 +- **設計**: 適切な archetype、gate、資源の分割を選びます。 +- **実行**: 統一 CLI で作成、検証、最適化、昇格を進めます。 +- **出力**: 最終的に skill package と、評価・ガバナンス・移植性の証拠が残ります。 ## Quick Start diff --git a/docs/README.ru-RU.md b/docs/README.ru-RU.md index b2ba67f..bc47d09 100644 --- a/docs/README.ru-RU.md +++ b/docs/README.ru-RU.md @@ -14,49 +14,23 @@ ## Архитектура -Система специально построена слоями, чтобы новый пользователь мог понять ее сверху вниз: сначала routing, затем method, потом validation, а уже после этого packaging и governance. +В hero-версии вся система сводится к одной линии: превратить разрозненный вход в управляемый и переиспользуемый skill package. ```mermaid -flowchart TD - A["Входы
workflows / prompts / transcripts / docs / notes"] --> B["Router
SKILL.md"] - B --> C["Method layer
references/"] - B --> D["Authoring flow
scripts/yao.py"] - - C --> C1["Skill Archetype"] - C --> C2["Gate Selection"] - C --> C3["Non-Skill Decision"] - C --> C4["Operating Modes"] - C --> C5["Governance"] - C --> C6["Resource Boundaries"] - - D --> E["Создание
init / template"] - D --> F["Проверка
lint / boundary / governance"] - D --> G["Оценка
trigger / suites / judge / confusion"] - D --> H["Промоушен
promotion policy / candidate registry"] - D --> I["Упаковка
neutral source -> target adapters"] - D --> J["Отчеты
history / scorecards / context / portability"] - - E --> K["Skill Package"] - F --> K - G --> L["evals/"] - H --> M["reports/"] - I --> N["dist/ или target outputs"] - - K --> K1["SKILL.md"] - K --> K2["agents/interface.yaml"] - K --> K3["manifest.json"] - K --> K4["optional references / scripts / evals / reports"] - - L --> M +flowchart LR + A["Входы
workflow / prompt / transcript / docs / notes"] --> B["Маршрут
SKILL.md"] + B --> C["Проектирование
method + gates"] + C --> D["Исполнение
create / validate / eval / promote"] + D --> E["Выходы
skill package + reports + adapters"] ``` -Эту схему удобнее читать как 5 слоев: +Как читать это за 10 секунд: -- **Слой входов**: разрозненные операционные материалы становятся сырьем для будущего skill package. -- **Слой routing**: `SKILL.md` остается легким и сначала определяет границы, режим и output contract. -- **Слой method**: doctrinal docs определяют, стоит ли вообще skill-изировать запрос и какие quality gates ему нужны. -- **Слой authoring flow**: единый CLI связывает создание, проверку, оптимизацию, promotion, reporting и packaging. -- **Слой доказательств и выходов**: итогом становится не только skill package, но и eval-артефакты, governance signals, portability outputs и история итераций. +- **Входы**: стартуем с workflow, prompt, документов и заметок. +- **Маршрут**: компактный `SKILL.md` сначала задает границу и trigger. +- **Проектирование**: выбираются нужные archetype, quality gates и разбиение ресурсов. +- **Исполнение**: единый CLI создает, проверяет, оптимизирует и продвигает skill. +- **Выходы**: результатом становится skill package плюс доказательства оценки, governance и portability. ## Quick Start diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md index 65111bd..6eec92a 100644 --- a/docs/README.zh-CN.md +++ b/docs/README.zh-CN.md @@ -14,49 +14,23 @@ ## 架构图 -这套系统是分层设计的，方便新用户从上到下理解：先路由，再选方法，再做验证，最后再打包和治理。 +Hero 版可以压缩成一条主线：把零散输入变成一个可治理、可复用的 skill 包。 ```mermaid -flowchart TD - A["输入
workflow / prompt / transcript / docs / notes"] --> B["路由入口
SKILL.md"] - B --> C["方法层
references/"] - B --> D["作者流
scripts/yao.py"] - - C --> C1["Skill Archetype"] - C --> C2["Gate Selection"] - C --> C3["Non-Skill Decision"] - C --> C4["Operating Modes"] - C --> C5["Governance"] - C --> C6["Resource Boundaries"] - - D --> E["创建
init / template"] - D --> F["校验
lint / boundary / governance"] - D --> G["评测
trigger / suites / judge / confusion"] - D --> H["晋升
promotion policy / candidate registry"] - D --> I["打包
neutral source -> target adapters"] - D --> J["报告
history / scorecards / context / portability"] - - E --> K["Skill Package"] - F --> K - G --> L["evals/"] - H --> M["reports/"] - I --> N["dist/ 或目标导出物"] - - K --> K1["SKILL.md"] - K --> K2["agents/interface.yaml"] - K --> K3["manifest.json"] - K --> K4["可选 references / scripts / evals / reports"] - - L --> M +flowchart LR + A["输入
workflow / prompt / transcript / docs / notes"] --> B["路由
SKILL.md"] + B --> C["设计
方法 + 质量门"] + C --> D["执行
create / validate / eval / promote"] + D --> E["产出
skill 包 + 报告 + 适配层"] ``` -可以把这张图理解成 5 层： +10 秒理解这张图： -- **输入层**：把零散的操作材料作为 skill 的原始输入。 -- **路由层**：`SKILL.md` 保持轻量，优先定义边界、模式和输出契约。 -- **方法层**：方法文档决定这件事该不该 skill 化、该上哪些质量门。 -- **作者流层**：统一 CLI 把创建、校验、优化、晋升、报告和打包串成一条路径。 -- **证据与产出层**：最终产出不只是 skill 包，还包括 eval 结果、治理信号、portability 产物和迭代历史。 +- **输入**：从零散的 workflow、prompt、文档和笔记出发。 +- **路由**：先用精简的 `SKILL.md` 定义边界和触发。 +- **设计**：选择合适的 archetype、gates 和资源拆分方式。 +- **执行**：通过统一 CLI 完成创建、校验、优化和晋升。 +- **产出**：最终得到 skill 包，以及评测、治理和 portability 证据。 ## Quick Start