rockyshi1993 · Oct 27, 2026 · Oct 27, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,62 @@
+# Contributing to DevCodex
+
+Thanks for your interest in DevCodex. Bug reports, real-world usage feedback, host compatibility issues, Skill suggestions, documentation fixes, and code changes are all welcome.
+
+## Reporting issues
+
+- Open an [Issue](https://github.com/devcodex-labs/devcodex/issues) with: DevCodex version (`devcodex --version`), Node.js version, OS, which AI coding host you used, steps to reproduce, and what you expected.
+- Output from `devcodex status` or `devcodex doctor --json` helps. Remove secrets and private paths first.
+- Security vulnerabilities: do **not** open a public Issue. Follow [SECURITY.md](./SECURITY.md).
+
+## Development setup
+
+Requirements: Node.js >= 18.17.0 and npm.
+
+```bash
+git clone https://github.com/devcodex-labs/devcodex.git
+cd devcodex
+npm ci
+```
+
+To try your local checkout as the global `devcodex` command:
+
+```bash
+npm link
+devcodex --version
+```
+
+For normal use, install the published package with `npm install -g devcodex` as described in the README.
+
+## Validation
+
+The project uses a validation planner. Preview what a change needs before running it:
+
+```bash
+npm run test:plan        # plan for changed files
+npm run test:fast:plan   # plan for the fast route
+```
+
+Some routes require a human or CI attestation and will refuse to run from an AI agent session. CI on the pull request is the source of truth.
+
+If you change Skills under `content/skills/`, regenerate the portfolio instead of editing it by hand:
+
+```bash
+node scripts/generate-skill-portfolio.js
+node scripts/generate-skill-portfolio.js --check
+```
+
+## Pull requests
+
+1. Fork the repo and create a branch from `main`.
+2. Keep each PR focused on one change.
+3. Write code comments, commit messages, and README text in English. `README.zh-CN.md` is the optional Chinese translation; keep it in sync when you change `README.md`.
+4. Make sure CI passes.
+5. Describe what changed, why, and how you verified it.
+
+## Project rules
+
+See [RULES.md](./RULES.md) (in Chinese) for the engineering rules the project follows.
+
+## License of contributions
+
+DevCodex is licensed under [AGPL-3.0-or-later](./LICENSE). By submitting a contribution you agree that it is licensed under the same terms.
diff --git a/README.md b/README.md
@@ -2,51 +2,31 @@ English | [简体中文](README.zh-CN.md)
 
 <h1 align="center">DevCodex</h1>
 
-<p align="center">
-  <strong>An intent-driven, cross-host engineering harness for AI Coding</strong>
-</p>
-
-<p align="center">
-  <strong>Make AI Coding do more than generate code: start from the requirement and keep going until the engineering task is done.</strong>
-</p>
-
-<p align="center">
-  Recognize intent · Read the project · Invoke professional Skills · Confirm boundaries · Auto-advance · Make changes · Verify results · Save progress · Resume across sessions · Controlled evolution
-</p>
-
 <p align="center">
   <a href="https://www.npmjs.com/package/devcodex"><img src="https://img.shields.io/npm/v/devcodex" alt="npm version" /></a>
-  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-green" alt="AGPL-3.0" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0--or--later-green" alt="AGPL-3.0-or-later" /></a>
   <img src="https://img.shields.io/badge/Node.js-%3E%3D18.17.0-brightgreen" alt="Node.js >=18.17.0" />
   <img src="https://img.shields.io/badge/AI_Coding_Hosts-6-blue" alt="6 AI Coding hosts" />
   <img src="https://img.shields.io/badge/Professional_Skills-80%2B-blueviolet" alt="80+ professional Skills" />
 </p>
 
 <p align="center">
-  <a href="https://devcodex-labs.github.io/devcodex/">Full documentation</a>
-  ·
-  <a href="https://devcodex-labs.github.io/devcodex/guide/getting-started">5-minute start</a>
-  ·
-  <a href="https://devcodex-labs.github.io/devcodex/examples/resume">Cross-session resume example</a>
-  ·
-  <a href="https://github.com/devcodex-labs/devcodex/issues">Report an issue</a>
+  <a href="https://devcodex-labs.github.io/devcodex/">Full documentation</a> · <a href="#5-minute-start">Quick start</a> · <a href="#how-to-phrase-common-tasks">Common tasks</a> · <a href="#faq-and-troubleshooting">Troubleshooting</a> · <a href="https://github.com/devcodex-labs/devcodex/issues">Report an issue</a>
 </p>
 
-<p align="center">
-  <a href="#5-minute-start">Quick start</a>
-  ·
-  <a href="#how-to-phrase-common-tasks">Common tasks</a>
-  ·
-  <a href="#faq-and-troubleshooting">Troubleshooting</a>
-  ·
-  <a href="#updating">Updating</a>
-  ·
-  <a href="#uninstalling">Uninstalling</a>
-</p>
+**Your AI coding host writes the code. DevCodex makes sure the task is actually finished.**
 
-> **The model and the host do the reasoning, write the code, and run the tools. DevCodex starts from the task intent and decides what needs to be done, which project it applies to, what to read, which professional capabilities to load, which engineering process to follow, and how to prove the work is truly complete.**
+AI coding sessions lose context between chats, drift from the requirement, and say "done" without evidence. DevCodex is one engineering harness shared by 6 AI coding hosts (Codex, Claude Code, GitHub Copilot, Gemini CLI, Grok, and Cursor): it reads the project, picks a workflow and Skills, confirms boundaries, verifies results, and saves progress so the task can resume in a new session.
 
-**Intent-driven · 6 AI Coding hosts · 8 task workflows · 80+ professional Skills · Project context and memory · Sticky Auto advancement · Long-task recovery · Cross-session resume · Evidence-based completion · Controlled self-evolution**
+```mermaid
+flowchart LR
+  A[Your request] --> B[Recognize intent]
+  B --> C[Read project context]
+  C --> D[Workflow + Skills]
+  D --> E[Make changes in the host]
+  E --> F[Verify with evidence]
+  F --> G[Save checkpoint / resume later]
+```
 
 ```bash
 npm install -g devcodex
@@ -55,14 +35,7 @@ devcodex init
 devcodex status
 ```
 
-Keep your existing task after installing or updating. If the host offers connection reload, refresh the DevCodex connection and check the currently loaded version; if it does not, save a checkpoint, keep doing the work that can still be done, and reload the host when convenient. A successful install does not mean existing connections have loaded the new version, and there is no need to start a new task just for the update.
-
-Your first task can be phrased like this:
-
-```text
-Analyze the three issues most worth solving first in the current project.
-First state the read scope and evidence; analyze only, do not modify files.
-```
+> License: AGPL-3.0-or-later. Installing and using DevCodex creates no obligations for your own code; see [License](#license) for what the AGPL means for you.
 
 ## Contents
 
@@ -545,6 +518,8 @@ npm install -g devcodex
 devcodex --version
 ```
 
+Keep your existing task after installing or updating. If the host offers connection reload, refresh the DevCodex connection and check the currently loaded version; if it does not, save a checkpoint, keep doing the work that can still be done, and reload the host when convenient. A successful install does not mean existing connections have loaded the new version, and there is no need to start a new task just for the update.
+
 A normal install refreshes the user-level host adapters. If the package manager has install scripts disabled, or a later `status` shows the adapters are not ready, run:
 
 ```bash
@@ -927,9 +902,9 @@ For more, see [Trust, security, and data](https://devcodex-labs.github.io/devcod
 
 ## Contributing
 
-DevCodex is still evolving. Bugs, real-world usage feedback, host compatibility issues, Skill suggestions, documentation improvements, and engineering case studies are all welcome via [Issues](https://github.com/devcodex-labs/devcodex/issues).
+Bug reports, usage feedback, host compatibility issues, Skill suggestions, documentation fixes, and code changes are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).
 
-Please report security vulnerabilities privately following the repository's [Security Policy](./SECURITY.md); do not open a public Issue first.
+Please report security vulnerabilities privately following the [Security Policy](./SECURITY.md); do not open a public Issue first.
 
 ---
 ## Community
@@ -938,4 +913,10 @@ This project recognizes and thanks the [LINUX DO](https://linux.do/) community f
 
 ## License
 
-[AGPL-3.0](./LICENSE)
+DevCodex is licensed under the GNU Affero General Public License, version 3 or (at your option) any later version (`AGPL-3.0-or-later`, see [LICENSE](./LICENSE)). The repository's LICENSE file is the unmodified AGPL-3.0 text; no additional terms are added. This is a plain-language summary, not legal advice. The license text governs.
+
+- **Using it is unrestricted.** Installing DevCodex and running it on your machine or in CI, for personal or commercial work, needs no permission and creates no obligation (AGPL §2, §9).
+- **Your project code is not affected.** DevCodex is a tool you run. The code you write with an AI host while DevCodex is active is your own work; the license does not cover a program's output unless that output itself contains DevCodex code (§2).
+- **Modifying it privately is fine.** You can change DevCodex for your own use without publishing the changes (§2).
+- **If you distribute it** (original or modified, e.g. republishing the package or bundling it), you must keep it under the AGPL and provide the corresponding source (§4–§6).
+- **If you modify it and let others use it over a network** (for example, a hosted service built on a modified DevCodex), you must offer those users the source of your modified version (§13).
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -2,51 +2,31 @@
 
 <h1 align="center">DevCodex</h1>
 
-<p align="center">
-  <strong>意图驱动的跨宿主 AI Coding 工程化 Harness</strong>
-</p>
-
-<p align="center">
-  <strong>让 AI Coding 不只是生成代码，而是从需求开始，持续把工程任务做完。</strong>
-</p>
-
-<p align="center">
-  识别意图 · 读取项目 · 调用专业 Skill · 确认边界 · 自动推进 · 执行修改 · 验证结果 · 保存进度 · 跨会话续接 · 受控进化
-</p>
-
 <p align="center">
   <a href="https://www.npmjs.com/package/devcodex"><img src="https://img.shields.io/npm/v/devcodex" alt="npm version" /></a>
-  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-green" alt="AGPL-3.0" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0--or--later-green" alt="AGPL-3.0-or-later" /></a>
   <img src="https://img.shields.io/badge/Node.js-%3E%3D18.17.0-brightgreen" alt="Node.js >=18.17.0" />
   <img src="https://img.shields.io/badge/AI_Coding_Hosts-6-blue" alt="6 AI Coding hosts" />
   <img src="https://img.shields.io/badge/Professional_Skills-80%2B-blueviolet" alt="80+ professional Skills" />
 </p>
 
 <p align="center">
-  <a href="https://devcodex-labs.github.io/devcodex/">完整文档</a>
-  ·
-  <a href="https://devcodex-labs.github.io/devcodex/guide/getting-started">5 分钟开始</a>
-  ·
-  <a href="https://devcodex-labs.github.io/devcodex/examples/resume">跨会话续接案例</a>
-  ·
-  <a href="https://github.com/devcodex-labs/devcodex/issues">反馈问题</a>
+  <a href="https://devcodex-labs.github.io/devcodex/">完整文档</a> · <a href="#5-分钟开始">快速开始</a> · <a href="#常见任务怎么说">常见任务</a> · <a href="#常见问题与排错">排错</a> · <a href="https://github.com/devcodex-labs/devcodex/issues">反馈问题</a>
 </p>
 
-<p align="center">
-  <a href="#5-分钟开始">快速开始</a>
-  ·
-  <a href="#常见任务怎么说">常见任务</a>
-  ·
-  <a href="#常见问题与排错">排错</a>
-  ·
-  <a href="#更新">更新</a>
-  ·
-  <a href="#卸载">卸载</a>
-</p>
+**AI 编码宿主负责写代码，DevCodex 负责确认任务真的完成。**
 
-> **模型和宿主负责推理、写代码与执行工具；DevCodex 以任务意图为起点，负责判断要完成什么、作用于哪个项目、该读取什么、加载哪些专业能力、按什么工程流程推进，以及怎样证明真正完成。**
+AI 编码会话会在换窗口后丢失上下文、偏离需求，还会在没有证据时说"完成了"。DevCodex 是 6 个 AI 编码宿主（Codex、Claude Code、GitHub Copilot、Gemini CLI、Grok、Cursor）共用的一套工程化框架：读取项目、选择工作流和 Skills、确认边界、验证结果，并保存进度，换会话也能接着做。
 
-**意图驱动 · 6 个 AI Coding 宿主 · 8 条任务工作流 · 80+ 专业 Skill · 项目上下文与记忆 · Sticky Auto 自动推进 · 长任务恢复 · 跨会话续接 · 证据化完成 · 受控自我进化**
+```mermaid
+flowchart LR
+  A[你的需求] --> B[识别意图]
+  B --> C[读取项目上下文]
+  C --> D[工作流 + Skills]
+  D --> E[在宿主中修改]
+  E --> F[用证据验证]
+  F --> G[保存检查点 / 之后恢复]
+```
 
 ```bash
 npm install -g devcodex
@@ -55,14 +35,7 @@ devcodex init
 devcodex status
 ```
 
-安装或更新后保留原任务。宿主提供连接重载时，刷新 DevCodex 连接并核对当前加载版本；没有该能力时，保存检查点、继续可执行工作，方便时重载宿主。安装成功不代表已有连接已经加载新版，无需为更新另建任务。
-
-第一个任务可以直接这样说：
-
-```text
-分析当前项目最值得优先解决的三个问题。
-先说明读取范围和证据，只分析，不修改文件。
-```
+> 许可证：AGPL-3.0-or-later。安装和使用 DevCodex 不会给你自己的代码带来义务，详见[许可证](#许可证)一节。
 
 ## 目录
 
@@ -545,6 +518,8 @@ npm install -g devcodex
 devcodex --version
 ```
 
+安装或更新后保留原任务。宿主提供连接重载时，刷新 DevCodex 连接并核对当前加载版本；没有该能力时，保存检查点、继续可执行工作，方便时重载宿主。安装成功不代表已有连接已经加载新版，无需为更新另建任务。
+
 正常安装会刷新用户级宿主适配器。如果包管理器禁用了安装脚本，或后续 `status` 显示适配器未就绪，可执行：
 
 ```bash
@@ -927,9 +902,9 @@ npm uninstall -g devcodex
 
 ## 贡献
 
-DevCodex 仍在持续演进。Bug、真实使用反馈、宿主兼容问题、Skill 建议、文档改进和工程案例都欢迎通过 [Issues](https://github.com/devcodex-labs/devcodex/issues) 提交。
+欢迎提交 Bug、使用反馈、宿主兼容问题、Skill 建议、文档修正和代码改动，详见 [CONTRIBUTING.md](./CONTRIBUTING.md)（英文）。
 
-安全漏洞请按照仓库 [Security Policy](./SECURITY.md) 私下报告，不要先创建公开 Issue。
+安全漏洞请按照 [Security Policy](./SECURITY.md) 私下报告，不要先创建公开 Issue。
 
 ---
 ## 社区
@@ -938,4 +913,10 @@ DevCodex 仍在持续演进。Bug、真实使用反馈、宿主兼容问题、Sk
 
 ## 许可证
 
-[AGPL-3.0](./LICENSE)
+DevCodex 采用 GNU Affero 通用公共许可证第 3 版或（由你选择）任何更新版本（`AGPL-3.0-or-later`，见 [LICENSE](./LICENSE)）。仓库 LICENSE 为未修改的 AGPL-3.0 原文，没有附加条款。以下为通俗说明，不构成法律意见，以许可证原文为准。
+
+- **使用不受限制。** 在本机或 CI 中安装、运行 DevCodex，无论个人还是商业用途，都无需许可、不产生义务（第 2、9 条）。
+- **不影响你的项目代码。** DevCodex 是你运行的工具；启用它时借助 AI 宿主写出的代码属于你自己的作品。除非输出本身包含 DevCodex 代码，许可证不覆盖程序输出（第 2 条）。
+- **私下修改没问题。** 你可以为自己使用而修改 DevCodex，不必公开修改（第 2 条）。
+- **如果你分发它**（原版或修改版，例如重新发布或打包），必须继续使用 AGPL 并提供对应源代码（第 4–6 条）。
+- **如果你修改后通过网络让他人使用**（例如基于修改版 DevCodex 提供托管服务），必须向这些用户提供修改版的源代码（第 13 条）。
diff --git a/content/skills/portfolio.json b/content/skills/portfolio.json
@@ -13,10 +13,10 @@
     "publicTaxonomyDigest": "7f6ee8c30f5484b8881e27099af72c69625b73a7cf3b53fe51c8c0c147d4f124",
     "portfolioEvidence": "content/skills/portfolio-evidence.json",
     "portfolioEvidenceDigest": "cfd709b1248855c06c56373d1bcfe4798acefd7f1e0c11555b26cfd8caa1e8a6",
-    "consumerInventoryFileCount": 736,
-    "consumerInventoryDigest": "81929d6ce119c6c10ccca2e294ad62040038cd2ad7013119c9d62f2922760e21",
-    "consumerProjectionDigest": "c9fc625b27f1c99bdcb268cda38f3d33f54fe251c30d4e16f283fc21335ed563",
-    "portfolioInputDigest": "69541b02178c13a1663a979fa2448b8c1cb28b8785380e7f6da460f183cb3912"
+    "consumerInventoryFileCount": 737,
+    "consumerInventoryDigest": "01ff5658602038d470ba99168ccf5b786456baa7bd89fe5fc8d55ee5be8f391a",
+    "consumerProjectionDigest": "e320f28b46db89108197b4c56a32330bda338dcadff51940b4a550f2450fbacd",
+    "portfolioInputDigest": "6e998a3df0f4ccdcafcb3304e6b28bfdcc56ac0f879e5a40e779397b46948319"
   },
   "ordering": "skills.id asc; graph edges from/to asc",
   "summary": {
@@ -13649,6 +13649,10 @@
           "path": "changelogs/unreleased.md",
           "role": "current"
         },
+        {
+          "path": "CONTRIBUTING.md",
+          "role": "current"
+        },
         {
           "path": "cursor/plugins/devcodex-workspace/skills/devcodex-workspace/SKILL.md",
           "role": "current"
@@ -16858,6 +16862,10 @@
           "path": "changelogs/unreleased.md",
           "role": "current"
         },
+        {
+          "path": "CONTRIBUTING.md",
+          "role": "current"
+        },
         {
           "path": "grok/plugins/devcodex-workspace/skills/devcodex-workspace/SKILL.md",
           "role": "current"