harness-engineer 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.2.1
+
+- clarified that `harness-engineer init` bootstraps the full repository-owned Codex baseline in one command
+- updated generated prompts and documentation to tell Codex to reuse the scaffolded subagents, config, memory, runbooks, and docs before inventing ad hoc setup
+
+## 0.2.0
+
+- aligned the default `generic-software` preset with OpenAI's harness engineering article
+- switched the Codex entrypoint from generated `AGENTS.md` to generated `AGENTS.override.md`
+- reorganized generated repository docs around `design-docs`, `product-specs`, `generated`, `references`, and `exec-plans`
+- removed the old `agentadmin-codex` compatibility preset to keep the package repository-independent
+- updated package metadata for published consumers, including `main`, `types`, and `exports`
+
+## 0.1.0
+
+- initial public release of the `harness-engineer` npm package

package/README.md

@@ -1,36 +1,52 @@
 # harness-engineer
 
-`harness-engineer` is a Codex-first scaffolding CLI for repository-owned agent orchestration workflows.
+`harness-engineer` is an open-source Codex-first scaffolding CLI for repository-owned orchestration workflows.
 
-It turns the "harness as files" pattern into a reusable npm package: fixed role definitions, durable memory, runbooks, and task lifecycle artifacts can all be generated into a blank repository with one command.
+It packages the "harness as files" pattern into a reusable npm package: fixed roles, durable memory, runbooks, record-system docs, and execution-plan artifacts can all be generated into a blank repository with one command.
 
 中文说明见 [README.zh-CN.md](./README.zh-CN.md)。
 
 > License: [MIT](./LICENSE)
+> Package: [`harness-engineer` on npm](https://www.npmjs.com/package/harness-engineer)
+> Changelog: [CHANGELOG.md](./CHANGELOG.md)
+
+## Why This Shape
+
+The default preset is now aligned with OpenAI's harness engineering article:
+
+- keep the Codex entrypoint short
+- treat repository docs as the system of record
+- keep execution plans versioned and durable
+- give agents progressively deeper context instead of one giant instruction file
+
+The article uses `AGENTS.md` conceptually. This package generates `AGENTS.override.md` because that is the Codex entrypoint this tool targets.
 
 ## What It Creates
 
-- `AGENTS.md` as the short collaboration entrypoint
+- `AGENTS.override.md` as the short Codex collaboration map
 - `.codex/config.toml` and fixed role files under `.codex/agents/`
 - durable memory under `.codex/memory/`
-- `docs/index.md` plus runbooks and source-of-truth placeholders
-- task lifecycle folders under `docs/plans/` and `logs/codex/`
+- `ARCHITECTURE.md` plus record-system docs under `docs/design-docs/`, `docs/product-specs/`, `docs/generated/`, and `docs/references/`
+- execution-plan folders under `docs/exec-plans/` and run artifacts under `logs/codex/`
 - a machine-readable `harness-engineer.config.json`
 
 ## Quick Start
 
-For published package usage:
+The package is published on npm. The fastest way to scaffold a new repository is:
 
 ```bash
 pnpm dlx harness-engineer@latest init . \
   --preset generic-software \
   --project-name "Acme Platform" \
+  --language bilingual \
   --yes
 
 harness-engineer task new 2026-04-02-auth-debug --class B
 harness-engineer status
 ```
 
+That single `init` command is intended to bootstrap the full repository-owned Codex baseline in one pass: fixed subagents, `.codex` config, durable memory, runbooks, record-system docs, and task directories.
+
 If you are running from this source repository:
 
 ```bash
@@ -40,12 +56,13 @@ pnpm build
 node dist/cli.js init . \
   --preset generic-software \
   --project-name "Acme Platform" \
+  --language bilingual \
   --yes
 ```
 
-## Install From npm
+## Install Options
 
-Without cloning this repository, users can initialize a project directly from npm:
+### From npm without installing globally
 
 ```bash
 pnpm dlx harness-engineer@latest init . \
@@ -55,13 +72,20 @@ pnpm dlx harness-engineer@latest init . \
   --yes
 ```
 
-Or install it into a project first:
+### Install into an existing project
 
 ```bash
 npm install -D harness-engineer
 npx harness-engineer init . --preset generic-software --project-name "Acme Platform"
 ```
 
+### Install directly from GitHub
+
+```bash
+npm install -D git+https://github.com/Dai5297/harness-engineer-codex.git
+npx harness-engineer init . --preset generic-software --project-name "Acme Platform"
+```
+
 ## Presets
 
 ### `generic-software`
@@ -77,20 +101,24 @@ Fixed roles:
 - `reviewer`
 - `qa-guard`
 
-Truth-source docs live under `docs/source-of-truth/`.
+Record-system docs are organized like this:
 
-### `agentadmin-codex`
+- `ARCHITECTURE.md`
+- `docs/design-docs/`
+- `docs/product-specs/`
+- `docs/generated/`
+- `docs/references/`
+- `docs/exec-plans/`
 
-A compatibility preset extracted from the AgentAdmin harness structure.
+## Language Modes
 
-It keeps the AgentAdmin-specific document layering (`dev-docs/ + spec/`) and the original fixed role names:
+`init` supports three output modes:
 
-- `architect-backend`
-- `architect-frontend`
-- `runtime-executor`
-- `console-ui`
-- `reviewer`
-- `qa-guard`
+- `en` for English-only harness files
+- `zh` for Chinese-localized harness files
+- `bilingual` for bilingual harness docs, including `AGENTS.override.md`
+
+Canonical file paths stay unchanged across all three modes.
 
 ## CLI
 
@@ -108,11 +136,11 @@ harness-engineer init [dir] \
 
 Notes:
 
-- Generates files only when missing by default.
-- Use `--force` to overwrite managed templates.
-- `--dev-command` generates `.codex/environments/environment.toml`.
-- `init` also adds `harness-engineer` to `devDependencies`.
-- `--language bilingual` keeps the base `AGENTS.md` canonical and adds a bilingual `AGENTS.override.md` plus localized core harness docs.
+- generates files only when missing by default
+- use `--force` to overwrite managed templates
+- `--dev-command` generates `.codex/environments/environment.toml`
+- `init` also adds `harness-engineer` to `devDependencies`
+- `init` is designed to fully scaffold the baseline harness, not just create a minimal starter file
 
 ### `task new`
 
@@ -122,7 +150,7 @@ harness-engineer task new <slug> --class A|B|C
 
 Creates:
 
-- `docs/plans/active/<slug>.md`
+- `docs/exec-plans/active/<slug>.md`
 - `logs/codex/active/<slug>/run.md`
 - `logs/codex/active/<slug>/handoff.md`
 
@@ -162,13 +190,13 @@ The package is intentionally source-first. `dist/`, `coverage/`, and `node_modul
 
 - unit tests for rendering, config helpers, and preset selection
 - integration tests for init, task lifecycle, CLI smoke flow, and status drift detection
-- a self-contained AgentAdmin compatibility snapshot test under `tests/integration/agentadmin-golden.test.ts`
+- independence checks to ensure generated output does not retain external-project identifiers or machine-local paths
 
 ## Repository Layout
 
 ```text
 src/      source code for the CLI and generators
-tests/    unit, integration, and fixture-backed compatibility tests
+tests/    unit and integration tests
 ```
 
 ## Open-Source Release Notes

package/README.zh-CN.md

@@ -1,34 +1,50 @@
 # harness-engineer
 
-`harness-engineer` 是一个面向 Codex 的仓库协作脚手架 CLI，用来把“harness 作为文件结构”的工作方式封装成可复用 npm 包。
+`harness-engineer` 是一个开源的 Codex 优先仓库脚手架 CLI，用来把“harness 作为文件结构”的协作方式封装成可复用 npm 包。
 
-它可以在一个空白仓库里一次性生成固定角色、长期记忆、runbook、任务计划与 handoff 结构，适合团队把 AI 协作流程沉淀为仓库内真源。
+它可以在空白仓库中一次性生成固定角色、长期记忆、runbook、记录系统文档以及执行计划闭环，让 AI 协作方式能够直接沉淀到仓库本身。
 
 > 许可证：[MIT](./LICENSE)
+> npm 包地址：[harness-engineer](https://www.npmjs.com/package/harness-engineer)
+> 更新记录：[CHANGELOG.md](./CHANGELOG.md)
+
+## 为什么现在是这个结构
+
+默认 preset 已按 OpenAI 的 harness engineering 文章思路调整：
+
+- 让 Codex 入口文件保持简短
+- 把仓库文档当成记录系统
+- 把执行计划当成一等工件进行版本化
+- 通过渐进式披露提供上下文，而不是塞一个巨大说明书
+
+文章里使用的是 `AGENTS.md` 概念；这个工具面向 Codex，因此实际生成的是 `AGENTS.override.md`。
 
 ## 它会生成什么
 
-- `AGENTS.md` 作为最短协作入口
+- `AGENTS.override.md` 作为简短的 Codex 协作地图
 - `.codex/config.toml` 和 `.codex/agents/` 下的固定角色文件
 - `.codex/memory/` 下的长期记忆
-- `docs/index.md`、runbook 和真源文档占位
-- `docs/plans/` 与 `logs/codex/` 下的任务闭环目录
+- `ARCHITECTURE.md` 以及 `docs/design-docs/`、`docs/product-specs/`、`docs/generated/`、`docs/references/` 下的记录系统文档
+- `docs/exec-plans/` 下的执行计划，以及 `logs/codex/` 下的运行产物
 - 机器可读配置 `harness-engineer.config.json`
 
 ## 快速开始
 
-发布后推荐这样使用：
+当前版本已经发布到 npm，最快的初始化方式是：
 
 ```bash
 pnpm dlx harness-engineer@latest init . \
   --preset generic-software \
   --project-name "Acme Platform" \
+  --language bilingual \
   --yes
 
 harness-engineer task new 2026-04-02-auth-debug --class B
 harness-engineer status
 ```
 
+这条 `init` 命令的目标就是一次性铺好完整的仓库内 Codex 基线：固定子代理、`.codex` 配置、长期记忆、runbook、记录系统文档以及任务目录。
+
 如果你是在当前源码仓库里本地运行：
 
 ```bash
@@ -38,12 +54,13 @@ pnpm build
 node dist/cli.js init . \
   --preset generic-software \
   --project-name "Acme Platform" \
+  --language bilingual \
   --yes
 ```
 
-## 直接从 npm 使用
+## 安装方式
 
-用户不需要 clone 当前仓库，也可以直接从 npm 初始化项目：
+### 直接从 npm 运行
 
 ```bash
 pnpm dlx harness-engineer@latest init . \
@@ -53,13 +70,20 @@ pnpm dlx harness-engineer@latest init . \
   --yes
 ```
 
-也可以先安装到项目里：
+### 安装到现有项目中
 
 ```bash
 npm install -D harness-engineer
 npx harness-engineer init . --preset generic-software --project-name "Acme Platform"
 ```
 
+### 直接从 GitHub 安装
+
+```bash
+npm install -D git+https://github.com/Dai5297/harness-engineer-codex.git
+npx harness-engineer init . --preset generic-software --project-name "Acme Platform"
+```
+
 ## 预设
 
 ### `generic-software`
@@ -75,20 +99,24 @@ npx harness-engineer init . --preset generic-software --project-name "Acme Platf
 - `reviewer`
 - `qa-guard`
 
-真源文档落在 `docs/source-of-truth/`。
+记录系统文档按以下结构组织：
 
-### `agentadmin-codex`
+- `ARCHITECTURE.md`
+- `docs/design-docs/`
+- `docs/product-specs/`
+- `docs/generated/`
+- `docs/references/`
+- `docs/exec-plans/`
 
-从 AgentAdmin harness 抽取出来的兼容预设。
+## 语言模式
 
-它保留 AgentAdmin 当前的文档分层方式（`dev-docs/ + spec/`）和固定角色命名：
+`init` 支持三种输出模式：
 
-- `architect-backend`
-- `architect-frontend`
-- `runtime-executor`
-- `console-ui`
-- `reviewer`
-- `qa-guard`
+- `en`：仅英文 harness 文件
+- `zh`：中文本地化 harness 文件
+- `bilingual`：双语 harness 文档，包括 `AGENTS.override.md`
+
+三种模式都保持相同的标准文件路径。
 
 ## CLI 命令
 
@@ -106,11 +134,11 @@ harness-engineer init [dir] \
 
 说明：
 
-- 默认只生成缺失文件，不覆盖已有模板。
-- 使用 `--force` 可以覆盖受管理模板。
-- 传入 `--dev-command` 时会生成 `.codex/environments/environment.toml`。
-- `init` 会把 `harness-engineer` 自动加入 `devDependencies`。
-- `--language bilingual` 会保留标准 `AGENTS.md`，并额外生成双语版 `AGENTS.override.md` 与本地化核心 harness 文档。
+- 默认只生成缺失文件，不覆盖已有模板
+- 使用 `--force` 可以覆盖受管理模板
+- 传入 `--dev-command` 时会生成 `.codex/environments/environment.toml`
+- `init` 会把 `harness-engineer` 自动加入 `devDependencies`
+- `init` 的设计目标是完整铺设基线 harness，而不仅是生成一个最小起步文件
 
 ### `task new`
 
@@ -120,7 +148,7 @@ harness-engineer task new <slug> --class A|B|C
 
 会创建：
 
-- `docs/plans/active/<slug>.md`
+- `docs/exec-plans/active/<slug>.md`
 - `logs/codex/active/<slug>/run.md`
 - `logs/codex/active/<slug>/handoff.md`
 
@@ -160,13 +188,13 @@ pnpm build
 
 - 单元测试：渲染、配置、预设选择
 - 集成测试：init、任务生命周期、CLI smoke、status 漂移检查
-- 兼容性测试：`tests/integration/agentadmin-golden.test.ts`
+- 独立性校验：确保生成结果不再残留外部项目标识或本机绝对路径
 
 ## 仓库结构
 
 ```text
 src/      CLI 与生成器源码
-tests/    单元、集成与 fixture 兼容性测试
+tests/    单元与集成测试
 ```
 
 ## 开源发布说明

package/dist/presets.d.ts

@@ -10,7 +10,6 @@ export interface PresetDefinition {
     paths: HarnessPathsConfig;
     roles: HarnessRoleConfig[];
     truthSources: TruthSourceConfig[];
-    includeOverrideFile: boolean;
     buildManagedFiles(config: HarnessConfig): GeneratedFile[];
 }
 export declare function getPreset(key: string): PresetDefinition;

package/dist/presets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../src/presets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAG1G,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAC3C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,kBAAkB,CAAC;IAC1B,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,EAAE,CAAC;CAC3D;AAo2ED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAQvD"}
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../src/presets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAG1G,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAC3C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,kBAAkB,CAAC;IAC1B,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,EAAE,CAAC;CAC3D;AAs0DD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAQvD"}