Skip to content

Harness engineering beginner tutorial, from 0 to 1

Fix docs routes and restore dead-link checks

sanbuphyb6fcf3849d6d
diff --git a/README-CN.md b/README-CN.md
index 80f532c..d8fc8cf 100644
--- a/README-CN.md
+++ b/README-CN.md
@@ -69,43 +69,43 @@ Harness engineering 指的是:围绕模型搭建一整套工作环境,让它
- [`clean-state-checklist.md`](./docs/resources/zh/templates/clean-state-checklist.md) —— 每次会话结束前的清理清单
- [`evaluator-rubric.md`](./docs/resources/zh/templates/evaluator-rubric.md) —— 评审 agent 产出质量的评分表
-每个文件的详细用法写在 [中文模板指南](./docs/resources/zh/templates/README.md)。英文版见 [English template guide](./docs/resources/en/templates/README.md)。
+每个文件的详细用法写在 [中文模板指南](./docs/resources/zh/templates/index.md)。英文版见 [English template guide](./docs/resources/en/templates/index.md)。
如果你想直接用 OpenAI 那篇 harness engineering 文章里的更完整高级结构,可以继续看
-[`docs/resources/zh/openai-advanced/`](./docs/resources/zh/openai-advanced/README.md)
-和 [`docs/resources/en/openai-advanced/`](./docs/resources/en/openai-advanced/README.md)。
+[`docs/resources/zh/openai-advanced/`](./docs/resources/zh/openai-advanced/index.md)
+和 [`docs/resources/en/openai-advanced/`](./docs/resources/en/openai-advanced/index.md)。
## 课程大纲
### 讲义
-- [Lecture 01. 模型能力强,不等于执行可靠](./lectures/lecture-01-why-capable-agents-still-fail/README.md)
-- [Lecture 02. Harness 的定义](./lectures/lecture-02-what-a-harness-actually-is/README.md)
-- [Lecture 03. 让代码仓库成为唯一的事实来源](./lectures/lecture-03-why-the-repository-must-become-the-system-of-record/README.md)
-- [Lecture 04. 把指令拆分到不同文件里](./lectures/lecture-04-why-one-giant-instruction-file-fails/README.md)
-- [Lecture 05. 让跨会话的任务保持上下文连续](./lectures/lecture-05-why-long-running-tasks-lose-continuity/README.md)
-- [Lecture 06. 让 agent 每次工作前先初始化](./lectures/lecture-06-why-initialization-needs-its-own-phase/README.md)
-- [Lecture 07. 给 agent 划清每次任务的边界](./lectures/lecture-07-why-agents-overreach-and-under-finish/README.md)
-- [Lecture 08. 用功能清单约束 agent 该做什么](./lectures/lecture-08-why-feature-lists-are-harness-primitives/README.md)
-- [Lecture 09. 防止 agent 提前宣告完成](./lectures/lecture-09-why-agents-declare-victory-too-early/README.md)
-- [Lecture 10. 跑通完整流程才算真正验证](./lectures/lecture-10-why-end-to-end-testing-changes-results/README.md)
-- [Lecture 11. 让 agent 的运行过程可观测](./lectures/lecture-11-why-observability-belongs-inside-the-harness/README.md)
-- [Lecture 12. 每次会话结束前都做好交接](./lectures/lecture-12-why-every-session-must-leave-a-clean-state/README.md)
+- [Lecture 01. 模型能力强,不等于执行可靠](./docs/lectures/lecture-01-why-capable-agents-still-fail/index.md)
+- [Lecture 02. Harness 的定义](./docs/lectures/lecture-02-what-a-harness-actually-is/index.md)
+- [Lecture 03. 让代码仓库成为唯一的事实来源](./docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md)
+- [Lecture 04. 把指令拆分到不同文件里](./docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)
+- [Lecture 05. 让跨会话的任务保持上下文连续](./docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md)
+- [Lecture 06. 让 agent 每次工作前先初始化](./docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)
+- [Lecture 07. 给 agent 划清每次任务的边界](./docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md)
+- [Lecture 08. 用功能清单约束 agent 该做什么](./docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)
+- [Lecture 09. 防止 agent 提前宣告完成](./docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md)
+- [Lecture 10. 跑通完整流程才算真正验证](./docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)
+- [Lecture 11. 让 agent 的运行过程可观测](./docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)
+- [Lecture 12. 每次会话结束前都做好交接](./docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)
### 项目
-- [Project 01. 只写提示词让 agent 做,和定好规则再让它做,差多少](./projects/project-01-baseline-vs-minimal-harness/README.md)
-- [Project 02. 让 agent 看懂项目、接住上次的工作](./projects/project-02-agent-readable-workspace/README.md)
-- [Project 03. 让 agent 关掉再打开还能接着干](./projects/project-03-multi-session-continuity/README.md)
-- [Project 04. 用运行反馈修正 agent 的行为](./projects/project-04-incremental-indexing/README.md)
-- [Project 05. 让 agent 自己检查自己做的对不对](./projects/project-05-grounded-qa-verification/README.md)
-- [Project 06. 搭建一套完整的 agent 工作环境](./projects/project-06-runtime-observability-and-debugging/README.md)
+- [Project 01. 只写提示词让 agent 做,和定好规则再让它做,差多少](./docs/projects/project-01-baseline-vs-minimal-harness/index.md)
+- [Project 02. 让 agent 看懂项目、接住上次的工作](./docs/projects/project-02-agent-readable-workspace/index.md)
+- [Project 03. 让 agent 关掉再打开还能接着干](./docs/projects/project-03-multi-session-continuity/index.md)
+- [Project 04. 用运行反馈修正 agent 的行为](./docs/projects/project-04-incremental-indexing/index.md)
+- [Project 05. 让 agent 自己检查自己做的对不对](./docs/projects/project-05-grounded-qa-verification/index.md)
+- [Project 06. 搭建一套完整的 agent 工作环境](./docs/projects/project-06-runtime-observability-and-debugging/index.md)
### 资料库
-- [Resource Library 总览](./docs/resources/README.md)
-- [中文资料库](./docs/resources/zh/README.md)
-- [English Resource Library](./docs/resources/en/README.md)
+- [Resource Library 总览](./docs/resources/index.md)
+- [中文资料库](./docs/resources/zh/index.md)
+- [English Resource Library](./docs/resources/en/index.md)
## 学习路径推荐
@@ -243,8 +243,8 @@ npm run docs:dev
## 仓库结构
-- `lectures/` - 全部讲义
-- `projects/` - 全部实践项目,包括 capstone
+- `docs/lectures/` - 全部讲义
+- `docs/projects/` - 全部实践项目,包括 capstone
- `docs/resources/` - 中英双语的可复用模板、检查清单和方法参考
每个 lecture 都带一个 `code/` 目录,用来放小型真实示例和 supporting artifacts。
diff --git a/README.md b/README.md
index 9232a49..cbafdaf 100644
--- a/README.md
+++ b/README.md
@@ -69,44 +69,44 @@ When your project gets more complex, add these:
- [`clean-state-checklist.md`](./docs/resources/en/templates/clean-state-checklist.md) — checklist to run before ending each session
- [`evaluator-rubric.md`](./docs/resources/en/templates/evaluator-rubric.md) — scorecard for reviewing agent output quality
-Each file has detailed usage instructions in the [English template guide](./docs/resources/en/templates/README.md). Chinese versions are available in [中文模板指南](./docs/resources/zh/templates/README.md).
+Each file has detailed usage instructions in the [English template guide](./docs/resources/en/templates/index.md). Chinese versions are available in [中文模板指南](./docs/resources/zh/templates/index.md).
If you want the fuller OpenAI-style repository layout from the
"Harness engineering" post, use the advanced pack in
-[`docs/resources/en/openai-advanced/`](./docs/resources/en/openai-advanced/README.md) or
-[`docs/resources/zh/openai-advanced/`](./docs/resources/zh/openai-advanced/README.md).
+[`docs/resources/en/openai-advanced/`](./docs/resources/en/openai-advanced/index.md) or
+[`docs/resources/zh/openai-advanced/`](./docs/resources/zh/openai-advanced/index.md).
## Syllabus
### Lectures
-- [Lecture 01. Strong models don't mean reliable execution](./lectures/lecture-01-why-capable-agents-still-fail/README.md)
-- [Lecture 02. What harness actually means](./lectures/lecture-02-what-a-harness-actually-is/README.md)
-- [Lecture 03. Make the repository your single source of truth](./lectures/lecture-03-why-the-repository-must-become-the-system-of-record/README.md)
-- [Lecture 04. Split instructions across files, not one giant file](./lectures/lecture-04-why-one-giant-instruction-file-fails/README.md)
-- [Lecture 05. Keep context alive across sessions](./lectures/lecture-05-why-long-running-tasks-lose-continuity/README.md)
-- [Lecture 06. Initialize before every agent session](./lectures/lecture-06-why-initialization-needs-its-own-phase/README.md)
-- [Lecture 07. Draw clear task boundaries for agents](./lectures/lecture-07-why-agents-overreach-and-under-finish/README.md)
-- [Lecture 08. Use feature lists to constrain what the agent does](./lectures/lecture-08-why-feature-lists-are-harness-primitives/README.md)
-- [Lecture 09. Stop agents from declaring victory early](./lectures/lecture-09-why-agents-declare-victory-too-early/README.md)
-- [Lecture 10. Only a full-pipeline run counts as real verification](./lectures/lecture-10-why-end-to-end-testing-changes-results/README.md)
-- [Lecture 11. Make the agent's runtime observable](./lectures/lecture-11-why-observability-belongs-inside-the-harness/README.md)
-- [Lecture 12. Clean handoff at the end of every session](./lectures/lecture-12-why-every-session-must-leave-a-clean-state/README.md)
+- [Lecture 01. Strong models don't mean reliable execution](./docs/lectures/lecture-01-why-capable-agents-still-fail/index.md)
+- [Lecture 02. What harness actually means](./docs/lectures/lecture-02-what-a-harness-actually-is/index.md)
+- [Lecture 03. Make the repository your single source of truth](./docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md)
+- [Lecture 04. Split instructions across files, not one giant file](./docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)
+- [Lecture 05. Keep context alive across sessions](./docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md)
+- [Lecture 06. Initialize before every agent session](./docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)
+- [Lecture 07. Draw clear task boundaries for agents](./docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md)
+- [Lecture 08. Use feature lists to constrain what the agent does](./docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)
+- [Lecture 09. Stop agents from declaring victory early](./docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md)
+- [Lecture 10. Only a full-pipeline run counts as real verification](./docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)
+- [Lecture 11. Make the agent's runtime observable](./docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)
+- [Lecture 12. Clean handoff at the end of every session](./docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)
### Projects
-- [Project 01. Prompt-only vs. rules-first: how much difference does it make](./projects/project-01-baseline-vs-minimal-harness/README.md)
-- [Project 02. Make the project readable and pick up where you left off](./projects/project-02-agent-readable-workspace/README.md)
-- [Project 03. Keep the agent working across session restarts](./projects/project-03-multi-session-continuity/README.md)
-- [Project 04. Use runtime feedback to correct agent behavior](./projects/project-04-incremental-indexing/README.md)
-- [Project 05. Make the agent verify its own work](./projects/project-05-grounded-qa-verification/README.md)
-- [Project 06. Build a complete agent harness](./projects/project-06-runtime-observability-and-debugging/README.md)
+- [Project 01. Prompt-only vs. rules-first: how much difference does it make](./docs/projects/project-01-baseline-vs-minimal-harness/index.md)
+- [Project 02. Make the project readable and pick up where you left off](./docs/projects/project-02-agent-readable-workspace/index.md)
+- [Project 03. Keep the agent working across session restarts](./docs/projects/project-03-multi-session-continuity/index.md)
+- [Project 04. Use runtime feedback to correct agent behavior](./docs/projects/project-04-incremental-indexing/index.md)
+- [Project 05. Make the agent verify its own work](./docs/projects/project-05-grounded-qa-verification/index.md)
+- [Project 06. Build a complete agent harness](./docs/projects/project-06-runtime-observability-and-debugging/index.md)
### Resource Library
-- [Resource Library Overview](./docs/resources/README.md)
-- [Chinese Resource Library](./docs/resources/zh/README.md)
-- [English Resource Library](./docs/resources/en/README.md)
+- [Resource Library Overview](./docs/resources/index.md)
+- [Chinese Resource Library](./docs/resources/zh/index.md)
+- [English Resource Library](./docs/resources/en/index.md)
## Recommended Learning Path
@@ -244,8 +244,8 @@ The final project also serves as the course's capstone harness.
## Repository Structure
-- `lectures/` - All lectures
-- `projects/` - All hands-on projects, including the capstone
+- `docs/lectures/` - All lectures
+- `docs/projects/` - All hands-on projects, including the capstone
- `docs/resources/` - Bilingual reusable templates, checklists, and method references
Each lecture includes a `code/` directory for small real-world examples and supporting artifacts.
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index a9faa30..526a253 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -78,7 +78,7 @@ export default defineConfig({
"A project-based course on designing the environments, state, verification, and control systems that make Codex and Claude Code reliable.",
cleanUrls: true,
srcExclude: ["temp/**"],
- ignoreDeadLinks: true,
+ ignoreDeadLinks: false,
locales: {
root: {
label: "简体中文",
diff --git a/docs/en/resources.md b/docs/en/resources.md
index 3e3ac85..32cba47 100644
--- a/docs/en/resources.md
+++ b/docs/en/resources.md
@@ -1,10 +1,10 @@
# Resource Library
-This page is the English entry point for reusable templates, checklists, and method notes.
+This page is the English overview for the bilingual resource library.
-Chinese is the default site language. The Chinese resource overview is available at [/resources/](../resources/).
+Chinese is the default site language. The Chinese resource overview is available at [/resources/](/resources/).
-## English Resources
+## English Resource Library
- [English Resource Library](/resources/en/)
- [English Templates](/resources/en/templates/)
diff --git a/docs/lectures/lecture-01-why-capable-agents-still-fail/code/README.md b/docs/lectures/lecture-01-why-capable-agents-still-fail/code/index.md
similarity index 100%
rename from docs/lectures/lecture-01-why-capable-agents-still-fail/code/README.md
rename to docs/lectures/lecture-01-why-capable-agents-still-fail/code/index.md
diff --git a/docs/lectures/lecture-01-why-capable-agents-still-fail/README.md b/docs/lectures/lecture-01-why-capable-agents-still-fail/index.md
similarity index 97%
rename from docs/lectures/lecture-01-why-capable-agents-still-fail/README.md
rename to docs/lectures/lecture-01-why-capable-agents-still-fail/index.md
index 4ac4dce..7253367 100644
--- a/docs/lectures/lecture-01-why-capable-agents-still-fail/README.md
+++ b/docs/lectures/lecture-01-why-capable-agents-still-fail/index.md
@@ -54,7 +54,7 @@ instrumentation and diagnosis, followed by targeted harness changes.
- Startup and health-check command list.
- Required verification command set.
- Session handoff notes in the repository.
-- Code examples for this lecture: [`code/README.md`](./code/README.md)
+- Code examples for this lecture: [`code/index.md`](./code/index.md)
## Readings
diff --git a/docs/lectures/lecture-02-what-a-harness-actually-is/code/README.md b/docs/lectures/lecture-02-what-a-harness-actually-is/code/index.md
similarity index 100%
rename from docs/lectures/lecture-02-what-a-harness-actually-is/code/README.md
rename to docs/lectures/lecture-02-what-a-harness-actually-is/code/index.md
diff --git a/docs/lectures/lecture-02-what-a-harness-actually-is/README.md b/docs/lectures/lecture-02-what-a-harness-actually-is/index.md
similarity index 97%
rename from docs/lectures/lecture-02-what-a-harness-actually-is/README.md
rename to docs/lectures/lecture-02-what-a-harness-actually-is/index.md
index 0efc9c6..028b7d6 100644
--- a/docs/lectures/lecture-02-what-a-harness-actually-is/README.md
+++ b/docs/lectures/lecture-02-what-a-harness-actually-is/index.md
@@ -47,7 +47,7 @@ surfaces vary. Performance changes are often harness effects, not model changes.
- Remove a component and ask whether agent access, action, state continuity, or
error recovery changed.
- If behavior changes materially, the removed component is harness-critical.
-- Lecture examples: [`code/README.md`](./code/README.md)
+- Lecture examples: [`code/index.md`](./code/index.md)
- Typical artifacts to audit:
- `AGENTS.md` or equivalent instruction entrypoint.
- Setup and verification scripts.
diff --git a/docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/README.md b/docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md
similarity index 100%
rename from docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/README.md
rename to docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md
diff --git a/docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/README.md b/docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
similarity index 97%
rename from docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/README.md
rename to docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
index 71094c0..2c7f913 100644
--- a/docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/README.md
+++ b/docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
@@ -49,7 +49,7 @@ minimal, durable, high-utility context for repeatable work.
- Validation check:
- Start a new agent session and ask it to explain the system and next tasks
using repository contents only.
-- Lecture examples: [`code/README.md`](./code/README.md)
+- Lecture examples: [`code/index.md`](./code/index.md)
## Readings
diff --git a/docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/README.md b/docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md
similarity index 100%
rename from docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/README.md
rename to docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md
diff --git a/docs/lectures/lecture-04-why-one-giant-instruction-file-fails/README.md b/docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
similarity index 98%
rename from docs/lectures/lecture-04-why-one-giant-instruction-file-fails/README.md
rename to docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
index 47be325..e55c522 100644
--- a/docs/lectures/lecture-04-why-one-giant-instruction-file-fails/README.md
+++ b/docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
@@ -51,7 +51,7 @@ moving specialized detail to targeted references.
- Repeated edge-case rules with no source links.
- Contradictory instructions across one large file.
- Large sections with unclear ownership and update cadence.
-- Lecture examples: [`code/README.md`](./code/README.md)
+- Lecture examples: [`code/index.md`](./code/index.md)
## Readings
diff --git a/docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/README.md b/docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md
similarity index 100%
rename from docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/README.md
rename to docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md
diff --git a/docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/README.md b/docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
similarity index 98%
rename from docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/README.md
rename to docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index 17a9004..5780bbd 100644
--- a/docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/README.md
+++ b/docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -68,7 +68,7 @@ work.
## Examples and Artifacts
-- See [`code/`](./code/README.md) for continuity failure and recovery examples.
+- See [`code/`](./code/index.md) for continuity failure and recovery examples.
- Typical continuity artifacts include a progress log, a feature-status file, a
clean commit checkpoint, and a short verification record from the latest run.
- A useful handoff artifact states repository status, runtime status, blockers,
diff --git a/docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/README.md b/docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md
similarity index 100%
rename from docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/README.md
rename to docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md
diff --git a/docs/lectures/lecture-06-why-initialization-needs-its-own-phase/README.md b/docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
similarity index 97%
rename from docs/lectures/lecture-06-why-initialization-needs-its-own-phase/README.md
rename to docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index 26db732..4d7beb0 100644
--- a/docs/lectures/lecture-06-why-initialization-needs-its-own-phase/README.md
+++ b/docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -46,7 +46,7 @@ instead of implicit assumptions?
## Examples and Artifacts
-- See [`code/`](./code/README.md) for initializer output and first-run
+- See [`code/`](./code/index.md) for initializer output and first-run
scaffolding examples.
- Common initialization artifacts include `init.sh`, a baseline commit, a
progress artifact, and a structured feature/task surface.
diff --git a/docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/README.md b/docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md
similarity index 100%
rename from docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/README.md
rename to docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md
diff --git a/docs/lectures/lecture-07-why-agents-overreach-and-under-finish/README.md b/docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
similarity index 97%
rename from docs/lectures/lecture-07-why-agents-overreach-and-under-finish/README.md
rename to docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index a7d8f5a..5ceb451 100644
--- a/docs/lectures/lecture-07-why-agents-overreach-and-under-finish/README.md
+++ b/docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -46,7 +46,7 @@ durable, testable behavior.
## Examples and Artifacts
-- See [`code/`](./code/README.md) for one-shot failure patterns and incremental
+- See [`code/`](./code/index.md) for one-shot failure patterns and incremental
task-shaping examples.
- Useful artifacts include a structured feature/task list with explicit status
values and a single active-item policy.
diff --git a/docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/README.md b/docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md
similarity index 100%
rename from docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/README.md
rename to docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md
diff --git a/docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/README.md b/docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
similarity index 97%
rename from docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/README.md
rename to docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index 5c344ad..b954e78 100644
--- a/docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/README.md
+++ b/docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -47,7 +47,7 @@ criteria.
## Examples and Artifacts
-- See [`code/`](./code/README.md) for pass-state gating and evaluator-loop
+- See [`code/`](./code/index.md) for pass-state gating and evaluator-loop
examples.
- A useful feature record includes identifier, behavior statement, verification
method, status, and evidence reference.
diff --git a/docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/README.md b/docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md
similarity index 100%
rename from docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/README.md
rename to docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md
diff --git a/docs/lectures/lecture-09-why-agents-declare-victory-too-early/README.md b/docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
similarity index 97%
rename from docs/lectures/lecture-09-why-agents-declare-victory-too-early/README.md
rename to docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index d994fe9..87a7104 100644
--- a/docs/lectures/lecture-09-why-agents-declare-victory-too-early/README.md
+++ b/docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -45,7 +45,7 @@ exit criteria before completion can be accepted.
and completion signals.
- [`code/clean-state-checklist.md`](./code/clean-state-checklist.md): session-exit
criteria for restartable state.
-- [`code/README.md`](./code/README.md): index of lecture artifacts.
+- [`code/index.md`](./code/index.md): index of lecture artifacts.
## Readings
diff --git a/docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/README.md b/docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md
similarity index 100%
rename from docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/README.md
rename to docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md
diff --git a/docs/lectures/lecture-10-why-end-to-end-testing-changes-results/README.md b/docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
similarity index 98%
rename from docs/lectures/lecture-10-why-end-to-end-testing-changes-results/README.md
rename to docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index d09d23f..8d13888 100644
--- a/docs/lectures/lecture-10-why-end-to-end-testing-changes-results/README.md
+++ b/docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -58,7 +58,7 @@ feedback loops — the agent sees the error and immediately knows the fix.
that should be testable and enforceable.
- [`code/review-feedback-to-rule.md`](./code/review-feedback-to-rule.md): example
of converting recurring review feedback into automation.
-- [`code/README.md`](./code/README.md): index of lecture artifacts.
+- [`code/index.md`](./code/index.md): index of lecture artifacts.
## Readings
diff --git a/docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/README.md b/docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md
similarity index 100%
rename from docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/README.md
rename to docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md
diff --git a/docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/README.md b/docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
similarity index 98%
rename from docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/README.md
rename to docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index 479c35c..186613d 100644
--- a/docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/README.md
+++ b/docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -71,7 +71,7 @@ explicit, pre-agreed standard.
completion criteria for a bounded upgrade.
- [`code/evaluator-rubric.md`](./code/evaluator-rubric.md): scoring framework for
grounded quality assessment.
-- [`code/README.md`](./code/README.md): index of lecture artifacts.
+- [`code/index.md`](./code/index.md): index of lecture artifacts.
## Readings
diff --git a/docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/README.md b/docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md
similarity index 100%
rename from docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/README.md
rename to docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md
diff --git a/docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/README.md b/docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
similarity index 98%
rename from docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/README.md
rename to docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index dc51096..19f9381 100644
--- a/docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/README.md
+++ b/docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -115,7 +115,7 @@ Operationally, clean state and measurement reinforce each other:
template for comparing harness variants.
- [`code/cleanup-loop.md`](./code/cleanup-loop.md): recurring maintenance cycle
for entropy reduction.
-- [`code/README.md`](./code/README.md): index of lecture artifacts.
+- [`code/index.md`](./code/index.md): index of lecture artifacts.
## Readings
diff --git a/docs/projects/project-01-baseline-vs-minimal-harness/README.md b/docs/projects/project-01-baseline-vs-minimal-harness/index.md
similarity index 100%
rename from docs/projects/project-01-baseline-vs-minimal-harness/README.md
rename to docs/projects/project-01-baseline-vs-minimal-harness/index.md
diff --git a/docs/projects/project-02-agent-readable-workspace/README.md b/docs/projects/project-02-agent-readable-workspace/index.md
similarity index 100%
rename from docs/projects/project-02-agent-readable-workspace/README.md
rename to docs/projects/project-02-agent-readable-workspace/index.md
diff --git a/docs/projects/project-03-multi-session-continuity/README.md b/docs/projects/project-03-multi-session-continuity/index.md
similarity index 100%
rename from docs/projects/project-03-multi-session-continuity/README.md
rename to docs/projects/project-03-multi-session-continuity/index.md
diff --git a/docs/projects/project-04-incremental-indexing/README.md b/docs/projects/project-04-incremental-indexing/index.md
similarity index 100%
rename from docs/projects/project-04-incremental-indexing/README.md
rename to docs/projects/project-04-incremental-indexing/index.md
diff --git a/docs/projects/project-05-grounded-qa-verification/README.md b/docs/projects/project-05-grounded-qa-verification/index.md
similarity index 100%
rename from docs/projects/project-05-grounded-qa-verification/README.md
rename to docs/projects/project-05-grounded-qa-verification/index.md
diff --git a/docs/projects/project-06-runtime-observability-and-debugging/README.md b/docs/projects/project-06-runtime-observability-and-debugging/index.md
similarity index 100%
rename from docs/projects/project-06-runtime-observability-and-debugging/README.md
rename to docs/projects/project-06-runtime-observability-and-debugging/index.md
diff --git a/docs/resources/en/README.md b/docs/resources/en/index.md
similarity index 82%
rename from docs/resources/en/README.md
rename to docs/resources/en/index.md
index 4f413a7..4fb8aa4 100644
--- a/docs/resources/en/README.md
+++ b/docs/resources/en/index.md
@@ -34,13 +34,13 @@ Then add:
If you want the fuller OpenAI-style repository structure from the
"Harness engineering" post, use the advanced pack:
-- [`openai-advanced/README.md`](./openai-advanced/README.md)
+- [`openai-advanced/index.md`](./openai-advanced/index.md)
## Library Structure
-- [`templates/`](./templates/README.md): templates to copy into a real repo
-- [`reference/`](./reference/README.md): method notes, startup flow, and failure-mode maps
-- [`openai-advanced/`](./openai-advanced/README.md): advanced repo skeleton,
+- [`templates/`](./templates/index.md): templates to copy into a real repo
+- [`reference/`](./reference/index.md): method notes, startup flow, and failure-mode maps
+- [`openai-advanced/`](./openai-advanced/index.md): advanced repo skeleton,
system-of-record docs, and agent-first governance templates
## Recommended Minimal Pack
@@ -54,5 +54,5 @@ Those four files are enough to make most agent workflows noticeably more stable.
When the repo grows into a longer-running system with multiple domains, active
plans, quality scoring, and reliability policies, move up to the
-[`openai-advanced/`](./openai-advanced/README.md) pack instead of stretching the
+[`openai-advanced/`](./openai-advanced/index.md) pack instead of stretching the
minimal pack too far.
diff --git a/docs/resources/en/openai-advanced/README.md b/docs/resources/en/openai-advanced/index.md
similarity index 91%
rename from docs/resources/en/openai-advanced/README.md
rename to docs/resources/en/openai-advanced/index.md
index 6f47556..c89b786 100644
--- a/docs/resources/en/openai-advanced/README.md
+++ b/docs/resources/en/openai-advanced/index.md
@@ -17,7 +17,7 @@ now needs:
## Included Starter Layout
-The starter pack under [`repo-template/`](./repo-template/README.md) mirrors the
+The starter pack under [`repo-template/`](./repo-template/index.md) mirrors the
structure below:
```text
@@ -52,7 +52,7 @@ docs/
## How To Adopt It
1. Start from the minimal pack if your repo is still small.
-2. Copy the files in [`repo-template/`](./repo-template/README.md) into your
+2. Copy the files in [`repo-template/`](./repo-template/index.md) into your
own repository once you need stronger structure.
3. Keep `AGENTS.md` short. Treat it as a router into the deeper docs, not as an
encyclopedia.
@@ -63,7 +63,7 @@ docs/
## SOP Library
-The [`sops/`](./sops/README.md) folder turns the article's diagrams into
+The [`sops/`](./sops/index.md) folder turns the article's diagrams into
step-by-step operating procedures:
- layered domain architecture setup
diff --git a/docs/resources/en/openai-advanced/repo-template/docs/exec-plans/active/README.md b/docs/resources/en/openai-advanced/repo-template/docs/exec-plans/active/index.md
similarity index 100%
rename from docs/resources/en/openai-advanced/repo-template/docs/exec-plans/active/README.md
rename to docs/resources/en/openai-advanced/repo-template/docs/exec-plans/active/index.md
diff --git a/docs/resources/en/openai-advanced/repo-template/docs/exec-plans/completed/README.md b/docs/resources/en/openai-advanced/repo-template/docs/exec-plans/completed/index.md
similarity index 100%
rename from docs/resources/en/openai-advanced/repo-template/docs/exec-plans/completed/README.md
rename to docs/resources/en/openai-advanced/repo-template/docs/exec-plans/completed/index.md
diff --git a/docs/resources/en/openai-advanced/repo-template/README.md b/docs/resources/en/openai-advanced/repo-template/index.md
similarity index 100%
rename from docs/resources/en/openai-advanced/repo-template/README.md
rename to docs/resources/en/openai-advanced/repo-template/index.md
diff --git a/docs/resources/en/openai-advanced/sops/README.md b/docs/resources/en/openai-advanced/sops/index.md
similarity index 100%
rename from docs/resources/en/openai-advanced/sops/README.md
rename to docs/resources/en/openai-advanced/sops/index.md
diff --git a/docs/resources/en/reference/README.md b/docs/resources/en/reference/index.md
similarity index 100%
rename from docs/resources/en/reference/README.md
rename to docs/resources/en/reference/index.md
diff --git a/docs/resources/en/templates/README.md b/docs/resources/en/templates/index.md
similarity index 100%
rename from docs/resources/en/templates/README.md
rename to docs/resources/en/templates/index.md
diff --git a/docs/resources/README.md b/docs/resources/index.md
similarity index 66%
rename from docs/resources/README.md
rename to docs/resources/index.md
index 8369913..9a4d223 100644
--- a/docs/resources/README.md
+++ b/docs/resources/index.md
@@ -6,15 +6,15 @@
## 先看中文
-- [中文资料库总览](./zh/README.md)
-- [中文模板](./zh/templates/README.md)
-- [中文参考](./zh/reference/README.md)
+- [中文资料库总览](./zh/index.md)
+- [中文模板](./zh/templates/index.md)
+- [中文参考](./zh/reference/index.md)
## English Resources
-- [English Resource Library](./en/README.md)
-- [English Templates](./en/templates/README.md)
-- [English Reference](./en/reference/README.md)
+- [English Resource Library](./en/index.md)
+- [English Templates](./en/templates/index.md)
+- [English Reference](./en/reference/index.md)
## 这里能找到什么
@@ -38,5 +38,5 @@
如果最小 harness 已经不够,可以继续看 OpenAI 风格的 advanced pack:
-- 中文:[`zh/openai-advanced/README.md`](./zh/openai-advanced/README.md)
-- English:[`en/openai-advanced/README.md`](./en/openai-advanced/README.md)
+- 中文:[`zh/openai-advanced/index.md`](./zh/openai-advanced/index.md)
+- English:[`en/openai-advanced/index.md`](./en/openai-advanced/index.md)
diff --git a/docs/resources/zh/README.md b/docs/resources/zh/index.md
similarity index 76%
rename from docs/resources/zh/README.md
rename to docs/resources/zh/index.md
index 10536b5..63a26b7 100644
--- a/docs/resources/zh/README.md
+++ b/docs/resources/zh/index.md
@@ -31,13 +31,13 @@
如果你想直接采用 OpenAI 那篇 harness engineering 文章里更完整的仓库组织方式,可以继续看:
-- [`openai-advanced/README.md`](./openai-advanced/README.md)
+- [`openai-advanced/index.md`](./openai-advanced/index.md)
## 资料库结构
-- [`templates/`](./templates/README.md):可以直接复制到真实仓库里的模板
-- [`reference/`](./reference/README.md):方法说明、启动流程和问题对照表
-- [`openai-advanced/`](./openai-advanced/README.md):更完整的 OpenAI 风格高级资源包,包括 repo skeleton、质量文档、执行计划和系统级治理文件
+- [`templates/`](./templates/index.md):可以直接复制到真实仓库里的模板
+- [`reference/`](./reference/index.md):方法说明、启动流程和问题对照表
+- [`openai-advanced/`](./openai-advanced/index.md):更完整的 OpenAI 风格高级资源包,包括 repo skeleton、质量文档、执行计划和系统级治理文件
## 推荐最小组合
@@ -49,4 +49,4 @@
先把这四样放进项目里,再开始让 agent 持续工作,通常就已经能明显降低返工和瞎猜。
如果你的仓库已经进入多模块、多阶段、多角色协作,可以直接升级到
-[`openai-advanced/`](./openai-advanced/README.md) 这一套高级结构,而不是继续把最小模板硬撑成一个大而乱的系统。
+[`openai-advanced/`](./openai-advanced/index.md) 这一套高级结构,而不是继续把最小模板硬撑成一个大而乱的系统。
diff --git a/docs/resources/zh/openai-advanced/README.md b/docs/resources/zh/openai-advanced/index.md
similarity index 89%
rename from docs/resources/zh/openai-advanced/README.md
rename to docs/resources/zh/openai-advanced/index.md
index 2d4c75a..63a588e 100644
--- a/docs/resources/zh/openai-advanced/README.md
+++ b/docs/resources/zh/openai-advanced/index.md
@@ -15,7 +15,7 @@ agent-first world》里更完整、更高阶的仓库组织方式整理成可以
## 包含的目录骨架
-[`repo-template/`](./repo-template/README.md) 里提供了一套可直接复制的 starter
+[`repo-template/`](./repo-template/index.md) 里提供了一套可直接复制的 starter
结构,核心布局如下:
```text
@@ -51,14 +51,14 @@ docs/
1. 如果仓库还小,先用最小资源包。
2. 一旦进入多模块、多轮会话、长期演化阶段,就把
- [`repo-template/`](./repo-template/README.md) 里的骨架复制到你的仓库。
+ [`repo-template/`](./repo-template/index.md) 里的骨架复制到你的仓库。
3. 保持 `AGENTS.md` 很短,把深层规则拆到 `docs/` 里。
4. 把质量文档、可靠性文档、执行计划当成日常开发的一部分,而不是事后补写。
5. 把生成物和外部 reference 明确收进仓库,避免 agent 依赖聊天上下文或人的记忆。
## SOP 资料库
-[`sops/`](./sops/README.md) 把文章里的几张关键图,整理成可以逐步执行的标准流程:
+[`sops/`](./sops/index.md) 把文章里的几张关键图,整理成可以逐步执行的标准流程:
- 分层领域架构搭建 SOP
- 把不可见知识编码进仓库的 SOP
diff --git a/docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/active/README.md b/docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/active/index.md
similarity index 100%
rename from docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/active/README.md
rename to docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/active/index.md
diff --git a/docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/completed/README.md b/docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/completed/index.md
similarity index 100%
rename from docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/completed/README.md
rename to docs/resources/zh/openai-advanced/repo-template/docs/exec-plans/completed/index.md
diff --git a/docs/resources/zh/openai-advanced/repo-template/README.md b/docs/resources/zh/openai-advanced/repo-template/index.md
similarity index 100%
rename from docs/resources/zh/openai-advanced/repo-template/README.md
rename to docs/resources/zh/openai-advanced/repo-template/index.md
diff --git a/docs/resources/zh/openai-advanced/sops/README.md b/docs/resources/zh/openai-advanced/sops/index.md
similarity index 100%
rename from docs/resources/zh/openai-advanced/sops/README.md
rename to docs/resources/zh/openai-advanced/sops/index.md
diff --git a/docs/resources/zh/reference/README.md b/docs/resources/zh/reference/index.md
similarity index 100%
rename from docs/resources/zh/reference/README.md
rename to docs/resources/zh/reference/index.md
diff --git a/docs/resources/zh/templates/README.md b/docs/resources/zh/templates/index.md
similarity index 100%
rename from docs/resources/zh/templates/README.md
rename to docs/resources/zh/templates/index.md