helloagents 2.2.16 → 2.3.3-beta.1

package/README.md

@@ -6,9 +6,9 @@
 
 <div align="center">
 
-**A multi-CLI workflow system that keeps going until tasks are implemented and verified.**
+**Let AI go beyond analysis — keep pushing until implementation and verification are done.**
 
-[![Version](https://img.shields.io/badge/version-2.2.16-orange.svg)](./pyproject.toml)
+[![Version](https://img.shields.io/badge/version-2.3.3-orange.svg)](./pyproject.toml)
 [![npm](https://img.shields.io/npm/v/helloagents.svg)](https://www.npmjs.com/package/helloagents)
 [![Python](https://img.shields.io/badge/python-%3E%3D3.10-3776AB.svg)](./pyproject.toml)
 [![Commands](https://img.shields.io/badge/workflow_commands-15-6366f1.svg)](./helloagents/functions)
@@ -26,83 +26,77 @@
 
 ## Table of Contents
 
-- [Why HelloAGENTS](#why-helloagents)
-- [What Changed vs Legacy Repo](#what-changed-vs-legacy-repo)
-- [Features](#features)
-- [Before and After (Snake Demo)](#before-and-after-snake-demo)
+- [Before and After](#before-and-after)
+- [Core Features](#core-features)
 - [Quick Start](#quick-start)
+- [Configuration](#configuration)
 - [How It Works](#how-it-works)
-- [Repository Guide](#repository-guide)
 - [In-Chat Workflow Commands](#in-chat-workflow-commands)
+- [Usage Guide](#usage-guide)
+- [Repository Guide](#repository-guide)
 - [FAQ](#faq)
 - [Troubleshooting](#troubleshooting)
 - [Version History](#version-history)
 - [Contributing](#contributing)
 - [License](#license)
 
-## Why HelloAGENTS
+## Before and After
+
+<table>
+<tr>
+<td width="50%" valign="top" align="center">
+
+**Without HelloAGENTS**
+
+<img src="./readme_images/08-demo-snake-without-helloagents.png" alt="Snake demo without HelloAGENTS" width="520">
 
-Many assistants can analyze tasks but often stop before real delivery. HelloAGENTS adds strict routing, staged execution, and verification gates.
+</td>
+<td width="50%" valign="top" align="center">
+
+**With HelloAGENTS**
+
+<img src="./readme_images/07-demo-snake-with-helloagents.png" alt="Snake demo with HelloAGENTS" width="520">
+
+</td>
+</tr>
+</table>
 
 | Challenge | Without HelloAGENTS | With HelloAGENTS |
-|---|---|---|
+|-----------|-------------------|-----------------|
 | Stops at planning | Ends with suggestions | Pushes to implementation and validation |
 | Output drift | Different structure every prompt | Unified routing and stage chain |
 | Risky operations | Easier to make destructive mistakes | EHRB risk detection and escalation |
 | Knowledge continuity | Context gets scattered | Built-in KB and session memory |
 | Reusability | Prompt-by-prompt effort | Commandized reusable workflow |
 
-<div align="center">
-  <img src="./readme_images/06-divider.svg" width="420" alt="divider">
-</div>
-
-## What Changed vs Legacy Repo
-
-Compared with legacy multi-bundle releases, the v2.x line is now package-first with a fundamentally different architecture.
-
-| Area | Legacy repo | Current repo |
-|---|---|---|
-| Distribution | Multiple bundle folders per CLI | One Python package + installer CLI |
-| Installation | Manual copy of config and skill folders | pip/uv install + `helloagents` interactive menu |
-| Routing | Three-layer (Context → Tools → Intent) | Five-dimension scoring (R0–R3) |
-| Workflow stages | 4 stages (Evaluate, Analyze, Design, Develop) | 3 stages (Evaluate, Design, Develop) + R1 fast flow, with sub-agent dispatch |
-| Agent system | None | RLM with 5 specialized roles + native sub-agents and session isolation |
-| Memory | No persistence | Three-layer: L0 user, L1 project KB, L2 session |
-| Safety | Basic EHRB | Three-layer EHRB (keyword + semantic + tool output) |
-| Hooks | None | Auto-deploy lifecycle hooks (Claude Code 9 events + Codex CLI notify) |
-| CLI targets | 5 visible bundle targets | 6 targets: codex, claude, gemini, qwen, grok, opencode |
-| Commands | 12 | 15 workflow commands |
-
-> ⚠️ **Migration notice:** Because repository structure and installation workflow changed in v2.x, legacy versions were moved to **helloagents-archive**: https://github.com/hellowind777/helloagents-archive
-
-## Features
+## Core Features
 
 <table>
 <tr>
 <td width="50%" valign="top">
 <img src="./readme_images/02-feature-icon-installer.svg" width="48" align="left">
 
-**RLM sub-agent orchestration**
+**RLM Sub-Agent Orchestration**
 
-5 specialized roles (reviewer, synthesizer, kb_keeper, pkg_keeper, writer) plus host CLI native sub-agents (explore/implement/test/design) are dispatched automatically based on task complexity, with session isolation per CLI instance. Tasks are scheduled via DAG dependency analysis with layer-by-layer parallel dispatch. Supports cross-CLI parallel scheduling and Agent Teams collaboration.
+5 specialized roles (reviewer / synthesizer / kb_keeper / pkg_keeper / writer) plus host CLI native sub-agents (explore / implement / test / design) are dispatched automatically based on task complexity. Tasks are scheduled via DAG dependency analysis with topological sort and layer-by-layer parallel dispatch. Supports cross-CLI parallel scheduling and Agent Teams collaboration.
 
 **Your gain:** complex tasks are broken down and handled by the right specialist, with parallel execution when possible.
 </td>
 <td width="50%" valign="top">
 <img src="./readme_images/03-feature-icon-workflow.svg" width="48" align="left">
 
-**Five-dimension routing (R0–R3)**
+**Structured Workflow (Evaluate → Design → Develop)**
 
-Every input is scored on action need, target clarity, decision scope, impact range, and EHRB risk — then routed to R0 direct response, R1 fast flow, R2 simplified flow, or R3 standard flow.
+Every input is scored on five dimensions and routed to R0 direct response, R1 fast flow, R2 simplified flow, or R3 standard flow. R2/R3 enter the full stage chain with explicit entry conditions, deliverables, and verification gates. Supports interactive and fully delegated modes.
 
-**Your gain:** proportional effort — simple queries stay fast, complex tasks get full process.
+**Your gain:** proportional effort — simple queries stay fast, complex tasks get full process with verification at every step.
 </td>
 </tr>
 <tr>
 <td width="50%" valign="top">
 <img src="./readme_images/04-feature-icon-safety.svg" width="48" align="left">
 
-**Three-layer safety detection (EHRB)**
+**Three-Layer Safety Detection (EHRB)**
 
 Keyword scan, semantic analysis, and tool-output inspection catch destructive operations before execution. Interactive and delegated modes enforce user confirmation.
 
@@ -111,7 +105,7 @@ Keyword scan, semantic analysis, and tool-output inspection catch destructive op
 <td width="50%" valign="top">
 <img src="./readme_images/05-feature-icon-compat.svg" width="48" align="left">
 
-**Three-layer memory model**
+**Three-Layer Memory Model**
 
 L0 user memory (global preferences), L1 project knowledge base (structured docs synced from code), and L2 session summaries (auto-persisted at stage transitions).
 
@@ -120,40 +114,24 @@ L0 user memory (global preferences), L1 project knowledge base (structured docs
 </tr>
 </table>
 
-### Data points from this repo
-
-- 6 CLI targets from helloagents/cli.py
-- 15 workflow commands from helloagents/functions
-- 5 RLM roles from helloagents/rlm/roles
-- 2 stage definitions from helloagents/stages
-- 5 core services from helloagents/services
-- 4 rule modules from helloagents/rules
-- 9 helper scripts from helloagents/scripts
-- 2 hooks configs from helloagents/hooks
-- 10 KB/plan templates from helloagents/templates
-
-## Before and After (Snake Demo)
+### Sub-Agent Native Mapping
 
-<table>
-<tr>
-<td width="50%" valign="top" align="center">
+| CLI | Native Sub-Agent Mechanism | RLM Mapping |
+|-----|---------------------------|-------------|
+| Claude Code | Task tool (explore / code / shell) | Direct mapping, supports Agent Teams |
+| Codex CLI | spawn_agent / Collab (multi-thread) | spawn_agent parallel scheduling, CSV batch orchestration |
+| OpenCode | Built-in agent mode | Fallback to sequential execution |
+| Gemini CLI | Built-in tool calls | Fallback to sequential execution |
+| Qwen CLI | Built-in tool calls | Fallback to sequential execution |
+| Grok CLI | Built-in tool calls | Fallback to sequential execution |
 
-**Without HelloAGENTS**
-
-<img src="./readme_images/08-demo-snake-without-helloagents.png" alt="Snake demo without HelloAGENTS" width="520">
+Additionally, HelloAGENTS provides: **five-dimension routing scoring** (action need, target clarity, decision scope, impact range, EHRB risk) to automatically determine processing depth for each input; **6 CLI targets** (Claude Code / Codex CLI / OpenCode / Gemini CLI / Qwen CLI / Grok CLI) with one rule set across all; **Hooks integration** (Claude Code 9 lifecycle hooks + Codex CLI notify hook) with automatic graceful degradation when unavailable.
 
-</td>
-<td width="50%" valign="top" align="center">
-
-**With HelloAGENTS**
-
-<img src="./readme_images/07-demo-snake-with-helloagents.png" alt="Snake demo with HelloAGENTS" width="520">
+## Quick Start
 
-</td>
-</tr>
-</table>
+> ⚠️ **Prerequisite:** All AI CLIs (Codex CLI / Claude Code, etc.) should be upgraded to the latest version with relevant feature flags enabled (e.g., sub-agents, CSV orchestration) to access all HelloAGENTS capabilities. VSCode extensions for these CLIs update more slowly — some newer features may require waiting for the extension to catch up. See CLI-specific compatibility notes below.
 
-## Quick Start
+> ⚠️ **Windows PowerShell 5.1** does not support `&&`. Run commands on each side of `&&` separately, or upgrade to [PowerShell 7+](https://learn.microsoft.com/powershell/scripting/install/installing-powershell-on-windows).
 
 ### Method A: One-line install script (recommended)
 
@@ -167,20 +145,34 @@ L0 user memory (global preferences), L1 project knowledge base (structured docs
 
 > The script auto-detects `uv` or `pip`, installs the HelloAGENTS package, and launches an interactive menu for you to select target CLIs. Re-running performs an update.
 
-**Update:**
+**Update:** re-run the install command above.
 
-    helloagents update
+**Uninstall:** `uv tool uninstall helloagents` or `pip uninstall helloagents` (depends on what the script detected)
+
+**Switch branch:**
+
+    # macOS / Linux
+    curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/beta/install.sh | HELLOAGENTS_BRANCH=beta bash
+
+    # Windows PowerShell
+    $env:HELLOAGENTS_BRANCH="beta"; irm https://raw.githubusercontent.com/hellowind777/helloagents/beta/install.ps1 | iex
 
 ### Method B: npx (Node.js >= 16)
 
     npx helloagents
 
-> Installs the Python package and launches an interactive menu. You can also specify directly: `npx helloagents install codex` (or use `npx -y` to auto-download without prompting)
+> Installs the Python package via pip and launches an interactive menu. You can also specify directly: `npx helloagents install codex` (or use `npx -y` to auto-download without prompting)
 
 > Requires Python >= 3.10. After first install, use the native `helloagents` command directly.
 
 > **Acknowledgment:** Thanks to @setsuna1106 for generously transferring the npm `helloagents` package ownership.
 
+**Update:** `npx helloagents@latest`
+
+**Uninstall:** `pip uninstall helloagents`
+
+**Switch branch:** `npx helloagents@beta`
+
 ### Method C: UV (isolated environment)
 
 **Step 0 — Install UV first (skip if already installed):**
@@ -193,17 +185,17 @@ L0 user memory (global preferences), L1 project knowledge base (structured docs
 
 > After installing UV, restart your terminal to make the `uv` command available.
 
-> ⚠️ Windows PowerShell 5.1 does not support `&&`. Please run commands separately, or upgrade to [PowerShell 7+](https://learn.microsoft.com/powershell/scripting/install/installing-powershell-on-windows).
-
 **Install and select targets (one command):**
 
     uv tool install --from git+https://github.com/hellowind777/helloagents helloagents && helloagents
 
 > Installs the package and launches an interactive menu for you to select target CLIs. You can also specify directly: `helloagents install codex`
 
-**Update:**
+**Update:** `uv tool install --from git+https://github.com/hellowind777/helloagents helloagents --force`
 
-    helloagents update
+**Uninstall:** `uv tool uninstall helloagents`
+
+**Switch branch:** `uv tool install --from git+https://github.com/hellowind777/helloagents@beta helloagents --force`
 
 ### Method D: pip (Python >= 3.10)
 
@@ -213,33 +205,26 @@ L0 user memory (global preferences), L1 project knowledge base (structured docs
 
 > Installs the package and launches an interactive menu for you to select target CLIs. You can also specify directly: `helloagents install codex`
 
-**Update:**
+**Update:** `pip install --upgrade git+https://github.com/hellowind777/helloagents.git`
 
-    pip install --upgrade git+https://github.com/hellowind777/helloagents.git
+**Uninstall:** `pip uninstall helloagents`
 
-### Install HelloAgents for different CLI targets
+**Switch branch:** `pip install --upgrade git+https://github.com/hellowind777/helloagents.git@beta`
 
-    helloagents                  # interactive menu
+### HelloAGENTS commands (after installation)
 
-    helloagents install codex    # specify target directly
+> ⚠️ These commands depend on the installed package. If a remote update causes issues, use the native install/update/uninstall commands from your installation method above.
 
+    helloagents                  # interactive menu
+    helloagents install codex    # specify target directly
     helloagents install --all    # install to all detected CLIs
-
-### Verify
-
-    helloagents status
-
-    helloagents version
-
-### Uninstall
-
-    helloagents uninstall codex
-
-    helloagents uninstall --all
-
-### Clean caches
-
-    helloagents clean
+    helloagents status           # check installation status
+    helloagents version          # check version
+    helloagents update           # update + auto-sync all targets
+    helloagents update beta      # switch branch + auto-sync
+    helloagents uninstall codex  # uninstall from a CLI target
+    helloagents uninstall --all  # uninstall from all targets
+    helloagents clean            # clean caches
 
 ### Codex CLI example
 
@@ -266,13 +251,17 @@ L0 user memory (global preferences), L1 project knowledge base (structured docs
     helloagents update
 
 > ⚠️ **Codex CLI config.toml compatibility notes:** The following settings may affect HelloAGENTS:
-> - `[features]` `steer = true` — changes input submission behavior, may interfere with workflow interaction
 > - `[features]` `child_agents_md = true` — experimental, injects extra instructions that may conflict with HelloAGENTS
 > - `project_doc_max_bytes` too low — default 32KB, AGENTS.md will be truncated (auto-set to 131072 during install)
 > - `agent_max_depth = 1` — limits sub-agent nesting depth, recommend keeping default or ≥2
-> - `agent_max_threads` too low — default 6, lower values limit parallel sub-agent scheduling
+> - `agent_max_threads` too low — default 6, lower values limit parallel sub-agent scheduling (CSV batch mode recommends ≥16)
 > - `[features]` `multi_agent = true` — must be enabled for sub-agent orchestration to work
-> - Collab sub-agent scheduling is experimental, requires Codex CLI feature gate to be enabled
+> - `[features]` `sqlite = true` — must be enabled for CSV batch orchestration (spawn_agents_on_csv)
+> - Collab sub-agent scheduling requires Codex CLI feature gate to be enabled
+>
+> 💡 **Best practices:**
+> - HelloAGENTS is optimized for Codex CLI — supports `high` and below reasoning effort levels. `xhigh` reasoning is **not supported** and may cause instruction-following issues
+> - Use the terminal/CLI version of Codex for the best experience. The VSCode extension updates lag behind the CLI — newer features (e.g., CSV batch orchestration, Collab multi-agent) may require waiting for the extension to catch up
 
 ### Claude Code example
 
@@ -303,25 +292,37 @@ L0 user memory (global preferences), L1 project knowledge base (structured docs
 > - Agent Teams collaboration mode requires environment variable: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
 > - Parallel sub-agent count is managed automatically by the model, no user-side limit config needed
 
-### Beta branch
+## Configuration
 
-To install from the `beta` branch, append `@beta` to the repository URL:
+Customize workflow behavior via `config.json` after installation. Only include keys you want to override — missing keys use defaults.
 
-    # One-line script (auto-launches interactive menu after install)
-    # macOS / Linux
-    curl -fsSL https://raw.githubusercontent.com/hellowind777/helloagents/beta/install.sh | HELLOAGENTS_BRANCH=beta bash
+**Storage locations (highest priority first):**
 
-    # Windows PowerShell
-    $env:HELLOAGENTS_BRANCH="beta"; irm https://raw.githubusercontent.com/hellowind777/helloagents/beta/install.ps1 | iex
+1. Project-level: `{project_root}/.helloagents/config.json` — current project only
+2. Global: `~/.helloagents/config.json` — all projects
+3. Built-in defaults
 
-    # npx (or use npx -y to auto-download without prompting)
-    npx helloagents@beta
+**Available keys:**
 
-    # UV
-    uv tool install --from git+https://github.com/hellowind777/helloagents@beta helloagents && helloagents
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `OUTPUT_LANGUAGE` | string | `zh-CN` | Language for AI output and KB files |
+| `KB_CREATE_MODE` | int | `2` | KB creation: `0`=OFF, `1`=on-demand (prompt ~init), `2`=auto on code changes, `3`=always auto |
+| `BILINGUAL_COMMIT` | int | `1` | Commit language: `0`=OUTPUT_LANGUAGE only, `1`=OUTPUT_LANGUAGE + English |
+| `EVAL_MODE` | int | `1` | Clarification mode: `1`=progressive (1 question/round, max 5), `2`=one-shot (all at once, max 3) |
+| `UPDATE_CHECK` | int | `72` | Update check cache TTL in hours: `0`=OFF |
+| `CSV_BATCH_MAX` | int | `16` | CSV batch max concurrency: `0`=OFF, cap 64 (Codex CLI only) |
 
-    # pip
-    pip install git+https://github.com/hellowind777/helloagents.git@beta && helloagents
+**Example:**
+
+```json
+{
+  "KB_CREATE_MODE": 0,
+  "EVAL_MODE": 2
+}
+```
+
+> File missing or unparseable is silently skipped with defaults applied. Unknown keys produce a warning and are ignored.
 
 ## How It Works
 
@@ -333,21 +334,6 @@ To install from the `beta` branch, append `@beta` to the repository URL:
 6. Three-layer memory (user / project KB / session) preserves context across sessions.
 7. Stage chain completes with verified output and optional knowledge base sync.
 
-## Repository Guide
-
-- AGENTS.md: router and workflow protocol
-- SKILL.md: skill discovery metadata for CLI targets
-- pyproject.toml: package metadata (v2.2.16)
-- helloagents/cli.py: installer entry
-- helloagents/functions: workflow commands
-- helloagents/stages: design, develop
-- helloagents/services: knowledge, package, memory and support services
-- helloagents/rules: state, cache, tools, scaling
-- helloagents/rlm: role library and orchestration helpers
-- helloagents/hooks: Claude Code and Codex CLI hooks configs
-- helloagents/scripts: automation scripts
-- helloagents/templates: KB and plan templates
-
 ## In-Chat Workflow Commands
 
 These commands run inside AI chat, not your system shell.
@@ -366,6 +352,160 @@ These commands run inside AI chat, not your system shell.
 | ~rlm | role orchestration (spawn / agents / resume / team) |
 | ~status / ~help | status and help |
 
+## Usage Guide
+
+### Three Workflow Modes
+
+| Mode | Description | When to use |
+|------|-------------|-------------|
+| `~auto` | Full autonomous flow from requirement to verified implementation (Evaluate → Design → Develop → Verify) | Clear requirement, want end-to-end delivery |
+| `~plan` | Planning only, generates a proposal package then stops — no code written | Want to review the plan before committing |
+| `~exec` | Skip evaluation and design, execute an existing plan package directly | After `~plan` review, ready to implement |
+
+Typical pattern: `~plan` first → review → `~exec` to implement. Or just `~auto` for one-shot delivery.
+
+### Interactive vs Delegated Mode
+
+When `~auto` or `~plan` presents its confirmation, you choose:
+
+- **Interactive (default):** pauses at key decision points (plan selection, failure handling)
+- **Delegated (fully automatic):** auto-advances all stages, auto-selects recommended options, only pauses on EHRB risk
+- **Plan-only delegated:** fully automatic but stops after design, never enters development
+
+Without `~` commands, plain-text input is automatically routed to R0–R3 based on complexity.
+
+### Requirement Evaluation
+
+Before R2/R3 tasks enter execution, the system scores requirements on four dimensions (scope 0–3, deliverable spec 0–3, implementation conditions 0–2, acceptance criteria 0–2, total 10). Score ≥ 8 proceeds to confirmation; < 8 triggers clarifying questions:
+
+- `EVAL_MODE=1` (default, progressive): asks 1 lowest-scoring dimension per round, up to 5 rounds
+- `EVAL_MODE=2` (one-shot): asks all low-scoring dimensions at once, up to 3 rounds
+
+Context inferred from the existing codebase counts toward the score automatically. Say "skip evaluation / just do it" to bypass the questioning phase.
+
+### Parallel Design Proposals
+
+In the R3 standard path, the design stage dispatches 3–6 sub-agents to independently generate competing implementation proposals. The main agent evaluates all proposals across four dimensions: user value, solution soundness, risk (including EHRB), and implementation cost. Weights are dynamically adjusted based on project characteristics (e.g., performance-critical systems weight soundness higher; MVPs weight cost higher).
+
+- Interactive mode: user selects a proposal or requests re-generation (max 1 retry)
+- Delegated mode: recommended proposal is auto-selected
+- R2 simplified path skips multi-proposal comparison and goes directly to planning
+
+### Auto Dependency Management
+
+During development, the system auto-detects the project's package manager via lockfiles (`yarn.lock` → yarn, `uv.lock` → uv, `Gemfile.lock` → bundler, etc.) and handles dependencies:
+
+- Declared but missing dependencies: auto-installed
+- New dependencies required by tasks: auto-added with declaration file updated
+- Ambiguous dependencies: user is asked before installing
+
+### Quality Verification (Ralph Loop & Break-loop)
+
+**Ralph Loop** (Claude Code, via SubagentStop Hook): after a sub-agent completes code changes, the project's verification command runs automatically. On failure, the sub-agent is blocked from exiting and must fix the issue (max 1 retry loop). Verification command priority: `.helloagents/verify.yaml` → `package.json` scripts → auto-detected.
+
+**Break-loop** (deep root cause analysis): triggered when a task fails repeatedly (after Ralph Loop + at least 1 manual fix attempt), performing five-dimension root cause analysis:
+
+1. Root cause classification (logic error / type mismatch / missing dependency / environment / design flaw)
+2. Why previous fixes didn't work
+3. Prevention mechanism suggestions
+4. Systemic scan — same issue in other modules?
+5. Lessons learned recorded in the acceptance report
+
+### Custom Command Extension
+
+Create `.helloagents/commands/` in your project and drop in Markdown files — the filename becomes the command name:
+
+    .helloagents/commands/deploy.md  →  ~deploy
+    .helloagents/commands/release.md →  ~release
+
+File content defines the execution rules. The system applies a lightweight gate (requirement understanding + EHRB check).
+
+### Smart Commit (~commit)
+
+`~commit` does more than generate a message:
+
+- Analyzes `git diff` to auto-generate Conventional Commits formatted messages
+- Pre-commit quality checks (code-doc consistency, test coverage, verification commands)
+- Auto-excludes sensitive files (`.env`, `*.pem`, `*.key`, etc.) — never runs `git add .`
+- Shows file list before staging, supports exclusion
+- Options: local commit only / commit + push / commit + push + create PR
+- Bilingual commit messages when `BILINGUAL_COMMIT=1`
+
+### Manual Sub-Agent Invocation
+
+Beyond automatic dispatch, you can manually invoke specific roles:
+
+    ~rlm spawn reviewer "review src/api/ for security issues"
+    ~rlm spawn writer "generate API reference docs"
+    ~rlm spawn reviewer,synthesizer "analyze and summarize the auth module"  # parallel
+
+Available roles: `reviewer` (code review), `synthesizer` (multi-source synthesis), `kb_keeper` (KB maintenance), `pkg_keeper` (plan package management), `writer` (documentation).
+
+### Multi-Terminal Collaboration
+
+Multiple terminals (across different CLIs) can share a task list:
+
+    # Terminal A
+    hellotasks=my-project codex
+
+    # Terminal B
+    hellotasks=my-project claude
+
+Commands once enabled:
+
+    ~rlm tasks                  # view shared task list
+    ~rlm tasks available        # see unclaimed tasks
+    ~rlm tasks claim <id>       # claim a task
+    ~rlm tasks complete <id>    # mark done
+    ~rlm tasks add "task title" # add a new task
+
+Tasks are stored in `{KB_ROOT}/tasks/` with file locking to prevent concurrent conflicts.
+
+### KB Auto-Sync & CHANGELOG
+
+The knowledge base syncs automatically at these points:
+
+- After every development stage, `kb_keeper` sub-agent syncs module docs to reflect actual code
+- After every R1/R2/R3 task completion, CHANGELOG is auto-appended
+- On session end (Claude Code Stop Hook), KB sync + L2 session summary write triggered asynchronously
+
+CHANGELOG uses semantic versioning (X.Y.Z). Version source priority: user-specified → project file (package.json, pyproject.toml, etc., supporting 15+ languages/frameworks) → git tag → last CHANGELOG entry → 0.1.0. R1 fast-path changes are recorded under a "Quick Modifications" category with file:line range.
+
+`KB_CREATE_MODE` controls automatic behavior: `0`=off, `1`=prompt on demand, `2`=auto on code changes (default), `3`=always auto.
+
+### Worktree Isolation
+
+When multiple sub-agents need to modify different regions of the same file simultaneously (Claude Code only), the system automatically uses `Task(isolation="worktree")` to create an independent git worktree for each sub-agent, preventing Edit tool conflicts. The main agent merges all worktree changes in the consolidation phase. Only activated when sub-agents have overlapping file writes; read-only tasks don't use it.
+
+### CSV Batch Orchestration (Codex CLI)
+
+When ≥6 structurally identical tasks exist in the same execution layer, the system auto-converts `tasks.md` into a task CSV and dispatches via `spawn_agents_on_csv`. Each worker receives its row data + instruction template, executes independently, and reports results.
+
+- Progress tracked in real-time via `agent_job_progress` events (pending/running/completed/failed/ETA)
+- State persisted in SQLite for crash recovery
+- Partial failures still export results with failure summary
+- Heterogeneous tasks automatically fall back to `spawn_agent` sequential dispatch
+- Configure concurrency via `CSV_BATCH_MAX` (default 16, max 64, set to 0 to disable)
+
+### Update Check
+
+On the first response of each session, the system silently checks for new versions. Results are cached at `~/.helloagents/.update_cache`, valid for the duration set by `UPDATE_CHECK` (default 72 hours, set to 0 to disable). When a new version is available, `⬆️ New version {version} available` appears in the response footer. Any errors during the check are silently skipped and never interrupt normal usage.
+
+## Repository Guide
+
+- AGENTS.md: router and workflow protocol
+- SKILL.md: skill discovery metadata for CLI targets
+- pyproject.toml: package metadata (v2.3.3)
+- helloagents/cli.py: installer entry
+- helloagents/functions: workflow commands (15)
+- helloagents/stages: design, develop
+- helloagents/services: knowledge, package, memory and support services
+- helloagents/rules: state, cache, tools, scaling, evaluation, sub-agent protocols
+- helloagents/rlm: role library and orchestration helpers
+- helloagents/hooks: Claude Code and Codex CLI hooks configs
+- helloagents/scripts: automation scripts
+- helloagents/templates: KB and plan templates
+
 ## FAQ
 
 - Q: Is this a Python CLI tool or prompt package?
@@ -402,7 +542,27 @@ These commands run inside AI chat, not your system shell.
 
 ## Version History
 
-### v2.2.16 (current)
+### v2.3.3 (current)
+
+- AGENTS.md slimmed from 1186 to ~700 lines (-41%), reducing risk of LLMs selectively ignoring rules
+- G4 evaluation details, G9/G10 sub-agent protocols extracted to on-demand module files via G7
+- Sub-agent rule file (subagent.md) reduced from 26KB to 1.4KB (-94%)
+- Eliminated cross-module reference risks by inlining critical rules at usage sites
+- inject_context.py gains module-load signals to ensure rule recovery after context compaction
+
+### v2.3.0
+
+- Comprehensive cross-audit fix: unified role output format, normalized path references, code-doc consistency alignment
+- Quality verification loop (Ralph Loop): auto-verify after sub-agent completion, block and feedback on failure
+- Auto context injection for sub-agents and rule reinforcement for main agent
+- Deep 5-dimension root cause analysis on repeated failures (break-loop)
+- Auto-inject project technical guidelines before sub-agent development
+- Pre-commit quality checks (code-doc consistency, test coverage, verification commands)
+- Worktree isolation for parallel editing
+- Custom command extension (.helloagents/commands/)
+- Auto-append Git author info to CHANGELOG entries
+
+### v2.2.16
 
 - Refactored evaluation dimension system with dimension isolation rule, pass threshold tuned to 8/10. Options are user-need-driven, organized by style direction rather than complexity tiers (e.g. UI design offers different styles instead of simple/medium/complex); recommended option points to the most complete deliverable, derived from recommendation principles and scoring criteria rather than hardcoded
 - Proposal design requires both implementation path and deliverable design direction to differ across alternatives, each sub-agent independently outputs a complete proposal including presentation direction, style, and experience
@@ -415,73 +575,6 @@ These commands run inside AI chat, not your system shell.
 - Adjusted Codex CLI memory limit to 128 KiB to prevent rules file truncation
 - Improved recommendation option generation rules, proposal differentiation requirements, and evaluation scoring criteria
 
-### v2.2.14
-
-- DAG dependency scheduling for task execution (depends_on, topological sort, layer-by-layer parallel dispatch with failure propagation)
-- Graded retry and standardized sub-agent return format with scope verification
-- Sub-agent orchestration paradigm: four-step method, prompt template, behavior constraints (route-skip, output format)
-- Execution path hardening: explicit R1 upgrade triggers, DESIGN retry limits, DEVELOP entry/exit conditions
-- Workflow rule audit: terminology and format consistency, redundancy cleanup
-
-### v2.2.13
-
-- R3 design proposals default ≥3 parallel, parallel batch limit ≤6, explicit sub-agent count principle (count = independent work units, no vague wording), add sub-agent orchestration config tips to README
-
-### v2.2.12
-
-- Comprehensive parallel sub-agent orchestration across all flows and commands, extend G10 coverage, eliminate hardcoded agent counts, add universal parallel information gathering principle
-
-### v2.2.11
-
-- Three-stage gate model: merge analysis into design stage (EVALUATE → DESIGN → DEVELOP), optimize stop points and fix sub-agent orchestration consistency
-
-### v2.2.10
-
-- Streamline sub-agent roles and integrate native multi-agent orchestration for all supported CLIs
-
-### v2.2.9
-
-- Comprehensive Windows file-locking fix: preemptive unlock and rename-aside fallback for install/update/uninstall/clean
-
-### v2.2.8
-
-- Codex CLI attention optimization for more stable HelloAGENTS execution
-
-### v2.2.7
-
-- **G12 Hooks integration spec:** 9 Claude Code lifecycle hooks + Codex CLI notify hook
-- **Auto-deploy Hooks:** auto-deploy and clean up Hooks config during install/uninstall
-- **Codex CLI native sub-agent:** G10 adds spawn_agent protocol with cross-CLI parallel scheduling
-- **Agent Teams protocol:** G10 adds Claude Code multi-role collaboration protocol
-- **SKILL integration:** auto-deploy SKILL.md to skills discovery directory for all CLI targets
-- **RLM command expansion:** add ~rlm agents/resume/team subcommands with parallel multi-role dispatch
-- **Stage parallel optimization:** parallel rules for develop stage, serial annotation for design
-- **Memory v2 bridge:** add Codex Memory v2 bridge protocol
-- **Script modularization:** extract config_helpers.py module
-
-### v2.2.5
-
-- **RLM sub-agent system:** 5 specialized roles + native sub-agents with automatic dispatch and session isolation
-- **Five-dimension routing (R0–R3):** replaces legacy three-layer routing
-- **Four-stage workflow + R1 fast flow:** stage chain (Evaluate → Analyze → Design → Develop) with R1 fast flow for single-point operations
-- **Three-layer memory:** L0 user preferences, L1 project knowledge base, L2 session summaries
-- **Three-layer EHRB:** keyword + semantic + tool-output safety detection
-- **Package-first installer:** pip/uv install with `helloagents` interactive menu
-- **15 workflow commands:** added ~rlm, ~validatekb, ~status
-- **6 CLI targets:** added OpenCode support
-- **Interactive installation menu:** multi-select target CLIs with one command
-- **Auto locale detection:** CLI messages switch between Chinese and English based on system locale
-- **Windows encoding fix:** UTF-8 safe subprocess handling on all platforms
-- **Knowledge base service:** structured project docs auto-synced from code changes
-- **Attention service:** live status tracking and progress snapshots
-
-### v2.0.1 (legacy multi-bundle baseline)
-
-- Multi-bundle distribution with manual copy-based installation
-- Three-layer routing (Context → Tools → Intent)
-- 4 workflow stages, 12 commands, 5 CLI targets
-- No sub-agent system, no persistent memory
-
 ## Contributing
 
 See CONTRIBUTING.md for contribution rules and PR checklist.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "2.2.16",
+  "version": "2.3.3-beta.1",
   "type": "module",
   "description": "HelloAGENTS - AI-native sub-agent orchestration framework for multi-CLI environments",
   "author": "HelloWind",
@@ -16,7 +16,18 @@
   "files": [
     "bin/"
   ],
-  "keywords": ["ai", "agent", "claude", "codex", "gemini", "qwen", "grok", "opencode", "cli", "workflow"],
+  "keywords": [
+    "ai",
+    "agent",
+    "claude",
+    "codex",
+    "gemini",
+    "qwen",
+    "grok",
+    "opencode",
+    "cli",
+    "workflow"
+  ],
   "engines": {
     "node": ">=16"
   }