Refine bilingual repository landing pages

XenoExia · sisyphus-dev-ai · XenoExia · commit 7c4acc188933 · 2026-03-23T20:10:15.000+08:00
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 # opencode-workflow-playbook
 
-**An opinionated OpenCode workflow stack for spec-driven delivery, disciplined execution, specialist augmentation, and runtime validation.**
+**A structured OpenCode workflow for turning ideas into tracked execution without losing routing clarity.**
 
 [简体中文](./README.zh-CN.md) · [Architecture](./docs/en/architecture.md) · [Setup](./docs/en/setup.md) · [Example Prompts](./examples/prompts.en.md)
 
@@ -18,16 +18,19 @@
 
 > **Status:** private-first working draft. The structure is stable enough to share internally now and is being shaped for a later public open-source release.
 
+> [!IMPORTANT]
+> One primary owner per task. Other layers may assist, but they do not compete for ownership.
+
 ---
 
 ## Start here
 
-If you are reading this repo for the first time, use this order:
+Choose the path that matches what you need:
 
-1. Read [Workflow stack](#workflow-stack) for the mental model
-2. Read [Operating model](#operating-model) to understand ownership and overlays
-3. Read [`docs/en/setup.md`](./docs/en/setup.md) if you want to reproduce the setup
-4. Read [`examples/prompts.en.md`](./examples/prompts.en.md) for practical usage patterns
+- **Understand the model** → [Workflow stack](#workflow-stack) and [Operating model](#operating-model)
+- **Reproduce the setup** → [`docs/en/setup.md`](./docs/en/setup.md)
+- **Learn the terminology** → [`docs/en/glossary.md`](./docs/en/glossary.md)
+- **Adapt the prompts** → [`examples/prompts.en.md`](./examples/prompts.en.md)
 
 ## Why this repo
 
@@ -38,6 +41,12 @@ Most AI coding setups fail in one of two ways:
 
 This repository documents a workflow stack designed to avoid both failure modes.
 
+It is for people who already use AI coding tools and want:
+
+- a clear lifecycle owner for tracked work
+- stronger execution discipline without duplicate process
+- runtime validation when local confidence is not enough
+
 It captures a converged OpenCode setup where:
 
 - **OpenSpec** owns tracked lifecycle work through `opsx-*`
@@ -68,6 +77,9 @@ It captures a converged OpenCode setup where:
 
 ## Quick start
 
+> [!TIP]
+> Most teams should start with two layers, not five: OmO for orchestration, plus OpenSpec for tracked lifecycle work.
+
 ### 1. Understand the model
 
 Read these first:
@@ -92,6 +104,8 @@ The core rule of this stack is simple:
 
 ## Operating model
 
+At runtime, the workflow stays simple: pick one owner first, then add overlays only when they contribute a different kind of value.
+
 ```text
                user request
                     │
@@ -145,47 +159,31 @@ The core rule of this stack is simple:
 3. Pull in the relevant Gentleman skill for framework-specific quality
 4. Use Sentry MCP when runtime evidence matters
 
-## Repository map
-
-```text
-.
-├── README.md
-├── README.zh-CN.md
-├── config/
-│   ├── opencode.template.json
-│   ├── ROUTING_POLICY.template.md
-│   └── ENV_SELF_CHECK_POLICY.template.md
-├── docs/
-│   ├── en/
-│   └── zh-CN/
-└── examples/
-    ├── prompts.en.md
-    └── prompts.zh-CN.md
-```
-
 ## Adoption paths
 
 You do not need to adopt everything at once.
 
+Most teams should begin with a small, legible stack and only add layers when the pain is real.
+
 ### Minimal
 
-- OmO baseline only
+- OmO baseline only — good for solo experimentation and lightweight local work
 
 ### Structured
 
-- OmO + OpenSpec lifecycle via `opsx-*`
+- OmO + OpenSpec lifecycle via `opsx-*` — good for repeatable, tracked execution
 
 ### Disciplined
 
-- OmO + OpenSpec + Superpowers
+- OmO + OpenSpec + Superpowers — good when quality drift starts becoming expensive
 
 ### Specialist-ready
 
-- OmO + OpenSpec + Superpowers + selected Gentleman skills
+- OmO + OpenSpec + Superpowers + selected Gentleman skills — good for framework-heavy repositories
 
 ### Runtime-aware
 
-- add Sentry MCP when local confidence is not enough
+- add Sentry MCP when local confidence is not enough and production evidence should shape decisions
 
 ## FAQ
 
@@ -210,15 +208,56 @@ It detects drift in commands, skills, disabled assets, MCP auth, and duplicate l
 
 </details>
 
+<details>
+<summary><strong>Who is this repo for?</strong></summary>
+
+It is for people who already use AI coding tools and want a cleaner ownership model, better execution discipline, and a workflow stack that stays composable instead of collapsing into duplicate process.
+
+</details>
+
 ## Documentation
 
-- English architecture: [`docs/en/architecture.md`](./docs/en/architecture.md)
-- English setup: [`docs/en/setup.md`](./docs/en/setup.md)
-- English context log: [`docs/en/context-2026-03-22.md`](./docs/en/context-2026-03-22.md)
-- Chinese architecture: [`docs/zh-CN/architecture.md`](./docs/zh-CN/architecture.md)
-- Chinese setup: [`docs/zh-CN/setup.md`](./docs/zh-CN/setup.md)
-- Chinese context log: [`docs/zh-CN/context-2026-03-22.md`](./docs/zh-CN/context-2026-03-22.md)
+- **Read in English**
+  - [Architecture](./docs/en/architecture.md)
+  - [Setup](./docs/en/setup.md)
+  - [Glossary](./docs/en/glossary.md)
+  - [Config overview](./docs/en/config-overview.md)
+  - [Context log](./docs/en/context-2026-03-22.md)
+- **Read in Chinese**
+  - [架构说明](./docs/zh-CN/architecture.md)
+  - [安装说明](./docs/zh-CN/setup.md)
+  - [术语表](./docs/zh-CN/glossary.md)
+  - [配置总览](./docs/zh-CN/config-overview.md)
+  - [上下文记录](./docs/zh-CN/context-2026-03-22.md)
+
+<details>
+<summary><strong>Repository map</strong></summary>
+
+```text
+.
+├── README.md
+├── README.zh-CN.md
+├── CHANGELOG.md
+├── CONTRIBUTING.md
+├── CODE_OF_CONDUCT.md
+├── config/
+│   ├── opencode.template.json
+│   ├── ROUTING_POLICY.template.md
+│   └── ENV_SELF_CHECK_POLICY.template.md
+├── docs/
+│   ├── en/
+│   └── zh-CN/
+└── examples/
+    ├── prompts.en.md
+    └── prompts.zh-CN.md
+```
+
+</details>
+
+## Contributing
+
+Private-first today, public-friendly by design. See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution expectations and [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) for collaboration norms.
 
 ## License
 
-License selection is intentionally left open until the repository is ready to be published publicly.
+License is intentionally undecided while the repository remains in private-first draft mode.
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -2,7 +2,7 @@
 
 # opencode-workflow-playbook
 
-**一套偏工程化的 OpenCode 工作流栈，用于规格驱动交付、纪律化执行、专家技能增强与运行时验证。**
+**一套结构清晰的 OpenCode 工作流，用来把想法稳定地推进成可跟踪执行，而不丢掉路由清晰度。**
 
 [English](./README.md) · [架构说明](./docs/zh-CN/architecture.md) · [安装说明](./docs/zh-CN/setup.md) · [示例提示词](./examples/prompts.zh-CN.md)
 
@@ -18,16 +18,19 @@
 
 > **当前状态：** 这是一个 private-first 的工作草稿版仓库。结构已经稳定到可以内部分享，后续会继续整理成适合公开开源的版本。
 
+> [!IMPORTANT]
+> 每个任务只能有一个 primary owner。其他层可以辅助，但不能争抢 ownership。
+
 ---
 
 ## 从哪里开始看
 
-如果你是第一次打开这个仓库，建议按下面顺序看：
+如果你是第一次打开这个仓库，可以按目标选择入口：
 
-1. 先看 [工作流栈](#工作流栈)，理解整套模型
-2. 再看 [运行模型](#运行模型)，理解 owner 和 overlay 的关系
-3. 如果想复现环境，再看 [`docs/zh-CN/setup.md`](./docs/zh-CN/setup.md)
-4. 如果想知道怎么实际使用，再看 [`examples/prompts.zh-CN.md`](./examples/prompts.zh-CN.md)
+- **想理解模型** → [工作流栈](#工作流栈) 和 [工作流运行模型](#工作流运行模型)
+- **想复现环境** → [`docs/zh-CN/setup.md`](./docs/zh-CN/setup.md)
+- **想先懂术语** → [`docs/zh-CN/glossary.md`](./docs/zh-CN/glossary.md)
+- **想直接看提示词** → [`examples/prompts.zh-CN.md`](./examples/prompts.zh-CN.md)
 
 ## 为什么做这个仓库
 
@@ -38,6 +41,12 @@
 
 这个仓库记录的，就是一套为了避开这两个极端而收敛出来的 OpenCode 工作流栈。
 
+它适合已经在用 AI 编码工具、但希望进一步得到这些能力的人：
+
+- tracked work 有明确生命周期 owner
+- 执行更有纪律，但不会平白多出第二套流程
+- 本地信心不够时，可以接入运行时真实证据
+
 它的关键点是：
 
 - **OpenSpec** 通过 `opsx-*` 拥有 tracked lifecycle
@@ -68,6 +77,9 @@
 
 ## 快速开始
 
+> [!TIP]
+> 大多数团队不需要一开始就装满整套栈。通常从 OmO + OpenSpec 两层开始，就已经很有价值了。
+
 ### 1. 先理解模型
 
 建议先读：
@@ -90,7 +102,9 @@
 
 > 每个任务只允许一个 primary owner，其他层只在确实能提供不同价值时作为 overlay 参与。
 
-## 运行模型
+## 工作流运行模型
+
+在运行时，这套工作流的思路很简单：先选 owner，再按需加 overlay。不要一开始就把所有层都压上去。
 
 ```text
                  用户请求
@@ -144,47 +158,31 @@
 3. 根据技术栈加载相应 Gentleman skill
 4. 在运行时证据重要时接入 Sentry MCP
 
-## 仓库结构
-
-```text
-.
-├── README.md
-├── README.zh-CN.md
-├── config/
-│   ├── opencode.template.json
-│   ├── ROUTING_POLICY.template.md
-│   └── ENV_SELF_CHECK_POLICY.template.md
-├── docs/
-│   ├── en/
-│   └── zh-CN/
-└── examples/
-    ├── prompts.en.md
-    └── prompts.zh-CN.md
-```
-
 ## 采用路径
 
 你不需要一次性把整套全装上。
 
+更实际的做法，是从最少的层数开始，只在痛点真正出现时再加东西。
+
 ### 最小化采用
 
-- 只使用 OmO 底座
+- 只使用 OmO 底座 —— 适合个人实验和轻量本地任务
 
 ### 结构化采用
 
-- OmO + OpenSpec `opsx-*`
+- OmO + OpenSpec `opsx-*` —— 适合可重复、可追踪的任务执行
 
 ### 强纪律采用
 
-- OmO + OpenSpec + Superpowers
+- OmO + OpenSpec + Superpowers —— 适合质量漂移已经开始变贵的场景
 
 ### 专家增强采用
 
-- OmO + OpenSpec + Superpowers + 有选择地安装 Gentleman skills
+- OmO + OpenSpec + Superpowers + 有选择地安装 Gentleman skills —— 适合框架密集型仓库
 
 ### 加入运行时验证
 
-- 当本地验证不够时，再接入 Sentry MCP
+- 当本地验证不够时，再接入 Sentry MCP，让生产/运行时证据参与判断
 
 ## 常见问题
 
@@ -209,15 +207,56 @@
 
 </details>
 
+<details>
+<summary><strong>这个仓库更适合什么样的人？</strong></summary>
+
+它更适合已经在使用 AI 编码工具，但希望把 ownership、执行纪律和运行时验证整理得更清楚的人，而不是想找一套“装上就自动完美”的神奇框架的人。
+
+</details>
+
 ## 文档入口
 
-- 中文架构：[`docs/zh-CN/architecture.md`](./docs/zh-CN/architecture.md)
-- 中文安装：[`docs/zh-CN/setup.md`](./docs/zh-CN/setup.md)
-- 中文上下文记录：[`docs/zh-CN/context-2026-03-22.md`](./docs/zh-CN/context-2026-03-22.md)
-- English architecture: [`docs/en/architecture.md`](./docs/en/architecture.md)
-- English setup: [`docs/en/setup.md`](./docs/en/setup.md)
-- English context log: [`docs/en/context-2026-03-22.md`](./docs/en/context-2026-03-22.md)
+- **中文阅读路径**
+  - [架构说明](./docs/zh-CN/architecture.md)
+  - [安装说明](./docs/zh-CN/setup.md)
+  - [术语表](./docs/zh-CN/glossary.md)
+  - [配置总览](./docs/zh-CN/config-overview.md)
+  - [上下文记录](./docs/zh-CN/context-2026-03-22.md)
+- **English reading path**
+  - [Architecture](./docs/en/architecture.md)
+  - [Setup](./docs/en/setup.md)
+  - [Glossary](./docs/en/glossary.md)
+  - [Config overview](./docs/en/config-overview.md)
+  - [Context log](./docs/en/context-2026-03-22.md)
+
+<details>
+<summary><strong>仓库结构</strong></summary>
+
+```text
+.
+├── README.md
+├── README.zh-CN.md
+├── CHANGELOG.md
+├── CONTRIBUTING.md
+├── CODE_OF_CONDUCT.md
+├── config/
+│   ├── opencode.template.json
+│   ├── ROUTING_POLICY.template.md
+│   └── ENV_SELF_CHECK_POLICY.template.md
+├── docs/
+│   ├── en/
+│   └── zh-CN/
+└── examples/
+    ├── prompts.en.md
+    └── prompts.zh-CN.md
+```
+
+</details>
+
+## 参与与协作
+
+这个仓库目前仍然是 private-first，但已经按公开协作的方向组织。贡献说明见 [CONTRIBUTING.md](./CONTRIBUTING.md)，协作行为规范见 [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)。
 
 ## License
 
-正式开源前，License 暂时留空，等仓库公开阶段再统一决定。
+在仓库仍处于 private-first 草稿阶段时，License 暂时保持未定。
