helloagents 3.0.9-beta.1 → 3.0.10

package/README.md

@@ -6,9 +6,9 @@
 
 <div align="center">
 
-**Quality-driven workflow framework for AI coding CLIs — 14 auto-activated skills, process discipline, and checklist-based quality checks.**
+**A workflow layer for AI coding CLIs: skills, project knowledge, delivery checks, safer config writes, and resumable execution.**
 
-[![Version](https://img.shields.io/badge/version-3.0.9-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.10-orange.svg)](./package.json)
 [![npm](https://img.shields.io/npm/v/helloagents.svg)](https://www.npmjs.com/package/helloagents)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](./package.json)
 [![Skills](https://img.shields.io/badge/skills-14-6366f1.svg)](./skills)
@@ -25,35 +25,30 @@
 ---
 
 > [!IMPORTANT]
-> **Looking for v2.x?** The legacy Python-based codebase has been moved to a separate archive repository: [helloagents-archive](https://github.com/hellowind777/helloagents-archive). The v3 line is a complete rewrite — pure Node.js/Markdown architecture, no Python dependency.
+> Looking for `v2.x`? The old Python line now lives in [helloagents-archive](https://github.com/hellowind777/helloagents-archive). The `v3` line is a full rewrite based on Node.js, Markdown rules, skills, and small runtime scripts.
 
-## 📑 Table of Contents
+## Contents
 
-<details>
-<summary><strong>Click to expand</strong></summary>
+- [What HelloAGENTS Does](#what-helloagents-does)
+- [What Changed Since v3.0.7](#what-changed-since-v307)
+- [Core Features](#core-features)
+- [Quick Start](#quick-start)
+- [CLI Management](#cli-management)
+- [Commands in Chat](#commands-in-chat)
+- [Project Knowledge Base](#project-knowledge-base)
+- [Workflow and Delivery](#workflow-and-delivery)
+- [Configuration](#configuration)
+- [How Each CLI Is Integrated](#how-each-cli-is-integrated)
+- [Verification](#verification)
+- [FAQ](#faq)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
 
-- [🎯 Why HelloAGENTS?](#-why-helloagents)
-- [🆚 Compared with v2.3.8](#-compared-with-v238)
-- [✨ Core Features](#-core-features)
-- [🚀 Quick Start](#-quick-start)
-- [🔄 Installation Lifecycle & File Writes](#-installation-lifecycle--file-writes)
-- [📖 Commands](#-commands)
-- [🔧 Configuration](#-configuration)
-- [⚙️ How It Works](#️-how-it-works)
-- [📚 Usage Guide](#-usage-guide)
-- [🧪 Verification](#-verification)
-- [❓ FAQ](#-faq)
-- [🛠️ Troubleshooting](#️-troubleshooting)
-- [📈 Version History](#-version-history)
-- [📜 License](#-license)
+## What HelloAGENTS Does
 
-</details>
+AI coding CLIs can move fast, but they can also stop at advice, skip checks, lose project context, or report completion before the work is really done.
 
-## 🎯 Why HelloAGENTS?
-
-Ever had an AI coding assistant that stops at "here's what you should do" instead of actually doing it? Or one that writes code but skips tests, ignores edge cases, and calls it done?
-
-HelloAGENTS fixes that. It's a workflow layer that sits on top of your AI CLI and enforces quality at every step.
+HelloAGENTS adds a workflow layer on top of Claude Code, Gemini CLI, and Codex CLI. It helps the agent choose the right path, use task-specific quality skills, keep a project knowledge base, and verify work before delivery.
 
 <table>
 <tr>
@@ -74,814 +69,573 @@ HelloAGENTS fixes that. It's a workflow layer that sits on top of your AI CLI an
 </tr>
 </table>
 
-| Challenge | Without HelloAGENTS | With HelloAGENTS |
-|-----------|-------------------|-----------------|
-| **Stops at planning** | Ends with suggestions | Pushes through to implementation and verification |
-| **Quality inconsistency** | Varies by prompt | 14 skills auto-activate based on task type |
-| **Risky operations** | Easy to make destructive mistakes | Guard system blocks dangerous commands |
-| **No verification** | "It should work" | Ralph Loop runs lint/test/build before completion |
-| **Knowledge loss** | Context scattered across sessions | Project KB persists and grows |
+| Problem | Without HelloAGENTS | With HelloAGENTS |
+|---------|---------------------|------------------|
+| Stops too early | Ends with suggestions | Continues into build, verify, and closeout |
+| Quality is inconsistent | Depends on each prompt | 14 quality skills activate by task type |
+| Context is scattered | Plans live in chat history | Project knowledge and plan files stay on disk |
+| Completion is vague | Natural language says “done” | Delivery checks use state, evidence, and verification |
+| Config writes are risky | CLI files can drift | Install, update, cleanup, and doctor flows check managed files |
 
-### 💡 Best For
-- ✅ **Developers using AI CLIs** who want consistent, verified output
-- ✅ **Teams** that need quality guardrails on AI-assisted coding
-- ✅ **Complex projects** requiring structured design → develop → verify workflows
+## What Changed Since v3.0.7
 
-### ⚠️ Not For
-- ❌ Simple one-off questions (HelloAGENTS adds process overhead)
-- ❌ Non-coding tasks (optimized for software engineering)
+These are the main user-visible runtime and install changes in `v3.0.10`, compared with `v3.0.7`:
 
-## 🆚 Compared with v2.3.8
+- Main-agent delivery now uses structured `turn-state` values such as `complete`, `waiting`, and `blocked`; stop, notify, and closeout no longer infer completion from natural-language text.
+- Workflow recovery now uses the current `state_path`, with session-scoped state files under `.helloagents/sessions/<branch>/<session-or-default>/STATE.md`.
+- The old project-root state fallback has been removed, so recovery follows one current state path.
+- Codex standby/global install, refresh, cleanup, and doctor checks are stricter: managed `notify` entries are marked, multiline `notify` arrays are preserved, and user-owned `model_instructions_file`, `notify`, and non-managed `codex_hooks` are kept during restore.
+- Codex global mode now refreshes the home read root, local plugin root, marketplace entry, enabled plugin block, and cache copy after reinstall, update, or local branch changes.
 
-If the last version you used seriously was `v2.3.8`, this is not a minor update. The current line is a full product-line reset.
+## Core Features
 
-| Dimension | v2.3.8 | Local `v3.0.9` |
-|-----------|--------|----------------|
-| **Implementation base** | Python package plus mixed scripts/rules | Pure Node.js + Markdown runtime built around `cli.mjs`, `bootstrap*.md`, `skills/`, and `scripts/` |
-| **Product shape** | More like a multi-CLI management tool plus prompt protocol bundle | More like a quality workflow framework for AI CLIs, centered on routing, checks, verification, and resumable execution |
-| **Installation model** | pip / uv / npx / shell installers in parallel | npm-first; install the package, then deploy explicitly to Claude / Gemini / Codex |
-| **CLI strategy** | 6 targets with uneven capabilities | Focused on 3 primary surfaces: Claude Code, Gemini CLI, and Codex CLI |
-| **Workflow model** | R0/R1/R2 routing plus older design/develop semantics | ROUTE/TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE 6-stage workflow |
-| **Command surface** | 15 commands including `~exec`, `~rollback`, `~rlm`, `~validatekb` | 13 focused commands such as `~idea`, `~plan`, `~build`, `~verify`, `~prd`, `~loop`, `~wiki`, and `~help` |
-| **Quality model** | More distributed rules, more reliance on prose | 14 auto-activated skills + checklist-based quality checks + Ralph Loop + verification records |
-| **Project state** | KB felt auxiliary | `.helloagents/` is now the activation boundary; `STATE.md`, plan packages, `DESIGN.md`, and `contract.json` anchor the workflow |
-| **KB storage** | Project-local only | Project-local by default, plus `project_store_mode=repo-shared` for sharing stable KB/plan assets across git worktrees |
-| **Codex integration** | Earlier compatibility layers and legacy paths | Standby = injected rules + local links; global = native local-plugin chain with less noise and drift |
+### 1) 14 task-aware quality skills
 
-In one sentence: `v2.3.8` was closer to "workflow glue for multiple CLIs"; `v3.0.9` is a workflow framework that unifies quality rules, plan files, verification records, and installation lifecycle into one operating model.
+HelloAGENTS includes 14 `hello-*` skills. They are loaded only when the current stage needs them, so simple tasks stay light while complex work gets stricter checks.
 
-## ✨ Core Features
+| Skill | Focus |
+|-------|-------|
+| `hello-ui` | UI planning, design contracts, implementation mapping, visual validation |
+| `hello-api` | API design, validation, error format, compatibility |
+| `hello-security` | auth, secrets, permissions, injection risks |
+| `hello-test` | TDD, coverage, edge cases, test structure |
+| `hello-verify` | review, command verification, delivery evidence, closeout |
+| `hello-errors` | error handling, logs, retry and recovery behavior |
+| `hello-perf` | performance, caching, query and rendering risks |
+| `hello-data` | database, migrations, transactions, indexes |
+| `hello-arch` | architecture, boundaries, code size, maintainability |
+| `hello-debug` | bug diagnosis and escalation when stuck |
+| `hello-subagent` | subagent delegation and result integration |
+| `hello-review` | code review with structured findings |
+| `hello-write` | documentation, reports, and written deliverables |
+| `hello-reflect` | reusable lessons and knowledge updates |
 
-HelloAGENTS enforces quality through three mechanisms working together:
+All UI work first follows the shared UI quality baseline.
+In activated projects or explicit UI workflows, `hello-ui` adds deeper design-contract execution, design-system mapping, and visual validation.
+When visual evidence is required, HelloAGENTS can record `.helloagents/.ralph-visual.json`.
 
-<table>
-<tr>
-<td width="50%" valign="top">
-<img src="./readme_images/02-feature-icon-installer.svg" width="48" align="left">
+### 2) Commands for different work styles
 
-**🎯 14 Auto-Activated Quality Skills**
+Commands run inside the AI CLI chat with a `~` prefix. The command skill is read directly; unrelated skills are not loaded unless the workflow needs them.
 
-Skills activate automatically based on what you're building — no configuration needed.
-- UI, Security, API, Architecture, Performance
-- Testing, Error Handling, Data, Code Review
-- Debugging, Subagents, Documentation, Verification, Reflection
+| Command | Purpose |
+|---------|---------|
+| `~idea` | Lightweight exploration and option comparison; does not write files |
+| `~auto` | Chooses the main path and keeps going until delivery or a real blocker |
+| `~plan` | Requirements, solution design, task breakdown, and plan package |
+| `~build` | Implementation from the current request or an existing plan |
+| `~prd` | Modern product requirements document through guided dimension-by-dimension exploration |
+| `~loop` | Iterative improvement with metric, guard command, keep/revert decisions |
+| `~wiki` | Create or sync only the project knowledge base |
+| `~init` | Full project bootstrap: knowledge base plus project-level rule files and skill links |
+| `~test` | Write tests for a target module or recent change |
+| `~verify` | Review, run verification commands, fix failures, and close out |
+| `~commit` | Generate a conventional commit message and sync knowledge |
+| `~clean` | Archive finished plans and clean temporary runtime files |
+| `~help` | Show commands and current settings |
 
-**Your gain:** every task gets the right quality checks without you remembering to ask.
+Compatibility aliases:
 
-</td>
-<td width="50%" valign="top">
-<img src="./readme_images/03-feature-icon-workflow.svg" width="48" align="left">
+- `~do` → `~build`
+- `~design` → `~plan`
+- `~review` → `~verify` in review-first mode
 
-**📋 Checklist-Based Delivery Checks**
+### 3) Project knowledge base
 
-After coding, HelloAGENTS collects delivery checklists from all activated skills and verifies each item before reporting completion.
+HelloAGENTS can create and maintain a project knowledge base under `.helloagents/`.
 
-**Your gain:** nothing ships until it actually passes quality checks — not just "looks done."
+The knowledge base helps future turns understand the repo without re-discovering the same facts. It can store:
 
-</td>
-</tr>
-<tr>
-<td width="50%" valign="top">
-<img src="./readme_images/04-feature-icon-safety.svg" width="48" align="left">
+| File or directory | Purpose |
+|-------------------|---------|
+| `context.md` | project overview, stack, architecture, module index |
+| `guidelines.md` | non-obvious coding conventions inferred from the repo |
+| `verify.yaml` | verification commands such as lint, test, build |
+| `CHANGELOG.md` | project-level change history |
+| `DESIGN.md` | stable UI design contract when the project has UI work |
+| `modules/*.md` | module-specific notes and lessons |
+| `plans/<feature>/` | active plan packages |
+| `archive/` | archived plan packages |
 
-**🛡️ Guard System + Ralph Loop**
+`~wiki` creates or updates the knowledge base only.
 
-L1 blocks destructive commands (`rm -rf /`, `git push --force`, `DROP DATABASE`). L2 scans for hardcoded secrets and security patterns. Ralph Loop auto-runs verification commands after every task.
+`~init` does more: it creates or updates the knowledge base, writes project-level rule files, and refreshes host-native project skill links for supported hosts.
 
-**Your gain:** safer defaults with zero-config protection, verified output every time.
+### 4) Structured plan packages
 
-</td>
-<td width="50%" valign="top">
-<img src="./readme_images/05-feature-icon-compat.svg" width="48" align="left">
+Complex work can be stored as plan packages instead of a single paragraph in chat.
 
-**⚡ Structured Workflow**
+For `~plan`, HelloAGENTS uses:
 
-Simple tasks stay fast. Complex tasks use a 6-stage workflow: ROUTE/TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE, with explicit command lanes for ideation, planning, implementation, and validation.
+- `requirements.md`
+- `plan.md`
+- `tasks.md`
+- `contract.json`
 
-**Your gain:** proportional effort — quick tasks stay fast, complex tasks get full process.
+For `~prd`, HelloAGENTS also creates PRD files such as:
 
-</td>
-</tr>
-<tr>
-<td width="50%" valign="top">
-<img src="./readme_images/02-feature-icon-installer.svg" width="48" align="left">
+- `prd/00-overview.md`
+- `prd/01-user-stories.md`
+- `prd/02-functional.md`
+- `prd/03-ui-design.md`
+- `prd/04-technical.md`
+- `prd/05-nonfunctional.md`
+- `prd/06-i18n-l10n.md`
+- `prd/07-accessibility.md`
+- `prd/08-content.md`
+- `prd/09-testing.md`
+- `prd/10-deployment.md`
+- `prd/11-legal-privacy.md`
+- `prd/12-timeline.md`
 
-**🧠 Structured Plan Files**
+`contract.json` is used by the workflow to decide verification scope, reviewer/tester focus, optional advisor checks, and optional visual validation.
 
-Complex tasks no longer rely on one paragraph of planning prose. They land as `requirements.md`, `plan.md`, `tasks.md`, `contract.json`, `STATE.md`, and `DESIGN.md` when needed.
+### 5) State and recovery
 
-**Your gain:** routing, implementation, verification, and closeout all work from the same plan files instead of drifting across free-form summaries.
+Long tasks need a small recovery snapshot, but one shared state file is not safe enough for concurrent work.
 
-</td>
-<td width="50%" valign="top">
-<img src="./readme_images/05-feature-icon-compat.svg" width="48" align="left">
+HelloAGENTS now resolves the current state file from `state_path`:
 
-**🗂️ Local / Shared Project Storage**
+- with a stable session id: `.helloagents/sessions/<branch>/<session>/STATE.md`
+- without a stable session id: `.helloagents/sessions/<branch>/default/STATE.md`
 
-By default, KB and plan packages stay in the project's local `.helloagents/`. If you work with multiple worktrees, `project_store_mode=repo-shared` moves the stable project memory to `~/.helloagents/projects/<repo-key>/`.
+`STATE.md` records where the current workflow stopped. It is not a universal memory file for every conversation.
 
-**Your gain:** local runtime isolation stays intact while stable KB and plan files stop fragmenting across worktrees.
+### 6) Verification and delivery evidence
 
-</td>
-</tr>
-</table>
+HelloAGENTS does not treat “tests passed” and “task complete” as the same thing. Delivery can also require plan coverage, task checklist status, review evidence, advisor evidence, and visual evidence.
+
+Runtime evidence files include:
+
+- `.helloagents/.ralph-review.json`
+- `.helloagents/.ralph-advisor.json`
+- `.helloagents/.ralph-visual.json`
+- `.helloagents/.ralph-closeout.json`
+- `.helloagents/loop-results.tsv`
+
+### 7) Safer install, update, cleanup, and diagnostics
+
+The CLI manages host files explicitly:
 
-## 🚀 Quick Start
+- `install` writes only the selected target unless `--all` is used
+- `update` refreshes the selected target or all targets
+- `cleanup` removes managed injections and links
+- `uninstall` performs scoped cleanup before package removal
+- `doctor` reports drift in carriers, links, hooks, config entries, plugin roots, cache copies, and versions
 
-### 1) Install once
+## Quick Start
+
+### 1) Install the package
 
 ```bash
 npm install -g helloagents
 ```
 
-If your system already has another `helloagents` executable in `PATH`, use the bundled stable alias instead:
+If another executable named `helloagents` already exists in your `PATH`, use the stable alias:
 
 ```bash
 helloagents-js
 ```
 
-`postinstall` now only installs the package and initializes `~/.helloagents/helloagents.json`. It **does not auto-deploy to any CLI target**.
+`postinstall` only installs the package command and initializes `~/.helloagents/helloagents.json`. It does not deploy to any AI CLI automatically.
+
+### 2) Deploy to a CLI
 
-After the package is installed, deploy explicitly to the targets you want:
+Use standby mode for selected projects and explicit activation:
 
 ```bash
 helloagents install codex --standby
 helloagents install --all --standby
 ```
 
-> `npm install helloagents` without `-g` follows the same rule: it installs the package only and does not modify any CLI config automatically.
-
-### 2) Choose your mode
-
-| Goal | What to run | What happens |
-|------|-------------|--------------|
-| Install the package without touching hosts yet | `npm install -g helloagents` | Installs the command and `~/.helloagents/helloagents.json` only |
-| Keep HelloAGENTS light by default | `helloagents install --all --standby` | **Standby mode** explicitly deploys lite rules to the target CLIs |
-| Enable full rules everywhere | `helloagents install --all --global` or `helloagents --global` | Switches to **global mode**; Claude/Gemini use native plugin/extension installs, Codex gets the native local-plugin chain automatically |
-| Re-sync after local branch switch / file updates | `helloagents update codex`, `helloagents install --all --standby`, or `helloagents --global` | Refreshes injected/copied files for the target or current mode |
-
-### 2.1) Manage one CLI at a time
-
-```bash
-helloagents install codex --standby
-helloagents install --all --global
-helloagents update codex
-helloagents cleanup claude --global
-helloagents uninstall gemini
-```
-
-- Supported targets: `claude`, `gemini`, `codex`, or `--all`
-- If you omit `--standby` / `--global`, HelloAGENTS reuses the tracked/detected mode for that CLI and falls back to `standby`
-- `install` / `update` affect only the selected CLI; use `--all` when you want an explicit bulk deploy
-- Claude Code / Gemini CLI still require native plugin/extension install or uninstall commands in `global` mode; Codex CLI is still handled automatically
-
-If you want full rules everywhere, switch to global mode:
+Use global mode when you want full rules everywhere:
 
 ```bash
 helloagents --global
 ```
 
-Then install the native plugin/extension for your CLI where required:
+### 3) Verify inside your AI CLI
 
-```bash
-# Claude Code
-/plugin marketplace add hellowind777/helloagents
+Type:
 
-# Gemini CLI
-gemini extensions install https://github.com/hellowind777/helloagents
+```text
+~help
 ```
 
-Codex CLI does not need a manual plugin command. `helloagents --global` now installs the native local-plugin chain automatically by writing:
-- `~/.agents/plugins/marketplace.json`
-- `~/plugins/helloagents/`
-- `~/.codex/plugins/cache/local-plugins/helloagents/local/`
-- `helloagents@local-plugins` in `~/.codex/config.toml`
+You should see the 13 chat commands and the current settings.
 
-### 3) Verify in chat
+### 4) Create project knowledge
 
-```bash
-# In your AI CLI chat, type:
-~help
-```
+For knowledge base only:
 
-**Expected output:**
+```text
+~wiki
 ```
-💡【HelloAGENTS】- Help
 
-Available commands: ~idea, ~auto, ~plan, ~build, ~prd, ~loop, ~wiki, ~init, ~test, ~verify, ~commit, ~clean, ~help
+For full project bootstrap:
 
-Auto-activated skills (14): hello-ui, hello-api, hello-security, hello-test, hello-verify, hello-errors, hello-perf, hello-data, hello-arch, hello-debug, hello-subagent, hello-review, hello-write, hello-reflect
+```text
+~init
 ```
 
-### 4) First use
-
-```bash
-# Simple task — direct execution
-"Fix the typo in src/utils.ts line 42"
+## CLI Management
 
-# Complex task — use ~auto for full workflow
-~auto "Add user authentication with JWT"
+### Shell commands
 
-# Want to review the plan first?
-~plan "Refactor the payment module"
+```bash
+helloagents --standby
+helloagents --global
+helloagents install codex --standby
+helloagents install --all --global
+helloagents update codex
+helloagents cleanup claude --global
+helloagents uninstall gemini
+helloagents doctor
+helloagents doctor codex --json
 ```
 
-## 🔄 Installation Lifecycle & File Writes
-
-HelloAGENTS touches different files depending on mode. The write/cleanup rules are predictable and reversible.
+Supported targets:
 
-### Standby mode (default)
+- `claude`
+- `gemini`
+- `codex`
+- `--all`
 
-| CLI | Files HelloAGENTS writes or updates | What it preserves | What uninstall / mode switch cleans |
-|-----|-------------------------------------|-------------------|-------------------------------------|
-| Claude Code | `~/.claude/CLAUDE.md`, `~/.claude/settings.json`, `~/.claude/helloagents -> <package-root>` | Existing non-HelloAGENTS markdown, settings, permissions, and hooks | Removes injected marker block, HelloAGENTS hooks/permissions, and symlink |
-| Gemini CLI | `~/.gemini/GEMINI.md`, `~/.gemini/settings.json`, `~/.gemini/helloagents -> <package-root>` | Existing markdown, hooks, and unrelated settings | Removes injected marker block, HelloAGENTS hooks, and symlink |
-| Codex CLI | `~/.codex/AGENTS.md`, `~/.codex/config.toml`, timestamped backups like `~/.codex/config.toml_YYYYMMDD-HHMMSS.bak`, `~/.codex/helloagents -> <package-root>` | Existing top-level TOML keys and unrelated sections via backup/restore | Removes injected marker block, HelloAGENTS config keys, symlink, and the latest HelloAGENTS-managed backup |
+If you omit `--standby` or `--global`, HelloAGENTS first reuses the tracked/detected mode for that CLI, then falls back to `standby`.
 
-### Global mode
+### Standby mode files
 
-| CLI | How installation works | Files involved |
-|-----|------------------------|----------------|
-| Claude Code | Native plugin install (manual CLI command) | Managed by Claude's plugin system |
-| Gemini CLI | Native extension install (manual CLI command) | Managed by Gemini's extension system |
-| Codex CLI | Native local-plugin chain (automatic) | `~/.agents/plugins/marketplace.json`, `~/plugins/helloagents/`, `~/.codex/plugins/cache/local-plugins/helloagents/local/`, `~/.codex/config.toml`, `~/.codex/helloagents -> ~/plugins/helloagents` |
-
-### Update / reinstall / branch-switch behavior
-
-- **Standby mode** keeps scripts, skills, templates, and hooks on `~/.claude/helloagents`, `~/.gemini/helloagents`, and `~/.codex/helloagents` symlinks, so linked package files reflect local changes immediately. The injected rules files (`CLAUDE.md`, `GEMINI.md`, `AGENTS.md`) are still snapshots and must be refreshed after bootstrap or branch changes.
-- **Codex global mode** uses copied runtime files and keeps `~/.codex/helloagents -> ~/plugins/helloagents` as the stable read-root fallback expected by bootstrap routing. Re-running `helloagents --global` refreshes both `~/plugins/helloagents/` and the Codex cache copy.
-- Re-running the current mode command is supported intentionally: `helloagents --standby` and `helloagents --global` both act as **switch-or-refresh** commands.
-- For deterministic manual cleanup, run `helloagents cleanup` before `npm uninstall -g helloagents`.
-- `npm uninstall -g helloagents` removes the package; `~/.helloagents/helloagents.json` is intentionally preserved.
-
-## 📖 Commands
-
-All commands run inside AI chat with the `~` prefix:
-
-**Workflow Commands:**
-
-| Command | Purpose |
-|---------|---------|
-| `~idea` | Lightweight ideation — compare directions and explore options without writing files |
-| `~auto` | End-to-end execution — picks the main lane, keeps chaining into build / verify / closeout, and reuses an active plan package before reopening a new lane |
-| `~plan` | Structured planning — requirement gathering + solution convergence + plan package |
-| `~build` | Execution workflow — implement from the current request or an existing plan package |
-| `~prd` | Complete PRD — 13-dimension brainstorm-style exploration, generates product requirements |
-| `~loop` | Autonomous iteration — set a target + metric, AI loops until goal is met |
-
-**Quality Commands:**
-
-| Command | Purpose |
-|---------|---------|
-| `~test` | Write complete tests (TDD: Red → Green → Refactor) |
-| `~verify` | Unified verification entry — review, lint, typecheck, test, build, and fix loops |
-
-**Utility Commands:**
-
-| Command | Purpose |
-|---------|---------|
-| `~wiki` | Create or sync the project knowledge base only (`.helloagents/`) |
-| `~init` | Full project bootstrap: KB + project-level rule files |
-| `~commit` | Generate conventional commit message + KB sync |
-| `~clean` | Archive completed plans, clean temp files |
-| `~help` | Show all commands and current config |
-
-Compatibility aliases:
-- `~design` → `~plan`
-- `~do` → `~build`
-- `~review` → `~verify` (review-priority mode)
+| CLI | Files written or updated | Cleanup behavior |
+|-----|--------------------------|------------------|
+| Claude Code | `~/.claude/CLAUDE.md`, `~/.claude/settings.json`, `~/.claude/helloagents -> <package-root>` | removes managed marker block, HelloAGENTS hooks/permissions, and symlink |
+| Gemini CLI | `~/.gemini/GEMINI.md`, `~/.gemini/settings.json`, `~/.gemini/helloagents -> <package-root>` | removes managed marker block, HelloAGENTS hooks, and symlink |
+| Codex CLI | `~/.codex/AGENTS.md`, `~/.codex/config.toml`, `~/.codex/helloagents -> <package-root>`, managed backups | removes managed marker block, managed config keys, symlink, and the latest managed backup |
 
-## 🔧 Configuration
+### Global mode files
 
-Config file: `~/.helloagents/helloagents.json` (auto-created on install)
+| CLI | Install method | Files involved |
+|-----|----------------|----------------|
+| Claude Code | native plugin install | managed by Claude Code plugin system |
+| Gemini CLI | native extension install | managed by Gemini extension system |
+| Codex CLI | native local-plugin chain | `~/.agents/plugins/marketplace.json`, `~/plugins/helloagents/`, `~/.codex/plugins/cache/local-plugins/helloagents/local/`, `~/.codex/config.toml`, `~/.codex/helloagents -> ~/plugins/helloagents` |
 
-Only include keys you want to override — missing keys use defaults.
+Claude Code and Gemini CLI global mode still require their host-native install commands:
 
-```json
-{
-  "output_language": "",
-  "output_format": true,
-  "notify_level": 0,
-  "ralph_loop_enabled": true,
-  "guard_enabled": true,
-  "kb_create_mode": 1,
-  "project_store_mode": "local",
-  "commit_attribution": "",
-  "install_mode": "standby"
-}
+```text
+/plugin marketplace add hellowind777/helloagents
+gemini extensions install https://github.com/hellowind777/helloagents
 ```
 
-| Key | Default | Description |
-|-----|---------|-------------|
-| `output_language` | `""` | Empty = follow user language. Set `zh-CN`, `en`, etc. to override |
-| `output_format` | `true` | `true` = only the main agent's final closing reply after streaming ends may use the HelloAGENTS layout; all streaming/progress/intermediate output and all subagent replies stay natural, `false` = natural output |
-| `notify_level` | `0` | `0`=off, `1`=desktop, `2`=sound, `3`=both |
-| `ralph_loop_enabled` | `true` | Auto-run verification after task completion |
-| `guard_enabled` | `true` | Block dangerous commands |
-| `kb_create_mode` | `1` | `0`=off, `1`=auto on coding tasks in activated projects or global mode, `2`=always in activated projects or global mode |
-| `project_store_mode` | `"local"` | `"local"` = keep KB/plan files in project-local `.helloagents/`; `"repo-shared"` = keep local `.helloagents/` only for activation/STATE/runtime files and move KB/plan files to `~/.helloagents/projects/<repo-key>/` |
-| `commit_attribution` | `""` | Empty = no attribution. Set text to append to commit messages |
-| `install_mode` | `"standby"` | `"standby"` = per-project activation (lite rules), `"global"` = full rules for all projects |
-
-<details>
-<summary>📝 Common configuration scenarios</summary>
-
-**Switch to global mode (full rules everywhere):**
-```bash
-helloagents --global
-```
+Codex global mode is installed by HelloAGENTS automatically through the local-plugin path.
 
-**Switch back to standby mode (default):**
-```bash
-helloagents --standby
-```
+## Commands in Chat
 
-**English-only output:**
-```json
-{ "output_language": "en" }
-```
+### Typical flows
 
-**Disable KB auto-creation:**
-```json
-{ "kb_create_mode": 0 }
-```
+| Goal | Use |
+|------|-----|
+| Compare ideas before writing files | `~idea "compare two API designs"` |
+| Let HelloAGENTS choose the path and continue | `~auto "add JWT login"` |
+| Review a plan before implementation | `~plan "refactor payment module"` |
+| Implement from a clear request or active plan | `~build "finish task 2 in the plan"` |
+| Build a full product requirement document | `~prd "modern dashboard for operations team"` |
+| Iterate toward a metric | `~loop "reduce bundle size" --metric "npm run size" --direction lower` |
+| Create or refresh project knowledge only | `~wiki` |
+| Fully activate project workflow | `~init` |
+| Validate current work | `~verify` |
+| Generate commit message and sync knowledge | `~commit` |
 
-**Share KB and plan packages across multiple worktrees:**
-```json
-{ "project_store_mode": "repo-shared" }
-```
+### Activated vs unactivated projects
 
-**Enable desktop + sound notifications:**
-```json
-{ "notify_level": 3 }
-```
+In standby mode, unactivated projects get lighter rules and explicit `~command` entry points. A project becomes activated when `.helloagents/` exists, usually through `~wiki` or `~init`.
 
-**Disable guard (not recommended):**
-```json
-{ "guard_enabled": false }
-```
+In global mode, HelloAGENTS applies full rules by default.
 
-</details>
+## Project Knowledge Base
 
-## ⚙️ How It Works
+### Local mode
 
-**Short version:** HelloAGENTS selects execution depth based on task type, risk, and project state. In standby mode, unactivated projects keep a lightweight rule set: safety, completion constraints, a compact quality floor, and explicit `~command` lanes. Once the project is activated through `.helloagents/`, or when global mode is enabled, HelloAGENTS switches to the full 6-stage workflow with explicit ideation, planning, build, verification, and consolidation stages.
+By default, project knowledge lives in the project:
 
-**The 6-stage workflow:**
+```text
+.helloagents/
+```
 
-1. **ROUTE / TIER** — Decide whether the task belongs in `~idea`, `~plan`, `~build`, `~verify`, `~prd`, or `~auto`
-2. **SPEC** — Clarify goals, constraints, and success criteria
-3. **PLAN** — Mark required quality skills and prepare plan files such as `requirements.md`, `plan.md`, and `tasks.md`
-4. **BUILD** — Implement with TDD (test → code → refactor), verify incrementally
-5. **VERIFY** — Run Ralph Loop, review diffs when needed, and collect delivery checklists
-6. **CONSOLIDATE** — Update `STATE.md`, sync KB files, and archive completed plan packages
+This directory acts as both:
 
-**Delivery Tier:**
-- `T0` — read-only exploration and idea comparison
-- `T1` — low-risk focused fixes or explicit verification
-- `T2` — multi-file features, new projects, or work that needs structured files
-- `T3` — high-risk or irreversible chains such as auth, security, payment, database, or production release work
+- the activation signal
+- the local knowledge, plan, state, and runtime directory
 
-**Routing rules:**
-- Exploration / compare options → `~idea`
-- Simple tasks (single file, clear fix) → Direct execution or `~build`
-- Complex tasks (3+ files, architecture change, new project) → `~plan`, `~auto`, or `~prd`
-- Review / validation requests → `~verify`
+### Repo-shared mode
 
-**Quality rules and skills by task type:**
-- UI / frontend / visual interaction work always follows the active bootstrap's UI quality baseline
-- In activated projects, global mode, or explicit UI workflow commands, `hello-ui` adds deeper design-contract execution, design-system mapping, and visual validation
-- When a UI `contract.json` explicitly asks for heavier UI assurance, HelloAGENTS keeps the default path light and only then adds optional `.helloagents/.ralph-advisor.json` and `.helloagents/.ralph-visual.json` records
-- Touching API endpoints? → `hello-api` activates (REST conventions, validation, error format)
-- Any code change? → `hello-test`, `hello-verify`, `hello-review` activate
+When `project_store_mode = "repo-shared"`:
 
-### Standby vs Global Mode
+- local `.helloagents/` keeps activation and runtime files
+- stable knowledge and plan files move to `~/.helloagents/projects/<repo-key>/`
+- multiple worktrees of the same git repo can share the same stable knowledge
 
-HelloAGENTS supports two installation modes with different installation methods:
+Runtime state and evidence remain local to the working project:
 
-| Mode | Install Method | Rules | Skills | Best For |
-|------|---------------|-------|--------|----------|
-| **Standby** (default) | `helloagents install <target> --standby` or `helloagents install --all --standby` | `bootstrap-lite.md` (lite rules with compact quality floor, UI quality baseline, safety, and completion constraints) | `~command` on demand; before activation, UI tasks still follow the UI quality baseline; after `.helloagents/`, the full workflow activates | Selective use, keeping other projects unaffected |
-| **Global** | Manual plugins for Claude/Gemini; native local-plugin auto-install for Codex | `bootstrap.md` (full rules) | 14 skills auto-activate | All-in on HelloAGENTS across every project |
+- `state_path`
+- `.ralph-*.json`
+- `loop-results.tsv`
 
-Standby mode injects rules into `~/.claude/CLAUDE.md`, `~/.gemini/GEMINI.md`, and `~/.codex/AGENTS.md`; for Codex, HelloAGENTS also writes a managed `model_instructions_file` in `~/.codex/config.toml` that points to the synced `~/.codex/AGENTS.md`, so the same home rules file becomes Codex's base instructions override. Cleanup restores the user's original `model_instructions_file` value. Each CLI also gets a `helloagents` package-root symlink. Claude Code and Gemini still use hooks where their host surfaces support quiet injection well. Codex deliberately does **not** enable HelloAGENTS hooks by default: the latest pre-source shows hook lifecycle output in TUI and does not honor `suppressOutput` as a true silent injection path, so Codex relies on the injected rules file plus the local symlink/native plugin layout instead. In global mode, Claude Code uses plugin hooks from `.claude-plugin/plugin.json`, Gemini loads `bootstrap.md` via `contextFileName` plus extension hooks, and Codex uses the native local-plugin chain (marketplace + local plugin root + cache + plugin enablement in `config.toml`) plus the same `~/.codex/AGENTS.md` home baseline, still without plugin hooks.
+### Knowledge creation rules
 
-In standby mode, `.helloagents/` is the activation boundary. Before activation, the lite rules file does **not** run the full 6-stage workflow or semantic auto-routing; it keeps the lightweight execution rules, explicit `~command` entry points, and minimum quality/completion guardrails. Once `.helloagents/` exists, the active project switches to the full project workflow and `bootstrap.md` becomes the runtime rules source.
+| Command or setting | Behavior |
+|--------------------|----------|
+| `~wiki` | creates or syncs the knowledge base only |
+| `~init` | creates knowledge base plus project-level rule files and skill links |
+| `kb_create_mode = 0` | disables automatic knowledge updates |
+| `kb_create_mode = 1` | updates knowledge automatically for coding tasks in activated projects or global mode |
+| `kb_create_mode = 2` | updates knowledge more aggressively in activated projects or global mode |
 
-Bulk switch via CLI: `helloagents --global` or `helloagents --standby`
+## Workflow and Delivery
 
-Re-running the same mode command is also valid. It refreshes the current mode's injected/copied files after branch switches, local development changes, or manual cleanup.
+### Workflow stages
 
-## 📚 Usage Guide
+HelloAGENTS uses this stage model for structured work:
 
-### Core Workflow Lanes
+```text
+ROUTE / TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE
+```
 
-| Mode | Description | When to use |
-|------|-------------|-------------|
-| `~idea` | Lightweight ideation only, no files written | Need help choosing a direction without activating full project flow |
-| `~plan` | Interactive planning only, generates a plan package | Want to review the plan before coding |
-| `~build` | Implementation workflow from the current task or existing plan package | Requirement is clear and you want execution |
-| `~verify` | Verification / review workflow | Want audit, checks, and fix loops |
-| `~auto` | End-to-end execution across the lanes above, continuing until delivery unless blocked | Want HelloAGENTS to choose the right path end-to-end |
-| `~prd` | 13-dimension PRD generation | Need comprehensive product requirements |
+| Stage | Purpose |
+|-------|---------|
+| `ROUTE / TIER` | decide whether the task is idea, plan, build, verify, PRD, or automatic flow |
+| `SPEC` | clarify goal, constraints, and success criteria |
+| `PLAN` | prepare plan files and choose needed skills |
+| `BUILD` | implement and run local checks |
+| `VERIFY` | review, run commands, check contract and evidence |
+| `CONSOLIDATE` | update state, knowledge, and closeout evidence |
 
-Typical pattern: `~idea` first to compare directions, then `~plan` to lock a solution, then `~build`, then `~verify`. Or just `~auto` for one-shot end-to-end execution. If the project already has an active plan package, `~auto` should reuse that workflow state before reopening ideation or planning. For UI work, the decision priority is always `plan.md` / PRD UI decisions → `DESIGN.md` → generic UI rules.
+### Delivery tiers
 
-### Quality Verification (Ralph Loop)
+| Tier | Typical use |
+|------|-------------|
+| `T0` | read-only analysis, idea exploration, comparison |
+| `T1` | low-risk focused fixes or explicit verification |
+| `T2` | multi-file features, new projects, structured plans |
+| `T3` | high-risk or irreversible work such as auth, payment, database, release, production operations |
 
-After every task, Ralph Loop auto-runs your project's verification commands:
-- Priority: logical `.helloagents/verify.yaml` (`project_store_mode=repo-shared` resolves it from the shared project store) → `package.json` scripts → auto-detected
-- All pass? → Collect skill checklists → Verify → Done
-- Any fail? → Reflect → Fix → Re-run (circuit breaker after 3 failures)
-- Completion is also held back if the active plan package still has open tasks, missing required plan files, or unreplaced template placeholders
+### UI workflow
 
-### Knowledge Base (`.helloagents/`)
+UI work follows this priority:
 
-`~wiki` creates or syncs the project knowledge base only. `~init` is the fuller bootstrap: it also writes project-level rule files (`AGENTS.md`, `CLAUDE.md`, `.gemini/GEMINI.md`), refreshes host-native project skill links, and appends the related ignore rules. In standby mode, the presence of the local `.helloagents/` is what promotes the current project into the full project workflow; project-level rule files are optional.
+1. current `plan.md` or PRD UI decisions
+2. `.helloagents/DESIGN.md`
+3. shared UI quality baseline
+4. `hello-ui` implementation and validation rules
 
-By default, KB and plan files live in the project's local `.helloagents/`. The active recovery snapshot now has a single authoritative path: `state_path`. When the host exposes a stable conversation/session identifier, HelloAGENTS writes it to `.helloagents/sessions/<branch>/<session>/STATE.md`; otherwise it uses the branch default slot at `.helloagents/sessions/<branch>/default/STATE.md`. If `project_store_mode = "repo-shared"`, the local `.helloagents/` directory keeps the activation signal, session-scoped `STATE.md`, and runtime files such as `.ralph-*`, while `context.md`, `guidelines.md`, `DESIGN.md`, `verify.yaml`, `modules/`, `plans/`, and `archive/` move to `~/.helloagents/projects/<repo-key>/` so multiple worktrees of the same git repo can share stable project memory.
+For heavier UI work, `contract.json` can require:
 
-`STATE.md` is the active recovery snapshot resolved from `state_path`, not a universal memory file for every interaction. Its branch + session layout prevents concurrent conversations on the same repo from fighting over one shared file. It is created and continuously updated for long-running project workflows such as `~wiki`, `~init`, `~plan`, `~build`, `~auto`, `~prd`, and `~loop`; updated when already present for verification/review style tasks; and intentionally not created for one-off read-only interactions such as `~help`.
+- `ui.styleAdvisor.required`
+- `ui.visualValidation.required`
 
-| File | Purpose |
-|------|---------|
-| `STATE.md` | Project-level recovery snapshot (≤70 lines, survives compression as a resumable snapshot) |
-| `DESIGN.md` | Project-level UI contract (design system, component patterns, state coverage, accessibility) |
-| `context.md` | Project architecture, tech stack, conventions |
-| `guidelines.md` | Non-obvious coding rules |
-| `verify.yaml` | Verification commands |
-| `CHANGELOG.md` | Change history |
-| `modules/*.md` | Module documentation + experience |
-| `plans/` | Active plan packages (`requirements.md`, `plan.md`, `tasks.md`, `contract.json`) |
-| `archive/` | Completed plan packages |
+Those requirements are closed with `.helloagents/.ralph-advisor.json` and `.helloagents/.ralph-visual.json`.
 
-### Smart Commit (`~commit`)
+### Verification sources
 
-- Analyzes `git diff` to generate Conventional Commits messages
-- Pre-commit quality checks (code-doc consistency, test coverage)
-- Auto-excludes sensitive files (`.env`, `*.pem`, `*.key`)
-- Respects `commit_attribution` config
-- Syncs KB per `kb_create_mode` setting
+Verification commands are detected in this order:
 
-### Autonomous Iteration (`~loop`)
+1. logical `.helloagents/verify.yaml`
+2. package manager scripts such as `package.json`
+3. automatic detection
 
-Set a target and metric, then let AI iterate:
-1. Review → Ideate → Modify → Commit → Verify → Decide → Log → Repeat
-2. Results tracked in `.helloagents/loop-results.tsv`
-3. Uses `git revert` for clean rollback on failed experiments
+When `project_store_mode = "repo-shared"`, logical `.helloagents/verify.yaml` resolves from the shared project store.
 
-## 🧪 Verification
+## Configuration
 
-HelloAGENTS ships with Node's built-in test runner:
+Config file:
 
-```bash
-npm test
+```text
+~/.helloagents/helloagents.json
 ```
 
-The test suite validates:
-- standby/global install, reinstall, refresh, uninstall, and cross-mode switching
-- Claude/Gemini/Codex config file merge, restore, and cleanup behavior
-- Codex local-plugin refresh after local branch or file changes
-- runtime inject/route/guard/Ralph Loop chains
-- cleanup when Codex global files exist but `~/.codex/` is already gone
+Default shape:
 
-## ❓ FAQ
+```json
+{
+  "output_language": "",
+  "output_format": true,
+  "notify_level": 0,
+  "ralph_loop_enabled": true,
+  "guard_enabled": true,
+  "kb_create_mode": 1,
+  "project_store_mode": "local",
+  "commit_attribution": "",
+  "install_mode": "standby"
+}
+```
 
-<details>
-<summary><strong>Q: Is this a CLI tool or a prompt framework?</strong></summary>
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `output_language` | `""` | follow the user language unless set |
+| `output_format` | `true` | only the main agent's final closeout message may use the HelloAGENTS layout |
+| `notify_level` | `0` | `0` off, `1` desktop, `2` sound, `3` both |
+| `ralph_loop_enabled` | `true` | run verification after task completion |
+| `guard_enabled` | `true` | block dangerous commands |
+| `kb_create_mode` | `1` | control automatic knowledge base updates |
+| `project_store_mode` | `"local"` | `local` or `repo-shared` |
+| `commit_attribution` | `""` | optional text appended to commit messages |
+| `install_mode` | `"standby"` | current default install mode |
 
-**A:** Both. The CLI (`cli.mjs`) handles installation, mode switching, and CLI configuration. The actual workflow comes from `bootstrap.md` / `bootstrap-lite.md` rules, quality skills, and host-appropriate runtime helpers. On Claude/Gemini that includes hook scripts such as `notify.mjs`, `guard.mjs`, and `ralph-loop.mjs`; on Codex the default path is rules-file driven to keep TUI output quiet. Think of it as a delivery system + intelligent quality protocol.
-</details>
+## How Each CLI Is Integrated
 
-<details>
-<summary><strong>Q: What changed from v2.x to v3.x?</strong></summary>
+### Claude Code
 
-**A:** Everything. The v3 line is a complete rewrite:
-- Python package → pure Node.js/Markdown architecture
-- 15 commands → 12 commands + 14 auto-activated quality skills
-- 6 CLI targets → 3 (Claude Code + Codex CLI + Gemini CLI)
-- New: checklist gate control, guard system, ~prd, ~loop, ~verify, design system generation
-- See [Version History](#-version-history) for full details.
-</details>
+- standby writes `~/.claude/CLAUDE.md`
+- standby updates `~/.claude/settings.json` with managed hooks and permissions
+- standby creates `~/.claude/helloagents -> <package-root>`
+- global mode uses Claude Code's plugin system
 
-<details>
-<summary><strong>Q: Which CLI should I use?</strong></summary>
+### Gemini CLI
 
-**A:** Claude Code gets the best experience (plugin system, 11 lifecycle hooks, Agent Teams support). Gemini CLI works via extension system. Codex CLI works well too. Install the package first, then deploy explicitly to the CLI you want with `helloagents install <target> --standby` or `helloagents install --all --standby`.
-</details>
+- standby writes `~/.gemini/GEMINI.md`
+- standby updates `~/.gemini/settings.json` with managed hooks
+- standby creates `~/.gemini/helloagents -> <package-root>`
+- global mode uses Gemini's extension system
 
-<details>
-<summary><strong>Q: What are the 14 quality skills?</strong></summary>
+### Codex CLI
 
-**A:** They auto-activate based on task type:
-- **hello-ui**: deep UI implementation and validation (contracts, design-system mapping, accessibility, responsive, animation)
-- **hello-api**: API design (REST, validation, error format, rate limiting)
-- **hello-security**: Security (auth, input validation, XSS/CSRF, secrets management)
-- **hello-test**: Testing (TDD workflow, boundary cases, AAA pattern)
-- **hello-verify**: Verification gate (Ralph Loop, circuit breaker)
-- **hello-errors**: Error handling (structured errors, logging, recovery)
-- **hello-perf**: Performance (N+1, caching, code splitting, virtual scroll)
-- **hello-data**: Database (migrations, transactions, indexes, integrity)
-- **hello-arch**: Architecture (SOLID, boundaries, code volume limits)
-- **hello-debug**: Debugging (4-stage process, escalation on stuck)
-- **hello-subagent**: Subagent orchestration (dispatch, coordination, review)
-- **hello-review**: Code review (logic, security, performance, maintainability)
-- **hello-write**: Documentation (pyramid principle, audience-aware)
-- **hello-reflect**: Experience capture (lessons learned → KB)
+Codex is rules-file driven by default.
 
-Subagents may skip workflow packaging such as routing, interaction flow, and output formatting, but they still follow core rules such as coding principles, safety constraints, and failure handling.
-</details>
+- standby writes `~/.codex/AGENTS.md`
+- standby writes a managed `model_instructions_file` pointing to that file
+- standby writes a managed `notify` command for closeout notification
+- standby creates `~/.codex/helloagents -> <package-root>`
+- global mode installs the native local-plugin chain
+- HelloAGENTS does not enable Codex hooks by default
 
-<details>
-<summary><strong>Q: What is standby vs global mode?</strong></summary>
+## Verification
 
-**A:** Standby mode (default) deploys lite rules to the targets you choose, typically with `helloagents install <target> --standby` or `helloagents install --all --standby`. A project enters the full project flow once it has `.helloagents/`, usually via `~wiki` (KB only) or `~init` (full bootstrap). Global mode uses each CLI's native plugin/extension system for full rules everywhere; deploy it with `helloagents install <target> --global`, `helloagents install --all --global`, or bulk-switch with `helloagents --global`.
-</details>
+Run all tests:
 
-<details>
-<summary><strong>Q: Where does project knowledge go?</strong></summary>
+```bash
+npm test
+```
 
-**A:** By default, in the project-local `.helloagents/` directory. It can be created by `~wiki` (KB only) or `~init` (full project bootstrap), then auto-synced on code changes according to `kb_create_mode`. If `project_store_mode = "repo-shared"`, the local `.helloagents/` keeps only the activation signal, `STATE.md`, and `.ralph-*` runtime files, while KB and plan files move to `~/.helloagents/projects/<repo-key>/`. `STATE.md` is used as a concise recovery snapshot for long-running workflows, not as a catch-all memory file for every interaction.
-</details>
+The current test suite covers:
 
-<details>
-<summary><strong>Q: What is the Guard system?</strong></summary>
+- install, update, uninstall, cleanup, and mode switching
+- Claude, Gemini, and Codex config merge and restore behavior
+- Codex managed `model_instructions_file`, `notify`, local plugin, marketplace, and cache behavior
+- `helloagents doctor`
+- project storage and `repo-shared` behavior
+- session-scoped `state_path`
+- runtime routing, guard, verification, visual evidence, and delivery gates
+- README and skill contract alignment
 
-**A:** Two-layer safety:
-- **L1 Blocking**: Stops destructive commands before execution (`rm -rf /`, `git push --force`, `DROP DATABASE`, `chmod 777`, `FLUSHALL`)
-- **L2 Advisory**: Scans file writes for hardcoded secrets, API keys, .env exposure — warns but doesn't block
-</details>
+## FAQ
 
-<details>
-<summary><strong>Q: What does the bottom next-step bar mean when formatted output is enabled?</strong></summary>
+### Is this a CLI tool or a prompt framework?
 
-**A:** It always shows the most appropriate next action. If a natural follow-up exists, HelloAGENTS states it directly. If the current task is fully complete with no meaningful follow-up, it falls back to a completion/waiting status instead of empty filler.
-</details>
+Both.
 
-<details>
-<summary><strong>Q: Can I disable features I don't need?</strong></summary>
+- `cli.mjs` handles install, update, cleanup, diagnostics, and host config
+- `bootstrap.md` and `bootstrap-lite.md` define workflow rules
+- `skills/` defines task-specific behavior
+- `scripts/` provides runtime helpers for routing, guard, notify, verification, state, and evidence
 
-**A:** Yes. Set `guard_enabled: false` to disable the guard, `ralph_loop_enabled: false` to skip verification, `kb_create_mode: 0` to disable KB. Quality skills auto-activate but don't add overhead for unrelated tasks.
-</details>
+### Should I use `~wiki` or `~init`?
 
-<details>
-<summary><strong>Q: What is ~prd?</strong></summary>
+Use `~wiki` when you only want project knowledge.
 
-**A:** A 13-dimension PRD generator. It walks through product overview, user stories, functional requirements, UI/UX design, technical architecture, non-functional requirements, i18n, accessibility, content strategy, testing, deployment, legal/privacy, and timeline — brainstorm-style, one dimension at a time.
-</details>
+Use `~init` when you also want project-level rule files and host-native project skill links.
 
-## 🛠️ Troubleshooting
+### What is the difference between standby and global?
 
-### Plugin not loading (Claude Code)
+`standby` is lighter and explicit. It deploys rules to selected CLIs and keeps full project workflow behind project activation.
 
-**Problem:** `~help` not recognized after plugin installation
+`global` applies full rules broadly. Claude and Gemini use native plugin/extension installs. Codex uses the local-plugin path.
 
-**Solution:** Restart Claude Code. If still not working, check `/plugin list` to verify installation.
+### Why does Codex not use hooks by default?
 
----
+The current Codex integration is more predictable with managed rules files, `model_instructions_file`, `notify`, and local plugins. Hooks can still show output in the TUI, so HelloAGENTS does not enable Codex hooks by default.
 
-### Extension not working (Gemini CLI)
+### Can I turn off notifications or guard checks?
 
-**Problem:** `~help` not recognized after `gemini extensions install`
+Yes.
 
-**Solution:** Restart Gemini CLI. Verify with `gemini extensions list`. Make sure the extension is enabled.
+- set `notify_level` to `0` to disable notifications
+- set `guard_enabled` to `false` to disable command guards
 
----
+### Does `npm uninstall -g helloagents` remove project knowledge?
 
-### File writes blocked outside workspace
+No. Package uninstall removes the package. Project `.helloagents/` files and `~/.helloagents/helloagents.json` are intentionally preserved unless you remove them yourself.
 
-**Problem:** Gemini CLI or Codex CLI reports that a file path is outside the allowed workspace.
+## Troubleshooting
 
-**Solution:** Write files inside the current project workspace, or inside the CLI's temporary workspace directory. In headless verification, prefer paths under the current repo instead of arbitrary absolute paths.
+### `~help` is not recognized
 
----
+Check:
 
-### Commands not found
+```bash
+npm list -g helloagents
+helloagents doctor
+```
 
-**Problem:** `~help` not recognized after installation
+Then restart the target CLI.
 
-**Solution:**
-- Verify installation: `npm list -g helloagents`
-- Claude Code: check `~/.claude/CLAUDE.md` contains HelloAGENTS markers
-- Gemini CLI: check `~/.gemini/GEMINI.md` contains HelloAGENTS markers
-- Codex CLI: check `~/.codex/AGENTS.md` contains HelloAGENTS markers and `~/.codex/config.toml` keeps `model_instructions_file` pointing to `~/.codex/AGENTS.md` plus `notify`
-- Restart your CLI
+### A CLI appears installed but behavior is stale
 
----
+Run:
 
-### Local branch switched but Codex global plugin still uses old files
+```bash
+helloagents doctor
+helloagents update codex
+helloagents --standby
+helloagents --global
+```
 
-**Problem:** You changed branches or updated a linked local checkout, but Codex global mode is still running older copied files.
+Use the command that matches your installed mode and target CLI.
 
-**Solution:** Re-run the current mode command:
-- `helloagents --global` → refreshes `~/plugins/helloagents/` and the Codex cache copy
-- `helloagents --standby` → refreshes injected files and symlinks for standby mode
+### Codex still uses old files after a local branch switch
 
----
+Refresh Codex:
 
-### Guard blocking legitimate commands
+```bash
+helloagents update codex
+```
 
-**Problem:** Guard blocks a command you actually want to run
+For global mode, you can also run:
 
-**Solution:** Set `guard_enabled: false` in `~/.helloagents/helloagents.json`. Or review the blocked command — the guard only blocks truly destructive operations like `rm -rf /` and `git push --force`.
+```bash
+helloagents --global
+```
 
----
+### Notifications do not work
 
-### Ralph Loop keeps failing
+Check `notify_level` first.
 
-**Problem:** Verification loop won't pass
+- Windows: PowerShell must be able to show desktop notifications or play sound
+- macOS: `afplay` should be available
+- Linux: install `aplay`, `paplay`, or `notify-send`
 
-**Solution:**
-- Check `.helloagents/verify.yaml` for correct commands
-- Run the verification commands manually to see actual errors
-- Circuit breaker activates after 3 consecutive failures — `hello-debug` escalation kicks in
+### Guard blocks a command you intended to run
 
----
+Review the command. Guard blocks known destructive operations and warns about risky writes. If you still want to disable it:
 
-### CCswitch replaces HelloAGENTS config
+```json
+{ "guard_enabled": false }
+```
 
-**Problem:** After switching CCswitch profiles, HelloAGENTS stops working
+## License
 
-**Solution:** Re-run `/plugin marketplace add hellowind777/helloagents` after switching profiles. CCswitch replaces the entire CLI config directory.
+Code is licensed under [Apache-2.0](./LICENSE.md). Documentation is licensed under CC BY 4.0.
 
----
+## Contributing
 
-### Notifications not working
-
-**Problem:** No sound or desktop notifications
-
-**Solution:**
-- Check `notify_level` in config (0=off by default)
-- Windows: Ensure PowerShell can access `System.Media.SoundPlayer`
-- macOS: Ensure `afplay` is available
-- Linux: Ensure `aplay` or `paplay` is installed
-
-## 📈 Version History
-
-### v3.0.9 (current)
-
-**Fixes and verification:**
-- 🔧 Claude Code / Gemini CLI `stop` delivery gating now prioritizes structured `turn-state` instead of inferring completion from natural-language text, so ordinary waiting turns no longer get misclassified as finished delivery
-- 🔧 Codex cleanup now preserves user-owned post-install replacements for `model_instructions_file`, `notify`, and non-managed `codex_hooks` instead of restoring stale pre-install values over them
-- 🧪 Added lifecycle/runtime regressions for structured `stop` gating and Codex config preservation after post-install user edits
-
-### v3.0.7
-
-**What the current line now delivers relative to `v2.3.8`:**
-- ✨ Full rewrite from a Python package to a Node.js/Markdown workflow framework, including install flow, runtime injection, skill system, and verification chain
-- ✨ Replaced the older layered routing / design-develop model with one 6-stage workflow: ROUTE/TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE
-- ✨ Re-centered the command surface around `~idea`, `~plan`, `~build`, `~verify`, `~prd`, `~loop`, and `~wiki`, plus 14 auto-activated quality skills
-- ✨ Turned project files into first-class workflow records: `STATE.md`, `DESIGN.md`, `requirements.md`, `plan.md`, `tasks.md`, `contract.json`, and `.ralph-*` records
-- ✨ Rebuilt installation around standby/global dual-mode deployment; Codex now uses the native local-plugin chain while Claude/Gemini keep host-native integration
-- ✨ Added `project_store_mode=repo-shared`, so multiple worktrees of one git repo can share stable KB and plan files while local `.helloagents/` still isolates activation and runtime state
-
-### v3.0.4
-
-**Standby and runtime boundaries:**
-- 🔧 Clarified the activation boundary relative to `v3.0.3`: the full 6-stage workflow stays in `bootstrap.md`, while `bootstrap-lite.md` is treated as the standby rules file before project activation
-- ✨ Solidified standby, unactivated projects with a compact quality floor so lightweight mode still keeps modern stack, performance, and UI-quality baselines
-- 🔧 Refined bootstrap terminology and runtime wording for more precise, professional guidance without changing the existing guardrail model
-
-### v3.0.3
-
-**Workflow and KB activation:**
-- ✨ Added `~wiki` for creating or syncing `.helloagents/` without writing project-level rule files
-- 🔧 Clarified the activation boundary: in standby mode, `.helloagents/` is the actual project activation signal; project-level rule files remain optional and belong to `~init`
-- 🔧 Refined `kb_create_mode` wording across bootstrap, help text, and README so it only describes sync timing inside activated projects or global mode
-- 🧪 Added routing coverage for `~wiki` and kept standby `.helloagents/` activation behavior under test
-
-### v3.0.2
-
-**Fixes and verification:**
-- 🔧 Removed the Codex-only static runtime-context block that had been reintroduced into generated `AGENTS.md` rules files in standby/global installs
-- 🔧 Re-checked Claude/Gemini standby/global static rules files and confirmed they do not inject the same deprecated runtime-context rule block
-- 🔧 Updated Codex installation docs to match the current `model_instructions_file -> ~/.codex/AGENTS.md` path and the actual no-hooks behavior
-- 🧪 Added regression assertions to ensure Codex standby/global rules files no longer contain the removed runtime-context prefix
-
-### v3.0.1
-
-**Fixes and verification:**
-- 🔧 `STATE.md` recovery rules are tightened: update on key decision changes, rewrite immediately when long-running work makes the snapshot stale, and confirm sync before host-driven compaction/recovery stages
-- 🔧 Codex cleanup now removes empty `~/.agents/plugins/marketplace.json` residue during config restore
-- 🔧 Scoped `update` continues to reuse the detected host mode even when tracked config is stale, matching the intended `helloagents update <cli>` behavior
-- 🔧 Standby branch/bootstrap refresh semantics are now documented precisely: symlinked package files update immediately, while injected rules files refresh on `install` / `update` / mode-refresh commands
-- 🧪 Added lifecycle coverage for standby rules-file refresh, stale-mode inference, empty Codex marketplace cleanup, and version-agnostic npm pack testing
-
-### v3.0.0 🎉
-
-**Breaking Changes:**
-- 🔴 Complete rewrite: Python package → pure Node.js/Markdown architecture. `pip`/`uv` installation no longer available
-- 🔴 Commands renamed/removed: `~design` → `~plan`, `~review` → `~verify`, `~do` → `~build`, removed `~exec`/`~rollback`/`~rlm`/`~status`/`~validatekb`/`~upgradekb`/`~cleanplan`
-- 🔴 Configuration keys changed from uppercase to lowercase. Removed: `BILINGUAL_COMMIT`, `EVAL_MODE`, `UPDATE_CHECK`, `CSV_BATCH_MAX`
-
-**New Features:**
-- ✨ 14 auto-activated quality skills: hello-ui, hello-api, hello-security, hello-test, hello-verify, hello-errors, hello-perf, hello-data, hello-arch, hello-debug, hello-subagent, hello-review, hello-write, hello-reflect
-- ✨ 3 supported CLIs: Claude Code (plugin/marketplace), Gemini CLI (extension), Codex CLI (npm)
-- ✨ Checklist-based delivery checks: all activated skills must pass the delivery checklist before task completion
-- ✨ `~prd` command: 13-dimension brainstorm-style PRD framework
-- ✨ `~loop` command: autonomous iteration optimization with metric tracking and git-based rollback
-- ✨ `~verify` command: auto-detect and run all verification commands
-- ✨ Guard system (`guard.mjs`): L1 blocking for destructive commands + L2 advisory for security patterns
-- ✨ Standby/Global mode: `install_mode` config for per-project or global activation
-- ✨ Flow state management (`STATE.md`): recovery snapshot for compaction/resume handoff (≤70 lines)
-- ✨ Design system generation (`DESIGN.md`): auto-created for UI projects as a project-level contract
-- ✨ Plan package system: `requirements.md` + `plan.md` + `tasks.md` + `contract.json`
-- ✨ Optional advisor contract/records: only for T3 / UI / high-risk flows, via `contract.json` + `.helloagents/.ralph-advisor.json`
-- ✨ Optional visual validation records: only when the UI contract explicitly requires it, via `contract.json` + `.helloagents/.ralph-visual.json`
-
-**Architecture:**
-- 📦 6-stage workflow: ROUTE/TIER → SPEC → PLAN → BUILD → VERIFY → CONSOLIDATE
-- 📦 Simplified configuration: 8 lowercase keys with sensible defaults
-- 📦 Dual-mode installation: standby (explicit non-plugin deploy) / global (plugin/extension)
-- 📦 Modular script architecture: `cli-utils.mjs` (shared utilities), `notify-ui.mjs` (cross-platform sound/desktop), `guard.mjs` (security), `ralph-loop.mjs` (verification)
-- 📦 Cross-platform hook compatibility: dynamic event name resolution (Claude Code / Gemini CLI / Codex CLI) via environment variables or CLI argument inference
-- 📦 Standby mode routing isolation: new project detection only triggers in global mode or activated projects, keeping unactivated projects undisturbed
-- 📦 Notification system with cross-platform sound + desktop support (Windows toast, macOS osascript, Linux notify-send)
-
-### v2.3.8
-
-**Architecture Changes:**
-- Routing tier consolidation: removed R2 simplified flow and R3 standard flow, unified to R0/R1/R2 three-tier routing
-- Evaluation driven by dimension sufficiency, replacing fixed total score threshold
-- Last-round question+confirmation combined, reducing standalone confirmation steps
-- Removed L0 user memory system and custom command extension
-- Config system consolidation: single `~/.helloagents/helloagents.json`
-- Added code size control rules: warning 300/40 lines, mandatory split 400/60 lines
-
-**New Features:**
-- ✨ 5 new workflow commands: `~test`, `~rollback`, `~validatekb`, `~upgradekb`, `~cleanplan`
-- ✨ `notify_level` config key for notification behavior control
-- ✨ Standalone config reader module for hook scripts
-
-**Security:**
-- Fixed path injection vulnerability in `shared_tasks.py`
-- Fixed incomplete path traversal guard in `validate_package.py`
-
-### v2.3.7
-
-**Bug Fixes:**
-- Fixed non-coding tasks incorrectly creating KB when `KB_CREATE_MODE=2`
-- Fixed R2 standard flow redirecting to archive instead of DEVELOP after proposal selection
-- Fixed non-coding tasks incorrectly creating plan packages
-
-**Improvements:**
-- 📦 Optimized implementation plan state recovery after context compression
-- 📦 Optimized overall design flow
-
-### v2.3.6
-
-**New Features:**
-- ✨ Sub-agent orchestration overhaul: brainstormer sub-agent for parallel proposal ideation
-- ✨ Sub-agent blocking mechanism: auto-block and fallback on failure/timeout
-
-**Improvements:**
-- 📦 Tool/Shell constraint optimization: allow fallback to Shell when built-in tools fail
-- 📦 Shell encoding constraint refinement: explicit UTF-8 no-BOM requirement
-- 📦 Removed 3 redundant sub-agents, functionality returned to main agent and RLM roles
-
-### v2.3.5
-
-**New Features:**
-- ✨ Voice notification system with 5 event sounds across Windows/macOS/Linux
-- ✨ Claude Code hooks expanded from 9 to 11 lifecycle event types
-- ✨ Hooks support expanded to Gemini CLI and Grok CLI
-- ✨ Configuration integrity check on session start
-- ✨ Recovery snapshot injection before context compaction
-- ✨ User-defined tool registration and orchestration
-
-**Improvements:**
-- 📦 Comprehensive audit fixes (21 issues: 6 HIGH + 9 MEDIUM + 6 LOW)
-- 📦 Core architecture: new dispatcher module, Codex roles, Claude rules management
-- 📦 Install/update script refactoring with persistent configuration
-
-## 📜 License
-
-This project is dual-licensed: Code under [Apache-2.0](./LICENSE.md), Documentation under CC BY 4.0.
-
-See [LICENSE.md](./LICENSE.md) for full details.
-
-## 🤝 Contributing
-
-- 🐛 **Bug reports**: [Create an issue](https://github.com/hellowind777/helloagents/issues)
-- 💡 **Feature requests**: [Start a discussion](https://github.com/hellowind777/helloagents/issues)
-- 📖 **Documentation**: PRs welcome
-
-## Supported CLIs
-
-| CLI | Standby Install (default) | Global Install (plugin) | Uninstall |
-|-----|--------------------------|------------------------|-----------|
-| Claude Code | `helloagents install claude --standby` | `/plugin marketplace add hellowind777/helloagents` | `npm uninstall -g helloagents` (+ `/plugin remove helloagents` if global) |
-| Gemini CLI | `helloagents install gemini --standby` | `gemini extensions install https://github.com/hellowind777/helloagents` | `npm uninstall -g helloagents` (+ `gemini extensions uninstall helloagents` if global) |
-| Codex CLI | `helloagents install codex --standby` | `helloagents install codex --global` | `npm uninstall -g helloagents` |
+- Bug reports: [open an issue](https://github.com/hellowind777/helloagents/issues)
+- Feature requests: [open an issue](https://github.com/hellowind777/helloagents/issues)
+- Pull requests are welcome
 
 ---
 
 <div align="center">
 
-If this project helps your workflow, a star is always appreciated.
-
-Thanks to <a href="https://codexzh.com/?ref=EEABC8">codexzh.com</a> / <a href="https://ccodezh.com">ccodezh.com</a> for supporting this project
+If this project helps you, a star is the best support.
 
-[⬆ Back to top](#helloagents)
+Thanks to <a href="https://codexzh.com/?ref=EEABC8">codexzh.com</a> / <a href="https://ccodezh.com">ccodezh.com</a> for supporting this project.
 
 </div>