repo-harness 0.5.0 → 0.5.1

package/README.es.md

@@ -1,17 +1,26 @@
 # repo-harness
 
-Repo-local agentic development harness CLI y skill runtime para workflows de
-Claude/Codex.
+`repo-harness` convierte las sesiones de programación con Claude/Codex en un
+workflow repo-local repetible. Incluye un CLI y hooks de skill/runtime que
+escriben contexto, planes, handoffs, checks y evidencias de review dentro del
+proyecto, para que la siguiente sesión de agente continúe desde archivos y no
+desde el historial de chat.
+
+Úsalo para:
+
+- adoptar un repositorio existente con un contrato de agente tasks-first
+- mantener Claude y Codex alineados sobre los mismos planes, checks, handoffs y
+  límites de contexto
+- gastar menos tokens redescubriendo estructura gracias a CodeGraph y la carga
+  progresiva de contexto
+
+Entrega al agente un PRD o Sprint completo; después, tu bucle es solo review and
+`next`, o iniciar `/goal` y quedar AFK.
 
 [English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [Français](README.fr.md) | [Español](README.es.md)
 
 Dirección del repositorio: `https://github.com/Ancienttwo/repo-harness`
 
-`repo-harness` es un harness de workflow que aterriza el proceso de programación
-con IA en archivos del repositorio. Es a la vez el repositorio fuente de la CLI
-`repo-harness` y de su skill runtime, y el ejemplo autoalojado del workflow
-repo-local que él mismo genera para los proyectos downstream.
-
 ## Por qué usar repo-harness
 
 - **El estado de la sesión vive en archivos, no en el historial de chat.** Las
@@ -200,16 +209,41 @@ retoma contra un sprint concreto en vez de reinterpretar el chat original.
 Esta es la ruta más rápida para evaluar si un repositorio real es apto para
 adoptar este workflow.
 
-### Instalar o refrescar el runtime local
+### Instalar el CLI
+
+La ruta por defecto no requiere Node.js: el instalador usa Bun como runtime. Si
+Bun no existe, instala Bun primero y después instala el CLI `repo-harness`.
+
+```bash
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.sh | sh
+
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.ps1 | iex
+```
+
+<details>
+<summary>¿Ya tienes Bun o Node? Usa gestores de paquetes</summary>
 
 ```bash
+# Bun
+bun add -g repo-harness
+repo-harness init
+
+# Node/npm, con Bun ya en PATH porque el CLI corre sobre Bun
 npx -y repo-harness init
 ```
 
-La npm package release line y el generated workflow stamp usan ahora la misma
-línea `0.4.x`. `repo-harness init` es el bootstrap
-global, `repo-harness update` es el refresco user-level y `repo-harness adopt`
-es el refresco repo-local. `repo-harness init`
+</details>
+
+### Bootstrap del runtime del host
+
+```bash
+repo-harness init
+```
+
+`repo-harness init` es el bootstrap global, `repo-harness update` es el refresco
+user-level y `repo-harness adopt` es el refresco repo-local. `repo-harness init`
 configura el CLI, los hook adapters de nivel usuario, Waza, Mermaid, el brain
 root y CodeGraph MCP; el viejo camino Claude plugin `scripts/setup-plugins.sh`
 queda retirado.
@@ -346,8 +380,8 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.5.0`
-- Generated workflow stamp: `repo-harness@0.5.0+template@0.5.0`
+- npm package: `repo-harness@0.5.1`
+- Generated workflow stamp: `repo-harness@0.5.1+template@0.5.1`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -391,9 +425,28 @@ Los command facades públicos están en `assets/skill-commands/`; preservan la
 compatibilidad de discovery por skills, mientras el CLI y los hooks ejecutan:
 
 - Planning / review: `repo-harness-plan`, `repo-harness-review`, `repo-harness-autoplan`
+- Product planning layer: `repo-harness-prd` (activa `$geju`, luego usa drafting Claude-first con `claude -p --model opus`; Codex queda solo como fallback)
+- Sprint program layer: `repo-harness-sprint` (convierte un PRD en un backlog ordenado bajo `plans/sprints/`)
+- Goal session layer: `repo-harness-goal` / `repo-harness:goal` (prepara prompts `/goal` de Codex/Claude desde un PRD o Sprint detallado; si falta el documento, lo pide primero)
 - Repo workflow actions: `repo-harness-ship`, `repo-harness-init`, `repo-harness-migrate`, `repo-harness-upgrade`, `repo-harness-capability`, `repo-harness-architecture`, `repo-harness-handoff`, `repo-harness-deploy`, `repo-harness-repair`, `repo-harness-check`
 - Branch project creation: `repo-harness-scaffold`
 
+La cadena de planning está separada por capas:
+
+```text
+idea -> repo-harness-prd -> repo-harness-sprint from-prd -> repo-harness-goal
+```
+
+Usa `repo-harness-prd` cuando la fuente todavía es una idea de producto: primero
+ejecuta un direction pass con `$geju`, luego pide a Claude vía `claude -p --model opus` que
+redacte el PRD, con Codex solo como fallback. Usa
+`repo-harness-sprint from-prd <plans/prds/*.prd.md>` para convertir un PRD
+aprobado en un Sprint backlog ordenado con acceptance lines verificables por
+máquina. Usa `repo-harness-goal` solo cuando ya exista un PRD o Sprint detallado;
+prepara un prompt `/goal` acotado para Codex/Claude y mantiene el PRD/Sprint como
+source of truth. Si falta ese documento, el goal command debe pedirlo antes de
+empezar implementación desde el chat.
+
 `repo-harness adopt` se usa para repositorios existentes; `repo-harness-scaffold`
 queda como branch command para crear proyectos o módulos nuevos. `hooks-init`, `docs-init` y
 `create-project-dirs` son pasos internos, no commands públicos.

package/README.fr.md

@@ -1,17 +1,26 @@
 # repo-harness
 
-Harness CLI de développement agentique repo-local et skill runtime pour les
-workflows Claude/Codex.
+`repo-harness` transforme les sessions de code Claude/Codex en workflow
+repo-local répétable. Il fournit un CLI et des hooks skill/runtime qui écrivent
+le contexte, les plans, les handoffs, les checks et les preuves de review dans le
+projet, afin que la session d'agent suivante reprenne depuis les fichiers plutôt
+que depuis l'historique de chat.
+
+Utilisez-le pour :
+
+- adopter un dépôt existant avec un contrat d'agent tasks-first
+- garder Claude et Codex alignés sur les mêmes plans, checks, handoffs et limites
+  de contexte
+- dépenser moins de tokens à redécouvrir la structure grâce à CodeGraph et au
+  chargement progressif du contexte
+
+Donnez à l'agent un PRD ou Sprint complet ; ensuite, votre boucle se limite à
+review and `next`, ou à lancer `/goal` puis passer AFK.
 
 [English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [Français](README.fr.md) | [Español](README.es.md)
 
 Adresse du dépôt : `https://github.com/Ancienttwo/repo-harness`
 
-`repo-harness` est un harness de workflow qui matérialise le processus de
-programmation par IA dans les fichiers du dépôt. C'est à la fois le dépôt source
-du CLI `repo-harness` et de son skill runtime, et un exemple auto-hébergé du
-workflow repo-local qu'il génère lui-même pour les projets en aval.
-
 ## Pourquoi utiliser repo-harness
 
 - **L'état de session vit dans les fichiers, pas dans l'historique de chat.** Des
@@ -205,16 +214,43 @@ initial.
 C'est le chemin le plus rapide pour évaluer si un dépôt réel se prête à l'adoption
 de ce workflow.
 
-### Installer ou rafraîchir le runtime local
+### Installer le CLI
+
+Le chemin par défaut ne demande pas Node.js : l'installateur utilise Bun comme
+runtime. Si Bun est absent, il installe Bun d'abord, puis installe le CLI
+`repo-harness`.
+
+```bash
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.sh | sh
+
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.ps1 | iex
+```
+
+<details>
+<summary>Vous avez déjà Bun ou Node ? Utilisez les gestionnaires de packages</summary>
 
 ```bash
+# Bun
+bun add -g repo-harness
+repo-harness init
+
+# Node/npm, avec Bun déjà sur PATH car le CLI s'exécute sur Bun
 npx -y repo-harness init
 ```
 
-La release line du package npm et le generated workflow stamp utilisent
-désormais la même ligne `0.4.x`. `repo-harness init`
-sert au bootstrap global, `repo-harness update` au rafraîchissement
-user-level, et `repo-harness adopt` au rafraîchissement repo-local. `repo-harness init` configure le CLI, les hook adapters de niveau
+</details>
+
+### Bootstrap du runtime hôte
+
+```bash
+repo-harness init
+```
+
+`repo-harness init` sert au bootstrap global, `repo-harness update` au
+rafraîchissement user-level, et `repo-harness adopt` au rafraîchissement
+repo-local. `repo-harness init` configure le CLI, les hook adapters de niveau
 utilisateur, Waza, Mermaid, le brain root et CodeGraph MCP ; l'ancien chemin
 Claude plugin `scripts/setup-plugins.sh` est retiré.
 
@@ -350,8 +386,8 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.5.0`
-- Generated workflow stamp : `repo-harness@0.5.0+template@0.5.0`
+- npm package : `repo-harness@0.5.1`
+- Generated workflow stamp : `repo-harness@0.5.1+template@0.5.1`
 - GitHub repository : `Ancienttwo/repo-harness`
 - Release history : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -396,9 +432,28 @@ préservent la découverte par skills, tandis que l'exécution appartient au CLI
 aux hooks :
 
 - Planning / review : `repo-harness-plan`, `repo-harness-review`, `repo-harness-autoplan`
+- Product planning layer : `repo-harness-prd` (active `$geju`, puis rédige en Claude-first avec `claude -p --model opus` ; Codex ne sert que de fallback)
+- Sprint program layer : `repo-harness-sprint` (transforme un PRD en backlog ordonné dans `plans/sprints/`)
+- Goal session layer : `repo-harness-goal` / `repo-harness:goal` (prépare des prompts `/goal` Codex/Claude depuis un PRD ou Sprint détaillé ; si le document manque, il le demande d'abord)
 - Repo workflow actions : `repo-harness-ship`, `repo-harness-init`, `repo-harness-migrate`, `repo-harness-upgrade`, `repo-harness-capability`, `repo-harness-architecture`, `repo-harness-handoff`, `repo-harness-deploy`, `repo-harness-repair`, `repo-harness-check`
 - Branch project creation : `repo-harness-scaffold`
 
+La chaîne de planning est volontairement découpée en couches :
+
+```text
+idea -> repo-harness-prd -> repo-harness-sprint from-prd -> repo-harness-goal
+```
+
+Utilisez `repo-harness-prd` quand la source est encore une idée produit : il
+lance d'abord un direction pass `$geju`, puis demande à Claude via `claude -p --model opus`
+de rédiger le PRD, avec Codex seulement en fallback. Utilisez
+`repo-harness-sprint from-prd <plans/prds/*.prd.md>` pour transformer
+un PRD approuvé en Sprint backlog ordonné avec des lignes d'acceptance
+vérifiables par machine. Utilisez `repo-harness-goal` seulement lorsqu'un PRD ou
+Sprint détaillé existe déjà ; il prépare un prompt `/goal` borné pour
+Codex/Claude et garde le PRD/Sprint comme source of truth. Si ce document manque,
+le goal command doit le demander avant de lancer une implémentation depuis le chat.
+
 `repo-harness adopt` sert aux dépôts existants ; `repo-harness-scaffold` sert de
 branch command pour créer un nouveau projet ou module. `hooks-init`, `docs-init` et
 `create-project-dirs` sont des étapes internes, pas des commands publiques.

package/README.ja.md

@@ -1,16 +1,23 @@
 # repo-harness
 
-Claude/Codex の workflow 向けに、repo-local な agentic development harness の CLI と
-skill runtime を提供します。
+`repo-harness` は、Claude/Codex のコーディング session を、繰り返し使える
+repo-local workflow に変えます。CLI と skill/runtime hooks によって、context、plan、
+handoff、check、review evidence をプロジェクト内のファイルへ書き戻し、次の agent session が
+chat memory ではなくファイルから続きに入れるようにします。
+
+主な用途:
+
+- 既存リポジトリへ tasks-first agent contract を導入する
+- Claude と Codex を同じ plan、check、handoff、context boundary に揃える
+- CodeGraph と段階的な context loading により、構造を再発見するための token 消費を減らす
+
+Agent に完全な PRD または Sprint を渡せば、あとは review and `next` だけで進めるか、
+`/goal` を開始して AFK できます。
 
 [English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [Français](README.fr.md) | [Español](README.es.md)
 
 リポジトリ：`https://github.com/Ancienttwo/repo-harness`
 
-`repo-harness` は、AI 開発フローをリポジトリ内のファイルへ落とし込む workflow harness です。
-`repo-harness` CLI と skill runtime のソースリポジトリであると同時に、下流プロジェクト向けに
-自身が生成する repo-local workflow を、自分自身に適用したセルフホスト例でもあります。
-
 ## なぜ repo-harness を使うのか
 
 - **セッションの状態はファイルに残り、チャット履歴には残らない。** 別々の agent
@@ -172,13 +179,39 @@ PRD Sprint が durable source of truth となり、Codex Goal mode は元の cha
 
 実際のリポジトリがこの workflow を導入するのに適しているかを評価する、最速の経路です。
 
-### ローカル runtime をインストールまたはリフレッシュする
+### CLI をインストールする
+
+既定の経路では Node.js は不要です。installer は Bun を runtime として使います。
+Bun が見つからない場合は、先に Bun をインストールしてから `repo-harness` CLI をインストールします。
+
+```bash
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.sh | sh
+
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.ps1 | iex
+```
+
+<details>
+<summary>Bun または Node がすでにある場合は package manager も使えます</summary>
 
 ```bash
+# Bun
+bun add -g repo-harness
+repo-harness init
+
+# Node/npm。CLI runtime は Bun なので、Bun が PATH 上に必要です。
 npx -y repo-harness init
 ```
 
-npm package と generated workflow stamp は現在同じ `0.4.x` release line を使います。
+</details>
+
+### host runtime を bootstrap する
+
+```bash
+repo-harness init
+```
+
 `repo-harness init` は global bootstrap、`repo-harness update` は
 user-level refresh、`repo-harness adopt` は repo-local refresh です。`repo-harness init` は CLI、user-level hook adapters、Waza、Mermaid、
 brain root、CodeGraph MCP を設定し、退役した `scripts/setup-plugins.sh` の Claude plugin path は使いません。
@@ -312,8 +345,8 @@ hook がブロックしたときは、まず terminal の構造化された出
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.5.0`
-- Generated workflow stamp：`repo-harness@0.5.0+template@0.5.0`
+- npm package：`repo-harness@0.5.1`
+- Generated workflow stamp：`repo-harness@0.5.1+template@0.5.1`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -355,9 +388,28 @@ knowledge sync、handoff retrieval の workflow 設計に影響を与えてい
 公開 command facades は `assets/skill-commands/` にあります。host skill discovery との互換性を残しつつ、実行は CLI と hooks が担います。
 
 - Planning / review：`repo-harness-plan`、`repo-harness-review`、`repo-harness-autoplan`
+- Product planning layer：`repo-harness-prd`（先に `$geju` を有効化し、Claude-first の `claude -p --model opus` で PRD を起草する。Codex は fallback のみ）
+- Sprint program layer：`repo-harness-sprint`（PRD を `plans/sprints/` の順序付き backlog に分解する）
+- Goal session layer：`repo-harness-goal` / `repo-harness:goal`（詳細な PRD または Sprint artifact から Codex/Claude の `/goal` prompt を準備する。文書がなければ先に要求する）
 - Repo workflow actions：`repo-harness-ship`、`repo-harness-init`、`repo-harness-migrate`、`repo-harness-upgrade`、`repo-harness-capability`、`repo-harness-architecture`、`repo-harness-handoff`、`repo-harness-deploy`、`repo-harness-repair`、`repo-harness-check`
 - Branch project creation：`repo-harness-scaffold`
 
+planning chain は意図的に層を分けています。
+
+```text
+idea -> repo-harness-prd -> repo-harness-sprint from-prd -> repo-harness-goal
+```
+
+入力がまだプロダクトアイデアなら `repo-harness-prd` を使います。まず `$geju` の
+direction pass を行い、その後 Claude に `claude -p --model opus` で PRD を起草させます。Codex は
+Claude が使えない、または失敗した場合だけ fallback です。承認済み PRD を
+machine-checkable acceptance line 付きの順序付き Sprint backlog にするには
+`repo-harness-sprint from-prd <plans/prds/*.prd.md>` を使います。
+`repo-harness-goal` は詳細な PRD または Sprint artifact がある場合だけ使い、
+Codex/Claude 向けの bounded `/goal` prompt を準備し、PRD/Sprint を source of truth
+として維持します。その文書がない場合、goal command はチャット文脈から実装を始めず、
+先に文書を要求しなければなりません。
+
 `repo-harness adopt` は既存リポジトリ向け、`repo-harness-scaffold` は支線 command として新しいプロジェクトやモジュールを作成します。
 `hooks-init`、`docs-init`、`create-project-dirs` は内部ステップであり、公開 commands ではありません。
 

package/README.md

@@ -4,18 +4,25 @@
   <img src="docs/images/image.png" alt="One next button joining Claude and Codex under repo-harness workflow rules" width="760">
 </p>
 
-Repo-local agentic development harness CLI and skill runtime for Claude/Codex
-workflows. The npm package and primary command are now `repo-harness`.
-The legacy `repo-harness-skill` and `project-initializer` install paths are
-retired and removed by installed-copy sync.
-Repository: `https://github.com/Ancienttwo/repo-harness`
+`repo-harness` turns Claude/Codex coding sessions into a repeatable repo-local
+workflow. It ships a CLI plus skill/runtime hooks that write context, plans,
+handoffs, checks, and review evidence back into the project, so the next agent
+session can continue from files instead of chat memory.
 
-[English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [Français](README.fr.md) | [Español](README.es.md)
+Use it to:
+
+- adopt an existing repo with a tasks-first agent contract
+- keep Claude and Codex aligned on the same plans, checks, handoffs, and context
+  boundaries
+- spend fewer tokens rediscovering structure by using CodeGraph and progressive
+  context loading
+
+Give the agent a complete PRD or Sprint; after that, your loop is just review
+and `next`, or start `/goal` and go AFK.
 
-This repository now dogfoods its own tasks-first contract. It is both:
+Repository: `https://github.com/Ancienttwo/repo-harness`
 
-- the source repo for the `repo-harness` CLI and `repo-harness` skill runtime
-- a self-hosted example of the repo-local workflow it generates for other projects
+[English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [Français](README.fr.md) | [Español](README.es.md)
 
 ## Why repo-harness
 
@@ -214,12 +221,39 @@ safe to adopt in a real repo. It separates the machine-level runtime bootstrap
 from the repo-local contract install, so a dry run can show exactly what will
 change before anything is applied.
 
-### 1. Bootstrap the host runtime once
+### 1. Install the CLI
+
+No Node.js required for the default path: the installer uses Bun as the runtime.
+If Bun is missing, it installs Bun first, then installs the `repo-harness` CLI.
 
 ```bash
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.sh | sh
+
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.ps1 | iex
+```
+
+<details>
+<summary>Already have Bun or Node? Use package managers instead</summary>
+
+```bash
+# Bun
+bun add -g repo-harness
+repo-harness init
+
+# Node/npm, with Bun already on PATH because the CLI runs on Bun
 npx -y repo-harness init
 ```
 
+</details>
+
+### 2. Bootstrap the host runtime once
+
+```bash
+repo-harness init
+```
+
 `init` is the first-run global bootstrap path. It installs the current npm
 package as the global CLI, refreshes repo-harness skill aliases, installs
 user-level hook adapters, configures Waza runtime skills, persists a brain root
@@ -236,8 +270,8 @@ optional command, and verification surface for the Agent to execute deliberately
 ### Install and refresh examples
 
 ```bash
-# First machine bootstrap: global CLI, skills, host adapters, Waza, brain, CodeGraph.
-npx -y repo-harness init
+# First machine bootstrap after installing the CLI: skills, host adapters, Waza, brain, CodeGraph.
+repo-harness init
 
 # Refresh user-level CLI/runtime pieces after a package update.
 repo-harness update
@@ -249,7 +283,7 @@ repo-harness update --check
 repo-harness adopt --repo /path/to/repo
 ```
 
-### 2. Preview the repo-local contract
+### 3. Preview the repo-local contract
 
 ```bash
 npx -y repo-harness adopt --dry-run
@@ -261,7 +295,7 @@ created or refreshed. It should not create an application stack; existing repos
 use `repo-harness adopt`, while new projects or modules use
 `repo-harness-scaffold`.
 
-### 3. Apply, then prove the workflow
+### 4. Apply, then prove the workflow
 
 ```bash
 npx -y repo-harness adopt
@@ -427,8 +461,8 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.5.0`
-- Generated workflow stamp: `repo-harness@0.5.0+template@0.5.0`
+- npm package: `repo-harness@0.5.1`
+- Generated workflow stamp: `repo-harness@0.5.1+template@0.5.1`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -512,11 +546,28 @@ Source-owned command facades live in `assets/skill-commands/`. They keep host
 skill discovery compatible while the CLI and hooks own execution:
 
 - Planning and review: `repo-harness-plan`, `repo-harness-review`, `repo-harness-autoplan`
-- Product planning layer: `repo-harness-prd` (upper-layer PRDs in `plans/prds/`, evidence-marked unknowns, sprint-consumable sections)
+- Product planning layer: `repo-harness-prd` (activates `$geju`, then uses Claude-first `claude -p --model opus` drafting with Codex fallback to write upper-layer PRDs in `plans/prds/`)
 - Sprint program layer: `repo-harness-sprint` (ordered sprint backlogs in `plans/sprints/`, each row expanded with `$think` before the contract flow)
+- Goal session layer: `repo-harness-goal` / `repo-harness:goal` (prepares Codex/Claude `/goal` prompts from detailed PRD or Sprint artifacts and asks for those docs when missing)
 - Repo workflow actions: `repo-harness-ship`, `repo-harness-init`, `repo-harness-migrate`, `repo-harness-upgrade`, `repo-harness-capability`, `repo-harness-architecture`, `repo-harness-handoff`, `repo-harness-deploy`, `repo-harness-repair`, `repo-harness-check`
 - Branch project creation command: `repo-harness-scaffold`
 
+The planning chain is intentionally layered:
+
+```text
+idea -> repo-harness-prd -> repo-harness-sprint from-prd -> repo-harness-goal
+```
+
+Use `repo-harness-prd` when the source is still a product idea; it first runs a
+`$geju` direction pass, then asks Claude via `claude -p --model opus` to draft the PRD, with
+Codex only as fallback. Use
+`repo-harness-sprint from-prd <plans/prds/*.prd.md>` to turn an approved PRD into
+an ordered Sprint backlog with machine-checkable acceptance lines. Use
+`repo-harness-goal` only after a detailed PRD or Sprint artifact exists; it
+prepares a bounded Codex/Claude `/goal` prompt and keeps the PRD/Sprint as the
+source of truth. If that document is missing, the goal command must ask for it
+instead of starting implementation from chat context.
+
 `repo-harness adopt` is for an existing repo; `repo-harness-scaffold` creates a
 new project or module scaffold as a side command. `hooks-init`, `docs-init`, and
 `create-project-dirs` are internal steps, not public commands.
@@ -653,8 +704,18 @@ Configured in `assets/initializer-question-pack.v4.json` and consumed by `script
 
 ## Verification
 
+Use the single CI-equivalent gate for release review:
+
+```bash
+bun run check:ci
+```
+
+The gate expands to the owned checks below; `bun run check:release` adds only the npm unpublished-version preflight before delegating to the same gate.
+
 ```bash
 bun test
+bash scripts/check-deploy-sql-order.sh
+bash scripts/check-architecture-sync.sh
 bash scripts/check-task-sync.sh
 bash scripts/check-task-workflow.sh --strict
 bun scripts/inspect-project-state.ts --repo . --format text

package/README.zh-CN.md

@@ -1,16 +1,23 @@
 # repo-harness
 
-Repo-local agentic development harness CLI and skill runtime for Claude/Codex
-workflows.
+`repo-harness` 把 Claude/Codex 的 AI 编程会话变成可复用、可恢复、可检查的
+repo-local workflow。它提供 CLI 和 skill/runtime hooks，把上下文、计划、
+handoff、检查结果和 review evidence 写回项目文件，让下一个 agent 会话可以从文件继续，
+而不是依赖聊天记录。
+
+它主要解决三件事：
+
+- 用 tasks-first agent contract 快速接入已有仓库。
+- 让 Claude 和 Codex 共享同一套计划、检查、handoff 和上下文边界。
+- 用 CodeGraph 和渐进式 context loading 减少重复摸仓库结构的 token 消耗。
+
+你只需要把完整 PRD/Sprint 发给 Agent；之后的工作就是 review and `next`，
+或者启动 `/goal` 后 AFK。
 
 [English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [Français](README.fr.md) | [Español](README.es.md)
 
 仓库地址：`https://github.com/Ancienttwo/repo-harness`
 
-`repo-harness` 是一个把 AI 编程流程落到仓库文件里的工作流 harness。它既是
-`repo-harness` CLI 和 skill runtime 的源码仓库，也是它自己生成给下游项目的
-repo-local workflow 的自托管样例。
-
 ## 为什么用 repo-harness
 
 - **会话状态落在文件里，不在聊天记录里。** 不同 agent 会话——Claude、Codex、现在或之后——
@@ -178,12 +185,39 @@ source of truth，Codex Goal mode 只围绕具体 sprint 恢复和推进，而
 bootstrap 和 repo-local contract install 分开，所以 dry-run 能先展示会改什么，
 再决定是否应用。
 
-### 1. 先做一次 host runtime bootstrap
+### 1. 安装 CLI
+
+默认路径不需要 Node.js：installer 使用 Bun 作为 runtime。如果机器上没有 Bun，
+它会先安装 Bun，再安装 `repo-harness` CLI。
+
+```bash
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.sh | sh
+
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.ps1 | iex
+```
+
+<details>
+<summary>已经有 Bun 或 Node？可以改用包管理器</summary>
 
 ```bash
+# Bun
+bun add -g repo-harness
+repo-harness init
+
+# Node/npm；仍要求 Bun 已在 PATH 上，因为 CLI runtime 是 Bun
 npx -y repo-harness init
 ```
 
+</details>
+
+### 2. 先做一次 host runtime bootstrap
+
+```bash
+repo-harness init
+```
+
 `init` 是首次全局引导入口。它把当前 npm 包安装成全局 CLI，刷新 repo-harness
 skill aliases，安装 user-level hook adapters，配置 Waza runtime skills，把 brain
 root 持久化到 `~/.repo-harness/config.json`，并配置 CodeGraph MCP。它不会把当前目录
@@ -198,8 +232,8 @@ targets、可选 command 和 verification 的 `agent_actions`，由 Agent 再显
 ### 安装和刷新例子
 
 ```bash
-# 首次机器级 bootstrap：global CLI、skills、host adapters、Waza、brain、CodeGraph。
-npx -y repo-harness init
+# 安装 CLI 后做首次机器级 bootstrap：skills、host adapters、Waza、brain、CodeGraph。
+repo-harness init
 
 # 包更新后刷新 user-level CLI/runtime。
 repo-harness update
@@ -211,7 +245,7 @@ repo-harness update --check
 repo-harness adopt --repo /path/to/repo
 ```
 
-### 2. 预览 repo-local contract
+### 3. 预览 repo-local contract
 
 ```bash
 npx -y repo-harness adopt --dry-run
@@ -221,7 +255,7 @@ npx -y repo-harness adopt --dry-run
 helper runtime、hook adapter target 和 verification files。它不会创建应用技术栈；
 已有仓库走 `repo-harness adopt`，新项目或新模块走 `repo-harness-scaffold`。
 
-### 3. 应用后验证 workflow
+### 4. 应用后验证 workflow
 
 ```bash
 npx -y repo-harness adopt
@@ -360,8 +394,8 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.5.0`
-- Generated workflow stamp：`repo-harness@0.5.0+template@0.5.0`
+- npm package：`repo-harness@0.5.1`
+- Generated workflow stamp：`repo-harness@0.5.1+template@0.5.1`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -415,9 +449,25 @@ Co-authored-by: codex <codex@openai.com>
 兼容性，真正执行由 CLI 和 hooks 负责：
 
 - Planning / review：`repo-harness-plan`、`repo-harness-review`、`repo-harness-autoplan`
+- Product planning layer：`repo-harness-prd`（先激活 `$geju` 做格局判断，再优先用 Claude `claude -p --model opus` 起草 PRD；Codex 只做 fallback）
+- Sprint program layer：`repo-harness-sprint`（把 PRD 拆成 `plans/sprints/` 里的有序 backlog）
+- Goal session layer：`repo-harness-goal` / `repo-harness:goal`（从详细 PRD 或 Sprint 文档准备 Codex/Claude `/goal` prompt；缺文档时先要求补文档）
 - Repo workflow actions：`repo-harness-ship`、`repo-harness-init`、`repo-harness-migrate`、`repo-harness-upgrade`、`repo-harness-capability`、`repo-harness-architecture`、`repo-harness-handoff`、`repo-harness-deploy`、`repo-harness-repair`、`repo-harness-check`
 - 支线项目创建 command：`repo-harness-scaffold`
 
+规划链路按层推进：
+
+```text
+idea -> repo-harness-prd -> repo-harness-sprint from-prd -> repo-harness-goal
+```
+
+`repo-harness-prd` 处理产品想法：先跑 `$geju` direction pass，再用 Claude `claude -p --model opus`
+起草 PRD，Codex 只在 Claude 不可用或失败时 fallback。`repo-harness-sprint from-prd <plans/prds/*.prd.md>`
+把已批准 PRD 拆成带 machine-checkable acceptance 的 Sprint backlog；
+`repo-harness-goal` 只在已有详细 PRD 或 Sprint artifact 后使用，用它生成有边界的
+Codex/Claude `/goal` prompt，并把 PRD/Sprint 保持为 source of truth。缺少这份文档时，
+goal command 必须先要求补文档，而不是从聊天上下文直接开工。
+
 `repo-harness adopt` 用于已有仓库；`repo-harness-scaffold` 作为支线 command 创建新项目或模块。
 `hooks-init`、`docs-init` 和 `create-project-dirs` 是内部步骤，不是公共 commands。
 
@@ -448,8 +498,18 @@ bun scripts/assemble-template.ts --target agents --plan C --name "MyProject"
 
 ### Verification
 
+发布前 review 使用唯一 CI-equivalent gate：
+
+```bash
+bun run check:ci
+```
+
+这个 gate 展开为下面这些 repo-owned checks；`bun run check:release` 只是在委托同一个 gate 前增加 npm 版本未发布检查。
+
 ```bash
 bun test
+bash scripts/check-deploy-sql-order.sh
+bash scripts/check-architecture-sync.sh
 bash scripts/check-task-sync.sh
 bash scripts/check-task-workflow.sh --strict
 bun scripts/inspect-project-state.ts --repo . --format text